Module: INFRA

• 1: Configuration
• 2: Parameters
• 3: Playbook
• 4: Monitoring
• 5: Metrics
• 6: FAQ
• 7: Administration
  • 7.1: Nginx Management
  • 7.2: Software Repository
  • 7.3: Domain Management
  • 7.4: Module Management
  • 7.5: CA and Certificates
  • 7.6: Grafana High Availability: Using PostgreSQL Backend

infra_portal:  # domain names and upstream servers
  home         : { domain: i.pigsty }
  grafana      : { domain: g.pigsty ,endpoint: "${admin_ip}:3000" , websocket: true }
  prometheus   : { domain: p.pigsty ,endpoint: "${admin_ip}:8428" }   # VMUI
  alertmanager : { domain: a.pigsty ,endpoint: "${admin_ip}:9059" }
  blackbox     : { endpoint: "${admin_ip}:9115" }
  vmalert      : { endpoint: "${admin_ip}:8880" }
  #logs         : { domain: logs.pigsty ,endpoint: "${admin_ip}:9428" }
  #minio        : { domain: sss.pigsty  ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }

curl -L http://i.pigsty/pigsty.repo -o /etc/yum.repos.d/pigsty.repo

[pigsty-local]
name=Pigsty local $releasever - $basearch
baseurl=file:///www/pigsty/
enabled=1
gpgcheck=0

# Configure single INFRA node
infra: { hosts: { 10.10.10.10: { infra_seq: 1 } }}

# Configure two INFRA nodes
infra:
  hosts:
    10.10.10.10: { infra_seq: 1 }
    10.10.10.11: { infra_seq: 2 }

./infra.yml     # Install INFRA module on infra group
./infra-rm.yml  # Full removal, including data and packages

./infra.yml -t repo              # Create local repo from internet or offline package

./infra.yml -t repo_dir          # Create local repo directory
./infra.yml -t repo_check        # Check if local repo already exists
./infra.yml -t repo_prepare      # If exists, use existing local repo
./infra.yml -t repo_build        # If not exists, build local repo from upstream
./infra.yml     -t repo_upstream     # Handle upstream repo files in /etc/yum.repos.d
./infra.yml     -t repo_remove       # If repo_remove == true, delete existing repo files
./infra.yml     -t repo_add          # Add upstream repo files to /etc/yum.repos.d (or /etc/apt/sources.list.d)
./infra.yml     -t repo_url_pkg      # Download packages from internet defined by repo_url_packages
./infra.yml     -t repo_cache        # Create upstream repo metadata cache with yum makecache / apt update
./infra.yml     -t repo_boot_pkg     # Install SOW and dnf/yum download utilities
./infra.yml     -t repo_pkg          # Download packages & dependencies from upstream repos
./infra.yml     -t repo_create       # Atomically create RPM/APT metadata with sow create --pigsty
./infra.yml     -t repo_use          # Add newly built repo to /etc/yum.repos.d | /etc/apt/sources.list.d
./infra.yml -t repo_nginx        # If no nginx serving, start nginx as web server

./infra.yml     -t repo_upstream     # Add upstream repos defined in repo_upstream to INFRA nodes
./infra.yml     -t repo_pkg          # Download packages and dependencies from upstream repos
./infra.yml     -t repo_create       # Create/update local RPM/APT repository metadata with SOW

./infra.yml -t infra           # Configure infrastructure
./infra.yml -t infra_user      # Setup infra OS user group
./infra.yml -t infra_dir       # Create infrastructure data, config, and runtime directories
./infra.yml -t infra_env       # Configure admin environment: env_patroni, env_pg, env_pgadmin, env_etcd, env_pglog, env_var
./infra.yml -t infra_pkg       # Install software packages required by INFRA: infra_packages
./infra.yml -t infra_cert      # Issue certificates for infra components
./infra.yml -t dns             # Configure DNSMasq: dns_config, dns_record, dns_launch
./infra.yml -t nginx           # Configure Nginx: nginx_config, nginx_cert, nginx_static, nginx_launch, nginx_certbot, nginx_reload, nginx_exporter
./infra.yml -t victoria        # Configure VictoriaMetrics/Logs/Traces: vmetrics|vlogs|vtraces|vmalert
./infra.yml -t alertmanager    # Configure AlertManager: alertmanager_config, alertmanager_launch
./infra.yml -t blackbox        # Configure Blackbox Exporter: blackbox_config, blackbox_launch
./infra.yml -t grafana         # Configure Grafana: grafana_clean, grafana_config, grafana_launch, grafana_provision
./infra.yml -t infra_register  # Register infra components to VictoriaMetrics / Grafana

./infra.yml -t nginx_index                        # Re-render Nginx homepage content
./infra.yml -t nginx_config,nginx_reload          # Re-render Nginx portal config, expose new upstream services
./infra.yml -t vmetrics_config,vmetrics_launch    # Regenerate VictoriaMetrics main config and restart service
./infra.yml -t vlogs_config,vlogs_launch          # Re-render VictoriaLogs config
./infra.yml -t vmetrics_clean                     # Clean VictoriaMetrics storage data directory
./infra.yml -t grafana_provision                     # Reload Grafana dashboards and data sources

./infra-rm.yml               # Full removal: deregister, stop, remove config/environment/data, and uninstall packages
./infra-rm.yml -t deregister # Only deregister monitoring targets, datasources, and log collection
./infra-rm.yml -t service    # Stop infrastructure services on INFRA
./infra-rm.yml -t data       # Remove INFRA data
./infra-rm.yml -t package    # Uninstall packages

1 - Configuration

Configuration Guide

INFRA primarily provides monitoring infrastructure. It is optional for PostgreSQL databases.

INFRA failures typically do not affect PostgreSQL cluster operation. Exceptions apply if you manually configure dependencies on INFRA DNS/NTP services.

One INFRA node is sufficient for most scenarios. For production HA, we recommend 2-3 INFRA nodes.

ETCD, which PostgreSQL HA requires, can share nodes with INFRA to use resources more efficiently.

More than 3 INFRA nodes provide little extra benefit. More ETCD nodes, such as 5, can improve DCS availability.

Configuration Examples

Add node IP addresses to the infra inventory group. Assign an INFRA instance number with infra_seq.

Default single INFRA node config:

all:
  children:
    infra: { hosts: { 10.10.10.10: { infra_seq: 1 } }}

During configuration, Pigsty replaces 10.10.10.10 with the current node’s primary IP address by default.

Run infra.yml to initialize the INFRA module on these nodes.

More Nodes

Two INFRA nodes config:

all:
  children:
    infra:
      hosts:
        10.10.10.10: { infra_seq: 1 }
        10.10.10.11: { infra_seq: 2 }

Three INFRA nodes config (with params):

all:
  children:
    infra:
      hosts:
        10.10.10.10: { infra_seq: 1 }
        10.10.10.11: { infra_seq: 2, repo_enabled: false }
        10.10.10.12: { infra_seq: 3, repo_enabled: false }
      vars:
        grafana_clean: false
        vmetrics_clean: false
        vlogs_clean: false
        vtraces_clean: false

INFRA High Availability

Most INFRA components have no state or share identical state. Thus, load balancing is the main HA requirement.

Use a Keepalived L2 VIP or HAProxy L4 load balancing for HA. We recommend an L2 VIP where nodes share an accessible L2 network.

Config example:

infra:
  hosts:
    10.10.10.10: { infra_seq: 1 }
    10.10.10.11: { infra_seq: 2 }
    10.10.10.12: { infra_seq: 3 }
  vars:
    vip_enabled: true
    vip_vrid: 128
    vip_address: 10.10.10.8
    vip_interface: eth1

    infra_portal:
      home         : { domain: i.pigsty }
      grafana      : { domain: g.pigsty ,endpoint: "10.10.10.8:3000" , websocket: true }
      prometheus   : { domain: p.pigsty ,endpoint: "10.10.10.8:8428" }
      alertmanager : { domain: a.pigsty ,endpoint: "10.10.10.8:9059" }
      blackbox     : { endpoint: "10.10.10.8:9115" }
      vmalert      : { endpoint: "10.10.10.8:8880" }

Set VIP-related params and modify service endpoints in infra_portal.

Nginx Configuration

See Nginx Parameter Config and Tutorial: Nginx.

Local Repo Configuration

See Repo Parameter Config.

DNS Configuration

See DNS Parameter Config and Tutorial: DNS.

NTP Configuration

See NTP Parameter Config.

2 - Parameters

The INFRA module deploys Pigsty infrastructure. This includes the local software repository, Nginx, DNSMasq, VictoriaMetrics, VictoriaLogs, Grafana, Alertmanager, and Blackbox Exporter. It also deploys other monitoring and alerting components.

Pigsty v4.x replaces Prometheus with VictoriaMetrics and Loki with VictoriaLogs for observability.

Parameter Overview

META parameters define Pigsty metadata, including version string, admin node IP, repository mirror region, default language, and proxy settings.

CA parameters configure Pigsty’s self-signed CA certificate management, including CA creation, CA name, and certificate validity.

INFRA_ID parameters define infrastructure node identity, including node sequence number, service portal configuration, and data directory.

REPO parameters configure the local software repository, including repository enable switch, directory paths, upstream source definitions, and packages to download.

INFRA_PACKAGE parameters define RPM/DEB packages to install on infrastructure nodes.

NGINX parameters configure Nginx web server and reverse proxy, including enable switch, ports, SSL mode, certificates, and basic authentication.

DNS parameters configure DNSMasq DNS server, including enable switch, listen port, and dynamic DNS records.

VICTORIA parameters configure the VictoriaMetrics/Logs/Traces observability stack, including enable switches, ports, and data retention policies.

PROMETHEUS parameters configure Alertmanager and Blackbox Exporter, providing alert management and network probing capabilities.

GRAFANA parameters configure the Grafana visualization platform, including enable switch, port, admin credentials, and data source configuration.

META

This section defines Pigsty deployment metadata: version string, admin node IP address, repository mirror region, default language, and HTTP(S) proxy for downloading packages.

version: v4.5.0                   # pigsty version string
admin_ip: 10.10.10.10             # admin node ip address
region: default                   # upstream mirror region: default,china,europe
language: en                      # default language: en or zh
proxy_env:                        # global proxy env when downloading packages
  no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
  # http_proxy:  # set your proxy here: e.g http://user:pass@proxy.xxx.com
  # https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
  # all_proxy:   # set your proxy here: e.g http://user:pass@proxy.xxx.com

version

name: version, type: string, level: G

Pigsty version string. The current source default is v4.5.0.

Pigsty uses this version string internally for feature control and content rendering. Do not modify this parameter arbitrarily.

Pigsty uses semantic versioning, and the version string typically starts with the character v, e.g., v4.5.0.

admin_ip

name: admin_ip, type: ip, level: G

Admin node IP address, default is the placeholder IP address: 10.10.10.10

This parameter identifies the admin node. It usually points to the first Pigsty node, which is the control node.

The default value 10.10.10.10 is a placeholder that will be replaced with the actual admin node IP address during configure.

Many parameters reference this parameter, such as:

• infra_portal
• repo_endpoint
• repo_upstream
• dns_records
• node_default_etc_hosts
• node_etc_hosts

Pigsty replaces ${admin_ip} in these parameters with the actual admin_ip value. This lets you specify different admin nodes for different nodes.

region

name: region, type: enum, level: G

Upstream mirror region. The options are default, china, and europe. The default is default.

If you select another region, Pigsty looks for its matching baseurl in repo_upstream. If found, it uses that URL instead of the default baseurl.

If the region is china, Pigsty tries Chinese mirrors to accelerate downloads. If a repository has no China mirror, Pigsty uses its default upstream mirror.

For repo_url_packages, Pigsty also changes repo.pigsty.io to repo.pigsty.cc to use domestic mirrors.

language

name: language, type: enum, level: G

Default language. The options are en (English) and zh (Chinese). The default is en.

This parameter affects the language preference of some Pigsty-generated configurations and content, such as the initial language setting of Grafana dashboards.

For Chinese content, we recommend that you set this parameter to zh.

proxy_env

name: proxy_env, type: dict, level: G

Global proxy environment variables for package downloads. The default sets no_proxy, which lists addresses that should bypass the proxy:

proxy_env:
  no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
  #http_proxy: 'http://username:password@proxy.address.com'
  #https_proxy: 'http://username:password@proxy.address.com'
  #all_proxy: 'http://username:password@proxy.address.com'

When installing from the Internet in mainland China, certain packages may be blocked. You can use a proxy to solve this problem.

If you use the Docker module, Pigsty also writes these proxy settings to the Docker Daemon configuration file.

If you run ./configure with -x, Pigsty reads the proxy settings from the current environment. It writes them to the generated pigsty.yaml file.

CA

Pigsty uses self-signed CA certificates to support advanced security features such as HTTPS access, PostgreSQL SSL connections, etc.

ca_create: true                   # allow creation if CA private key is missing? default true
ca_cn: pigsty-ca                  # CA CN name, fixed as pigsty-ca
cert_validity: 7300d              # certificate validity, default 20 years

ca_create

name: ca_create, type: bool, level: G

Specifies whether to create a CA private key if it is missing. The default is true.

When set to true, Pigsty creates a new CA private key if files/pki/ca/ca.key is absent. If ca.crt is absent, it uses the existing or newly created private key to issue the CA certificate.

If you already have a CA public-private key pair, you can copy them to the files/pki/ca directory:

• files/pki/ca/ca.crt: CA public key certificate
• files/pki/ca/ca.key: CA private key file

Pigsty reuses an existing CA key pair. If the private key is absent and this parameter is false, deployment stops with an error. If only ca.crt is missing, Pigsty still reissues it with the existing private key. Always back up and restore the matching ca.key and ca.crt together to avoid a certificate/key mismatch.

Keep and back up the new CA private key during deployment. You need it to issue certificates later.

Note: Pigsty v3.x used ca_method with values create/recreate/copy. Version v4.x replaces it with the boolean ca_create.

ca_cn

name: ca_cn, type: string, level: G

CA CN (Common Name). It is fixed at pigsty-ca. We do not recommend changes.

You can use the following command to view the Pigsty CA certificate details on a node:

openssl x509 -text -in /etc/pki/ca.crt

cert_validity

name: cert_validity, type: interval, level: G

Validity period for issued certificates. The default is 7300d, or 20 years. This is sufficient for most scenarios.

This parameter affects the validity of all certificates issued by the Pigsty CA, including:

• PostgreSQL server certificates
• Patroni API certificates
• etcd server/client certificates
• Other internal service certificates

Note: nginx_cert_validity separately controls the validity of Nginx HTTPS certificates. Modern browsers impose stricter website certificate limits: a maximum of 397 days.

INFRA_ID

Infrastructure identity and portal definition.

#infra_seq: 1                     # infra node sequence, REQUIRED identity parameter
infra_portal:                     # infrastructure services exposed via Nginx portal
  home : { domain: i.pigsty }     # default home server definition
infra_data: /data/infra           # infrastructure default data directory
infra_services: [...]             # built-in home navigation entries
infra_extra_services: []          # additional home navigation entries

infra_seq

name: infra_seq, type: int, level: I

Infrastructure node sequence number. This identity parameter is REQUIRED and has no default. Set it explicitly on each infrastructure node.

This parameter uniquely identifies each infrastructure node. Typically, use positive integers starting at 1.

Example configuration:

infra:
  hosts:
    10.10.10.10: { infra_seq: 1 }
    10.10.10.11: { infra_seq: 2 }

infra_portal

name: infra_portal, type: dict, level: G

Infrastructure services exposed via Nginx portal. The v4.x default value is very concise:

infra_portal:
  home : { domain: i.pigsty }     # default home server definition

Pigsty configures reverse proxies for the enabled components automatically. Usually, you only need to define the home domain name.

Each record has a key and a value dictionary. The key, name, identifies the component. The value defines these parameters:

• name: REQUIRED, specifies the name of the Nginx server
  • Default record: home is a fixed name, please do not modify it.
  • Used as part of the Nginx configuration file name, corresponding to: /etc/nginx/conf.d/<name>.conf
  • Nginx servers without a domain field will not generate configuration files but will be used as references.
• domain: OPTIONAL for a reference-only entry. It is REQUIRED to expose a service through Nginx and specifies its domain name.
  • In Pigsty self-signed Nginx HTTPS certificates, the domain will be added to the SAN field of the Nginx SSL certificate
  • Pigsty web page cross-references will use the default domain name here
• endpoint: Upstream server address for a reverse proxy. Usually, use it as an alternative to path.
  • ${admin_ip} can be used as a placeholder in the configuration and will be dynamically replaced with admin_ip during deployment
  • Default reverse proxy servers use endpoint.conf as the configuration template
  • Reverse proxy servers can also configure websocket and schema parameters
• path: Local directory for a file server. Usually, use it as an alternative to endpoint.
  • Local web servers use path.conf as the configuration template
  • Local web servers can also configure the index parameter to enable file index pages
• certbot: Certbot certificate name; if configured, Certbot will be used to apply for certificates
  • If servers share a certbot value, Pigsty combines their certificate requests. This value becomes the certificate name.
• cert: Certificate file path; if configured, will override the default certificate path
• key: Certificate key file path; if configured, will override the default certificate key path
• websocket: Whether to enable WebSocket support
  • Only reverse proxies can use this parameter. If enabled, it permits upstream WebSocket connections.
• schema: Protocol used by the upstream server; if configured, will override the default protocol
  • Default is http; if configured as https, it will force HTTPS connections to the upstream server
• index: Whether to enable file index pages
  • Only local file servers can use this parameter. If enabled, autoindex generates directory index pages.
• log: Nginx log file path
  • If specified, Nginx writes access logs to this file. Otherwise, the server type determines the default log file.
  • Reverse proxy servers use /var/log/nginx/<name>.log as the default log file path
  • Local web servers use the default Access log
• conf: Nginx template filename
  • Specifies a configuration template in roles/infra/templates/nginx or templates/nginx.
  • Takes precedence over automatic selection by home / path / endpoint. Development sources also have specialized site templates such as repo.conf, beta.conf, demo.conf, pgext.conf, and pgweb.conf; see Development Maintenance Reference.
  • If this parameter is not specified, the default configuration template will be used
• cache_dir: Portal cache directory. When nonempty, the role creates it with owner nginx:nginx and mode 0750. Directory management was added to development sources on 2026-09-01 and is absent from the v4.5.0 release.
• domains: Additional domain list included in Certbot’s domain set. Development sources since 2026-09-01 also include it in SANs when issuing new self-signed certificates. Whether the template listens for these aliases still depends on its server_name.
• config: Nginx configuration code block
  • Configuration text directly injected into the Nginx Server configuration block
• enforce_https: Redirect HTTP to HTTPS
  • Global configuration can be specified via nginx_sslmode: enforce
  • This setting does not affect the default home server. For compatibility, that server always listens on both ports 80 and 443.

infra_data

name: infra_data, type: path, level: G

Infrastructure data directory, default value is /data/infra.

This directory is used to store data files for infrastructure components, including:

• VictoriaMetrics time series database data
• VictoriaLogs log data
• VictoriaTraces trace data
• Other infrastructure component persistent data

We recommend a separate data disk for this directory. This simplifies management and expansion.

infra_services

name: infra_services, type: service[], level: G

Built-in navigation entries on the Pigsty home page. Current defaults include Metrics, Logs, Traces, Monitor Targets, Alert Rules, Alert Manager, CA Certificate, Software Repo, and Explain Visualizer.

Each item can use name, url, desc, and icon, plus the Chinese display fields name_cn and desc_cn. This parameter replaces the entire default list. To append entries, use infra_extra_services.

infra_extra_services

name: infra_extra_services, type: service[], level: G

Navigation entries appended to infra_services. The default is [], and each item uses the same structure as infra_services. For example:

infra_extra_services:
  - { name: My Service, url: 'https://example.com', desc: 'External Service', icon: 'database' }

REPO

This section is about local software repository configuration. Pigsty enables a local software repository (APT/YUM) on infrastructure nodes by default.

During initialization, Pigsty downloads packages and dependencies from the internet. repo_packages specifies the packages, and repo_upstream specifies the upstream repositories. The destination is {{ nginx_home }} / {{ repo_name }}, which defaults to /www/pigsty. The total software and dependency size is approximately 1GB.

The current package candidate is SOW 0.3.0. The source uses SOW to generate RPM/APT metadata. After a successful build, repo_complete is both a SHA-256 manifest and a completion marker. When it is present, Pigsty skips downloading and rebuilding by default and uses the existing repository. Force a rebuild with ./infra.yml -t repo_build -e repo_build=true.

Both repo_create and cache_create run sow create --pigsty directly. They do not fall back to createrepo_c or dpkg-scanpackages.

Older offline bundles or local repositories might lack SOW. First, refresh the media or install SOW from the Pigsty INFRA repository.

If package downloads are too slow, set a proxy with proxy_env for the initial download. You can also download a prebuilt offline package. This is a local repository built on the same operating system.

repo_enabled: true                # create local repo on this infra node?
repo_home: /www                   # repo home directory, default /www
repo_name: pigsty                 # repo name, default pigsty
repo_endpoint: http://${admin_ip}:80 # repo access endpoint
repo_remove: true                 # remove existing upstream repo definitions
repo_modules: infra,node,pgsql    # enabled upstream repo modules
#repo_upstream: []                # upstream repo definitions (inherited from OS variables)
#repo_packages: []                # packages to download (inherited from OS variables)
#repo_extra_packages: []          # extra packages to download
repo_url_packages: []             # extra packages downloaded via URL

repo_enabled

name: repo_enabled, type: bool, level: G/I

Specifies whether to create a local repository on this infrastructure node. The default is true, which creates a repository on every Infra node.

With multiple infrastructure nodes, you can keep repositories on only 1-2 nodes. Set this parameter to false elsewhere to avoid duplicate downloads and builds.

repo_home

name: repo_home, type: path, level: G

Local software repository home directory, defaults to Nginx’s root directory: /www.

On a fresh installation, if this path does not exist, the role creates a symlink to nginx_data. Existing directories and symlinks are preserved unchanged. We generally recommend that you preserve this value. If you change it, keep it consistent with nginx_home.

repo_name

name: repo_name, type: string, level: G

Local repository name, default is pigsty. Changing this repository name is not recommended.

The final repository path is {{ repo_home }}/{{ repo_name }}, defaulting to /www/pigsty.

repo_endpoint

name: repo_endpoint, type: url, level: G

Endpoint used by other nodes to access this repository, default value: http://${admin_ip}:80.

Pigsty starts Nginx on infrastructure nodes at ports 80/443 by default, providing local software repository (static files) service.

Adjust this parameter after changes to nginx_port or nginx_ssl_port. Also adjust it if the infrastructure node differs from the control node.

If you use a domain name, you can add resolution in node_default_etc_hosts, node_etc_hosts, or dns_records.

repo_remove

name: repo_remove, type: bool, level: G/A

Specifies whether to remove existing upstream repository definitions during a local repository build. The default is true.

When this parameter is enabled, all existing repository files in /etc/yum.repos.d will be moved and backed up to /etc/yum.repos.d/backup. On Debian systems, /etc/apt/sources.list and /etc/apt/sources.list.d are removed and backed up to /etc/apt/backup.

Pigsty does not control the content of existing operating-system sources. Pigsty-validated upstream sources can improve package download speed and success rate.

Some EL/Deb-compatible variants use private sources for many packages. If you need to preserve existing upstream repository definitions, set this parameter to false.

repo_modules

name: repo_modules, type: string, level: G/A

Which upstream repository modules will be added to the local software source, default value: infra,node,pgsql

When Pigsty attempts to add upstream repositories, it filters entries in repo_upstream based on this parameter’s value. Only entries whose module field matches this parameter’s value will be added to the local software source.

During the build stage, infra is automatically added to the effective module list so SOW can be installed. This bootstrap dependency is restored even if a user overrides repo_modules without infra.

Modules are comma-separated. Available module lists can be found in the repo_upstream definitions; common modules include:

• local: Local Pigsty repository
• infra: Infrastructure packages (Nginx, Docker, etc.)
• node: OS base packages
• pgsql: PostgreSQL-related packages
• extra: Extra PostgreSQL extensions
• docker: Docker-related
• redis: Redis-related
• mongo: MongoDB-related
• mysql: MySQL-related
• etc…

repo_upstream

name: repo_upstream, type: upstream[], level: G

Upstream package sources for the local repository build. This parameter has no direct default. If unset, Pigsty loads repo_upstream_default from roles/node_id/vars. It selects the definition for the current node’s operating-system family.

Pigsty provides complete upstream repository definitions for currently supported OS versions (EL 8/9/10, Debian 12/13, Ubuntu 22/24/26), including:

• OS base repositories (BaseOS, AppStream, EPEL, etc.)
• PostgreSQL official PGDG repository
• Pigsty extension repository
• Various third-party software repositories (Docker, Nginx, Grafana, etc.)

Each upstream repository definition contains the following fields:

- name: pigsty-pgsql              # repository name
  description: 'Pigsty PGSQL'     # repository description
  module: pgsql                   # module it belongs to
  releases: [8,9,10]              # supported OS versions
  arch: [x86_64, aarch64]         # supported CPU architectures
  baseurl:                        # repository URL, configured by region
    default: 'https://repo.pigsty.io/yum/pgsql/el$releasever.$basearch'
    china: 'https://repo.pigsty.cc/yum/pgsql/el$releasever.$basearch'
  # meta: { module_hotfixes: 1 } # enable only when explicitly replacing an EL module stream

RPM upstream repositories retain native DNF module filtering by default. Set meta.module_hotfixes only on a repository that must actually replace an EL module stream. Clients use module_hotfixes=1 for Pigsty’s aggregated local repository. Pigsty no longer generates artificial modules.yaml / ModuleMD metadata.

Users typically don’t need to modify this parameter unless they have special repository requirements. For detailed repository definitions, refer to the configuration files for corresponding operating systems in the roles/node_id/vars/ directory.

repo_packages

name: repo_packages, type: string[], level: G

String array of packages to download with their dependencies. Each entry is a space-separated package list. Downloads use repotrack or apt download.

This parameter has no direct default. If unset, Pigsty loads repo_packages_default from roles/node_id/vars:

[ node-bootstrap, infra-package, infra-addons, node-package1, node-package2, node-package3, pgsql-utility, extra-modules ]

Each element in this parameter will be translated according to the package_map in the above files, based on the specific OS distro major version. For example, on EL systems it translates to:

node-bootstrap:          "ansible python3 python3-requests python3-jmespath python3-cryptography dnf-utils sow sshpass"
infra-package:           "nginx dnsmasq etcd haproxy vip-manager node-exporter keepalived-exporter pg-exporter pgbackrest-exporter redis-exporter redis valkey silo mcli sow pig"
infra-addons:            "grafana grafana-plugins grafana-victoriametrics-ds grafana-victorialogs-ds victoria-metrics victoria-logs victoria-traces vlogscli vmutils vector alertmanager"

By convention, repo_packages contains packages independent of the PostgreSQL major version, including Infra, Node, and PGDG Common packages. Put version-specific kernels and extensions in repo_extra_packages. This simplifies PostgreSQL major-version changes.

repo_extra_packages

name: repo_extra_packages, type: string[], level: G/C/I

Additional packages to download without changing repo_packages. These are typically specific to a PostgreSQL major version. The default is an empty list.

If not explicitly defined, Pigsty will load the default from the repo_extra_packages_default variable defined in roles/node_id/vars:

[ pgsql-main ]

Pigsty translates these package names. It replaces $v with pg_version, the current PostgreSQL major version. The default version is 18.

The pgsql-main here translates on EL systems to:

postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl pg_repack_$v wal2json_$v pgvector_$v

Users can typically specify PostgreSQL major version-related packages here without affecting the other PG version-independent packages defined in repo_packages.

repo_url_packages

name: repo_url_packages, type: object[] | string[], level: G

Packages downloaded directly from the Internet using URLs, default is an empty array: []

You can use URL strings directly as array elements in this parameter, or use object structures to explicitly specify URLs and filenames.

The region variable affects this parameter. For mainland China, Pigsty automatically changes repo.pigsty.io URLs to repo.pigsty.cc.

INFRA_PACKAGE

These RPM/DEB packages are installed only on INFRA nodes.

infra_packages

name: infra_packages, type: string[], level: G

Packages to install on Infra nodes. Each array entry is a space-separated package list.

The default varies by platform. If unset, Pigsty loads infra_packages_default from the matching file under roles/node_id/vars. It selects the file by operating-system version and CPU architecture.

For example, the current mapping for EL 9 x86_64 is:

infra_packages_default:
  - grafana,grafana-plugins,grafana-victorialogs-ds,grafana-victoriametrics-ds,victoria-metrics,victoria-logs,victoria-traces,vmutils,vlogscli,alertmanager
  - node-exporter,blackbox-exporter,nginx-exporter,pg-exporter,pev2,nginx,dnsmasq,ansible,etcd,python3-requests,redis,mcli,restic,certbot,python3-certbot-nginx

The current mapping for Debian 13 x86_64 is:

infra_packages_default:
  - grafana,grafana-plugins,grafana-victorialogs-ds,grafana-victoriametrics-ds,victoria-metrics,victoria-logs,victoria-traces,vmutils,vlogscli,alertmanager
  - node-exporter,blackbox-exporter,nginx-exporter,pg-exporter,pev2,nginx,dnsmasq,ansible,etcd,python3-requests,redis,mcli,restic,certbot,python3-certbot-nginx

Note: v4.x uses the VictoriaMetrics suite to replace Prometheus and Loki, so the package list differs significantly from v3.x.

NGINX

Nginx proxies Pigsty web services, including the Home Page, Grafana, and VictoriaMetrics. It also proxies optional tools such as PGWeb, Jupyter Lab, Pgadmin, and Bytebase. It serves static resources and reports, including pev, schemaspy, and pgbadger.

Nginx also serves the local Yum/Apt repository, which stores and distributes Pigsty packages.

nginx_enabled: true               # enable Nginx on this infra node?
nginx_clean: false                # clean existing Nginx config during init?
nginx_exporter_enabled: true      # enable nginx_exporter?
nginx_exporter_port: 9113         # nginx_exporter listen port
nginx_sslmode: enable             # SSL mode: disable,enable,enforce
nginx_cert_validity: 397d         # self-signed cert validity
nginx_home: /www                  # Nginx content directory (symlink)
nginx_data: /data/nginx           # Nginx actual data directory
nginx_users: {}                   # basic auth users dictionary
nginx_port: 80                    # HTTP port
nginx_ssl_port: 443               # HTTPS port
certbot_sign: false               # sign cert with certbot?
certbot_email: your@email.com     # certbot email
certbot_options: ''               # certbot extra options

nginx_enabled

name: nginx_enabled, type: bool, level: G/I

Specifies whether to enable Nginx on this Infra node. The default is true.

Nginx is a core component of Pigsty infrastructure, responsible for:

• Providing local software repository service
• Reverse proxying Grafana, VictoriaMetrics, and other web services
• Hosting static files and reports

nginx_clean

name: nginx_clean, type: bool, level: G/A

Specifies whether to delete existing Nginx configuration during initialization. The default is false.

If set to true, Pigsty deletes all configuration files under /etc/nginx/conf.d/ during Nginx initialization. This starts with an empty configuration directory.

If you’re deploying for the first time or want to completely rebuild Nginx configuration, you can set this parameter to true.

nginx_exporter_enabled

name: nginx_exporter_enabled, type: bool, level: G/I

Specifies whether to enable nginx_exporter on this infrastructure node. The default is true.

If this option is disabled, the /nginx health check stub will also be disabled. Consider disabling this when your Nginx version doesn’t support this feature.

nginx_exporter_port

name: nginx_exporter_port, type: port, level: G

nginx_exporter listen port, default value is 9113.

nginx_exporter is used to collect Nginx operational metrics for VictoriaMetrics to scrape and monitor.

nginx_sslmode

name: nginx_sslmode, type: enum, level: G

Nginx SSL operating mode. The options are disable, enable, and enforce. The default, enable, enables SSL but does not require it.

• disable: Only listen on the port specified by nginx_port to serve HTTP requests.
• enable: Also listen on the port specified by nginx_ssl_port to serve HTTPS requests.
• enforce: All links will be rendered to use https:// by default
  • Also redirect port 80 to port 443 for non-default servers in infra_portal

nginx_cert_validity

name: nginx_cert_validity, type: duration, level: G

Nginx self-signed certificate validity, default value is 397d (approximately 13 months).

The default follows the modern browser limit of 397 days for website certificates. We do not recommend longer validity because browsers can reject these certificates.

nginx_home

name: nginx_home, type: path, level: G

Nginx server static content directory, default: /www

This is a symlink that actually points to the nginx_data directory. This directory contains static resources and software repository files.

Avoid unnecessary changes to this parameter. If changed, keep it consistent with repo_home.

nginx_data

name: nginx_data, type: path, level: G

Nginx actual data directory, default is /data/nginx.

This directory stores Nginx static files. The nginx_home symlink points to it.

We recommend a data disk for this directory to simplify management of large package files.

nginx_users

name: nginx_users, type: dict, level: G

Nginx Basic Authentication user dictionary, default is an empty dictionary {}.

Format is { username: password } key-value pairs, for example:

nginx_users:
  admin: pigsty
  viewer: readonly

These users can be used to protect certain Nginx endpoints that require authentication.

nginx_port

name: nginx_port, type: port, level: G

Nginx HTTP listen port. The default is 80. We recommend that you keep the default.

If port 80 is occupied, you can use another port. Also update repo_endpoint to match the new port.

nginx_ssl_port

name: nginx_ssl_port, type: port, level: G

Nginx SSL listen port. The default is 443. We recommend that you keep the default.

certbot_sign

name: certbot_sign, type: bool, level: G/A

Specifies whether Certbot signs Nginx certificates during installation. The default is false.

If set to true, Pigsty uses Certbot to request free Let’s Encrypt SSL certificates automatically. The nginx role does this during infra.yml and deploy.yml.

For an infra_portal entry with certbot set, Pigsty requests a certificate for its domain. The certbot value becomes the certificate name.

If multiple servers or domains share the same certbot value, Pigsty combines them in one request. It uses that value as the certificate name.

Enabling this option requires:

• A public domain resolves to the current node’s public IP and provides access to the node.
• The current node can access the Let’s Encrypt API interface

This option is disabled by default. After installation, run make cert manually if needed. It calls the generated /etc/nginx/sign-cert script to request or update certificates with Certbot.

certbot_email

name: certbot_email, type: string, level: G/A

Email address for receiving certificate expiration reminder emails, default value is your@email.com.

When certbot_sign is set to true, it’s recommended to provide this parameter. Let’s Encrypt will send reminder emails to this address when certificates are about to expire.

certbot_options

name: certbot_options, type: string, level: G/A

Additional configuration parameters passed to certbot, default value is an empty string.

Use this parameter for extra Certbot command-line options. For example, --dry-run previews and tests the operation without requesting actual certificates.

DNS

Pigsty enables DNSMASQ on Infra nodes by default. It resolves auxiliary names such as i.pigsty, m.pigsty, and api.pigsty. The optional sss.pigsty name can provide the Silo endpoint.

Resolution records are stored in the /etc/dnsmasq.d/pigsty/default file on Infra nodes. To use this DNS server, you must add nameserver <ip> to /etc/resolv.conf. The node_dns_servers parameter handles this.

dns_enabled: true                 # setup dnsmasq on this infra node?
dns_port: 53                      # DNS server listen port
dns_records:                      # dynamic DNS records
  - "${admin_ip} i.pigsty"
  - "${admin_ip} m.pigsty supa.pigsty api.pigsty adm.pigsty cli.pigsty ddl.pigsty"

dns_enabled

name: dns_enabled, type: bool, level: G/I

Specifies whether to enable DNSMASQ on this Infra node. The default is true.

Set this value to false if you do not need the default DNS server. For example, you might have an external server or a provider that prohibits DNS servers. Use static records in node_default_etc_hosts and node_etc_hosts instead.

dns_port

name: dns_port, type: port, level: G

DNSMASQ default listening port, default is 53. It’s not recommended to modify the default DNS service port.

dns_records

name: dns_records, type: string[], level: G

Dynamic DNS records resolved by dnsmasq, generally used to resolve auxiliary domain names to the admin node. These records are written to the /etc/dnsmasq.d/pigsty/default file on infrastructure nodes.

v4.x default value:

dns_records:
  - "${admin_ip} i.pigsty"
  - "${admin_ip} m.pigsty supa.pigsty api.pigsty adm.pigsty cli.pigsty ddl.pigsty"

The ${admin_ip} placeholder is used here and will be replaced with the actual admin_ip value during deployment.

Common domain name purposes:

• i.pigsty: Pigsty home page
• m.pigsty: Commonly used for the Silo console (optional)
• p.pigsty: Commonly used for the VictoriaMetrics Web UI when explicitly configured in infra_portal
• api.pigsty: API service
• adm.pigsty: Admin service
• Others customized based on actual deployment needs

VICTORIA

Pigsty v4.x uses the VictoriaMetrics suite for observability in place of Prometheus and Loki:

• VictoriaMetrics: Replaces Prometheus as the time series database for storing monitoring metrics
• VictoriaLogs: Replaces Loki as the log aggregation storage
• VictoriaTraces: Distributed trace storage
• VMAlert: Replaces Prometheus Alerting for alert rule evaluation

vmetrics_enabled: true            # enable VictoriaMetrics?
vmetrics_clean: false             # clean data during init?
vmetrics_port: 8428               # listen port
vmetrics_scrape_interval: 10s     # global scrape interval
vmetrics_scrape_timeout: 8s       # global scrape timeout
vmetrics_options: >-
  -retentionPeriod=15d
  -promscrape.fileSDCheckInterval=5s
vlogs_enabled: true               # enable VictoriaLogs?
vlogs_clean: false                # clean data during init?
vlogs_port: 9428                  # listen port
vlogs_options: >-
  -retentionPeriod=15d
  -retention.maxDiskSpaceUsageBytes=50GiB
  -insert.maxLineSizeBytes=1MB
  -search.maxQueryDuration=120s
vtraces_enabled: true             # enable VictoriaTraces?
vtraces_clean: false              # clean data during init?
vtraces_port: 10428               # listen port
vtraces_options: >-
  -retentionPeriod=15d
  -retention.maxDiskSpaceUsageBytes=50GiB
vmalert_enabled: true             # enable VMAlert?
vmalert_port: 8880                # listen port
vmalert_options: ''               # extra CLI options

vmetrics_enabled

name: vmetrics_enabled, type: bool, level: G/I

Specifies whether to enable VictoriaMetrics on this Infra node. The default is true.

VictoriaMetrics is the core monitoring component in Pigsty v4.x, replacing Prometheus as the time series database, responsible for:

• Scraping monitoring metrics from various exporters
• Storing time series data
• Providing PromQL-compatible query interface
• Supporting Grafana data sources

vmetrics_clean

name: vmetrics_clean, type: bool, level: G/A

Specifies whether to delete existing VictoriaMetrics data during initialization. The default is false.

When set to true, existing time series data will be deleted during initialization. Use this option carefully unless you’re sure you want to rebuild monitoring data.

vmetrics_port

name: vmetrics_port, type: port, level: G

VictoriaMetrics listen port, default value is 8428.

This port is used for:

• HTTP API access
• Web UI access
• Prometheus-compatible remote write/read
• Grafana data source connections

vmetrics_scrape_interval

name: vmetrics_scrape_interval, type: interval, level: G

VictoriaMetrics global metrics scrape interval, default value is 10s.

A 10-30 second scrape interval is suitable for production. A shorter interval gives more detailed monitoring data but increases storage and CPU overhead.

vmetrics_scrape_timeout

name: vmetrics_scrape_timeout, type: interval, level: G

VictoriaMetrics global scrape timeout, default is 8s.

A scrape timeout helps prevent monitoring queries from accumulating. Set it below and close to vmetrics_scrape_interval. This keeps each scrape shorter than the interval.

vmetrics_options

name: vmetrics_options, type: arg, level: G

VictoriaMetrics extra command line options, default value:

vmetrics_options: >-
  -retentionPeriod=15d
  -promscrape.fileSDCheckInterval=5s

Common parameter descriptions:

• -retentionPeriod=15d: Data retention period, default 15 days
• -promscrape.fileSDCheckInterval=5s: File service discovery refresh interval

You can add other VictoriaMetrics-supported parameters as needed.

vlogs_enabled

name: vlogs_enabled, type: bool, level: G/I

Specifies whether to enable VictoriaLogs on this Infra node. The default is true.

VictoriaLogs replaces Loki as the log aggregation storage, responsible for:

• Receiving log data from Vector
• Storing and indexing logs
• Providing log query interface
• Supporting Grafana VictoriaLogs data source

vlogs_clean

name: vlogs_clean, type: bool, level: G/A

Specifies whether to delete existing VictoriaLogs data during initialization. The default is false.

vlogs_port

name: vlogs_port, type: port, level: G

VictoriaLogs listen port, default value is 9428.

vlogs_options

name: vlogs_options, type: arg, level: G

VictoriaLogs extra command line options, default value:

vlogs_options: >-
  -retentionPeriod=15d
  -retention.maxDiskSpaceUsageBytes=50GiB
  -insert.maxLineSizeBytes=1MB
  -search.maxQueryDuration=120s

Common parameter descriptions:

• -retentionPeriod=15d: Log retention period, default 15 days
• -retention.maxDiskSpaceUsageBytes=50GiB: Maximum disk usage
• -insert.maxLineSizeBytes=1MB: Maximum single log line size
• -search.maxQueryDuration=120s: Maximum query execution time

vtraces_enabled

name: vtraces_enabled, type: bool, level: G/I

Specifies whether to enable VictoriaTraces on this Infra node. The default is true.

VictoriaTraces stores and queries distributed trace data. It supports Jaeger, Zipkin, and other trace protocols.

vtraces_clean

name: vtraces_clean, type: bool, level: G/A

Specifies whether to delete existing VictoriaTraces data during initialization. The default is false.

vtraces_port

name: vtraces_port, type: port, level: G

VictoriaTraces listen port, default value is 10428.

vtraces_options

name: vtraces_options, type: arg, level: G

VictoriaTraces extra command line options, default value:

vtraces_options: >-
  -retentionPeriod=15d
  -retention.maxDiskSpaceUsageBytes=50GiB

vmalert_enabled

name: vmalert_enabled, type: bool, level: G/I

Specifies whether to enable VMAlert on this Infra node. The default is true.

VMAlert evaluates alert rules and works with Alertmanager. It replaces Prometheus Alerting.

vmalert_port

name: vmalert_port, type: port, level: G

VMAlert listen port, default value is 8880.

vmalert_options

name: vmalert_options, type: arg, level: G

VMAlert extra command line options, default value is an empty string.

PROMETHEUS

This section now primarily contains Blackbox Exporter and Alertmanager configuration.

Note: Pigsty v4.x uses VictoriaMetrics instead of Prometheus. The current interface no longer includes prometheus_* and pushgateway_*. Use vmetrics_* and vmalert_* under VICTORIA for metric storage and rule evaluation.

blackbox_enabled: true            # enable blackbox_exporter?
blackbox_port: 9115               # blackbox_exporter listen port
blackbox_options: ''              # extra CLI options
alertmanager_enabled: true        # enable alertmanager?
alertmanager_port: 9059           # alertmanager listen port
alertmanager_options: ''          # extra CLI options
exporter_metrics_path: /metrics   # exporter metrics path

blackbox_enabled

name: blackbox_enabled, type: bool, level: G/I

Specifies whether to enable BlackboxExporter on this Infra node. The default is true.

BlackboxExporter sends ICMP packets to node IP addresses, VIP addresses, and PostgreSQL VIP addresses to test network connectivity. It can also perform HTTP, TCP, DNS, and other probes.

blackbox_port

name: blackbox_port, type: port, level: G

Blackbox Exporter listen port, default value is 9115.

blackbox_options

name: blackbox_options, type: arg, level: G

BlackboxExporter extra command line options, default value: empty string.

alertmanager_enabled

name: alertmanager_enabled, type: bool, level: G/I

Specifies whether to enable AlertManager on this Infra node. The default is true.

AlertManager receives alerts from VMAlert. It groups, inhibits, silences, routes, and otherwise processes these alerts.

alertmanager_port

name: alertmanager_port, type: port, level: G

AlertManager listen port, default value is 9059.

If you modify this port, ensure you update the alertmanager entry’s endpoint configuration in infra_portal accordingly (if defined).

alertmanager_options

name: alertmanager_options, type: arg, level: G

AlertManager extra command line options, default value: empty string.

exporter_metrics_path

name: exporter_metrics_path, type: path, level: G

HTTP endpoint path where monitoring exporters expose metrics, default: /metrics. Not recommended to modify this parameter.

This parameter defines the standard path for all exporters to expose monitoring metrics.

GRAFANA

Grafana provides the monitoring system frontend. It also supports data analysis, visualization, low-code data application development, and application prototyping.

grafana_enabled: true             # enable Grafana?
grafana_port: 3000                # Grafana listen port
grafana_clean: false              # clean data during init?
grafana_admin_username: admin     # admin username
grafana_admin_password: pigsty    # admin password
grafana_auth_proxy: false         # enable auth proxy?
grafana_pgurl: ''                 # external PostgreSQL URL
grafana_view_password: DBUser.Viewer  # PG datasource password

grafana_enabled

name: grafana_enabled, type: bool, level: G/I

Specifies whether to enable Grafana on this Infra node. The default is true, which installs and enables Grafana on all infrastructure nodes.

grafana_port

name: grafana_port, type: port, level: G

Grafana listen port, default value is 3000.

If you need to access Grafana directly (not through Nginx reverse proxy), you can use this port.

grafana_clean

name: grafana_clean, type: bool, level: G/A

Specifies whether to delete Grafana data files during initialization. The default is false.

This operation removes /var/lib/grafana/grafana.db, ensuring a fresh Grafana installation.

If you want to preserve existing Grafana configuration (such as dashboards, users, data sources, etc.), set this parameter to false.

grafana_admin_username

name: grafana_admin_username, type: username, level: G

Grafana admin username, default is admin.

grafana_admin_password

name: grafana_admin_password, type: password, level: G

Grafana admin password, default is pigsty.

IMPORTANT: Change this password before production deployment.

grafana_auth_proxy

name: grafana_auth_proxy, type: bool, level: G

Specifies whether to enable the Grafana authentication proxy. The default is false.

If enabled, Grafana trusts user identity information from the Nginx reverse proxy. This supports single sign-on (SSO).

This is typically used for integration with external identity authentication systems.

grafana_pgurl

name: grafana_pgurl, type: url, level: G

External PostgreSQL database URL for Grafana persistence storage. Default is an empty string.

If specified, Grafana will use this PostgreSQL database instead of the default SQLite database to store its configuration data.

Format example: postgres://grafana:password@pg-meta:5432/grafana?sslmode=disable

This is useful for scenarios requiring Grafana high availability deployment or data persistence.

grafana_view_password

name: grafana_view_password, type: password, level: G

Read-only user password used by Grafana metadb PG data source, default is DBUser.Viewer.

This password is used for Grafana to connect to the PostgreSQL CMDB data source to query metadata in read-only mode.

3 - Playbook

Pigsty provides three playbooks related to the INFRA module:

• deploy.yml: Deploy the NODE, INFRA, ETCD, MINIO, and PGSQL core modules on all nodes in one pass
• infra.yml: Initialize Pigsty infrastructure on infra nodes
• infra-rm.yml: Remove infrastructure components from infra nodes

deploy.yml

Deploy NODE, INFRA, ETCD, MINIO, and PGSQL on all nodes in one pass. This resolves the circular dependency between INFRA and NODE.

The playbook interleaves subtasks from infra.yml and node.yml. It deploys core components in this 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:

./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
• If /www/pigsty/repo_complete exists, the playbook skips internet downloads. SOW generates this SHA-256 manifest and completion marker.
• Complete execution takes approximately 1-3 minutes, depending on machine configuration and network conditions

Available Tasks

# 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:

./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

4 - Monitoring

This document describes monitoring dashboards and alert rules for the INFRA module in Pigsty.

Dashboards

The current files/grafana/infra directory contains 11 dashboards. The table also includes Pigsty Home from the root directory. See Monitoring System for overall dashboard and rule counts, and Metrics for endpoints and labels.

Alert Rules

Pigsty provides the following two alert rules for the INFRA module:

Both alerts fire when the corresponding recorded metric stays below 1 for one minute, with severity CRIT. AgentDown covers the actual exclusion list in agent_up, not every exporter; see Current Recording Rules. Source comments and alert summaries still contain older component names and the type label. Current registration uses cls / ins; troubleshoot using expressions and actual labels.

You can modify or add new infrastructure alert rules in files/victoria/rules/infra.yml.

Alert Rule Configuration

################################################################
#                Infrastructure Alert Rules                    #
################################################################
- name: infra-alert
  rules:

    #==============================================================#
    #                       Infra Aliveness                        #
    #==============================================================#
    # infra components (victoria,grafana) down for 1m triggers a P1 alert
    - alert: InfraDown
      expr: infra_up < 1
      for: 1m
      labels: { level: 0, severity: CRIT, category: infra }
      annotations:
        summary: "CRIT InfraDown {{ $labels.type }}@{{ $labels.instance }}"
        description: |
          infra_up[type={{ $labels.type }}, instance={{ $labels.instance }}] = {{ $value  | printf "%.2f" }} < 1

    #==============================================================#
    #                       Agent Aliveness                        #
    #==============================================================#

    # agent aliveness are determined directly by exporter aliveness
    # including: node_exporter, pg_exporter, pgbouncer_exporter, haproxy_exporter
    - alert: AgentDown
      expr: agent_up < 1
      for: 1m
      labels: { level: 0, severity: CRIT, category: infra }
      annotations:
        summary: 'CRIT AgentDown {{ $labels.ins }}@{{ $labels.instance }}'
        description: |
          agent_up[ins={{ $labels.ins }}, instance={{ $labels.instance }}] = {{ $value  | printf "%.2f" }} < 1

5 - Metrics

INFRA monitors VictoriaMetrics, VictoriaLogs, VictoriaTraces, VMAlert, Alertmanager, Grafana, Nginx Exporter, and Blackbox Exporter. Targets come from roles/infra/templates/prometheus/infra.yml.j2; scrape jobs are defined in roles/infra/templates/victoria/prometheus.yml.

Component versions and enabled services affect the raw metric set. This page lists scrape targets, rules, and common metrics for the Victoria stack. See Monitoring System for site-wide counts.

Metric Definitions and Counts

• Raw metrics: Produced by components or exporters. Read TYPE and HELP at /metrics for their types and meanings.
• Recorded metrics: Computed from expressions by vmalert and queried in VictoriaMetrics. They have no independent TYPE metadata and cannot all be classified as Counter or Gauge.
• Scrape status: up and scrape_* are generated by the collection system. up=1 indicates a successful scrape; database and application availability still require functional checks.

Histogram / Summary _bucket, _sum, and _count are different samples of the same metric family. Historical table rows, recording rules, and live time series count different objects and cannot be added together.

Scrape Endpoints and Labels

All targets below use job=infra and HTTP /metrics. The default target file is /infra/targets/infra/infra-<infra_seq>.yml.

Each target also carries ip and the scrape endpoint instance. The template does not inject the old type label; use cls to distinguish components. Targets are registered only for enabled components. VMAlert requires both vmalert_enabled and vmetrics_enabled; Nginx target registration depends on nginx_enabled.

Blackbox Exporter’s own metrics belong to job=infra. ICMP probe_* metrics produced through /probe belong to the separate job=ping. These are different target types.

Current Recording Rules

files/victoria/rules/infra.yml defines 2 recording rules, evaluated by vmalert and written back to VictoriaMetrics:

infra_up and agent_up are recording rules, absent from components’ raw /metrics output. The exclusion list above defines the scope of agent_up: it does not exclude jobs such as kafka, ping, or pgrds, and does not cover exporters already in node or pgsql. up=1 indicates only successful scraping. Assess functional service health with nginx_up, probe results, or component metrics.

The InfraDown and AgentDown alerts fire when their respective metrics stay below 1 for one minute. Both use severity CRIT. See Monitoring and Alerting for the rules.

Shared Liveness Recording Rules

In addition to module rules, roles/infra/templates/victoria/agent.yml generates 14 shared liveness rules, deployed to /infra/rules/agent.yml. The table retains template expressions; configuration variables render the ports. All derive from collector-generated up and indicate scrape success, not necessarily successful database queries, quorum, or application requests.

These recorded metrics are also absent from raw /metrics endpoints. Rules matching ports do not restrict job, so port overrides must remain consistent between the Infra rule template and service configuration.

Key Dashboard Metrics

The following names come from queries in the current files/grafana/infra dashboards and provide troubleshooting entry points. Availability depends on the installed version’s /metrics output.

These are raw metric names. Counters usually require rate() / increase() before analysis. Histogram / Summary _bucket, _sum, and _count are samples of one metric family, not unrelated families counted by row.

Get the Actual Metric List

Run these queries in VictoriaMetrics VMUI (default http://<infra-ip>:8428/vmui) or Grafana Explore:

up{job="infra"}
count by (cls) (up{job="infra"})
count by (__name__) ({job="infra"})

The first query checks each target’s scrape status, the second counts registered component endpoints, and the third lists visible series counts by metric name at the query time. To count distinct metric names, use count(count by (__name__) ({job="infra"})). This is still not an exporter metric-family count and cannot be added directly to other module counts.

Read raw types, HELP text, and labels from the target endpoint, for example:

curl -fsS http://127.0.0.1:8428/metrics
curl -fsS http://127.0.0.1:9428/metrics
curl -fsS http://127.0.0.1:8880/metrics

6 - FAQ

What components are included in the INFRA module?

The current infra role directly manages these components:

• Nginx: Exposes Grafana, VictoriaMetrics (VMUI), Alertmanager, and other WebUIs, and hosts local YUM/APT repositories.
• DNSMasq: Provides DNS registration and resolution.
• VictoriaMetrics suite: VictoriaMetrics, VMAlert, VictoriaLogs, and VictoriaTraces.
• Alertmanager, Blackbox Exporter, and Grafana: Alert dispatch, blackbox probing, and visualization.

infra.yml also runs the CA, repository, NODE, HAProxy, and node-monitoring roles. These configure supporting services such as the self-signed CA, Chronyd, Node Exporter, and Vector on Infra nodes.

ETCD, PostgreSQL, and Docker are separate modules. The infra.yml playbook does not deploy them. Use etcd.yml, pgsql.yml, and docker.yml, respectively.

How to re-register monitoring targets to VictoriaMetrics?

VictoriaMetrics uses static service discovery through the /infra/targets/<job>/*.yml directory. If target files are accidentally deleted, use the following commands to re-register:

./infra.yml  -t infra_register   # Re-render Infra self-monitoring targets
./node.yml   -t node_register    # Re-render node / HAProxy / Vector targets
./etcd.yml   -t etcd_register    # Re-render Etcd targets
./minio.yml  -t minio_register   # Re-render Silo module targets
./pgsql.yml  -t pg_register      # Re-render PGSQL/Patroni targets
./redis.yml  -t redis_register   # Re-render Redis targets

Other modules (such as pg_monitor.yml and mysql.yml) also provide corresponding *_register tags that can be executed as needed.

How to re-register PostgreSQL datasources to Grafana?

PGSQL databases defined in pg_databases are registered as Grafana datasources by default (for use by PGCAT applications).

If you accidentally delete postgres datasources registered in Grafana, you can register them again using the following command:

# Register all pgsql databases (defined in pg_databases) as grafana datasources
./pgsql.yml -t register_grafana

How to re-register node HAProxy admin pages to Nginx?

If you accidentally delete the registered haproxy proxy settings in /etc/nginx/conf.d/haproxy, you can restore them using the following command:

./node.yml -t register_nginx     # Register all haproxy admin page proxy settings to nginx on infra nodes

How to restore DNS registration records in DNSMASQ?

PGSQL cluster/instance domains are registered by default to /etc/dnsmasq.d/pigsty/<name> on infra nodes. You can restore them using the following command:

./pgsql.yml -t pg_dns    # Register pg DNS names to dnsmasq on infra nodes

How to expose new upstream services via Nginx?

You can access services directly through IP:Port. However, we recommend domain names and the Nginx proxy for WebUI access. This centralizes access, reduces exposed ports, and simplifies access control and auditing.

If you want to expose new WebUI services through the Nginx portal, you can add service definitions to the infra_portal parameter. For example, here’s the Infra portal configuration used by Pigsty’s official demo, exposing several additional services:

infra_portal:
  home         : { domain: home.pigsty.cc }
  grafana      : { domain: demo.pigsty.io ,endpoint: "${admin_ip}:3000" ,websocket: true }
  prometheus   : { domain: p.pigsty.cc ,endpoint: "${admin_ip}:8428" }
  alertmanager : { domain: a.pigsty.cc ,endpoint: "${admin_ip}:9059" }
  blackbox     : { endpoint: "${admin_ip}:9115" }
  vmalert      : { endpoint: "${admin_ip}:8880" }
  # Additional web portals
  minio        : { domain: sss.pigsty  ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }
  postgrest    : { domain: api.pigsty.cc  ,endpoint: "127.0.0.1:8884"   }
  pgadmin      : { domain: adm.pigsty.cc  ,endpoint: "127.0.0.1:8885"   }
  pgweb        : { domain: cli.pigsty.cc  ,endpoint: "127.0.0.1:8886"   }
  bytebase     : { domain: ddl.pigsty.cc  ,endpoint: "127.0.0.1:8887"   }
  gitea        : { domain: git.pigsty.cc  ,endpoint: "127.0.0.1:8889"   }
  wiki         : { domain: wiki.pigsty.cc ,endpoint: "127.0.0.1:9002"   }
  noco         : { domain: noco.pigsty.cc ,endpoint: "127.0.0.1:9003"   }
  supa         : { domain: supa.pigsty.cc ,endpoint: "127.0.0.1:8000", websocket: true }

After completing the Nginx upstream service definition, use the following configuration and commands to register new services to Nginx.

./infra.yml -t nginx_config           # Regenerate Nginx configuration files
./infra.yml -t nginx_launch           # Update and apply Nginx configuration

# You can also manually reload Nginx config with Ansible
ansible infra -b -a 'nginx -s reload'  # Reload Nginx config

For HTTPS, delete files/pki/csr/pigsty.csr and files/pki/nginx/pigsty.{key,crt} to force Nginx SSL/TLS certificate regeneration. The new certificates include the new upstream domains.

To use certificates from an authoritative CA instead of the Pigsty self-signed CA, put them in /etc/nginx/conf.d/cert/. Update the corresponding /etc/nginx/conf.d/<name>.conf configuration.

How to manually add upstream repo files to nodes?

Pigsty has a built-in wrapper script bin/repo-add that calls the ansible playbook node.yml to add repo files to corresponding nodes.

bin/repo-add <selector> [modules]
bin/repo-add 10.10.10.10           # Add node repo for node 10.10.10.10
bin/repo-add infra   node,infra    # Add node and infra repos for infra group
bin/repo-add infra   node,local    # Add node repo and local pigsty repo for infra group
bin/repo-add pg-test node,pgsql    # Add node and pgsql repos for pg-test group

7 - Administration

This section covers daily administration and operations for Pigsty deployments.

7.1 - Nginx Management

Pigsty installs Nginx on INFRA nodes as the entry point for all web services. It listens on standard ports 80/443.

In Pigsty, you can configure Nginx to provide various services through inventory:

• Expose web interfaces for monitoring components like Grafana, VictoriaMetrics (VMUI), Alertmanager, and VictoriaLogs
• Serve static files (software repos, documentation sites, websites, etc.)
• Proxy custom application services (internal apps, database management UIs, Docker application interfaces, etc.)
• Automatically issue self-signed HTTPS certificates, or use Certbot to obtain free Let’s Encrypt certificates
• Expose services through a single port using different subdomains for unified access

Basic Configuration

Customize Nginx behavior via infra_portal parameter:

infra_portal:
  home: { domain: i.pigsty }

infra_portal is a dictionary where each key defines a service and the value is the service configuration. Pigsty generates Nginx configuration files only for services with a defined domain.

• home: Special default server for homepage and built-in monitoring component reverse proxies
• Proxy services: Specify upstream service address via endpoint for reverse proxy
• Static services: Specify local directory via path for static file serving

Server Parameters

Basic Parameters

SSL/TLS Options

Advanced Settings

When conf is set, that template takes precedence. Otherwise, the role selects a generic template based on home, path, and endpoint.

Configuration Examples

Reverse Proxy Services

grafana: { domain: g.pigsty, endpoint: "${admin_ip}:3000", websocket: true }
pgadmin: { domain: adm.pigsty, endpoint: "127.0.0.1:8885" }

Static Files and Directory Listing

repo: { domain: repo.pigsty.io, path: "/www/repo", index: true }

Custom SSL Certificate

secure_app:
  domain: secure.pigsty.io
  endpoint: "${admin_ip}:8443"
  cert: "/etc/ssl/certs/custom.crt"
  key: "/etc/ssl/private/custom.key"

Using Let’s Encrypt Certificates

grafana:
  domain: demo.pigsty.io
  endpoint: "${admin_ip}:3000"
  websocket: true
  certbot: pigsty.demo    # Cert name, multiple domains can share one cert

Force HTTPS Redirect

web.io:
  domain: en.pigsty.io
  path: "/www/web.io"
  certbot: pigsty.doc
  enforce_https: true

Custom Config Snippet

web.cc:
  domain: pigsty.io
  path: "/www/web.io"
  domains: [ en.pigsty.io ]
  certbot: pigsty.doc
  config: |
    # rewrite /en/ to /
        location /en/ {
            rewrite ^/en/(.*)$ /$1 permanent;
        }

Management Commands

./infra.yml -t nginx           # Full Nginx reconfiguration
./infra.yml -t nginx_config    # Regenerate config files
./infra.yml -t nginx_launch    # Restart Nginx service
./infra.yml -t nginx_cert      # Regenerate SSL certificates
./infra.yml -t nginx_certbot   # Sign certificates with certbot
./infra.yml -t nginx_reload    # Reload Nginx configuration

Domain Resolution

Three ways to resolve domains to Pigsty servers:

1. Public domains: Configure via DNS provider
2. Internal DNS server: Configure internal DNS resolution
3. Local hosts file: Modify /etc/hosts

For local development, add to /etc/hosts:

<your_public_ip_address> i.pigsty

Pigsty includes dnsmasq service, configurable via dns_records parameter for internal DNS resolution.

HTTPS Configuration

Configure HTTPS via nginx_sslmode parameter:

For self-signed certificates, several access options:

• Trust the self-signed CA in browser (download at http://<ip>/ca.crt)
• Use browser security bypass (type “thisisunsafe” in Chrome)
• Configure proper CA-signed certs or Let’s Encrypt for production

Certbot Certificates

Pigsty supports using Certbot to request free Let’s Encrypt certificates.

Enable Certbot

1. Add certbot parameter to services in infra_portal, specifying cert name
2. Configure certbot_email with a valid email
3. Set certbot_sign to true for auto-signing during deployment

certbot_sign: true
certbot_email: your@email.com

Manual Certificate Signing

./infra.yml -t nginx_certbot   # Sign Let's Encrypt certificates

Or run the scripts directly on the server:

/etc/nginx/sign-cert           # Sign certificates
/etc/nginx/link-cert           # Link certificates to Nginx config directory

For more info, see Certbot: Request and Renew HTTPS Certificates

Default Homepage

Pigsty’s default home server provides these built-in routes:

These routes provide one entry point for all monitoring components. You do not need to configure multiple domains.

Best Practices

• Use domain names instead of IP:PORT for service access
• Properly configure DNS resolution or hosts file
• Enable WebSocket for real-time apps (e.g., Grafana, Jupyter)
• Enable HTTPS for production
• Use meaningful subdomains to organize services
• Monitor Let’s Encrypt certificate expiration
• Use config parameter for custom Nginx configurations

Full Example

Here’s the Nginx configuration used by Pigsty’s public demo site demo.pigsty.io:

infra_portal:
  home         : { domain: i.pigsty }
  io           : { domain: pigsty.io      ,path: "/www/pigsty.io"   ,cert: /etc/cert/pigsty.io.crt ,key: /etc/cert/pigsty.io.key }
  minio        : { domain: m.pigsty.io    ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }
  postgrest    : { domain: api.pigsty.io  ,endpoint: "127.0.0.1:8884" }
  pgadmin      : { domain: adm.pigsty.io  ,endpoint: "127.0.0.1:8885" }
  pgweb        : { domain: cli.pigsty.io  ,endpoint: "127.0.0.1:8886" }
  bytebase     : { domain: ddl.pigsty.io  ,endpoint: "127.0.0.1:8887" }
  jupyter      : { domain: lab.pigsty.io  ,endpoint: "127.0.0.1:8888" ,websocket: true }
  gitea        : { domain: git.pigsty.io  ,endpoint: "127.0.0.1:8889" }
  wiki         : { domain: wiki.pigsty.io ,endpoint: "127.0.0.1:9002" }
  noco         : { domain: noco.pigsty.io ,endpoint: "127.0.0.1:9003" }
  supa         : { domain: supa.pigsty.io ,endpoint: "10.10.10.10:8000" ,websocket: true }
  dify         : { domain: dify.pigsty.io ,endpoint: "10.10.10.10:8001" ,websocket: true }
  odoo         : { domain: odoo.pigsty.io ,endpoint: "127.0.0.1:8069"   ,websocket: true }
  mm           : { domain: mm.pigsty.io   ,endpoint: "10.10.10.10:8065" ,websocket: true }

Development Maintenance Reference

The specialized development templates below maintain Pigsty’s public sites and are not yet included in public sources. Ordinary portals can use the generic configuration above.

# Dedicated public repository node
nginx_exporter_scrape_uri: http://127.0.0.1:9180/nginx
infra_portal:
  repo:
    domain: repo.example.com
    conf: repo.conf
    path: /data/nginx/repo
    certbot: repo.example.com

7.2 - Software Repository

Pigsty’s REPO role downloads required packages and creates a local YUM/APT repository under /www/pigsty. Nginx can serve this repository.

The current package candidate is SOW 0.3.0. SOW generates metadata for both repository types. The source no longer calls createrepo_c, modifyrepo_c, or dpkg-scanpackages separately.

Quick Start

Add packages to repo_packages or repo_extra_packages, then run:

./infra.yml -t repo_build   # Download and build only when the repository is absent
./node.yml -t node_repo     # Refresh repository definitions and caches on each node

If /www/pigsty/repo_complete already exists, the default repo_build skips the build. To force a rebuild, override it explicitly:

./infra.yml -t repo_build -e repo_build=true

To rebuild metadata for packages already present without downloading new ones:

./infra.yml -t repo_create

SOW Prerequisites

Both repo_create and cache_create require sow on the target node. A fresh online build automatically adds infra to the effective repo_modules list. It installs SOW from the Pigsty INFRA upstream repository.

Offline bundles and local repositories created before this change may not contain SOW. Before you rebuild from old media, refresh the bundle or local repository. Alternatively, install the current SOW 0.3.0 candidate from Pigsty INFRA. Do not assume that older environments can still fall back to createrepo_c.

On a fresh installation, the role checks whether /www exists. If absent, it creates /data/nginx and points /www to it. It preserves existing directories and symlinks.

Build Flow

The command executed by repo_create is:

sow create --pigsty --timeout 10m -- /www/pigsty

--pigsty removes unneeded packages and packages likely to cause conflicts. It atomically publishes the result only after all metadata is complete. A typical layout is:

/www/pigsty/
├── *.rpm / *.deb
├── repodata/            # RPM repository
├── Packages             # APT repository
├── Packages.gz
└── repo_complete        # SHA-256 manifest and completion marker

repo_complete contains SHA-256 checksums. Do not treat it as an empty marker. Its presence means SOW completed publication of local repository metadata. It does not prove that remote mirrors, signed repositories, or offline bundles have been synchronized.

DNF Module Streams

Pigsty no longer fabricates modules.yaml / ModuleMD metadata for the aggregated local repository. System upstream repositories retain native DNF module filtering. Only an upstream repository that truly needs to replace an EL module stream should set meta explicitly:

- name: example
  module: pgsql
  # ... releases, arch, baseurl ...
  meta: { module_hotfixes: 1 }

The aggregated local repository uses module_hotfixes=1. This prevents system module streams from hiding local PostgreSQL packages. It does not generate artificial ModuleMD metadata.

Package Aliases

The default repo_packages uses these alias groups:

[node-bootstrap, infra-package, infra-addons, node-package1,
 node-package2, node-package3, pgsql-utility, extra-modules]

node-bootstrap includes Ansible, Python dependencies, SOW, and SSH tools. infra-package includes Nginx, etcd, HAProxy, Victoria exporters, Redis/Valkey, Silo, mcli, SOW, and Pig. Exact names vary by operating-system mapping. Use roles/node_id/vars/<os>.<arch>.yml as the authoritative source.

Common Commands

./infra.yml -t repo                           # Check, prepare, or build, then start repository service
./infra.yml -t repo_check,repo_prepare        # Only check and use an existing repository
./infra.yml -t repo_upstream                  # Refresh upstream repository definitions
./infra.yml -t repo_pkg                       # Download configured packages and dependencies
./infra.yml -t repo_create                    # Rebuild metadata in the existing directory with SOW
./infra.yml -t repo_build -e repo_build=true  # Force the complete build stage
./infra.yml -t repo_nginx                     # Configure/start repository Nginx
./node.yml -t node_repo                       # Refresh managed-node repository caches
./cache.yml                                   # Rebuild metadata with SOW, then create an offline bundle

7.3 - Domain Management

Use domain names instead of IP addresses to access Pigsty’s various web services.

Quick Start

Add the following static resolution records to /etc/hosts:

10.10.10.10 i.pigsty

Replace IP address with your actual Pigsty node’s IP.

Why Use Domain Names

• Easier to remember than IP addresses
• Flexible pointing to different IPs
• Unified service management through Nginx
• Support for HTTPS encryption
• Prevent ISP hijacking in some regions
• Allow access to internally bound services via proxy

DNS Mechanism

DNS Protocol: Resolves domain names to IP addresses. Multiple domains can point to same IP.

HTTP Protocol: The Host header routes requests to different sites on the same port (80/443).

Default Domains

Pigsty predefines the following default domains:

By default, access Grafana, VictoriaMetrics, and Alertmanager under i.pigsty. Their paths are /ui/, /vmetrics/, and /alertmgr/, respectively. To use dedicated domains such as g.pigsty, p.pigsty, and a.pigsty, configure them explicitly in infra_portal and dns_records.

Resolution Methods

Local Static Resolution

Add entries to /etc/hosts on the client machine:

# Linux/macOS
sudo vim /etc/hosts

# Windows
notepad C:\Windows\System32\drivers\etc\hosts

Add content:

10.10.10.10 i.pigsty m.pigsty

Internal Dynamic Resolution

Pigsty includes dnsmasq as an internal DNS server. Configure managed nodes to use INFRA node as DNS server:

node_dns_servers: ['${admin_ip}']   # Use INFRA node as DNS server
node_dns_method: add                # Add to existing DNS server list

Configure domain records resolved by dnsmasq via dns_records:

dns_records:
  - "${admin_ip} i.pigsty"
  - "${admin_ip} m.pigsty sss.pigsty api.pigsty adm.pigsty cli.pigsty ddl.pigsty"

Public Domain Names

Purchase a domain and add DNS A record pointing to public IP:

1. Purchase domain from registrar (e.g., example.com)
2. Configure A record pointing to server public IP
3. Use real domain in infra_portal

Built-in DNS Service

Pigsty runs dnsmasq on INFRA nodes as a DNS server.

Related Parameters

Default DNS records:

dns_records:
  - "${admin_ip} i.pigsty"
  - "${admin_ip} m.pigsty sss.pigsty api.pigsty adm.pigsty cli.pigsty ddl.pigsty"

Dynamic DNS Registration

Pigsty automatically registers DNS records for PostgreSQL clusters and instances:

• Instance-level DNS: <pg_instance> points to instance IP (e.g., pg-meta-1)
• Cluster-level DNS: <pg_cluster> points to primary IP or VIP (e.g., pg-meta)

Cluster-level DNS target controlled by pg_dns_target:

Add suffix to cluster DNS via pg_dns_suffix.

Node DNS Configuration

Pigsty manages DNS configuration on managed nodes.

Static hosts Records

Configure static /etc/hosts records via node_etc_hosts:

node_etc_hosts:
  - "${admin_ip} i.pigsty"
  - "${admin_ip} sss.pigsty"      # Optional: Silo S3 endpoint domain
  - "10.10.10.20 db.example.com"

DNS Server Configuration

node_dns_method options:

Default DNS options:

node_dns_options:
  - options single-request-reopen timeout:1

HTTPS Certificates

Pigsty uses self-signed certificates by default. Options include:

• Ignore warnings, use HTTP
• Trust self-signed CA certificate (download at http://<ip>/ca.crt)
• Use real CA or get free public domain certs via Certbot

See CA and Certificates documentation for details.

Extended Domains

Pigsty reserves the following domains for various application services:

Using these domains requires configuring corresponding services in infra_portal.

Management Commands

./infra.yml -t dns            # Full DNS service configuration
./infra.yml -t dns_config     # Regenerate dnsmasq config
./infra.yml -t dns_record     # Update default DNS records
./infra.yml -t dns_launch     # Restart dnsmasq service

./node.yml -t node_hosts      # Configure node /etc/hosts
./node.yml -t node_resolv     # Configure node DNS resolver

./pgsql.yml -t pg_dns         # Register PostgreSQL DNS records
./pgsql.yml -t pg_dns_ins     # Register instance-level DNS only
./pgsql.yml -t pg_dns_cls     # Register cluster-level DNS only

7.4 - Module Management

Use this guide for daily INFRA administration. It covers installation, removal, scaling, and component maintenance.

Install INFRA Module

Use the infra.yml playbook to install the INFRA module on the infra group:

./infra.yml     # Install INFRA module on infra group

Uninstall INFRA Module

Use the infra-rm.yml playbook to uninstall the INFRA module from the infra group:

./infra-rm.yml -l infra # Full removal: deregister, stop, remove config/environment/data, and uninstall packages

This playbook has no deletion safeguard. Full execution removes infra_data, nginx_data, nginx_home (default: /www), and /var/lib/grafana. If you only need to stop services or deregister targets, use -t service or -t deregister. Read the complete removal scope and back up required data before running it.

Scale Out INFRA Module

Assign infra_seq to new nodes and add them to the infra group in the inventory:

all:
  children:
    infra:
      hosts:
        10.10.10.10: { infra_seq: 1 }  # Existing node
        10.10.10.11: { infra_seq: 2 }  # New node

Use the -l limit option to execute the playbook on the new node only:

./infra.yml -l 10.10.10.11    # Install INFRA module on new node

Manage Local Repository

Local repository management tasks:

./infra.yml -t repo              # Create repo from internet or offline packages
./infra.yml -t repo_upstream     # Add upstream repositories
./infra.yml -t repo_pkg          # Download packages and dependencies
./infra.yml -t repo_create       # Create local yum/apt repository

Complete subtask list:

./infra.yml -t repo_dir          # Create local repository directory
./infra.yml -t repo_check        # Check if local repo exists
./infra.yml -t repo_prepare      # Use existing repo directly
./infra.yml -t repo_build        # Build repo from upstream
./infra.yml -t repo_upstream     # Add upstream repositories
./infra.yml -t repo_remove       # Delete existing repo files
./infra.yml -t repo_add          # Add repo to system directory
./infra.yml -t repo_url_pkg      # Download packages from internet
./infra.yml -t repo_cache        # Create metadata cache
./infra.yml -t repo_boot_pkg     # Install bootstrap packages
./infra.yml -t repo_pkg          # Download packages and dependencies
./infra.yml -t repo_create       # Create local repository
./infra.yml -t repo_use          # Add new repo to system
./infra.yml -t repo_nginx        # Start Nginx file server

Manage Nginx

Nginx management tasks:

./infra.yml -t nginx                       # Reset Nginx component
./infra.yml -t nginx_index                 # Re-render homepage
./infra.yml -t nginx_config,nginx_reload   # Re-render config and reload

Request HTTPS certificate:

./infra.yml -t nginx_certbot,nginx_reload -e certbot_sign=true

Manage Infrastructure Components

Management commands for various infrastructure components:

./infra.yml -t infra           # Configure infrastructure
./infra.yml -t infra_user      # Set up OS user
./infra.yml -t infra_dir       # Create infrastructure directories
./infra.yml -t infra_env       # Configure environment variables
./infra.yml -t infra_pkg       # Install packages
./infra.yml -t infra_cert      # Issue certificates
./infra.yml -t dns             # Configure DNSMasq
./infra.yml -t nginx           # Configure Nginx
./infra.yml -t victoria        # Configure VictoriaMetrics/Logs/Traces
./infra.yml -t alertmanager    # Configure AlertManager
./infra.yml -t blackbox        # Configure Blackbox Exporter
./infra.yml -t grafana         # Configure Grafana
./infra.yml -t infra_register  # Register to VictoriaMetrics/Grafana

Common maintenance commands:

./infra.yml -t nginx_index                        # Re-render homepage
./infra.yml -t nginx_config,nginx_reload          # Reconfigure and reload
./infra.yml -t vmetrics_config,vmetrics_launch    # Regenerate VictoriaMetrics config and restart
./infra.yml -t vlogs_config,vlogs_launch          # Update VictoriaLogs config
./infra.yml -t grafana_provision                  # Reload Grafana dashboards and data-source definitions

Manage Grafana Passwords

Grafana uses two password parameters. grafana_admin_password defaults to the public value pigsty. grafana_view_password defaults to DBUser.Viewer.

Change the public defaults before production. After initialization, a change to grafana_admin_password in the inventory does not reset the live Grafana account password. Change it through Grafana or a supported administration interface. Keep the inventory consistent and regenerate the environment when needed:

./infra.yml -t env_var            # Re-render environment variables

grafana_view_password is the password used by the default PostgreSQL metadb data source as dbuser_view. If the database role password changes, update both the declared value and the Grafana data source. A change on only one side breaks the dashboard connection.

7.5 - CA and Certificates

Pigsty maintains a self-signed Certificate Authority (CA) on the admin node by default. It signs certificates for PostgreSQL, Patroni, etcd, Silo, Nginx, and other internal services. Public Nginx entries can use Certbot/Let’s Encrypt certificates configured through infra_portal.

Self-Signed CA

The ca stage of infra.yml creates or reuses the CA locally on the admin node running Ansible. It does not create the CA on a remote Infra node. The default layout is:

files/pki/
├── ca/                       # CA key, certificate, and OpenSSL CA state
│   ├── ca.key
│   └── ca.crt
├── csr/                      # certificate signing requests
├── misc/                     # generic certificates issued by cert.yml
├── etcd/
├── infra/
├── kafka/
├── minio/                    # MINIO module (Silo) certificates
├── mongo/
├── mysql/
├── nginx/
└── pgsql/

The core defaults match the v4.5.0 roles:

The role hard-codes the CA certificate lifetime to 36500d (about 100 years). These long-lived certificates serve a controlled internal trust domain. Public browsers do not trust them by default. Clients must explicitly trust ca.crt. Public endpoints should use a publicly trusted CA.

Initialize the local CA stage:

./infra.yml -t ca

Running ./infra.yml -t ca may create a missing key or certificate and therefore changes PKI state. Confirm the admin node, configuration, and existing CA backup first.

Use an External CA

To reuse an enterprise CA:

1. Set ca_create: false in pigsty.yml.
2. Place a matching files/pki/ca/ca.key and files/pki/ca/ca.crt pair on the admin node.
3. Set permissions and verify that the public-key digests match.