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-user.yml | Add new business user to existing PostgreSQL cluster |
| PGSQL | pgsql-db.yml | Add new business database to 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 (required for patroni HA DCS) |
| MINIO | minio.yml | Init minio cluster (optional for pgbackrest repo) |
| 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