# Playbook

> How to use built-in Ansible playbooks to manage the INFRA module, with a quick reference for common commands.

---

LLMS index: [llms.txt](/llms.txt)

---

Pigsty provides three playbooks related to the INFRA module:

- [`deploy.yml`](#deployyml): Deploy the NODE, INFRA, ETCD, MINIO, and PGSQL core modules on all nodes in one pass
- [`infra.yml`](#infrayml): Initialize Pigsty infrastructure on infra nodes
- [`infra-rm.yml`](#infra-rmyml): Remove infrastructure components from infra nodes


----------------

## `deploy.yml`

Deploy the NODE, INFRA, ETCD, MINIO, and PGSQL core modules on all nodes in one pass, resolving INFRA/NODE circular dependency issues.

This playbook interleaves subtasks from `infra.yml` and `node.yml`, completing deployment of the core components in the following order:

1. **id**: Generate node and PostgreSQL identities
2. **ca**: Create self-signed CA on localhost
3. **repo**: Create local software repository on infra nodes
4. **node-init**: Initialize nodes and HAProxy
5. **infra**: Initialize Nginx, DNS, VictoriaMetrics, Grafana, etc.
6. **node-monitor**: Initialize node-exporter, vector
7. **etcd**: Initialize etcd (required for PostgreSQL HA)
8. **minio**: Initialize Silo (optional)
9. **pgsql**: Initialize PostgreSQL clusters and configure PostgreSQL monitoring

This playbook is equivalent to executing the following five playbooks sequentially:

```bash
./infra.yml -l infra    # Deploy infrastructure on infra group
./node.yml              # Initialize all nodes
./etcd.yml              # Initialize etcd cluster
./minio.yml             # Initialize MINIO (Silo) cluster (optional)
./pgsql.yml             # Initialize PostgreSQL clusters
```

`deploy.yml` does not currently deploy the Docker module. If Docker is required, set `docker_enabled: true` and run `docker.yml` separately.


----------------

## `infra.yml`

Initialize the infrastructure module on Infra nodes defined in the `infra` group of your configuration file.

This playbook performs the following tasks:

- Configures directories and environment variables on Infra nodes
- Downloads and creates a local software repository to accelerate subsequent installations
- Incorporates the current Infra node as a common node managed by Pigsty
- Deploys infrastructure components (VictoriaMetrics/Logs/Traces, VMAlert, Grafana, Alertmanager, Blackbox Exporter, etc.)

**Playbook notes:**

- This is an idempotent playbook - repeated execution will overwrite infrastructure components on Infra nodes
- To preserve historical monitoring data, set `vmetrics_clean`, `vlogs_clean`, `vtraces_clean` to `false` beforehand
- Unless `grafana_clean` is set to `false`, Grafana dashboards and configuration changes will be lost
- When `/www/pigsty/repo_complete` exists, this playbook skips internet downloads; the file is the SHA-256 manifest and completion marker generated by SOW
- Complete execution takes approximately 1-3 minutes, depending on machine configuration and network conditions


### Available Tasks

```text
# ca: create self-signed CA on localhost files/pki
#   - ca_dir        : create CA directory
#   - ca_private    : generate ca private key: files/pki/ca/ca.key
#   - ca_cert       : signing ca cert: files/pki/ca/ca.crt
#
# id: generate node identity
#
# repo: bootstrap a local yum repo from internet or offline packages
#   - repo_dir      : create repo directory
#   - repo_check    : check repo exists
#   - repo_prepare  : use existing repo if exists
#   - repo_build    : build repo from upstream if not exists
#     - repo_upstream    : handle upstream repo files in /etc/yum.repos.d
#       - repo_remove    : remove existing repo file if repo_remove == true
#       - repo_add       : add upstream repo files to /etc/yum.repos.d
#     - repo_url_pkg     : download packages from internet defined by repo_url_packages
#     - repo_cache       : make upstream yum cache with yum makecache
#     - repo_boot_pkg    : install sow and dnf/yum download utilities
#     - repo_pkg         : download packages & dependencies from upstream repo
#     - repo_create      : atomically create RPM/APT metadata with sow create --pigsty
#     - repo_use         : add newly built repo into /etc/yum.repos.d
#   - repo_nginx    : launch a nginx for repo if no nginx is serving
#
# node/haproxy/monitor: setup infra node as a common node
#   - node_name, node_hosts, node_resolv, node_firewall, node_ca, node_repo, node_pkg
#   - node_feature, node_kernel, node_tune, node_sysctl, node_profile, node_ulimit
#   - node_data, node_admin, node_timezone, node_ntp, node_crontab, node_vip
#   - haproxy_install, haproxy_config, haproxy_launch, haproxy_reload
#   - haproxy_register, node_exporter, node_register, vector
#
# infra: setup infra components
#   - infra_user     : setup infra os user group
#   - infra_dir      : create infra data/config/runtime directories
#   - infra_env      : env_patroni, env_pg, env_pgadmin, env_etcd, env_pglog, env_var
#   - infra_pkg      : install infra packages
#   - infra_cert     : issue cert for infra components
#   - dns            : dns_config, dns_record, dns_launch
#   - nginx          : nginx_dir, nginx_config, nginx_cert, nginx_static, nginx_launch, nginx_certbot, nginx_reload, nginx_exporter
#   - victoria       : vmetrics/vlogs/vtraces clean, config & launch; vmalert_config, vmalert_launch
#   - alertmanager   : alertmanager_config, alertmanager_launch
#   - blackbox       : blackbox_config, blackbox_launch
#   - grafana        : grafana_clean, grafana_dir, grafana_config, grafana_launch, grafana_provision
#   - infra_register : add_metrics, add_logs, add_ds
```


----------------

## `infra-rm.yml`

Remove Pigsty infrastructure from Infra nodes defined in the `infra` group of your configuration file.

Common subtasks include:

```bash
./infra-rm.yml               # Run all phases: deregister, stop, remove config/environment/data, and uninstall packages
./infra-rm.yml -t deregister # Only deregister monitoring targets, Grafana datasources, and Nginx log collection
./infra-rm.yml -t service    # Stop infrastructure services on INFRA
./infra-rm.yml -t config     # Remove INFRA configuration and systemd units
./infra-rm.yml -t env        # Remove admin environment files
./infra-rm.yml -t data       # Remove INFRA data
./infra-rm.yml -t package    # Uninstall INFRA packages
```

> [!CAUTION] Full removal deletes data
> `infra-rm.yml` has no deletion safeguard. Without tags, it runs every phase above. The `data` phase recursively removes `infra_data` (default: `/data/infra`), `nginx_data` (default: `/data/nginx`), `nginx_home` (default: `/www`), and `/var/lib/grafana`, including metrics, logs, traces, the software repository, and local Grafana data. Use the corresponding tag if you only want to stop services or deregister targets. Before a full run, back up everything that must survive and verify the exact `infra` target.