References

• 1: Supported Linux
• 2: Modules
• 3: File Hierarchy
• 4: Parameters
• 5: Playbooks
• 6: Port List

1 - Supported Linux

Pigsty runs on Linux with amd64/x86_64 and arm64/aarch64 architectures. It supports three major distribution families: EL, Debian, and Ubuntu.

Pigsty runs directly on the host without containers. It supports actively maintained mainstream releases in these three families on both architectures.

Overview

Recommended OS versions: Rocky Linux 9.8 / 10.2, Debian 12.15 / 13.7, Ubuntu 22.04.5 / 24.04.5 / 26.04.1.

These seven minor releases are the current validation baselines. The extension repository retains EL8 compatibility on both architectures. Thus, the complete package matrix covers 16 Linux platforms. EL8 is in its retirement transition and is no longer a recommended deployment baseline.

EL

Pigsty supports RHEL / Rocky / Alma / Anolis / CentOS 8, 9, 10.

Ubuntu

Pigsty supports Ubuntu 26.04 / 24.04 / 22.04:

Debian

Pigsty supports Debian 12 / 13. We recommend the latest Debian 13.7:

Vagrant

For local VM deployment, use these Vagrant base images. Pigsty development uses the same images:

• cloud-image/rocky-8: Rocky 8.10
• cloud-image/rocky-9: Rocky 9.8
• cloud-image/rocky-10: Rocky 10.2
• cloud-image/debian-12: Debian 12.15
• cloud-image/debian-13: Debian 13.7
• cloud-image/ubuntu-22.04: Ubuntu 22.04.5
• cloud-image/ubuntu-24.04: Ubuntu 24.04.5
• cloud-image/ubuntu-26.04: Ubuntu 26.04.1

OpenTofu

For cloud deployment, consider these OS image prefixes in OpenTofu templates (Aliyun example):

Alibaba Cloud’s public image selector matches the latest baseline build by prefix. For example, Debian 13.7 matches debian_13_7_x64_20G_alibase_20261019.vhd and debian_13_7_arm64_20G_alibase_20261019.vhd.

2 - Modules

Core and Extension Modules

The table lists modules with separate configuration and documentation. GA, BETA, and PILOT indicate maturity; the module count does not imply that every module is production-ready.

Core Modules

Pigsty provides four core modules. Together, they deliver complete, highly available PostgreSQL services:

• PGSQL: Self-healing PostgreSQL clusters with HA, PITR, IaC, SOP, monitoring, and 625 extensions.
• INFRA: Local software repository, VictoriaMetrics, VictoriaLogs, VictoriaTraces, Grafana, Alertmanager, Blackbox Exporter…
• NODE: Node convergence for hostname, timezone, NTP, SSH, sudo, HAProxy, Vector, and Keepalived.
• ETCD: Distributed key-value store used as DCS for HA PostgreSQL clusters: consensus leader election/config management/service discovery.

These four modules are usually installed together. You can also use them separately. In practice, only the NODE module is usually mandatory.

Extension Modules

Pigsty provides eight optional extension modules to expand the data infrastructure:

• MINIO: An S3-compatible object-storage module that deploys Silo and provides PostgreSQL backup integration and monitoring.
• REDIS: Redis server with standalone/sentinel/cluster production deployment and full monitoring support.
• DOCKER: Docker daemon service for one-click deployment of stateless software templates on Pigsty.
• VAULT: secrets/KMS module (roles/vault + roles/vault_remove) based on OpenBao, with Raft, mandatory TLS 1.3, and auto-unseal, for transparent encryption, object storage, and application secrets.
• JUICE: JuiceFS distributed filesystem module using PostgreSQL as metadata engine, providing shared POSIX storage.
• VIBE: Browser-based development environment with Code-Server, JupyterLab, Node.js, Claude Code, and Codex CLI.
• KAFKA: Apache Kafka 4.x dynamic KRaft clusters with TLS/SCRAM/ACL security baseline, declarative topics/users, and full monitoring.
• MYSQL: native MySQL 8.4 LTS (roles/mysql + roles/mysql_remove), standalone or three-node single-primary InnoDB Cluster, with mandatory TLS, node VIP, XtraBackup physical backups, and monitoring/alerts.

Ecosystem Modules

These PostgreSQL ecosystem components are optional compatibility kernels or experimental capabilities and are not counted among the 12 modules above:

• SUPABASE, DUCKDB: peripheral ecosystem integration.
• MSSQL, IVORY, POLAR, CITUS, CLOUDBERRY, PGEDGE: kernel replacement, distributed, and MPP forms.
• MySQL-compatible OpenHalo, ORIOLE, PGTDE, and AGENS: protocol compatibility, storage engines, transparent encryption, and graph databases. pg_mode: mysql selects PostgreSQL-based OpenHalo, distinct from the standalone native MYSQL 8.4 module.
• GREENPLUM, NEON: historical docs retained, no longer default public capabilities.
• KUBE, VICTORIA, JUPYTER: other pilot modules, currently not open for public use.

3 - File Hierarchy

Pigsty FHS

The default Pigsty home directory is ~/pigsty. It has this file structure:

Kernel fork templates reside under conf/fork/. See Configuration Templates for the full list.

/infra is a runtime symlink to /data/infra. This directory contains observability data and generated configuration:

metrics/           # VictoriaMetrics TSDB data
logs/              # VictoriaLogs data
traces/             # VictoriaTraces data
alertmgr/           # AlertManager data
rules/              # Rule definitions, including agent.yml
targets/            # FileSD monitoring targets
dashboards/         # Grafana dashboard definitions
datasources/        # Grafana datasource definitions
prometheus.yml      # Victoria Prometheus-compatible configuration

CA FHS

Pigsty’s self-signed CA is located in files/pki/ under the Pigsty home directory.

You must keep the CA key file secure: files/pki/ca/ca.key. The ca role generates this key when you run deploy.yml or infra.yml.

Pigsty installs these certificate files on managed nodes:

/etc/pki/ca.crt                             # root:root 0644, root cert on all nodes
/etc/pki/ca-trust/source/anchors/ca.crt     # EL system trust anchor
/usr/local/share/ca-certificates/ca.crt     # Debian/Ubuntu system trust anchor

All infra nodes have these certificates:

/etc/pki/infra.crt                          # root:infra 0644, infra node cert
/etc/pki/infra.key                          # root:infra 0640, infra node key

If the admin node fails, files/pki and pigsty.yml should be available on the backup admin node. Use rsync to copy them:

# run on meta-1, rsync to meta2
cd ~/pigsty;
rsync -avz ./ meta-2:~/pigsty

INFRA FHS

The infra role creates infra_data (default: /data/infra) and creates a symlink /infra -> /data/infra. The permissions for /data/infra are root:infra 0771. Subdirectories default to *:infra 0750, unless overridden:

This structure is created by: roles/infra/tasks/dir.yml, roles/infra/tasks/victoria.yml, roles/infra/tasks/register.yml, roles/infra/tasks/dns.yml, and roles/infra/tasks/env.yml.

Remote PostgreSQL / RDS exporters deployed on INFRA through pgsql-monitor.yml (roles/pg_exporters) also create /etc/pg_exporter/ (prometheus:infra 0755) with per-unit <unit>.yml files (0644). Only remote monitoring uses this directory; local exporters on PGSQL nodes use /etc/pg_exporter.yml directly.

Certbot integration also writes /etc/letsencrypt/renewal-hooks/deploy/10-reload-nginx (0755) to reload Nginx after renewal.

NODE FHS

node_data specifies the node data directory. The default is /data, with owner root:root and mode 0755.

Default module data and backup directories are organized under /data:

node_monitor also creates /var/lib/node_exporter/textfile (root:root 0755) for the node_exporter Textfile Collector. Modules publish local task/backup metrics there, such as VAULT’s vault.prom and MYSQL’s mysql.prom.

Chrony and tuned

Chrony uses the native OS configuration path: /etc/chrony.conf on EL and /etc/chrony/chrony.conf on Debian / Ubuntu. node_tuned_profile_dir selects the custom tuned profile directory: /etc/tuned/profiles on EL 10, Debian 13, and Ubuntu 26; /etc/tuned on the other currently supported platforms.

HAProxy

Pigsty starts HAProxy with its own systemd unit and manages the main configuration separately from service fragments:

/etc/systemd/system/haproxy.service   # systemd unit rendered by Pigsty
/etc/haproxy/haproxy.cfg              # HAProxy main configuration
/etc/haproxy/conf.d/*.cfg             # node and PostgreSQL service fragments
/etc/default/haproxy                  # optional user environment file; Pigsty does not create it

To append startup arguments in /etc/default/haproxy, use EXTRAOPTS and retain the default -S /run/haproxy-master.sock. The systemd unit loads configuration with explicit -f arguments. Do not add another -f to EXTRAOPTS.

Victoria FHS

Monitoring config has moved from the legacy /etc/prometheus layout to the /infra runtime layout. The main template is roles/infra/templates/victoria/prometheus.yml, rendered to /infra/prometheus.yml.

Pigsty copies files/victoria/bin/* to /infra/bin/ and files/victoria/rules/* to /infra/rules/. Each module registers FileSD targets under /infra/targets/*.

Pigsty stores generated INFRA units in /etc/systemd/system/. These include vmetrics, vlogs, vtraces, vmalert, alertmanager, blackbox_exporter, nginx_exporter, and dnsmasq. Distribution package unit directories are not write targets for these roles.

PostgreSQL FHS

The following parameters and internal variables are related to PostgreSQL directory layout:

• pg_dbsu_home: Postgres default user home directory, default: /var/lib/pgsql
• pg_bin_dir: Postgres binary directory, default: /usr/pgsql/bin/
• pg_fs_main: Postgres primary data directory, default: /data/postgres
• pg_fs_backup: Postgres backup disk mount point, default: /data/backups (optional; can also be a subdirectory on primary disk)
• pg_data: Internal variable, fixed to the Postgres data-directory symlink /pg/data
• pg_cluster_dir: Derived variable, {{ pg_fs_main }}/{{ pg_cluster }}-{{ pg_version }}
• pg_backup_dir: Derived variable, {{ pg_fs_backup }}/{{ pg_cluster }}-{{ pg_version }}

#--------------------------------------------------------------#
# Working assumptions:
#   {{ pg_fs_main   }} primary data directory, default: `/data/postgres` [SSD]
#   {{ pg_fs_backup }} backup data disk, default: `/data/backups`        [HDD]
#--------------------------------------------------------------#
# Default config (pg_cluster=pg-test, pg_version=18):
#     pg_fs_main = /data/postgres      High-speed SSD
#     pg_fs_backup = /data/backups     Cheap HDD (optional)
#
#     /pg        -> /data/postgres/pg-test-18
#     /pg/data   -> /data/postgres/pg-test-18/data
#     /pg/backup -> /data/backups/pg-test-18/backup
#--------------------------------------------------------------#
- name: create pgsql directories
  tags: pg_dir
  become: true
  block:

    - name: create pgsql directories
      file: path={{ item.path }} state=directory owner={{ item.owner|default(pg_dbsu) }} group={{ item.group|default('postgres') }} mode={{ item.mode }}
      with_items:
        - { path: "{{ pg_fs_main }}"            ,mode: "0700" }
        - { path: "{{ pg_fs_backup }}"          ,mode: "0700" }
        - { path: "{{ pg_cluster_dir }}"        ,mode: "0700" }
        - { path: "{{ pg_cluster_dir }}/bin"    ,mode: "0700" }
        - { path: "{{ pg_cluster_dir }}/log"    ,mode: "0750" }
        - { path: "{{ pg_cluster_dir }}/tmp"    ,mode: "0700" }
        - { path: "{{ pg_cluster_dir }}/cert"   ,mode: "0700" }
        - { path: "{{ pg_cluster_dir }}/conf"   ,mode: "0700" }
        - { path: "{{ pg_cluster_dir }}/data"   ,mode: "0700" }
        - { path: "{{ pg_cluster_dir }}/spool"  ,mode: "0700" }
        - { path: "{{ pg_backup_dir }}/backup"  ,mode: "0700" }
        - { path: "/var/run/postgresql"         ,mode: "0755" }
        - { path: "/etc/patroni"                ,mode: "0700" }
        - { path: "/etc/pgbackrest"             ,mode: "0750" }
        - { path: "/etc/pgbouncer"              ,mode: "0750" }

    - name: link pgsql directories
      file: src={{ item.src }} dest={{ item.dest }} state=link
      with_items:
        - { src: "{{ pg_backup_dir }}/backup" ,dest: "{{ pg_cluster_dir }}/backup" }
        - { src: "{{ pg_cluster_dir }}"       ,dest: "/pg" }

/etc/pgbackrest and /etc/pgbouncer are owned by {{ pg_dbsu }}:postgres with mode 0750; /etc/pgbackrest/pgbackrest.conf uses 0640. The local exporter writes configuration directly to /etc/pg_exporter.yml, without creating an /etc/pg_exporter subdirectory on PG nodes.

Data File Structure

# Physical directories
{{ pg_fs_main }}     /data/postgres                    # postgres:postgres 0700, primary data directory
{{ pg_cluster_dir }} /data/postgres/pg-test-18         # postgres:postgres 0700, cluster directory
                     /data/postgres/pg-test-18/bin     # postgres:postgres 0700 (scripts root:postgres 0755)
                     /data/postgres/pg-test-18/log     # postgres:postgres 0750, logs
                     /data/postgres/pg-test-18/tmp     # postgres:postgres 0700, temp files
                     /data/postgres/pg-test-18/cert    # postgres:postgres 0700, certs
                     /data/postgres/pg-test-18/conf    # postgres:postgres 0700, config index
                     /data/postgres/pg-test-18/data    # postgres:postgres 0700, main data
                     /data/postgres/pg-test-18/spool   # postgres:postgres 0700, pgBackRest spool
                     /data/postgres/pg-test-18/backup  # -> /data/backups/pg-test-18/backup

{{ pg_fs_backup  }}  /data/backups                     # postgres:postgres 0700, optional backup mount
{{ pg_backup_dir }}  /data/backups/pg-test-18          # postgres:postgres 0700, cluster backup directory
                     /data/backups/pg-test-18/backup   # postgres:postgres 0700, actual backup location

# Symlinks
/pg             ->   /data/postgres/pg-test-18         # pg root symlink
/pg/data        ->   /data/postgres/pg-test-18/data    # pg data directory
/pg/backup      ->   /data/backups/pg-test-18/backup   # pg backup directory

Binary File Structure

On EL-compatible distributions (using yum), PostgreSQL default installation location is:

/usr/pgsql-${pg_version}/

Pigsty creates the /usr/pgsql symlink. It points to the version specified by pg_version. For example:

/usr/pgsql -> /usr/pgsql-18

The default pg_bin_dir is therefore /usr/pgsql/bin/. Pigsty adds this path to the system PATH environment variable in /etc/profile.d/pgsql.sh.

export PATH="/usr/pgsql/bin:/pg/bin:$PATH"
export PGHOME=/usr/pgsql
export PGDATA=/pg/data

On Ubuntu/Debian, the default PostgreSQL Deb package installation location is:

/usr/lib/postgresql/${pg_version}/bin

Pigsty also stores generated PostgreSQL runtime units in /etc/systemd/system/. These primarily include patroni.service, postgres.service, pgbouncer.service, pg_exporter.service, pgbackrest_exporter.service, and pgbouncer_exporter.service. If VIP is enabled, they also include vip-manager.service.

Pgbouncer FHS

Pgbouncer runs under the same user as {{ pg_dbsu }} (default postgres), with configs in /etc/pgbouncer.

• pgbouncer.ini: main pool configuration (postgres:postgres 0640)
• database.txt: pooled database definitions (postgres:postgres 0600)
• useropts.txt: per-user connection options (postgres:postgres 0600)
• userlist.txt: password file maintained by /pg/bin/pgb-user (postgres:postgres 0600)
• pgb_hba.conf: access control file (postgres:postgres 0600)

/etc/pgbouncer/                # postgres:postgres 0750
/etc/pgbouncer/pgbouncer.ini   # postgres:postgres 0640
/etc/pgbouncer/database.txt    # postgres:postgres 0600
/etc/pgbouncer/useropts.txt    # postgres:postgres 0600
/etc/pgbouncer/userlist.txt    # postgres:postgres 0600 (managed by pgb-user)
/etc/pgbouncer/pgb_hba.conf    # postgres:postgres 0600
/pg/log/pgbouncer              # postgres:postgres 0750
/var/run/postgresql            # {{ pg_dbsu }}:postgres 0755 (managed by tmpfiles)

Object Storage FHS

The MINIO module currently deploys only Silo. It retains minio_* parameter and directory names for compatibility:

/etc/default/silo                             # root:minio 0640, service environment
/etc/systemd/system/silo.service              # root:root 0644, rendered by Pigsty
/data/minio/                                  # minio:minio 0750, default data directory
/infra/targets/minio/<cluster>-<seq>.yml      # victoria:infra 0640, FileSD target
/home/minio/.mcli/config.json                 # mcli alias; also written for the execution user

Silo certificates are stored in /home/minio/.minio/certs/. The module name, role parameters, data directory, and FileSD path retain the compatible MINIO / minio_* naming.

Redis FHS

Pigsty manages Redis or Valkey with the same directory layout and instance naming.

Service units call binaries according to redis_type (/bin/* is compatible with /usr/bin/* on most distributions):

/bin/redis-server  /bin/redis-cli    # redis_type: redis
/bin/valkey-server /bin/valkey-cli   # redis_type: valkey

For a Redis instance named redis-test-1-6379, the related resources are as follows:

/etc/systemd/system/redis-test-1-6379.service         # root:root 0644, rendered by Pigsty
/etc/systemd/system/redis_exporter.service            # root:root 0644, rendered by Pigsty
/etc/redis/                                           # redis:redis 0700
/etc/redis/redis-test-1-6379.conf                     # redis:redis 0600
/data/redis/                                          # redis:redis 0700
/data/redis/redis-test-1-6379                         # redis:redis 0700
/data/redis/redis-test-1-6379/redis-test-1-6379.rdb   # RDB file
/data/redis/redis-test-1-6379/redis-test-1-6379.aof   # AOF file
/var/log/redis/                                       # redis:redis 0700
/var/log/redis/redis-test-1-6379.log                  # logs
/var/run/redis/                                       # redis:redis 0700 (tmpfiles creates 0755 at boot)
/var/run/redis/redis-test-1-6379.pid                  # PID

Pigsty stores generated Redis/Valkey instance and exporter units in /etc/systemd/system/. Instance units use Type=notify. Packages can provide units in distribution directories. The roles do not write to those directories.

Vault FHS

VAULT runs OpenBao as openbao.service. Its node and admin-node layout is:

4 - Parameters

Use this page to find Pigsty v4.x parameters. For full explanations, read each module’s param page.

The files/cmdb.sql defaults contain 399 public parameters across 12 modules, including deployment and protected removal settings. See Modules for maturity levels.

Module Parameter Navigation

cmdb.sql combines INFRA_ID and INFRA_PACKAGE, giving INFRA 9 groups; docs split them into 10 for navigation. NODE also defines platform-derived node_tuned_profile_dir in defaults/main.yml, so its parameter page lists 74 entries. Native MYSQL 8.4 exposes 16 parameters, including mysql_data, mysql_backup_dir, mysql_backup_retention, and 3 removal safeguards. Fixed ports, versions, and timers are not public parameters.

Parameter Group Quick View

Recommendations

• Read in this order for first deployment: NODE, INFRA, PGSQL
• In production, always review: *_safeguard, password credentials, ports, and network exposure
• Validate changes on one cluster first. Then apply them globally in batches.

5 - Playbooks

This page summarizes Pigsty v4.x playbook entries and usage guidance by module. For detailed task tags, open each module’s playbook page.

Module Playbook Navigation

Playbook Matrix

Auxiliary Playbooks

The following playbooks are cross-module helpers.

Playbook Usage Notes

Protection Mechanism

Several modules provide deletion safeguards through *_safeguard parameters:

• PGSQL: pg_safeguard protects PostgreSQL clusters, default false
• ETCD: etcd_safeguard protects Etcd clusters, default false
• VAULT: vault_safeguard protects OpenBao secrets clusters, default true
• MINIO: minio_safeguard protects Silo clusters, default false
• REDIS: redis_safeguard protects Redis instances, default false
• KAFKA: kafka_safeguard blocks Kafka removal, default false
• MYSQL: mysql_safeguard protects native MySQL instances/clusters, default true

PGSQL, ETCD, MINIO, REDIS, and KAFKA default to false; explicitly enable their safeguards on initialized production clusters. VAULT and MYSQL default to true to prevent accidental destruction of encryption keys or MySQL data. mysql-rm.yml also defaults to mysql_rm_data: true, removing /data/mysql, configuration, and Router state while retaining mysql_backup_dir. Only full-cluster or standalone removal supports -e mysql_rm_data=false to stop with data retained.

When a safeguard is true, its *-rm.yml aborts immediately. After verifying risk and backups, override it explicitly on the command line:

./pgsql-rm.yml -l pg-test -e pg_safeguard=false
./etcd-rm.yml  -l etcd -e etcd_safeguard=false
./vault-rm.yml -l vault -e vault_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

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)

VAULT Module

./vault.yml -l vault                           # initialize or converge an OpenBao secrets cluster
./vault-rm.yml -l vault -e vault_safeguard=false   # remove cluster after collecting a final snapshot on the control node
./vault-rm.yml -l <ip> -e vault_safeguard=false    # safely remove one member
bin/vault-add                                  # initialize or converge cluster (wrapper)
bin/vault-add <ip>                             # add member and refresh cluster configuration (wrapper)
bin/vault-rm                                   # remove entire cluster (wrapper)
bin/vault-rm <ip>                              # retire one 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 Module

./mysql.yml -l <cls> --check     # read-only preflight
./mysql.yml -l <cls>             # create/converge a complete 1- or 3-member cluster
./mysql-rm.yml -l <cls> -e mysql_safeguard=false                      # remove cluster, data, and configuration by default
./mysql-rm.yml -l <cls> -e mysql_safeguard=false -e mysql_rm_data=false  # stop the whole cluster with data retained
./mysql-rm.yml -l <ip> -e mysql_safeguard=false                       # safely remove one HA member through a survivor

mysql-rm.yml requires explicit -l and -e mysql_safeguard=false. Default mysql_rm_data=true destroys /data/mysql, configuration, and Router state, but always retains physical backups under mysql_backup_dir (default /data/backups/mysql). A single-member target that is primary is switched away first. Single-member removal does not support -e mysql_rm_data=false.

6 - Port List

This page lists the default ports for Pigsty module components. Adjust them as needed. Use this list to configure specific firewall rules.

Kafka port 9404 is enabled only when kafka_jmx_exporter_enabled is true. The protocol exporter on 9308 is independent of this toggle.

The native MySQL pilot reuses port 3306 for MySQL Shell AdminAPI. A local systemd timer runs XtraBackup, which has no listening port. The role explicitly disables the MySQL Router REST management interface. The table lists only network endpoints currently managed by the role.

Public Port Recommendations

If you use firewall zone mode, expose only minimum required ports via node_firewall_public_port:

• Minimal management surface: 22, 80, 443 (recommended)
• If public direct DB access is required: additionally expose 5432

Avoid direct public exposure of internal component ports. Examples include:

Do not expose internal components directly to the Internet: etcd (2379/2380), OpenBao/Vault (8200/8201), patroni (8008), exporters (9xxx), object storage S3/admin ports (9000/9001), redis (6379), ferretdb (27017/27018), Kafka (9092/9093), and MySQL Group Replication (33061).

node_firewall_mode: zone
node_firewall_public_port: [22, 80, 443]
# node_firewall_public_port: [22, 80, 443, 5432]  # only if public DB access is required