Module: INFRA

Configuration | Administration | Playbooks | Monitoring | Parameters

Overview

Every Pigsty deployment includes a set of infrastructure components that provide services for 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.
• Database cluster/node monitoring metrics are scraped and stored by VictoriaMetrics on INFRA nodes, accessible via VMUI / PromQL.
• Database and node runtime logs are collected by Vector and pushed to VictoriaLogs on INFRA, searchable 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 is the access entry point for all WebUI services in Pigsty, using port 80 on the admin node by default.

Many infrastructure components with WebUI are exposed through Nginx, such as Grafana, VictoriaMetrics (VMUI), AlertManager, and HAProxy traffic management pages. Additionally, static file resources like yum/apt repos are served through Nginx.

Nginx exposes built-in Web services through subpaths under i.pigsty by default. It can also route access requests to corresponding upstream components based on domain names according to infra_portal configuration. 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:

• Using domains makes it easy to enable HTTPS traffic encryption, consolidate access to Nginx, audit all requests, and conveniently integrate authentication mechanisms.
• 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.

If you don’t have available internet domains or local DNS resolution, you can add local static resolution records in /etc/hosts (MacOS/Linux) or C:\Windows\System32\drivers\etc\hosts (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.

This repository is served by Nginx, located by default at /www/pigsty, accessible via 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 merely 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 uses the VictoriaMetrics family to replace Prometheus/Loki, providing unified monitoring, logging, and tracing capabilities:

• VictoriaMetrics listens on port 8428 by default, accessible via https://i.pigsty/vmetrics/ for VMUI, compatible with Prometheus API. 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, supports the https://i.pigsty/vlogs/ query interface. All nodes run Vector by default, pushing structured system logs, PostgreSQL logs, etc. to VictoriaLogs.
• VictoriaTraces listens on port 10428 for slow SQL / Trace collection, Grafana accesses it as a Jaeger datasource.
• Alertmanager listens on port 9059, accessible via https://i.pigsty/alertmgr/ for managing alert notifications. If a.pigsty is configured in infra_portal, it can also be accessed through a dedicated domain. After configuring SMTP, Webhook, etc., it can push messages.
• 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, listening on port 3000 by default. It can be accessed through https://i.pigsty/ui/ or directly via IP:3000; if g.pigsty is configured in infra_portal, it can also be accessed through a dedicated domain.

Pigsty comes with preconfigured datasources for VictoriaMetrics / Logs / Traces (vmetrics-*, vlogs-*, vtraces-*), and numerous dashboards with URL-based navigation for quick problem location.

Grafana can also be used as a general low-code visualization platform, so Pigsty installs plugins like ECharts and victoriametrics-datasource by default for building monitoring dashboards or inspection reports.

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

Ansible

Pigsty installs Ansible on the meta node by default. Ansible is a popular operations tool with declarative configuration style and idempotent playbook design that greatly reduces 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 the INFRA module on a node, first add it to the infra group in the config inventory and assign an instance number 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 Infra/Admin node and replaces the placeholder IP 10.10.10.10 in config 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 is an idempotent playbook; repeated execution will wipe infrastructure components on meta nodes.
• To preserve historical monitoring data, first set vmetrics_clean, vlogs_clean, vtraces_clean to false.
• When offline repo /www/pigsty/repo_complete exists, this playbook skips downloading software from internet. 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 INFRA module playbook deploy.yml 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