Module: INFRA

Configuration | Administration | Playbooks | Monitoring | Parameters

Overview

Each Pigsty deployment includes infrastructure components that serve managed nodes and database clusters:

In Pigsty, the PGSQL module uses some services on INFRA nodes, specifically:

• Database cluster/host node domains depend on DNSMASQ on INFRA nodes for resolution.
• Installing software on database nodes uses the local yum/apt repo hosted by Nginx on INFRA nodes.
• VictoriaMetrics on INFRA nodes collects and stores database cluster and node metrics. Access them through VMUI / PromQL.
• Vector collects database and node runtime logs and sends them to VictoriaLogs on INFRA nodes. Search these logs in Grafana.
• VMAlert evaluates alert rules based on metrics in VictoriaMetrics and forwards events to Alertmanager.
• Users initiate management of database nodes from Infra/Admin nodes using Ansible or other tools:
  • Execute cluster creation, scaling, instance/cluster recycling
  • Create business users, databases, modify services, HBA changes;
  • Execute log collection, garbage cleanup, backup, inspections, etc.
• Database nodes sync time from the NTP server on INFRA/ADMIN nodes by default
• If no dedicated cluster exists, the HA component Patroni uses etcd on INFRA nodes as the HA DCS.
• If no dedicated cluster exists, the backup component pgbackrest uses MinIO on INFRA nodes as an optional centralized backup repository.

Nginx

Nginx provides access to all Pigsty WebUI services. It uses port 80 on the admin node by default.

Nginx exposes infrastructure WebUIs, including Grafana, VictoriaMetrics (VMUI), AlertManager, and HAProxy traffic management pages. It also serves static files, including yum/apt repositories.

Nginx exposes built-in Web services through subpaths under i.pigsty by default. The infra_portal configuration also lets Nginx route requests to upstream components by domain name. If you use other domains or public domains, you can modify them here:

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 }

Pigsty strongly recommends using domain names to access Pigsty UI systems rather than direct IP+port access, for these reasons:

• Domains simplify HTTPS encryption and centralize access through Nginx. They also simplify request auditing and authentication integration.
• Some components only listen on 127.0.0.1 by default, so they can only be accessed through Nginx proxy.
• Domain names are easier to remember and provide additional configuration flexibility.

Without internet domains or local DNS, add static resolution records on the client. Use /etc/hosts on MacOS/Linux or C:\Windows\System32\drivers\etc\hosts on Windows.

Nginx configuration parameters are at: Configuration: INFRA - NGINX

Local Software Repository

Pigsty creates a local software repository during installation to accelerate subsequent software installation.

Nginx serves this repository. Its default directory is /www/pigsty, and its URL is http://i.pigsty/pigsty.

A Pigsty offline bundle is a compressed prebuilt RPM/APT repository directory. The current source uses SOW to create repositories. If /www/pigsty/repo_complete exists, Pigsty treats the local repository as complete and skips upstream downloads. This file contains SHA-256 checksums. It is not an empty marker.

The repo definition file is at /www/pigsty.repo, accessible by default via http://${admin_ip}/pigsty.repo

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

You can also use the file local repo directly without Nginx:

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

Local repository configuration parameters are at: Configuration: INFRA - REPO

Victoria Observability Suite

Pigsty v4 replaces Prometheus/Loki with the VictoriaMetrics family. These components provide integrated monitoring, logging, and tracing:

• VictoriaMetrics listens on port 8428 by default. Access VMUI at https://i.pigsty/vmetrics/. Its API is compatible with Prometheus. You can also configure a dedicated domain in infra_portal.
• VMAlert evaluates alert rules in /infra/rules/*.yml, listens on port 8880, and sends alert events to Alertmanager.
• VictoriaLogs listens on port 9428. Query logs through https://i.pigsty/vlogs/. All nodes run Vector by default to send structured system logs, PostgreSQL logs, and other logs to VictoriaLogs.
• VictoriaTraces listens on port 10428 for slow SQL / Trace collection. Grafana accesses it as a Jaeger datasource.
• Alertmanager listens on port 9059. Manage alert notifications at https://i.pigsty/alertmgr/. To use a dedicated domain, configure a.pigsty in infra_portal. Configure SMTP, Webhook, or another receiver to send notifications.
• Blackbox Exporter listens on port 9115 by default for Ping/TCP/HTTP probing, accessible via https://i.pigsty/blackbox/.

For more information, see: Configuration: INFRA - VICTORIA and Configuration: INFRA - PROMETHEUS.

Grafana

Grafana is the core of Pigsty’s WebUI. It listens on port 3000 by default. Access it through https://i.pigsty/ui/ or directly at IP:3000. To use a dedicated domain, configure g.pigsty in infra_portal.

Pigsty includes preconfigured VictoriaMetrics / Logs / Traces datasources: vmetrics-*, vlogs-*, and vtraces-*. It also includes many dashboards with URL-based navigation to help locate problems quickly.

Grafana also serves as a general low-code visualization platform. Pigsty installs plugins such as ECharts and victoriametrics-datasource by default. Use these plugins to build monitoring dashboards or inspection reports.

Grafana configuration parameters are at: Configuration: INFRA - GRAFANA.

Ansible

Pigsty installs Ansible on the meta node by default. Ansible uses declarative configuration and idempotent playbooks. These features reduce system maintenance complexity.

DNSMASQ

DNSMASQ provides DNS resolution services within the environment. Domain names from other modules are registered with the DNSMASQ service on INFRA nodes.

DNS records are placed by default in the /etc/dnsmasq.d/pigsty/ directory on all INFRA nodes.

DNSMASQ configuration parameters are at: Configuration: INFRA - DNS

Chronyd

NTP service synchronizes time across all nodes in the environment (optional)

NTP configuration parameters are at: Configuration: NODES - NTP

PostgreSQL

Pigsty’s metadata database (CMDB) usually runs on PostgreSQL, listening on port 5432 by default. It stores Pigsty metadata and backs several built-in applications.

For details, see the PGSQL module and Configuration: INFRA - META.

Configuration

To install INFRA on a node, add it to the infra inventory group. Assign an instance number with infra_seq.

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

Then use the infra.yml playbook to initialize the INFRA module on the nodes.

Administration

Here are some administration tasks related to the INFRA module:

Install/Uninstall Infra Module

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

infra-rm.yml has no deletion safeguard. Without tags, it removes infra_data, nginx_data, nginx_home (default: /www), and /var/lib/grafana. If you only need to stop services or deregister targets, use tags. See Playbooks for the complete removal scope.

Manage Local Software Repository

You can use the following playbook subtasks to manage the local yum repo on Infra nodes:

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

The most commonly used commands are:

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

Manage Infrastructure Components

You can use the following playbook subtasks to manage various infrastructure components on Infra nodes:

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

Other commonly used tasks include:

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

Playbooks

Pigsty provides three playbooks related to the INFRA module:

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

infra.yml

The INFRA module playbook infra.yml initializes pigsty infrastructure on INFRA nodes

Executing this playbook completes the following tasks

• Configure meta node directories and environment variables
• Download and build a local software repository to accelerate subsequent installation. (If using offline package, skip download phase)
• Add the current meta node as a regular node under Pigsty management
• Deploy infrastructure components including VictoriaMetrics/Logs/Traces, VMAlert, Grafana, Alertmanager, Blackbox Exporter, etc.

This playbook executes on INFRA nodes by default

• Pigsty uses the current node executing this playbook as Pigsty’s INFRA node and ADMIN node by default.
• During configuration, Pigsty marks the current node as the Infra/Admin node. It replaces 10.10.10.10 in templates with the current node’s primary IP address.
• Besides initiating management and hosting infrastructure, this node is no different from a regular managed node.
• In single-node installation, ETCD is also installed on this node to provide DCS service

Notes about this playbook

• This playbook is idempotent. Repeated execution wipes infrastructure components on meta nodes.
• To preserve historical monitoring data, first set vmetrics_clean, vlogs_clean, vtraces_clean to false.
• If /www/pigsty/repo_complete exists, the playbook skips internet downloads. Full execution takes about 5-8 minutes, depending on machine configuration.
• Downloading directly from upstream internet sources without offline package may take 10-20 minutes depending on your network conditions.

infra-rm.yml

The INFRA module playbook infra-rm.yml removes pigsty infrastructure from INFRA nodes

Common subtasks include:

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

Full execution has no deletion safeguard and removes infra_data, nginx_data, nginx_home (default: /www), and /var/lib/grafana. Back up any data you need before running it.

deploy.yml

The deploy.yml playbook deploys the NODE, INFRA, ETCD, MINIO, and PGSQL core chain on all nodes in one pass. Optional modules such as Docker, Redis, Kafka, native MySQL, JUICE, and VIBE require their own playbooks.

This playbook is described in more detail in Playbook: One-Time Installation.

Monitoring

Pigsty Home: Pigsty monitoring system homepage

INFRA Overview: Pigsty infrastructure self-monitoring overview

Nginx Instance: Nginx metrics and logs

Grafana Instance: Grafana metrics and logs

VictoriaMetrics Instance: VictoriaMetrics scraping, querying, and storage metrics

VMAlert Instance: Alert rule evaluation and queue status

Alertmanager Instance: Alert aggregation, notification pipelines, and Silences

VictoriaLogs Instance: Log ingestion rate, query load, and index hits

VictoriaTraces Instance: Trace/KV storage and Jaeger interface

Logs Instance: Node log search based on Vector + VictoriaLogs

CMDB Overview: CMDB visualization

ETCD Overview: etcd metrics and logs

Parameters

The INFRA module has the following 10 parameter groups.

• META: Pigsty metadata
• CA: Self-signed PKI/CA infrastructure
• INFRA_ID: Infrastructure portal, Nginx domains
• REPO: Local software repository
• INFRA_PACKAGE: Infrastructure software packages
• NGINX: Nginx web server
• DNS: DNSMASQ domain server
• VICTORIA: VictoriaMetrics / Logs / Traces suite
• PROMETHEUS: Alertmanager and Blackbox Exporter
• GRAFANA: Grafana observability suite