Playbooks
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
| Module | Count | Playbooks |
|---|---|---|
INFRA | 3 | deploy.yml infra.yml infra-rm.yml |
NODE | 2 | node.yml node-rm.yml |
ETCD | 2 | etcd.yml etcd-rm.yml |
VAULT | 2 | vault.yml vault-rm.yml |
PGSQL | 7 | pgsql.yml pgsql-rm.ymlpgsql-user.yml pgsql-db.ymlpgsql-monitor.yml pgsql-migration.yml pgsql-pitr.yml |
REDIS | 2 | redis.yml redis-rm.yml |
MINIO | 2 | minio.yml minio-rm.yml |
DOCKER | 1 | docker.yml |
JUICE | 1 | juice.yml |
VIBE | 1 | vibe.yml |
KAFKA | 2 | kafka.yml kafka-rm.yml |
MYSQL | 2 | mysql.yml mysql-rm.yml |
Playbook Matrix
| Playbook | Module | Purpose |
|---|---|---|
deploy.yml | INFRA | Deploy the core chain: infra → node → etcd → vault → minio → pgsql |
infra.yml | INFRA | Initialize infrastructure nodes |
infra-rm.yml | INFRA | Remove infrastructure components |
node.yml | NODE | Manage nodes and baseline configuration |
node-rm.yml | NODE | Decommission nodes |
etcd.yml | ETCD | Install or expand ETCD |
etcd-rm.yml | ETCD | Remove or shrink ETCD |
vault.yml | VAULT | Initialize or converge OpenBao secrets clusters |
vault-rm.yml | VAULT | Remove OpenBao clusters or retire members |
pgsql.yml | PGSQL | Initialize PostgreSQL clusters or add instances |
pgsql-rm.yml | PGSQL | Remove PostgreSQL clusters/instances |
pgsql-user.yml | PGSQL | Add application users |
pgsql-db.yml | PGSQL | Add application databases |
pgsql-monitor.yml | PGSQL | Monitor remote PostgreSQL |
pgsql-migration.yml | PGSQL | Generate migration runbooks/scripts |
pgsql-pitr.yml | PGSQL | Point-in-time recovery |
redis.yml | REDIS | Deploy Redis |
redis-rm.yml | REDIS | Remove Redis |
minio.yml | MINIO | Deploy Silo |
minio-rm.yml | MINIO | Remove Silo, configuration, and optional data |
docker.yml | DOCKER | Deploy Docker |
juice.yml | JUICE | Deploy/remove JuiceFS instances |
vibe.yml | VIBE | Deploy the VIBE development environment |
kafka.yml | KAFKA | Create/converge complete dynamic KRaft clusters |
kafka-rm.yml | KAFKA | Remove Kafka clusters or safely retire members |
mysql.yml | MYSQL | Converge native MySQL 8.4 standalone or three-node InnoDB Cluster |
mysql-rm.yml | MYSQL | Remove clusters/members; delete data/configuration by default, retain backups |
Auxiliary Playbooks
The following playbooks are cross-module helpers.
| Playbook | Description |
|---|---|
cache.yml | Build offline installation package cache |
cert.yml | Issue certificates using Pigsty CA |
app.yml | Install Docker Compose app templates |
slim.yml | Minimal component installation scenario |
Playbook Usage Notes
Protection Mechanism
Several modules provide deletion safeguards through *_safeguard parameters:
- PGSQL:
pg_safeguardprotects PostgreSQL clusters, defaultfalse - ETCD:
etcd_safeguardprotects Etcd clusters, defaultfalse - VAULT:
vault_safeguardprotects OpenBao secrets clusters, defaulttrue - MINIO:
minio_safeguardprotects Silo clusters, defaultfalse - REDIS:
redis_safeguardprotects Redis instances, defaultfalse - KAFKA:
kafka_safeguardblocks Kafka removal, defaultfalse - MYSQL:
mysql_safeguardprotects native MySQL instances/clusters, defaulttrue
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:
Limiting Execution Scope
Use -l to limit execution targets:
For a large deployment, validate one cluster first. Then deploy in batches.
Idempotency
Most playbooks are idempotent and safe to rerun, with caveats:
infra.ymldoes not clean data by default. All cleanup parameters default tofalse:vmetrics_clean,vlogs_clean,vtraces_clean,grafana_clean, andnginx_clean.- To rebuild from a clean state, explicitly set relevant clean parameters to
true - Re-running
*-rm.ymldeletion playbooks requires extra caution
Task Tags
Use -t to run only selected task subsets:
Quick Command Reference
INFRA Module
NODE Module
ETCD Module
VAULT Module
PGSQL Module
REDIS Module
MINIO Module
DOCKER Module
KAFKA Module
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-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.