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	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`
`PGSQL`	7	`pgsql.yml` `pgsql-rm.yml` `pgsql-user.yml` `pgsql-db.yml` `pgsql-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` (pilot)	2	`mysql.yml` `mysql-rm.yml`

Playbook Matrix

Playbook	Module	Purpose
`deploy.yml`	`INFRA`	One-pass deployment for the core chain (Infra/Node/Etcd/PGSQL, enabling MINIO by config)
`infra.yml`	`INFRA`	Initialize infrastructure nodes
`infra-rm.yml`	`INFRA`	Remove infrastructure components
`node.yml`	`NODE`	Node onboarding and baseline convergence
`node-rm.yml`	`NODE`	Node offboarding
`etcd.yml`	`ETCD`	ETCD install/scale-out
`etcd-rm.yml`	`ETCD`	ETCD remove/scale-in
`pgsql.yml`	`PGSQL`	Initialize PostgreSQL cluster or add instance
`pgsql-rm.yml`	`PGSQL`	Remove PostgreSQL cluster/instance
`pgsql-user.yml`	`PGSQL`	Add business users
`pgsql-db.yml`	`PGSQL`	Add business databases
`pgsql-monitor.yml`	`PGSQL`	Register remote PostgreSQL for monitoring
`pgsql-migration.yml`	`PGSQL`	Generate migration runbook and scripts
`pgsql-pitr.yml`	`PGSQL`	Point-in-time recovery (PITR)
`redis.yml`	`REDIS`	Deploy Redis
`redis-rm.yml`	`REDIS`	Remove Redis
`minio.yml`	`MINIO`	Deploy Silo
`minio-rm.yml`	`MINIO`	Remove Silo, its configuration, and optional data
`docker.yml`	`DOCKER`	Deploy Docker engine
`juice.yml`	`JUICE`	Deploy/remove JuiceFS instances
`vibe.yml`	`VIBE`	Deploy VIBE dev environment
`kafka.yml`	`KAFKA`	Create or converge a complete dynamic KRaft cluster
`kafka-rm.yml`	`KAFKA`	Remove a Kafka cluster, or safely retire a single member
`mysql.yml`	`MYSQL`	Converge a native MySQL 8.4 single node or three-node InnoDB Cluster (pilot)
`mysql-rm.yml`	`MYSQL`	Stop or retire a native MySQL instance or cluster while preserving local state (pilot)

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_safeguard
ETCD: etcd_safeguard
MINIO: minio_safeguard
REDIS: redis_safeguard
KAFKA: kafka_safeguard
MYSQL (pilot): mysql_safeguard and an exact-match mysql_rm_confirm jointly protect native MySQL retirement

The PGSQL, ETCD, MINIO, REDIS, and KAFKA role defaults are explicitly false. Set their safeguards to true for initialized production clusters.

Native MySQL uses mysql_safeguard: true by default. After you disable it, you must still set mysql_rm_confirm to exactly match the target instance or cluster.

If the safeguard is true, the corresponding *-rm.yml playbook aborts immediately. To override it, use the command line:

./pgsql-rm.yml -l pg-test -e pg_safeguard=false
./etcd-rm.yml  -l etcd -e etcd_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 -e mysql_rm_confirm=my-test

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)

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 Pilot Module

./mysql.yml -l <cls> --check
./mysql.yml -l <cls>             # accepts only a complete 1- or 3-member cluster scope
./mysql-rm.yml -l <instance> --check \
  -e mysql_safeguard=false -e mysql_rm_confirm=<instance>
./mysql-rm.yml -l <cls> \
  -e mysql_safeguard=false -e mysql_rm_confirm=<cls>

mysql-rm.yml stops the service, writes a retirement marker, and deregisters monitoring. It preserves data directories, backups, configuration, certificates, packages, and InnoDB Cluster metadata.