Skip to content

Playbooks

Pigsty v4.x preset Ansible playbook navigation and execution notes

This page summarizes Pigsty v4.x playbook entries and usage guidance by module. For detailed task tags, open each module’s playbook page.

Module Playbook Navigation

ModuleCountPlaybooks
INFRA3deploy.yml infra.yml infra-rm.yml
NODE2node.yml node-rm.yml
ETCD2etcd.yml etcd-rm.yml
VAULT2vault.yml vault-rm.yml
PGSQL7pgsql.yml pgsql-rm.yml
pgsql-user.yml pgsql-db.yml
pgsql-monitor.yml pgsql-migration.yml pgsql-pitr.yml
REDIS2redis.yml redis-rm.yml
MINIO2minio.yml minio-rm.yml
DOCKER1docker.yml
JUICE1juice.yml
VIBE1vibe.yml
KAFKA2kafka.yml kafka-rm.yml
MYSQL2mysql.yml mysql-rm.yml

Playbook Matrix

PlaybookModulePurpose
deploy.ymlINFRADeploy the core chain: infra → node → etcd → vault → minio → pgsql
infra.ymlINFRAInitialize infrastructure nodes
infra-rm.ymlINFRARemove infrastructure components
node.ymlNODEManage nodes and baseline configuration
node-rm.ymlNODEDecommission nodes
etcd.ymlETCDInstall or expand ETCD
etcd-rm.ymlETCDRemove or shrink ETCD
vault.ymlVAULTInitialize or converge OpenBao secrets clusters
vault-rm.ymlVAULTRemove OpenBao clusters or retire members
pgsql.ymlPGSQLInitialize PostgreSQL clusters or add instances
pgsql-rm.ymlPGSQLRemove PostgreSQL clusters/instances
pgsql-user.ymlPGSQLAdd application users
pgsql-db.ymlPGSQLAdd application databases
pgsql-monitor.ymlPGSQLMonitor remote PostgreSQL
pgsql-migration.ymlPGSQLGenerate migration runbooks/scripts
pgsql-pitr.ymlPGSQLPoint-in-time recovery
redis.ymlREDISDeploy Redis
redis-rm.ymlREDISRemove Redis
minio.ymlMINIODeploy Silo
minio-rm.ymlMINIORemove Silo, configuration, and optional data
docker.ymlDOCKERDeploy Docker
juice.ymlJUICEDeploy/remove JuiceFS instances
vibe.ymlVIBEDeploy the VIBE development environment
kafka.ymlKAFKACreate/converge complete dynamic KRaft clusters
kafka-rm.ymlKAFKARemove Kafka clusters or safely retire members
mysql.ymlMYSQLConverge native MySQL 8.4 standalone or three-node InnoDB Cluster
mysql-rm.ymlMYSQLRemove clusters/members; delete data/configuration by default, retain backups

Auxiliary Playbooks

The following playbooks are cross-module helpers.

PlaybookDescription
cache.ymlBuild offline installation package cache
cert.ymlIssue certificates using Pigsty CA
app.ymlInstall Docker Compose app templates
slim.ymlMinimal component installation scenario

Playbook Usage Notes

Protection Mechanism

Several modules provide deletion safeguards through *_safeguard parameters:

PGSQL, ETCD, MINIO, REDIS, and KAFKA default to false; explicitly enable their safeguards on initialized production clusters. VAULT and MYSQL default to true to prevent accidental destruction of encryption keys or MySQL data. mysql-rm.yml also defaults to mysql_rm_data: true, removing /data/mysql, configuration, and Router state while retaining mysql_backup_dir. Only full-cluster or standalone removal supports -e mysql_rm_data=false to stop with data retained.

When a safeguard is true, its *-rm.yml aborts immediately. After verifying risk and backups, override it explicitly on the command line:

./pgsql-rm.yml -l pg-test -e pg_safeguard=false
./etcd-rm.yml  -l etcd -e etcd_safeguard=false
./vault-rm.yml -l vault -e vault_safeguard=false
./minio-rm.yml -l minio -e minio_type=silo -e minio_safeguard=false
./redis-rm.yml -l redis-test -e redis_safeguard=false
./kafka-rm.yml -l kf-main -e kafka_safeguard=false
./mysql-rm.yml -l my-test -e mysql_safeguard=false

Limiting Execution Scope

Use -l to limit execution targets:

./pgsql.yml -l pg-meta            # run only on pg-meta cluster
./node.yml -l 10.10.10.10         # run only on one node
./redis.yml -l redis-test         # run only on redis-test cluster

For a large deployment, validate one cluster first. Then deploy in batches.

Idempotency

Most playbooks are idempotent and safe to rerun, with caveats:

  • infra.yml does not clean data by default. All cleanup parameters default to false: vmetrics_clean, vlogs_clean, vtraces_clean, grafana_clean, and nginx_clean.
  • To rebuild from a clean state, explicitly set relevant clean parameters to true
  • Re-running *-rm.yml deletion playbooks requires extra caution

Task Tags

Use -t to run only selected task subsets:

./pgsql.yml -l pg-test -t pg_service    # refresh services only on pg-test
./node.yml -t haproxy                   # configure haproxy only
./etcd.yml -t etcd_launch               # restart etcd only

Quick Command Reference

INFRA Module

./deploy.yml                     # deploy the core chain in one pass
./infra.yml                      # initialize infrastructure
./infra-rm.yml                   # remove infrastructure components
./cache.yml -l <infra-host>      # build an offline package from an existing repo on an Infra node
./cert.yml -e cn=<name>          # issue client certificate

NODE Module

./node.yml -l <cls|ip>           # add node
./node-rm.yml -l <cls|ip>        # remove node
bin/node-add <cls|ip>            # add node (wrapper)
bin/node-rm <cls|ip>             # remove node (wrapper)

ETCD Module

./etcd.yml                       # initialize etcd cluster
./etcd-rm.yml -l etcd            # remove etcd cluster; deletes local data and configuration by default
bin/etcd-add <ip>                # add etcd member (wrapper)
bin/etcd-rm <ip>                 # remove etcd member (wrapper)

VAULT Module

./vault.yml -l vault                           # initialize or converge an OpenBao secrets cluster
./vault-rm.yml -l vault -e vault_safeguard=false   # remove cluster after collecting a final snapshot on the control node
./vault-rm.yml -l <ip> -e vault_safeguard=false    # safely remove one member
bin/vault-add                                  # initialize or converge cluster (wrapper)
bin/vault-add <ip>                             # add member and refresh cluster configuration (wrapper)
bin/vault-rm                                   # remove entire cluster (wrapper)
bin/vault-rm <ip>                              # retire one member (wrapper)

PGSQL Module

./pgsql.yml -l <cls>                             # initialize PostgreSQL cluster
./pgsql-rm.yml -l <cls>                          # remove PostgreSQL cluster
./pgsql-user.yml -l <cls> -e username=<user>     # create business user
./pgsql-db.yml -l <cls> -e dbname=<db>           # create business database
./pgsql-monitor.yml -e clsname=<cls>             # monitor remote cluster
./pgsql-migration.yml -e@files/migration/<cls>.yml  # generate migration runbook
./pgsql-pitr.yml -l <cls> -e '{"pg_pitr": {}}'  # perform PITR recovery

bin/pgsql-add <cls>              # initialize cluster (wrapper)
bin/pgsql-rm <cls>               # remove cluster (wrapper)
bin/pgsql-user <cls> <user>      # create user (wrapper)
bin/pgsql-db <cls> <db>          # create database (wrapper)
bin/pgsql-svc <cls>              # refresh services (wrapper)
bin/pgsql-hba <cls>              # reload HBA (wrapper)
bin/pgmon-add <cls>              # monitor remote cluster (wrapper)

REDIS Module

./redis.yml -l <cls>             # initialize Redis cluster
./redis-rm.yml -l <cls>          # remove Redis cluster

MINIO Module

./minio.yml -l <cls>                       # initialize the MINIO module's Silo cluster
./minio-rm.yml -l <cls> -e minio_type=silo # remove Silo; this value must be confirmed explicitly

DOCKER Module

./docker.yml -l <host>           # install Docker
./app.yml -e app=<name>          # deploy Docker Compose app

KAFKA Module

./kafka.yml -l <cls>             # create / converge a complete Kafka cluster
./kafka.yml -l <cls> --check     # read-only precheck
./kafka-rm.yml -l <cls>          # remove the whole cluster
./kafka-rm.yml -l <ip>           # retire a single member from the cluster

For ordinary convergence, -l must include every declared member of the selected Kafka cluster. Only kafka-rm.yml accepts a single member for retirement.

MYSQL Module

./mysql.yml -l <cls> --check     # read-only preflight
./mysql.yml -l <cls>             # create/converge a complete 1- or 3-member cluster
./mysql-rm.yml -l <cls> -e mysql_safeguard=false                      # remove cluster, data, and configuration by default
./mysql-rm.yml -l <cls> -e mysql_safeguard=false -e mysql_rm_data=false  # stop the whole cluster with data retained
./mysql-rm.yml -l <ip> -e mysql_safeguard=false                       # safely remove one HA member through a survivor

mysql-rm.yml requires explicit -l and -e mysql_safeguard=false. Default mysql_rm_data=true destroys /data/mysql, configuration, and Router state, but always retains physical backups under mysql_backup_dir (default /data/backups/mysql). A single-member target that is primary is switched away first. Single-member removal does not support -e mysql_rm_data=false.

Was this page helpful?

Table reader