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`
`FERRET`	1	`mongo.yml`
`DOCKER`	1	`docker.yml`
`JUICE`	1	`juice.yml`
`VIBE`	1	`vibe.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 MinIO
`minio-rm.yml`	`MINIO`	Remove MinIO
`mongo.yml`	`FERRET`	Deploy FerretDB (Mongo API)
`docker.yml`	`DOCKER`	Deploy Docker engine
`juice.yml`	`JUICE`	Deploy/remove JuiceFS instances
`vibe.yml`	`VIBE`	Deploy VIBE dev environment

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:

By default, these safeguard parameters are undefined (not enabled). In production, explicitly set them to true for initialized clusters.

When safeguard is true, corresponding *-rm.yml playbooks abort immediately. You can force override via CLI:

./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_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 large-scale rollout, validate on 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 clean parameters (vmetrics_clean, vlogs_clean, vtraces_clean, grafana_clean, nginx_clean) default to false
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                     # one-pass full Pigsty deployment
./infra.yml                      # initialize infrastructure
./infra-rm.yml                   # remove infrastructure
./cache.yml                      # build offline package cache
./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                    # remove etcd cluster
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": {}}'     # execute 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 MinIO cluster
./minio-rm.yml -l <cls>          # remove MinIO cluster

FERRET Module

./mongo.yml -l ferret            # install FerretDB

DOCKER Module

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

Feedback

Was this page helpful?

Thanks for the feedback! Please let us know how we can improve.

Sorry to hear that. Please let us know how we can improve.

Last Modified 2026-02-14: docs(juice): refine JuiceFS config semantics and metric names (0510c97)