Playbook

Run playbooks with ansible

Pigsty implements admin controllers with idempotent Ansible playbooks. Playbooks require the ansible-playbook executable bin in your PATH. You’ll have to install ansible to run playbooks.

Here are built-in playbooks in Pigsty, you can also add your own.

Module	Playbook	Function
INFRA	`install.yml`	Install Pigsty on current node in one-pass
INFRA	`infra.yml`	Init pigsty infrastructure on infra nodes
INFRA	`infra-rm.yml`	Remove infrastructure components from infra nodes
INFRA	`cache.yml`	Make offline install packages from target node
INFRA	`cert.yml`	Issue cert with pigsty self-signed CA (e.g. for pg clients)
NODE	`node.yml`	Init node for pigsty, tune node into desired status
NODE	`node-rm.yml`	Remove node from pigsty
PGSQL	`pgsql.yml`	Init HA PostgreSQL clusters, or adding new replicas
PGSQL	`pgsql-rm.yml`	Remove PostgreSQL cluster, or remove replicas
PGSQL	`pgsql-db.yml`	Add new business database to existing PostgreSQL cluster
PGSQL	`pgsql-user.yml`	Add new business user to existing PostgreSQL cluster
PGSQL	`pgsql-pitr.yml`	Run point-in-time-recovery on existing PostgreSQL cluster
PGSQL	`pgsql-monitor.yml`	Monitor remote postgres instance with local exporters
PGSQL	`pgsql-migration.yml`	Generate Migration manual & scripts for existing PostgreSQL
PGSQL	`slim.yml`	Install Pigsty with minimal components
REDIS	`redis.yml`	Init redis cluster/node/instance
REDIS	`redis-rm.yml`	Remove redis cluster/node/instance
ETCD	`etcd.yml`	Init etcd cluster, or append new member
ETCD	`etcd-rm.yml`	Remove etcd cluster, or remove existing member
MINIO	`minio.yml`	Init minio cluster
MINIO	`minio-rm.yml`	Remove minio cluster
DOCKER	`docker.yml`	Install docker on nodes
DOCKER	`app.yml`	Install application with docker compose
FERRET	`mongo.yml`	Install Mongo/FerretDB on nodes

Deployment

The special playbook install.yml will deploy everything with ad hoc playbooks:

Playbook	Command	Group	`infra`	`[nodes]`	`etcd`	`minio`	`[pgsql]`
`infra.yml`	`./infra.yml`	`-l infra`	✓	✓
`node.yml`	`./node.yml`			✓	✓	✓	✓
`etcd.yml`	`./etcd.yml`	`-l etcd`			✓
`minio.yml`	`./minio.yml`	`-l minio`				✓
`pgsql.yml`	`./pgsql.yml`						✓

Circular Dependency Between NODE and INFRA

There is a weak circular dependency between NODE and INFRA: to register a NODE to INFRA, the INFRA should already exist, while the INFRA module relies on NODE to work.

One way to work around it is to init infra nodes first, then add other nodes, if you wish to deploy them all in one-pass, install.yml is the way to go.

Safety Considerations

Idempotent but Potentially Destructive

Most playbooks are idempotent, meaning that some deployment playbooks may erase existing databases and create new ones without the protection option turned on. Especially care with pgsql, minio, and infra playbooks.

Please read the documentation carefully and operate with caution. The author is not responsible for any loss of databases due to misuse.

Safety Best Practices

Read playbook documentation carefully before execution
Ctrl-C to stop immediately if you see something wrong
Start with non-production environments for testing
Limit execution hosts (-l) to avoid unintended hosts if applicable
Use specific tags (-t) to run subset of tasks if possible

Dry Run Mode

# Preview what would be changed without actually executing
./pgsql.yml -l pg-test --check --diff

# Combine with tags to check specific tasks
./pgsql.yml -l pg-test -t pg_config --check --diff