How to create a promotable resource in Pacemaker

Promotable resources model an active/passive service where only one node holds the primary role while other nodes remain ready as secondaries. This fits replicated storage and databases that must enforce a single writer, while still allowing Pacemaker to promote a standby during failover.

In Pacemaker, promotable resources are managed as a Promotable Clone with per-instance roles such as Promoted and Unpromoted. The pcs CLI converts an existing base resource into a promotable clone (commonly named <resource_id>-clone) and exposes role-aware meta attributes for scheduling and constraints. The example below uses the ocf:pacemaker:Stateful agent to demonstrate the workflow.

Promotion and demotion switch roles at the cluster level; underlying replication and fencing must be correct to avoid dual-primary split-brain and data loss. Older stacks may use Master and Slave terminology and older meta attribute names, so version-specific naming differences must be accounted for when following examples.

1. Check cluster status before changing resource roles.

   $ sudo pcs status
   Cluster name: clustername
   Cluster Summary:
     * Stack: corosync (Pacemaker is running)
     * Current DC: node-03 (version 2.1.6-6fdc9deea29) - partition with quorum
     * Last updated: Wed Dec 31 09:29:16 2025 on node-01
     * Last change:  Wed Dec 31 09:29:05 2025 by root via cibadmin on node-01
     * 3 nodes configured
     * 5 resource instances configured
   
   Node List:
     * Online: [ node-01 node-02 node-03 ]
   ##### snipped #####

2. Confirm the base resource exists.

   $ sudo pcs resource config stateful-demo
   Resource: stateful-demo (class=ocf provider=pacemaker type=Stateful)
     Operations:
       demote: stateful-demo-demote-interval-0s
         interval=0s timeout=10s
       monitor: stateful-demo-monitor-interval-10s
         interval=10s timeout=20s role=Promoted
       monitor: stateful-demo-monitor-interval-11s
         interval=11s timeout=20s role=Unpromoted
       notify: stateful-demo-notify-interval-0s
         interval=0s timeout=5s
       promote: stateful-demo-promote-interval-0s
         interval=0s timeout=10s
       reload-agent: stateful-demo-reload-agent-interval-0s
         interval=0s timeout=10s
       start: stateful-demo-start-interval-0s
         interval=0s timeout=20s
       stop: stateful-demo-stop-interval-0s
         interval=0s timeout=20s

   Replace stateful-demo with the resource ID intended for promotion.

   Related: How to create a Pacemaker resource

3. Make the resource promotable.

   $ sudo pcs resource promotable stateful-demo --wait=120
   Resource 'stateful-demo-clone' is promoted on node node-03; unpromoted on nodes node-01, node-02.

   The promotable clone resource ID is commonly created as stateful-demo-clone.

   Use pcs resource master on older pcs releases.

   Promotable resources on replicated storage require working fencing and safe replication, or promotion can cause split-brain and data loss.

4. Set promotable limits for the clone.

   $ sudo pcs resource update stateful-demo-clone promoted-max=1 promoted-node-max=1 clone-max=2 clone-node-max=1

   promoted-max limits promoted instances cluster-wide; promoted-node-max limits promoted instances per node; clone-max limits total instances; clone-node-max limits instances per node.

   Use master-max and master-node-max on older releases.

5. Verify the promotable resource status.

   $ sudo pcs status resources
     * Resource Group: web-stack:
       * cluster_ip (ocf:heartbeat:IPaddr2): Started node-02
       * web-service (systemd:nginx): Started node-02
     * Clone Set: dummy-check-clone [dummy-check]:
       * Started: [ node-01 node-03 ]
     * Clone Set: stateful-demo-clone [stateful-demo] (promotable):
       * Promoted: [ node-03 ]
       * Unpromoted: [ node-01 ]

   Older releases may display Masters and Slaves instead of Promoted and Unpromoted.