Merge branch 'resources'

README.md

@@ -10,7 +10,8 @@ An Ansible role for managing High Availability Clustering.
   repositories accessible.
 * The role replaces the configuration of HA Cluster on specified nodes. Any
   settings not specified in the role variables will be lost.
-* For now, the role is only capable of configuring a basic corosync cluster.
+* For now, the role is capable of configuring a basic corosync cluster and
+  pacemaker stonith and resources.
 
 ## Role Variables
 
@@ -41,6 +42,17 @@ to `no`, cluster services will be configured not to start on boot.
 
 list of fence agent packages to install, default: fence-agents-all, fence-virt
 
+#### `ha_cluster_extra_packages`
+
+list of additional packages to be installed, default: no packages
+
+This variable can be used to install additional packages not installed
+automatically by the role, for example custom resource agents.
+
+It is possible to specify fence agents here as well. However,
+`ha_cluster_fence_agent_packages` is preferred for that, so that its default
+value is overriden.
+
 #### `ha_cluster_hacluster_password`
 
 string, no default - must be specified
@@ -133,7 +145,7 @@ See also:
 
 #### `ha_cluster_pcs_permission_list`
 
-Structure and default value:
+structure and default value:
 ```yaml
 ha_cluster_pcs_permission_list:
   - type: "group"
@@ -162,6 +174,131 @@ string, default: `my-cluster`
 
 Name of the cluster.
 
+#### `ha_cluster_resource_primitives`
+
+structure, default: no resources
+
+```yaml
+ha_cluster_resource_primitives:
+  - id: "resource-id"
+    agent: "resource-agent"
+    instance_attrs:
+      - attrs:
+          - name: "attribute1_name"
+            value: "attribute1_value"
+          - name: "attribute2_name"
+            value: "attribute2_value"
+    meta_attrs:
+      - attrs:
+          - name: "meta_attribute1_name"
+            value: "meta_attribute1_value"
+          - name: "meta_attribute2_name"
+            value: "meta_attribute2_value"
+    operations:
+      - action: "operation1-action"
+        attrs:
+          - name: "operation1_attribute1_name"
+            value: "operation1_attribute1_value"
+          - name: "operation1_attribute2_name"
+            value: "operation1_attribute2_value"
+      - action: "operation2-action"
+        attrs:
+          - name: "operation2_attribute1_name"
+            value: "operation2_attribute1_value"
+          - name: "operation2_attribute2_name"
+            value: "operation2_attribute2_value"
+```
+
+This variable defines pacemaker resources (including stonith) configured by the
+role. The items are as follows:
+
+* `id` (mandatory) -  Id of a resource.
+* `agent` (mandatory) - Name of a resource or stonith agent, for example
+  `ocf:pacemaker:Dummy` or `stonith:fence_xvm`. It is mandatory to use
+  `stonith:` for stonith agents. For resource agents, it is possible to use a
+  short name, such as `Dummy` instead of `ocf:pacemaker:Dummy`. However, if
+  several agents with the same short name are installed, the role will fail as
+  it will be unable to decide which agent should be used. Therefore, it is
+  recommended to use full names.
+* `instance_attrs` (optional) - List of sets of the resource's instance
+  attributes. Currently, only one set is supported. The exact names and values
+  of attributes, as well as whether they are mandatory or not, depends on the
+  resource or stonith agent.
+* `meta_attrs` (optional) - List of sets of the resource's meta attributes.
+  Currently, only one set is supported.
+* `operations` (optional) - List of the resource's operations.
+  * `action` (mandatory) - Operation action as defined by pacemaker and the
+    resource or stonith agent.
+  * `attrs` (mandatory) - Operation options, at least one option must be
+    specified.
+
+You may take a look at
+[an example](#creating-a-cluster-with-fencing-and-several-resources).
+
+#### `ha_cluster_resource_groups`
+
+structure, default: no resource groups
+
+```yaml
+ha_cluster_resource_groups:
+  - id: "group-id"
+    resource_ids:
+      - "resource1-id"
+      - "resource2-id"
+    meta_attrs:
+      - attrs:
+          - name: "group_meta_attribute1_name"
+            value: "group_meta_attribute1_value"
+          - name: "group_meta_attribute2_name"
+            value: "group_meta_attribute2_value"
+```
+
+This variable defines resource groups. The items are as follows:
+
+* `id` (mandatory) - Id of a group.
+* `resources` (mandatory) - List of the group's resources. Each resource is
+  referenced by its id and the resources must be defined in
+  [`ha_cluster_resource_primitives`](#ha_cluster_resource_primitives). At least
+  one resource must be listed.
+* `meta_attrs` (optional) - List of sets of the group's meta attributes.
+  Currently, only one set is supported.
+
+You may take a look at
+[an example](#creating-a-cluster-with-fencing-and-several-resources).
+
+#### `ha_cluster_resource_clones`
+
+structure, default: no resource clones
+
+```yaml
+ha_cluster_resource_clones:
+  - resource_id: "resource-to-be-cloned"
+    promotable: yes
+    id: "custom-clone-id"
+    meta_attrs:
+      - attrs:
+          - name: "clone_meta_attribute1_name"
+            value: "clone_meta_attribute1_value"
+          - name: "clone_meta_attribute2_name"
+            value: "clone_meta_attribute2_value"
+```
+
+This variable defines resource clones. The items are as follows:
+
+* `resource_id` (mandatory) - Resource to be cloned. The resource must be
+  defined in
+  [`ha_cluster_resource_primitives`](#ha_cluster_resource_primitives) or
+  [`ha_cluster_resource_groups`](#ha_cluster_resource_groups).
+* `promotable` (optional) - Create a promotable clone, yes or no.
+* `id` (optional) - Custom id of the clone. If no id is specified, it will be
+  generated. Warning will be emitted if this option is not supported by the
+  cluster.
+* `meta_attrs` (optional) - List of sets of the clone's meta attributes.
+  Currently, only one set is supported.
+
+You may take a look at
+[an example](#creating-a-cluster-with-fencing-and-several-resources).
+
 ### Inventory
 
 Nodes' names and addresses can be configured in inventory. This is optional. If
@@ -194,20 +331,102 @@ all:
   have the same number of addresses and the order of the addresses matters
 
 
-## Example Playbook
+## Example Playbooks
+
+### Creating a cluster running no resources
+```yaml
+- hosts: node1 node2
+  vars:
+    ha_cluster_cluster_name: "my-new-cluster"
+    ha_cluster_hacluster_password: "password"
+
+  roles:
+    - linux-system-roles.ha_cluster
+```
 
-Minimalistic example to create a cluster running no resources:
+### Creating a cluster with fencing and several resources
 ```yaml
 - hosts: node1 node2
   vars:
     ha_cluster_cluster_name: "my-new-cluster"
     ha_cluster_hacluster_password: "password"
+    ha_cluster_resource_primitives:
+      - id: "xvm-fencing"
+        agent: "stonith:fence_xvm"
+        instance_attrs:
+          - attrs:
+              - name: "pcmk_host_list"
+                value: "node1 node2"
+      - id: "simple-resource"
+        agent: "ocf:pacemaker:Dummy"
+      - id: "resource-with-options"
+        agent: "ocf:pacemaker:Dummy"
+        instance_attrs:
+          - attrs:
+              - name: "fake"
+                value: "fake-value"
+              - name: "passwd"
+                value: "passwd-value"
+        meta_attrs:
+          - attrs:
+              - name: "target-role"
+                value: "Started"
+              - name: "is-managed"
+                value: "true"
+        operations:
+          - action: "start"
+            attrs:
+              - name: "timeout"
+                value: "30"
+          - action: "monitor"
+            attrs:
+              - name: "timeout"
+                value: "5"
+              - name: "interval"
+                value: "20"
+      - id: "dummy-1"
+        agent: "ocf:pacemaker:Dummy"
+      - id: "dummy-2"
+        agent: "ocf:pacemaker:Dummy"
+      - id: "dummy-3"
+        agent: "ocf:pacemaker:Dummy"
+      - id: "simple-clone"
+        agent: "ocf:pacemaker:Dummy"
+      - id: "clone-with-options"
+        agent: "ocf:pacemaker:Dummy"
+    ha_cluster_resource_groups:
+      - id: "simple-group"
+        resource_ids:
+          - "dummy-1"
+          - "dummy-2"
+        meta_attrs:
+          - attrs:
+              - name: "target-role"
+                value: "Started"
+              - name: "is-managed"
+                value: "true"
+      - id: "cloned-group"
+        resource_ids:
+          - "dummy-3"
+    ha_cluster_resource_clones:
+      - resource_id: "simple-clone"
+      - resource_id: "clone-with-options"
+        promotable: yes
+        id: "custom-clone-id"
+        meta_attrs:
+          - attrs:
+              - name: "clone-max"
+                value: "2"
+              - name: "clone-node-max"
+                value: "1"
+      - resource_id: "cloned-group"
+        promotable: yes
 
   roles:
     - linux-system-roles.ha_cluster
 ```
 
-To purge all cluster configuration, run this:
+### Purging all cluster configuration
 ```yaml
 - hosts: node1 node2
   vars:

defaults/main.yml

@@ -6,6 +6,8 @@ ha_cluster_cluster_present: yes
 
 ha_cluster_start_on_boot: yes
 
+ha_cluster_extra_packages: []
+
 ha_cluster_fence_agent_packages:
   - "fence-agents-all"
   - "fence-virt"
@@ -27,3 +29,7 @@ ha_cluster_pcs_permission_list:
       - "grant"
       - "read"
       - "write"
+
+ha_cluster_resource_primitives: []
+ha_cluster_resource_groups: []
+ha_cluster_resource_clones: []

examples/resources.yml

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: MIT
+---
+- name: Example ha_cluster role invocation - cluster resources definition
+  hosts: all
+  vars:
+    ha_cluster_cluster_name: my-new-cluster
+    ha_cluster_hacluster_password: password
+    ha_cluster_resource_primitives:
+      - id: xvm-fencing
+        agent: 'stonith:fence_xvm'
+        instance_attrs:
+          - attrs:
+              - name: pcmk_host_list
+                value: node1 node2
+      - id: simple-resource
+        agent: 'ocf:pacemaker:Dummy'
+      - id: resource-with-options
+        agent: 'ocf:pacemaker:Dummy'
+        instance_attrs:
+          - attrs:
+              - name: fake
+                value: fake-value
+              - name: passwd
+                value: passwd-value
+        meta_attrs:
+          - attrs:
+              - name: target-role
+                value: Started
+              - name: is-managed
+                value: 'true'
+        operations:
+          - action: start
+            attrs:
+              - name: timeout
+                value: 30
+          - action: monitor
+            attrs:
+              - name: timeout
+                value: 5
+              - name: interval
+                value: 20
+      - id: dummy-1
+        agent: 'ocf:pacemaker:Dummy'
+      - id: dummy-2
+        agent: 'ocf:pacemaker:Dummy'
+      - id: dummy-3
+        agent: 'ocf:pacemaker:Dummy'
+      - id: simple-clone
+        agent: 'ocf:pacemaker:Dummy'
+      - id: clone-with-options
+        agent: 'ocf:pacemaker:Dummy'
+    ha_cluster_resource_groups:
+      - id: simple-group
+        resource_ids:
+          - dummy-1
+          - dummy-2
+        meta_attrs:
+          - attrs:
+              - name: target-role
+                value: Started
+              - name: is-managed
+                value: 'true'
+      - id: cloned-group
+        resource_ids:
+          - dummy-3
+    ha_cluster_resource_clones:
+      - resource_id: simple-clone
+      - resource_id: clone-with-options
+        promotable: yes
+        id: custom-clone-id
+        meta_attrs:
+          - attrs:
+              - name: clone-max
+                value: 2
+              - name: clone-node-max
+                value: 1
+      - resource_id: cloned-group
+        promotable: yes
+
+  roles:
+    - linux-system-roles.ha_cluster