This is the multi-page printable view of this section. .

Return to the regular view of this page.

Infra

The portal and observability stack

1: Architecture
2: Configure
3: Parameter
4: Administration
5: Playbook
6: Monitor
7: FAQ

Architecture

    Architecture, core concepts, identity management

Configuration

    Configure infra module, and use multiple infra nodes.

Parameters

    Customize infra components with 57+ parameters

Administration

    Manage local repo, nginx portal, domain, certs, and more

Playbooks

    Ansible playbooks that can be used in this module

Monitoring

    Dashboards, metrics, record & alerting rules.

FAQ

    Frequently Asked Questions about infra module

1 - Architecture

Architecture and entities in the infra module

A standard Pigsty deployment comes with an INFRA module that provides the following services:

These are essential for a production-grade PostgreSQL service, and will be installed by default.

Component	Port	Domain	Description
`nginx`	`80`	`h.pigsty`	Web Service Portal (YUM/APT Repo)
`alertmanager`	`9059`	`a.pigsty`	Alert Aggregation and delivery
`prometheus`	`9058`	`p.pigsty`	Monitoring Time Series Database
`grafana`	`3000`	`g.pigsty`	Visualization Platform
`loki`	`3100`	-	Logging Collection Server
`pushgateway`	`9091`	-	Collect One-Time Job Metrics
`blackbox_exporter`	`9115`	-	ICMP, TCP, HTTP Probing
`dnsmasq`	`53`	-	DNS Server, optional
`chronyd`	`123`	-	NTP Time Server, optional

HA PG can be deployed without INFRA

If you don’t want these, the Minimal Install mode deploy HA Postgres without the Infra module.

Nginx: Acts as a web server for local repo and a reverse proxy for other web UI services
Grafana : Visualization platform for metrics, dashboards, and data analytics
Loki: Centralized log aggregation and querying via Grafana
Prometheus: Time-series monitoring database for metrics collection, storage, and alert evaluation
AlertManager: Alert aggregation, notification dispatch, and silencing
PushGateway: Collects metrics from one-off and batch jobs
BlackboxExporter: Probes node IP and VIP reachability
DNSMASQ: DNS resolution for Pigsty’s internal domains
Chronyd: NTP time synchronization to keep all nodes in sync

The INFRA module isn’t mandatory for HA PostgreSQL - for instance, it’s omitted in Slim Install mode.

However, since INFRA provides essential supporting services for production-grade HA PostgreSQL clusters, it’s strongly recommended for most deployments.

If you already have your own infrastructure (Nginx, local repos, monitoring, DNS, NTP), you can disable INFRA and configure Pigsty to use your existing stack instead.

Nginx

Nginx is the gateway for all WebUI services in Pigsty, serving on HTTP (80) / HTTPS (443) by default.

It exposes web UIs like Grafana, Prometheus, AlertManager, and HAProxy console, while also serving static resources like local yum/apt repos.

Nginx configuration follows infra_portal definitions, for example:

infra_portal:
  home         : { domain: h.pigsty }
  grafana      : { domain: g.pigsty ,endpoint: "${admin_ip}:3000" ,websocket: true }
  prometheus   : { domain: p.pigsty ,endpoint: "${admin_ip}:9058" }
  alertmanager : { domain: a.pigsty ,endpoint: "${admin_ip}:9059" }
  blackbox     : { endpoint: "${admin_ip}:9115" }
  loki         : { endpoint: "${admin_ip}:3100" }
  #minio        : { domain: sss.pigsty  ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }

These endpoint definitions are referenced by other services - logs go to loki endpoint, Grafana datasources register to grafana endpoint, alerts route to alertmanager endpoint.

Pigsty allows rich Nginx customization as a local file server or reverse proxy, with self-signed or real HTTPS certs.

For more details, check these tutorials:

Local Repo

During installation, Pigsty creates a local software repository on the INFRA node to speed up subsequent software installations.

Located at /www/pigsty and served by Nginx, it’s accessible via http://h.pigsty/pigsty.

Pigsty’s offline package is a tarball of a pre-built repo directory. If /www/pigsty exists with a /www/pigsty/repo_complete marker, Pigsty skips downloading from upstream - perfect for air-gapped environments!

Repo definition lives in /www/pigsty.repo, fetchable via http://${admin_ip}/pigsty.repo:

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

You can also use the file repository directly without Nginx:

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

Local repo configs are in: Config: INFRA - REPO

Prometheus

Prometheus, our TSDB for monitoring, listens on port 9058 (access via IP:9058 or http://p.pigsty).

Key features:

Service discovery via local static files with identity info
Metric scraping, pre-processing, and TSDB storage
Alert rule evaluation and forwarding to AlertManager

AlertManager

AlertManager handles alerts on port 9059 (IP:9059 or http://a.pigsty). While it receives Prometheus alerts, you’ll need extra config (e.g., SMTP) for notifications.

Configs for Prometheus, AlertManager, PushGateway, and BlackboxExporter are in: Config: INFRA - PROMETHEUS

Grafana

Grafana, our visualization powerhouse, runs on port 3000 (IP:3000 or http://g.pigsty).

Pigsty’s monitoring is dashboard-based with URL-driven navigation. Drill down or up quickly to pinpoint issues.

Fun fact: We’ve supercharged Grafana with extra viz plugins like ECharts - it’s not just monitoring, it’s a low-code data app platform!

Loki handles logs on port 3100, with Promtail shipping logs from nodes to the mothership.

Configs live in: Config: INFRA - GRAFANA and Config: INFRA - Loki

Ansible

Ansible is already installed on the Admin Node during bootstrap. So the ansible on infra nodes are not actually used. But it gives you a viable backup option in case your admin node is compromised.

DNSMASQ

DNSMASQ handles DNS resolution, with other modules registering their domains to INFRA’s DNSMASQ service.

DNS records live in /etc/hosts.d/ on all INFRA nodes.

Configs: Config: INFRA - DNS

Pigsty sets it up just for your convenience, and Pigsty actually does NOT use it internally (static DNS records in /etc/hosts are used instead).

Chronyd

Chronyd helps keep all nodes in sync!

NTP configs: Config: NODES - NTP

This is purely optional, if you already have your own NTP servers configured, just leave it alone.

2 - Configure

configure infra nodes, nginx, repo, dns, ntp, monitor system

The INFRA module primarily provides monitoring infrastructure and is optional for PostgreSQL service.

Unless you have manually configured dependencies on DNS/NTP services from INFRA nodes elsewhere, failures in the INFRA module typically won’t affect the normal operation of PostgreSQL database clusters.

In most cases, a single INFRA node is sufficient for typical scenarios. For production environments with higher requirements, we recommend using 2-3 INFRA nodes for high availability.

To improve resource utilization, PostgreSQL high availability typically relies on the ETCD module, which can share nodes with the INFRA module.

Using more than 3 INFRA nodes provides limited benefits, but you can use more ETCD nodes (e.g., 5) to enhance the availability and reliability of DCS services.

Examples

To install the INFRA module on nodes, first add node IPs to the infra group in the inventory and assign them an Infra instance number infra_seq.

By default, a single INFRA node configuration meets most requirements. All configuration templates include a default infra group definition:

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

The 10.10.10.10 IP placeholder in the infra group will be replaced with the current node’s primary IP address during configuration, meaning the INFRA module will be installed on the current node.

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

More Nodes

To configure two INFRA nodes, add new IPs to infra.hosts:

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

To configure three INFRA nodes with custom cluster/node parameters:

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
        prometheus_clean: false
        loki_clean: false

High Availability

Most components in the Infra module are “stateless/shared-state”. For these components, high availability primarily requires addressing load balancing.

Infra component load balancing can be achieved through two methods: Keepalived L2 VIP or HAProxy Layer 4 Load Balancing.

If your network environment supports Layer 2 connectivity, you can use Keepalived L2 VIP for high availability:

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: h.pigsty }
      grafana      : { domain: g.pigsty ,endpoint: "10.10.10.8:3000" , websocket: true }
      prometheus   : { domain: p.pigsty ,endpoint: "10.10.10.8:9058" }
      alertmanager : { domain: a.pigsty ,endpoint: "10.10.10.8:9059" }
      blackbox     : { endpoint: "10.10.10.8:9115" }
      loki         : { endpoint: "10.10.10.8:3100" }

In addition to configuring VIP-related parameters like vip_address, you need to modify endpoints for Infra services in infra_portal.

3 - Parameter

customize with options

Parameters for Pigsty infrastructure components: local YUM repository, Nginx, DNSMasq, Prometheus, Grafana, Loki, AlertManager, PushGateway, Blackbox Exporter, etc.

There are 9 sections in total, and 57 parameters in this module.

META: infra meta data
CA: self-signed CA
INFRA_ID: Portals and identity
REPO: local YUM/APT repository
INFRA_PACKAGE: packages to be installed
NGINX: Nginx web server
DNS: DNSMasq nameserver
PROMETHEUS: Prometheus, AlertManager, PushGateway & Blackbox Exporter
GRAFANA: Grafana, the visualization platform
LOKI: Loki, the logging server

Parameters

Name	Section	Type	Level	Comment
`version`	`META`	`string`	G	pigsty version string
`admin_ip`	`META`	`ip`	G	admin node ip address
`region`	`META`	`enum`	G	upstream mirror region: default, china, europe
`proxy_env`	`META`	`dict`	G	global proxy env when downloading packages
`ca_create`	`CA`	`bool`	G	create the CA when missing; true by default
`ca_cn`	`CA`	`string`	G	CA common name, fixed as pigsty-ca
`cert_validity`	`CA`	`interval`	G	cert validity, 20 years by default
`infra_seq`	`INFRA_ID`	`int`	I	infra node identity, REQUIRED
`infra_portal`	`INFRA_ID`	`dict`	G	infra services exposed via portal
`repo_enabled`	`REPO`	`bool`	G/I	create a yum repo on this infra node?
`repo_home`	`REPO`	`path`	G	repo home dir, `/www` by default
`repo_name`	`REPO`	`string`	G	repo name, pigsty by default
`repo_endpoint`	`REPO`	`url`	G	access point to this repo by domain or ip:port
`repo_remove`	`REPO`	`bool`	G/A	remove existing upstream repo
`repo_modules`	`REPO`	`string`	G/A	which repo modules are installed in repo_upstream
`repo_upstream`	`REPO`	`upstream[]`	G	where to download upstream packages
`repo_packages`	`REPO`	`string[]`	G	which packages to be included
`repo_extra_packages`	`REPO`	`string[]`	G/C/I	extra packages to be included
`repo_url_packages`	`REPO`	`string[]`	G	extra packages from url
`infra_packages`	`INFRA_PACKAGE`	`string[]`	G	packages to be installed on infra nodes
`infra_packages_pip`	`INFRA_PACKAGE`	`string`	G	pip installed packages for infra nodes
`nginx_enabled`	`NGINX`	`bool`	G/I	enable nginx on this infra node?
`nginx_exporter_enabled`	`NGINX`	`bool`	G/I	enable nginx_exporter on this infra node?
`nginx_sslmode`	`NGINX`	`enum`	G	nginx ssl mode? disable, enable, enforce
`nginx_cert_validity`	`NGINX`	`duration`	G	nginx self-signed cert validity, 397d by default
`nginx_home`	`NGINX`	`path`	G	nginx content dir, `/www` by default
`nginx_port`	`NGINX`	`port`	G	nginx listen port, 80 by default
`nginx_ssl_port`	`NGINX`	`port`	G	nginx ssl listen port, 443 by default
`nginx_navbar`	`NGINX`	`index[]`	G	nginx index page navigation links
`certbot_sign`	`NGINX`	`bool`	G/A	sign nginx cert with certbot during setup?
`certbot_email`	`NGINX`	`string`	G/A	certbot email address, used for free ssl
`certbot_options`	`NGINX`	`string`	G/A	certbot extra options
`dns_enabled`	`DNS`	`bool`	G/I	setup dnsmasq on this infra node?
`dns_port`	`DNS`	`port`	G	dns server listen port, 53 by default
`dns_records`	`DNS`	`string[]`	G	dynamic dns records resolved by dnsmasq
`prometheus_enabled`	`PROMETHEUS`	`bool`	G/I	enable prometheus on this infra node?
`prometheus_port`	`PROMETHEUS`	`port`	G	prometheus listen port, `9058` by default
`prometheus_clean`	`PROMETHEUS`	`bool`	G/A	clean prometheus data during init?
`prometheus_data`	`PROMETHEUS`	`path`	G	prometheus data dir, `/data/prometheus` by default
`prometheus_sd_dir`	`PROMETHEUS`	`path`	G	prometheus file service discovery directory
`prometheus_sd_interval`	`PROMETHEUS`	`interval`	G	prometheus target refresh interval, 5s by default
`prometheus_scrape_interval`	`PROMETHEUS`	`interval`	G	prometheus scrape & eval interval, 10s by default
`prometheus_scrape_timeout`	`PROMETHEUS`	`interval`	G	prometheus global scrape timeout, 8s by default
`prometheus_options`	`PROMETHEUS`	`arg`	G	prometheus extra server options
`pushgateway_enabled`	`PROMETHEUS`	`bool`	G/I	setup pushgateway on this infra node?
`pushgateway_options`	`PROMETHEUS`	`arg`	G	pushgateway extra server options
`blackbox_enabled`	`PROMETHEUS`	`bool`	G/I	setup blackbox_exporter on this infra node?
`blackbox_options`	`PROMETHEUS`	`arg`	G	blackbox_exporter extra server options
`alertmanager_enabled`	`PROMETHEUS`	`bool`	G/I	setup alertmanager on this infra node?
`alertmanager_port`	`PROMETHEUS`	`port`	G	alertmanager listen port, `9059` by default
`alertmanager_options`	`PROMETHEUS`	`arg`	G	alertmanager extra server options
`exporter_metrics_path`	`PROMETHEUS`	`path`	G	exporter metric path, `/metrics` by default
`exporter_install`	`PROMETHEUS`	`enum`	G	how to install exporter? none, yum, binary
`exporter_repo_url`	`PROMETHEUS`	`url`	G	exporter repo file url if install exporter via yum
`grafana_enabled`	`GRAFANA`	`bool`	G/I	enable grafana on this infra node?
`grafana_clean`	`GRAFANA`	`bool`	G/A	clean grafana data during init?
`grafana_admin_username`	`GRAFANA`	`username`	G	grafana admin username, `admin` by default
`grafana_admin_password`	`GRAFANA`	`password`	G	grafana admin password, `pigsty` by default
`loki_enabled`	`LOKI`	`bool`	G/I	enable loki on this infra node?
`loki_clean`	`LOKI`	`bool`	G/A	whether remove existing loki data?
`loki_data`	`LOKI`	`path`	G	loki data dir, `/data/loki` by default
`loki_retention`	`LOKI`	`interval`	G	loki log retention period, 15d by default

`META`

This section contains metadata for current Pigsty deployments, such as version string, admin node IP address, repository mirror region and HTTP(S) proxy when downloading packages.

version: v3.7.0                   # Pigsty version string
admin_ip: 10.10.10.10             # admin node ip address
region: default                   # upstream mirror region: default,china,europe
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:[email protected]
  # https_proxy: # set your proxy here: e.g http://user:[email protected]
  # all_proxy:   # set your proxy here: e.g http://user:[email protected]

`version`

type: string, level: G

pigsty version string

default value:v3.7.0

It will be used for pigsty introspection & content rendering.

`admin_ip`

type: ip, level: G

admin node ip address

default value:10.10.10.10

Node with this ip address will be treated as admin node, usually point to the first node that install Pigsty.

The default value 10.10.10.10 is a placeholder that will be replaced during configure

This parameter is referenced by many other parameters, such as:

The exact string ${admin_ip} will be replaced with the actual admin_ip for above parameters.

`region`

type: enum, level: G

upstream mirror region: default,china,europe

default value: default

If a region other than default is set, and there’s a corresponding entry in repo_upstream.[repo].baseurl, it will be used instead of default.

For example, if china is used, pigsty will use China mirrors designated in repo_upstream if applicable.

`proxy_env`

type: dict, level: G

global proxy env when downloading packages

default value:

proxy_env: # global proxy env when downloading packages
  http_proxy: 'http://username:[email protected]'
  https_proxy: 'http://username:[email protected]'
  all_proxy: 'http://username:[email protected]'
  no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.aliyuncs.com,mirrors.tuna.tsinghua.edu.cn,mirrors.zju.edu.cn"

It’s quite important to use an HTTP proxy in restricted production environments, or when your Internet access is blocked (e.g., Mainland China).

Please note that if the Docker module is used, the proxy server configuration will also be written to the Docker Daemon configuration file.

Please note that if the -x parameter is specified during ./configure, the proxy configuration information in the current environment will be automatically filled into the generated pigsty.yaml file.

`CA`

Self-Signed CA used by Pigsty. It is required to support advanced security features.

ca_create: true                   # create CA if missing; otherwise require supplied key/cert
ca_cn: pigsty-ca                  # CA common name, fixed as pigsty-ca
cert_validity: 7300d              # cert validity, 20 years by default

`ca_create`

type: bool, level: G

Default value: true. The ca role creates files/pki/ca/ca.key and files/pki/ca/ca.crt only when they are missing. Existing CA material is always reused. Set this to false when supplying an existing key and certificate; the role aborts if the key is then missing.

`ca_cn`

type: string, level: G

CA common name, not recommended to change it.

default value: pigsty-ca

You can check that with openssl x509 -text -in /etc/pki/ca.crt.

`cert_validity`

type: interval, level: G

certificate validity, 20 years by default, which is sufficient for most scenarios

default value: 7300d

`INFRA_ID`

Infrastructure identity and portal definition.

#infra_seq: 1                     # infra node identity, explicitly required
infra_portal:                     # infra services exposed via portal
  home         : { domain: h.pigsty }
  grafana      : { domain: g.pigsty ,endpoint: "${admin_ip}:3000" ,websocket: true }
  prometheus   : { domain: p.pigsty ,endpoint: "${admin_ip}:9058" }
  alertmanager : { domain: a.pigsty ,endpoint: "${admin_ip}:9059" }
  blackbox     : { endpoint: "${admin_ip}:9115" }
  loki         : { endpoint: "${admin_ip}:3100" }

`infra_seq`

type: int, level: I

infra node identity, REQUIRED, no default value, you have to assign it explicitly.

`infra_portal`

type: dict, level: G

infra services exposed via portal.

default value will expose home, grafana, prometheus, alertmanager via nginx with corresponding domain names.

infra_portal:                     # infra services exposed via portal
  home         : { domain: h.pigsty }
  grafana      : { domain: g.pigsty ,endpoint: "${admin_ip}:3000" ,websocket: true }
  prometheus   : { domain: p.pigsty ,endpoint: "${admin_ip}:9058" }
  alertmanager : { domain: a.pigsty ,endpoint: "${admin_ip}:9059" }
  blackbox     : { endpoint: "${admin_ip}:9115" }
  loki         : { endpoint: "${admin_ip}:3100" }

Each record consists of a Key and a Value dictionary, where name is the key, representing the component name, and the value is an object that can configure the following parameters:

Each record consists of a Key and a Value dictionary, where name is the key, representing the component name, and the value is an object that can configure the following parameters:

name: REQUIRED, specify the name of the Nginx server
- Default records: home, grafana, prometheus, alertmanager, blackbox, loki are fixed names, please do not modify them.
- Used as part of the Nginx configuration file name, corresponding to the configuration file: /etc/nginx/conf.d/<name>.conf
- Nginx servers without the domain field will not generate configuration files, but will be used as references.
domain: OPTIONAL, when the service needs to be exposed to the outside world via Nginx, it is a REQUIRED field, specifying the domain name used
- In Pigsty self-signed Nginx HTTPS certificate, the domain name 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: Usually used as an alternative to path, specifies the upstream server address. Setting endpoint indicates this is a reverse proxy server
- In the configuration, ${admin_ip} can be used as a placeholder, and will be dynamically replaced with admin_ip during deployment
- The default reverse proxy server uses endpoint.conf as the configuration template
- The reverse proxy server can also configure the websocket and schema parameters
path: Usually used as an alternative to endpoint, specifies the local file server path. Setting path means this is a local web server
- The local web server uses path.conf as the configuration template
- The local web server can also configure the index parameter, whether to enable the file index page
certbot: Certbot certificate name, if configured, will use Certbot to apply for a certificate
- If multiple servers specify the same certbot, Pigsty will merge the certificate application, and the final certificate name will be the name of this certbot
cert: Cert file path, if configured, will override the default certificate path
key: Cert key file path, if configured, will override the default certificate key path
websocket: Whether to enable WebSocket support
- Only reverse proxy servers can configure this parameter, if enabled it will allow upstream to use 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 page
- Only local web servers can configure this parameter, if enabled it will enable the autoindex configuration to automatically generate index pages for directories
log: Nginx log file path
- If specified, access logs will be written to this file, otherwise the default log file will be used according to the server type
- 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 configuration file path
- Explicitly specifies the configuration template file to use, located in roles/infra/templates/nginx or templates/nginx directory
- If this parameter is not specified, the default configuration template will be used, located in roles/infra/templates/nginx or templates/nginx directory
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 by nginx_sslmode: enforce
- This configuration does not affect the default home server, which will always listen on ports 80 and 443 simultaneously to ensure compatibility.

`REPO`

This section is about the local software repository. Pigsty will create a local software repository (APT/YUM) when initializing an infra node.

During the initialization process, Pigsty will download all packages and their dependencies (specified by repo_packages) from the Internet upstream repository (specified by repo_upstream) to {{ nginx_home }} / {{ repo_name }} (default is /www/pigsty), and the total size of all dependent software is approximately 1GB.

When creating a local repository, Pigsty will skip the software download phase if the directory already exists and there is a marker file named repo_complete in the directory.

If the download speed of some packages is too slow, you can set the download proxy to complete the initial download by using the proxy_env configuration entry or directly download the pre-packaged offline package, which is essentially a local software source built on the same operating system.

repo_enabled: true                # create a yum repo on this infra node?
repo_home: /www                   # repo home dir, `/www` by default
repo_name: pigsty                 # repo name, pigsty by default
repo_endpoint: http://${admin_ip}:80 # access point to this repo by domain or ip:port
repo_remove: true                 # remove existing upstream repo
repo_modules: infra,node,pgsql    # install upstream repo during repo bootstrap
#repo_upstream: []                # where to download
#repo_packages: []                # which packages to download
#repo_extra_packages: []          # extra packages to download
repo_url_packages: []             # extra packages from url

`repo_enabled`

type: bool, level: G/I

create a YUM repository on this infra node? default value: true

If you have multiple infra nodes, you can disable the YUM repository on other standby nodes to reduce Internet traffic.

`repo_home`

type: path, level: G

repository home directory, /www by default

`repo_name`

type: string, level: G

repository name, pigsty by default, it is not recommended to change this value

`repo_endpoint`

type: url, level: G

access point to this repository by domain or IP:port, default value: http://${admin_ip}:80

If you have changed the nginx_port or nginx_ssl_port, or use a different infra node from admin node, please adjust this parameter accordingly.

The ${admin_ip} will be replaced with actual admin_ip during runtime.

`repo_remove`

type: bool, level: G/A

remove existing upstream repository, default value: true

If you want to keep existing upstream repository, set this value to false.

`repo_modules`

type: string, level: G/A

which repository modules are installed in repo_upstream, default value: infra,node,pgsql

This is a comma separated value string, it is used to filter entries in repo_upstream with corresponding module field.

For Ubuntu / Debian users, you can add redis to the list: infra,node,pgsql,redis

`repo_upstream`

type: upstream[], level: G

This parameter defines the upstream software repository for Pigsty. It DOES NOT have default values; you can specify it explicitly, or leave it empty if you want to use the default values.

When leaving it empty, Pigsty will use the default values from the repo_upstream_default defined in roles/node_id/vars according to your OS.

For EL (8, 9, 10) system, the default values are:

- { name: pigsty-local   ,description: 'Pigsty Local'       ,module: local   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://${admin_ip}/pigsty'  }} # used by intranet nodes
- { name: pigsty-infra   ,description: 'Pigsty INFRA'       ,module: infra   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.pigsty.io/yum/infra/$basearch' ,china: 'https://repo.pigsty.cc/yum/infra/$basearch' }}
- { name: pigsty-pgsql   ,description: 'Pigsty PGSQL'       ,module: pgsql   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.pigsty.io/yum/pgsql/el$releasever.$basearch' ,china: 'https://repo.pigsty.cc/yum/pgsql/el$releasever.$basearch' }}
- { name: nginx          ,description: 'Nginx Repo'         ,module: infra   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://nginx.org/packages/rhel/$releasever/$basearch/' }}
- { name: docker-ce      ,description: 'Docker CE'          ,module: infra   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.docker.com/linux/centos/$releasever/$basearch/stable'    ,china: 'https://mirrors.aliyun.com/docker-ce/linux/centos/$releasever/$basearch/stable' ,europe: 'https://mirrors.xtom.de/docker-ce/linux/centos/$releasever/$basearch/stable' }}
- { name: baseos         ,description: 'EL 8+ BaseOS'       ,module: node    ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/BaseOS/$basearch/os/'     ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/BaseOS/$basearch/os/'         ,europe: 'https://mirrors.xtom.de/rocky/$releasever/BaseOS/$basearch/os/'     }}
- { name: appstream      ,description: 'EL 8+ AppStream'    ,module: node    ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/AppStream/$basearch/os/'  ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/AppStream/$basearch/os/'      ,europe: 'https://mirrors.xtom.de/rocky/$releasever/AppStream/$basearch/os/'  }}
- { name: extras         ,description: 'EL 8+ Extras'       ,module: node    ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/extras/$basearch/os/'     ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/extras/$basearch/os/'         ,europe: 'https://mirrors.xtom.de/rocky/$releasever/extras/$basearch/os/'     }}
- { name: powertools     ,description: 'EL 8 PowerTools'    ,module: node    ,releases: [8     ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/PowerTools/$basearch/os/' ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/PowerTools/$basearch/os/'     ,europe: 'https://mirrors.xtom.de/rocky/$releasever/PowerTools/$basearch/os/' }}
- { name: crb            ,description: 'EL 9 CRB'           ,module: node    ,releases: [  9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/CRB/$basearch/os/'        ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/CRB/$basearch/os/'            ,europe: 'https://mirrors.xtom.de/rocky/$releasever/CRB/$basearch/os/'        }}
- { name: epel           ,description: 'EL 8+ EPEL'         ,module: node    ,releases: [8,9   ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://mirrors.edge.kernel.org/fedora-epel/$releasever/Everything/$basearch/' ,china: 'https://mirrors.aliyun.com/epel/$releasever/Everything/$basearch/'         ,europe: 'https://mirrors.xtom.de/epel/$releasever/Everything/$basearch/'     }}
- { name: epel           ,description: 'EL 10 EPEL'         ,module: node    ,releases: [    10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://mirrors.edge.kernel.org/fedora-epel/$releasever.0/Everything/$basearch/' ,china: 'https://mirrors.aliyun.com/epel/$releasever.0/Everything/$basearch/'     ,europe: 'https://mirrors.xtom.de/epel/$releasever.0/Everything/$basearch/'   }}
- { name: pgdg-common    ,description: 'PostgreSQL Common'  ,module: pgsql   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/common/redhat/rhel-$releasever-$basearch' , europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg-el8fix    ,description: 'PostgreSQL EL8FIX'  ,module: pgsql   ,releases: [8     ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-centos8-sysupdates/redhat/rhel-8-$basearch/'  ,china: 'https://repo.pigsty.cc/yum/pgdg/common/pgdg-centos8-sysupdates/redhat/rhel-8-$basearch/'  ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-centos8-sysupdates/redhat/rhel-8-$basearch/'  }}
- { name: pgdg-el9fix    ,description: 'PostgreSQL EL9FIX'  ,module: pgsql   ,releases: [  9   ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-rocky9-sysupdates/redhat/rhel-9-$basearch/'   ,china: 'https://repo.pigsty.cc/yum/pgdg/common/pgdg-rocky9-sysupdates/redhat/rhel-9-$basearch/'   ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-rocky9-sysupdates/redhat/rhel-9-$basearch/'   }}
- { name: pgdg-el10fix   ,description: 'PostgreSQL EL10FIX' ,module: pgsql   ,releases: [    10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-rocky10-sysupdates/redhat/rhel-10-$basearch/' ,china: 'https://repo.pigsty.cc/yum/pgdg/common/pgdg-rocky10-sysupdates/redhat/rhel-10-$basearch/' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-rocky10-sysupdates/redhat/rhel-10-$basearch/' }}
- { name: pgdg13         ,description: 'PostgreSQL 13'      ,module: pgsql   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/13/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/13/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/13/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg14         ,description: 'PostgreSQL 14'      ,module: pgsql   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/14/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/14/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/14/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg15         ,description: 'PostgreSQL 15'      ,module: pgsql   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/15/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/15/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/15/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg16         ,description: 'PostgreSQL 16'      ,module: pgsql   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/16/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/16/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/16/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg17         ,description: 'PostgreSQL 17'      ,module: pgsql   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/17/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/17/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/17/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg18         ,description: 'PostgreSQL 18'      ,module: pgsql   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/18/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/18/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/18/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg-beta      ,description: 'PostgreSQL Testing' ,module: beta    ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/testing/19/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/testing/19/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/testing/19/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg-extras    ,description: 'PostgreSQL Extra'   ,module: extra   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-rhel$releasever-extras/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/common/pgdg-rhel$releasever-extras/redhat/rhel-$releasever-$basearch' , europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-rhel$releasever-extras/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg13-nonfree ,description: 'PostgreSQL 13+'     ,module: extra   ,releases: [8,9,10] ,arch: [x86_64         ] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/non-free/13/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/non-free/13/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/13/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg14-nonfree ,description: 'PostgreSQL 14+'     ,module: extra   ,releases: [8,9,10] ,arch: [x86_64         ] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/non-free/14/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/non-free/14/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/14/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg15-nonfree ,description: 'PostgreSQL 15+'     ,module: extra   ,releases: [8,9,10] ,arch: [x86_64         ] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/non-free/15/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/non-free/15/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/15/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg16-nonfree ,description: 'PostgreSQL 16+'     ,module: extra   ,releases: [8,9,10] ,arch: [x86_64         ] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/non-free/16/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/non-free/16/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/16/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg17-nonfree ,description: 'PostgreSQL 17+'     ,module: extra   ,releases: [8,9,10] ,arch: [x86_64         ] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/non-free/17/redhat/rhel-$releasever-$basearch' ,china: 'https://repo.pigsty.cc/yum/pgdg/non-free/17/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/17/redhat/rhel-$releasever-$basearch' }}
- { name: timescaledb    ,description: 'TimescaleDB'        ,module: extra   ,releases: [8,9   ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packagecloud.io/timescale/timescaledb/el/$releasever/$basearch'  }}
- { name: percona        ,description: 'Percona TDE'        ,module: percona ,releases: [8,9   ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.pigsty.io/yum/percona/el$releasever.$basearch' ,china: 'https://repo.pigsty.cc/yum/percona/el$releasever.$basearch' ,origin: 'http://repo.percona.com/ppg-17.5/yum/release/$releasever/RPMS/$basearch'  }}
- { name: wiltondb       ,description: 'WiltonDB'           ,module: mssql   ,releases: [8,9   ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.pigsty.io/yum/mssql/el$releasever.$basearch', china: 'https://repo.pigsty.cc/yum/mssql/el$releasever.$basearch' , origin: 'https://download.copr.fedorainfracloud.org/results/wiltondb/wiltondb/epel-$releasever-$basearch/' }}
- { name: groonga        ,description: 'Groonga'            ,module: groonga ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packages.groonga.org/almalinux/$releasever/$basearch/' }}
- { name: mysql          ,description: 'MySQL'              ,module: mysql   ,releases: [8,9   ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.mysql.com/yum/mysql-8.4-community/el/$releasever/$basearch/' }}
- { name: mongo          ,description: 'MongoDB'            ,module: mongo   ,releases: [8,9   ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.mongodb.org/yum/redhat/$releasever/mongodb-org/8.0/$basearch/' ,china: 'https://mirrors.aliyun.com/mongodb/yum/redhat/$releasever/mongodb-org/8.0/$basearch/' }}
- { name: redis          ,description: 'Redis'              ,module: redis   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://rpmfind.net/linux/remi/enterprise/$releasever/redis72/$basearch/' }}
- { name: grafana        ,description: 'Grafana'            ,module: grafana ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://rpm.grafana.com', china: 'https://mirrors.aliyun.com/grafana/yum/' }}
- { name: kubernetes     ,description: 'Kubernetes'         ,module: kube    ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://pkgs.k8s.io/core:/stable:/v1.33/rpm/', china: 'https://mirrors.aliyun.com/kubernetes-new/core/stable/v1.33/rpm/' }}
- { name: gitlab-ee      ,description: 'Gitlab EE'          ,module: gitlab  ,releases: [8,9   ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packages.gitlab.com/gitlab/gitlab-ee/el/$releasever/$basearch' }}
- { name: gitlab-ce      ,description: 'Gitlab CE'          ,module: gitlab  ,releases: [8,9   ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packages.gitlab.com/gitlab/gitlab-ce/el/$releasever/$basearch' }}
- { name: clickhouse     ,description: 'ClickHouse'         ,module: click   ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packages.clickhouse.com/rpm/stable/', china: 'https://mirrors.aliyun.com/clickhouse/rpm/stable/' }}

For Debian (11,12,13) or Ubuntu (22.04, 24.04) systems, the default values are:

- { name: pigsty-local   ,description: 'Pigsty Local'       ,module: local   ,releases: [11,12,13,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://${admin_ip}/pigsty ./' }}
- { name: pigsty-pgsql   ,description: 'Pigsty PgSQL'       ,module: pgsql   ,releases: [11,12,13,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.pigsty.io/apt/pgsql/${distro_codename} ${distro_codename} main', china: 'https://repo.pigsty.cc/apt/pgsql/${distro_codename} ${distro_codename} main' }}
- { name: pigsty-infra   ,description: 'Pigsty Infra'       ,module: infra   ,releases: [11,12,13,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.pigsty.io/apt/infra/ generic main' ,china: 'https://repo.pigsty.cc/apt/infra/ generic main' }}
- { name: nginx          ,description: 'Nginx'              ,module: infra   ,releases: [11,12,13,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://nginx.org/packages/${distro_name} ${distro_codename} nginx' }}
- { name: docker-ce      ,description: 'Docker'             ,module: infra   ,releases: [11,12,13,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.docker.com/linux/${distro_name} ${distro_codename} stable'                               ,china: 'https://mirrors.aliyun.com/docker-ce/linux/${distro_name} ${distro_codename} stable' }}
- { name: base           ,description: 'Debian Basic'       ,module: node    ,releases: [11,12,13         ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://deb.debian.org/debian/ ${distro_codename} main non-free-firmware'                                  ,china: 'https://mirrors.aliyun.com/debian/ ${distro_codename} main restricted universe multiverse' }}
- { name: updates        ,description: 'Debian Updates'     ,module: node    ,releases: [11,12,13         ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://deb.debian.org/debian/ ${distro_codename}-updates main non-free-firmware'                          ,china: 'https://mirrors.aliyun.com/debian/ ${distro_codename}-updates main restricted universe multiverse' }}
- { name: security       ,description: 'Debian Security'    ,module: node    ,releases: [11,12,13         ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://security.debian.org/debian-security ${distro_codename}-security main non-free-firmware'            ,china: 'https://mirrors.aliyun.com/debian-security/ ${distro_codename}-security main non-free-firmware' }}
- { name: base           ,description: 'Ubuntu Basic'       ,module: node    ,releases: [         20,22,24] ,arch: [x86_64         ] ,baseurl: { default: 'https://mirrors.edge.kernel.org/ubuntu/ ${distro_codename}           main universe multiverse restricted' ,china: 'https://mirrors.aliyun.com/ubuntu/ ${distro_codename}           main restricted universe multiverse' }}
- { name: updates        ,description: 'Ubuntu Updates'     ,module: node    ,releases: [         20,22,24] ,arch: [x86_64         ] ,baseurl: { default: 'https://mirrors.edge.kernel.org/ubuntu/ ${distro_codename}-backports main restricted universe multiverse' ,china: 'https://mirrors.aliyun.com/ubuntu/ ${distro_codename}-updates   main restricted universe multiverse' }}
- { name: backports      ,description: 'Ubuntu Backports'   ,module: node    ,releases: [         20,22,24] ,arch: [x86_64         ] ,baseurl: { default: 'https://mirrors.edge.kernel.org/ubuntu/ ${distro_codename}-security  main restricted universe multiverse' ,china: 'https://mirrors.aliyun.com/ubuntu/ ${distro_codename}-backports main restricted universe multiverse' }}
- { name: security       ,description: 'Ubuntu Security'    ,module: node    ,releases: [         20,22,24] ,arch: [x86_64         ] ,baseurl: { default: 'https://mirrors.edge.kernel.org/ubuntu/ ${distro_codename}-updates   main restricted universe multiverse' ,china: 'https://mirrors.aliyun.com/ubuntu/ ${distro_codename}-security  main restricted universe multiverse' }}
- { name: base           ,description: 'Ubuntu Basic'       ,module: node    ,releases: [         20,22,24] ,arch: [        aarch64] ,baseurl: { default: 'http://ports.ubuntu.com/ubuntu-ports/ ${distro_codename}             main universe multiverse restricted' ,china: 'https://mirrors.aliyun.com/ubuntu-ports/ ${distro_codename}           main restricted universe multiverse' }}
- { name: updates        ,description: 'Ubuntu Updates'     ,module: node    ,releases: [         20,22,24] ,arch: [        aarch64] ,baseurl: { default: 'http://ports.ubuntu.com/ubuntu-ports/ ${distro_codename}-backports   main restricted universe multiverse' ,china: 'https://mirrors.aliyun.com/ubuntu-ports/ ${distro_codename}-updates   main restricted universe multiverse' }}
- { name: backports      ,description: 'Ubuntu Backports'   ,module: node    ,releases: [         20,22,24] ,arch: [        aarch64] ,baseurl: { default: 'http://ports.ubuntu.com/ubuntu-ports/ ${distro_codename}-security    main restricted universe multiverse' ,china: 'https://mirrors.aliyun.com/ubuntu-ports/ ${distro_codename}-backports main restricted universe multiverse' }}
- { name: security       ,description: 'Ubuntu Security'    ,module: node    ,releases: [         20,22,24] ,arch: [        aarch64] ,baseurl: { default: 'http://ports.ubuntu.com/ubuntu-ports/ ${distro_codename}-updates     main restricted universe multiverse' ,china: 'https://mirrors.aliyun.com/ubuntu-ports/ ${distro_codename}-security  main restricted universe multiverse' }}
- { name: pgdg           ,description: 'PGDG'               ,module: pgsql   ,releases: [11,12,13,   22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://apt.postgresql.org/pub/repos/apt/ ${distro_codename}-pgdg main' ,china: 'https://repo.pigsty.cc/apt/pgdg/ ${distro_codename}-pgdg main' }}
- { name: pgdg-beta      ,description: 'PGDG Beta'          ,module: beta    ,releases: [11,12,13,   22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://apt.postgresql.org/pub/repos/apt/ ${distro_codename}-pgdg-testing main 19' ,china: 'https://mirrors.aliyun.com/postgresql/repos/apt/ ${distro_codename}-pgdg-testing main 19' }}
- { name: timescaledb    ,description: 'TimescaleDB'        ,module: extra   ,releases: [11,12,13,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packagecloud.io/timescale/timescaledb/${distro_name}/ ${distro_codename} main' }}
- { name: citus          ,description: 'Citus'              ,module: extra   ,releases: [11,12,   20,22   ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packagecloud.io/citusdata/community/${distro_name}/ ${distro_codename} main' } }
- { name: percona        ,description: 'Percona TDE'        ,module: percona ,releases: [11,12,   20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.pigsty.io/apt/percona ${distro_codename} main' ,china: 'https://repo.pigsty.cc/apt/percona ${distro_codename} main' ,origin: 'http://repo.percona.com/ppg-17.6/apt ${distro_codename} main' }}
- { name: wiltondb       ,description: 'WiltonDB'           ,module: mssql   ,releases: [         20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.pigsty.io/apt/mssql/ ${distro_codename} main', china: 'https://repo.pigsty.cc/apt/mssql/ ${distro_codename} main'   ,origin: 'https://ppa.launchpadcontent.net/wiltondb/wiltondb/ubuntu/ ${distro_codename} main'  }}
- { name: groonga        ,description: 'Groonga Debian'     ,module: groonga ,releases: [11,12,13         ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packages.groonga.org/debian/ ${distro_codename} main' }}
- { name: groonga        ,description: 'Groonga Ubuntu'     ,module: groonga ,releases: [         20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://ppa.launchpadcontent.net/groonga/ppa/ubuntu/ ${distro_codename} main' }}
- { name: mysql          ,description: 'MySQL'              ,module: mysql   ,releases: [11,12,   20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.mysql.com/apt/${distro_name} ${distro_codename} mysql-8.0 mysql-tools', china: 'https://mirrors.tuna.tsinghua.edu.cn/mysql/apt/${distro_name} ${distro_codename} mysql-8.0 mysql-tools' }}
- { name: mongo          ,description: 'MongoDB'            ,module: mongo   ,releases: [11,12,   20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.mongodb.org/apt/${distro_name} ${distro_codename}/mongodb-org/8.0 multiverse', china: 'https://mirrors.aliyun.com/mongodb/apt/${distro_name} ${distro_codename}/mongodb-org/8.0 multiverse' }}
- { name: redis          ,description: 'Redis'              ,module: redis   ,releases: [11,12,   20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packages.redis.io/deb ${distro_codename} main' }}
- { name: llvm           ,description: 'LLVM'               ,module: llvm    ,releases: [11,12,13,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://apt.llvm.org/${distro_codename}/ llvm-toolchain-${distro_codename} main' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/llvm-apt/${distro_codename}/ llvm-toolchain-${distro_codename} main' }}
- { name: haproxyd       ,description: 'Haproxy Debian'     ,module: haproxy ,releases: [11,12            ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://haproxy.debian.net/ ${distro_codename}-backports-3.1 main' }}
- { name: haproxyu       ,description: 'Haproxy Ubuntu'     ,module: haproxy ,releases: [         20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://ppa.launchpadcontent.net/vbernat/haproxy-3.1/ubuntu/ ${distro_codename} main' }}
- { name: grafana        ,description: 'Grafana'            ,module: grafana ,releases: [11,12,13,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://apt.grafana.com stable main' ,china: 'https://mirrors.aliyun.com/grafana/apt/ stable main' }}
- { name: kubernetes     ,description: 'Kubernetes'         ,module: kube    ,releases: [11,12,13,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://pkgs.k8s.io/core:/stable:/v1.33/deb/ /', china: 'https://mirrors.aliyun.com/kubernetes-new/core/stable/v1.33/deb/ /' }}
- { name: gitlab-ee      ,description: 'Gitlab EE'          ,module: gitlab  ,releases: [11,12,13,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packages.gitlab.com/gitlab/gitlab-ee/${distro_name}/ ${distro_codename} main' }}
- { name: gitlab-ce      ,description: 'Gitlab CE'          ,module: gitlab  ,releases: [11,12,13,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packages.gitlab.com/gitlab/gitlab-ce/${distro_name}/ ${distro_codename} main' }}
- { name: clickhouse     ,description: 'ClickHouse'         ,module: click   ,releases: [11,12,13,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packages.clickhouse.com/deb/ stable main', china: 'https://mirrors.aliyun.com/clickhouse/deb/ stable main' }}

`repo_packages`

type: string[], level: G

This parameter is an array of strings, with each string being a list of software packages separated by spaces, specifying which packages to be included and downloaded.

This param DOES NOT have a default value, you can specify it explicitly, or leaving it empty if you want to use the default values.

When leaving it empty, Pigsty will use the default values from the repo_packages_default defined in roles/node_id/vars according to your OS.

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

Each element in repo_packages will be translated into a list of package names according to the package_map defined in the above file, for specific OS distro version.

For example, on EL systems, it will be translated into:

node-bootstrap:          "ansible python3 python3-pip python3-virtualenv python3-requests python3-jmespath python3-cryptography dnf-utils modulemd-tools createrepo_c sshpass"
infra-package:           "nginx dnsmasq etcd haproxy vip-manager node_exporter keepalived_exporter pg_exporter pgbackrest_exporter redis_exporter redis minio mcli pig"
infra-addons:            "grafana grafana-plugins loki logcli promtail prometheus alertmanager pushgateway blackbox_exporter nginx_exporter pev2 certbot python3-certbot-nginx"
extra-modules:           "docker-ce docker-compose-plugin ferretdb2 duckdb restic juicefs vray grafana-infinity-ds"
node-package1:           "lz4 unzip bzip2 zlib yum pv jq git ncdu make patch bash lsof wget uuid tuned nvme-cli numactl grubby sysstat iotop htop rsync tcpdump perf flamegraph chkconfig"
node-package2:           "netcat socat ftp lrzsz net-tools ipvsadm bind-utils telnet audit ca-certificates readline vim-minimal keepalived chrony openssl openssh-server openssh-clients"
pgsql-utility:           "patroni patroni-etcd pgbouncer pgbackrest pgbadger pg_activity pg_timetable pgFormatter pg_filedump pgxnclient timescaledb-tools timescaledb-event-streamer pgcopydb"

And on Debian/Ubuntu systems, it will be translated into:

node-bootstrap:          "ansible python3 python3-pip python3-venv python3-jmespath dpkg-dev sshpass ftp linux-tools-generic"
infra-package:           "nginx dnsmasq etcd haproxy vip-manager node-exporter keepalived-exporter pg-exporter pgbackrest-exporter redis-exporter redis minio mcli pig"
infra-addons:            "grafana grafana-plugins loki logcli promtail prometheus alertmanager pushgateway blackbox-exporter nginx-exporter pev2 certbot python3-certbot-nginx"
extra-modules:           "docker-ce docker-compose-plugin ferretdb2 duckdb restic juicefs vray grafana-infinity-ds"
node-package1:           "lz4 unzip bzip2 zlib1g pv jq git ncdu make patch bash lsof wget uuid tuned nvme-cli numactl sysstat iotop htop rsync tcpdump acl chrony"
node-package2:           "netcat-openbsd socat lrzsz net-tools ipvsadm dnsutils telnet ca-certificates libreadline-dev vim-tiny keepalived openssl openssh-server openssh-client"
pgsql-utility:           "patroni pgbouncer pgbackrest pgbadger pg-activity pg-timetable pgformatter postgresql-filedump pgxnclient timescaledb-tools timescaledb-event-streamer pgcopydb pgloader"

As a convention, repo_packages usually includes software packages that are not related to the major version of PostgreSQL (such as Infra, Node, and PGDG Common), while software packages related to the major version of PostgreSQL (kernel, extensions) are usually specified in repo_extra_packages to facilitate switching between PG major versions.

`repo_extra_packages`

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

This parameter is the same as repo_packages, but it is used for additional software packages that need to be downloaded (usually PostgreSQL version-specific packages).

The default value is an empty list. You can override it at the cluster & instance level to specify additional software packages that need to be downloaded.

If this parameter is not explicitly defined, Pigsty will load the default value from the repo_extra_packages_default defined in roles/node_id/vars, which is:

[ pgsql-main ]

Each element in repo_packages will be translated into a list of package names according to the package_map defined in the above file, for specific OS distro version.

For example, on EL systems, it will be translated into:

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

And on Debian/Ubuntu systems, it will be translated into:

postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v postgresql-$v-repack postgresql-$v-wal2json postgresql-$v-pgvector

Here $v will be replaced with the actual PostgreSQL major version number pg_version, So you can add any PG version related packages here, and Pigsty will download them for you.

`repo_url_packages`

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

extra packages from URL, default values: []

You can use object list or string list in this parameter, in the latter case, Pigsty will use the url basename as the filename.

Note that if the region is set to china, pigsty.io will be replaced with pigsty.cc automatically.

`INFRA_PACKAGE`

These packages are installed on infra nodes only, including common rpm/deb/pip packages.

`infra_packages`

type: string[], level: G

This parameter is an array of strings, with each string being a list of common software packages separated by spaces, specifying which packages to be installed on INFRA nodes.

This parameter DOES NOT have a default value; you can specify it explicitly, or leave it empty if you want to use the default values.

When leaving it empty, Pigsty will use the default values from the repo_packages_default defined in roles/node_id/vars according to your OS.

For EL (7/8/9) system, the default values are:

infra_packages:                   # packages to be installed on infra nodes
  - grafana,loki,logcli,promtail,prometheus,alertmanager,pushgateway,grafana-plugins,restic,certbot,python3-certbot-nginx
  - node_exporter,blackbox_exporter,nginx_exporter,pg_exporter,pev2,nginx,dnsmasq,ansible,etcd,python3-requests,redis,mcli

For Debian (11,12) or Ubuntu (22.04, 22.04) systems, the default values are:

infra_packages:                   # packages to be installed on infra nodes
  - grafana,grafana-plugins,loki,logcli,promtail,prometheus,alertmanager,pushgateway,restic,certbot,python3-certbot-nginx
  - node-exporter,blackbox-exporter,nginx-exporter,pg-exporter,pev2,nginx,dnsmasq,ansible,etcd,python3-requests,redis,mcli

`infra_packages_pip`

type: string, level: G

pip installed packages for infra nodes, default value is empty string

`NGINX`

Pigsty exposes all web services through Nginx: Home Page, Grafana, Prometheus, AlertManager, etc., and other optional tools such as PGWeb, Jupyter Lab, pgAdmin, Bytebase, and other static resources & reports such as pev, schemaspy & pgbadger.

This Nginx also serves as a local YUM/APT repository.

nginx_enabled: true               # enable nginx on this infra node?
nginx_exporter_enabled: true      # enable nginx_exporter on this infra node?
nginx_sslmode: enable             # nginx ssl mode? disable,enable,enforce
nginx_cert_validity: 397d         # nginx self-signed cert validity, 397d by default
nginx_home: /www                  # nginx content dir, `/www` by default
nginx_port: 80                    # nginx listen port, 80 by default
nginx_ssl_port: 443               # nginx ssl listen port, 443 by default
nginx_navbar:                     # nginx index page navigation links
  - { name: CA Cert ,url: '/ca.crt'   ,desc: 'pigsty self-signed ca.crt'   }
  - { name: Package ,url: '/pigsty'   ,desc: 'local yum repo packages'     }
  - { name: PG Logs ,url: '/logs'     ,desc: 'postgres raw csv logs'       }
  - { name: Reports ,url: '/report'   ,desc: 'pgbadger summary report'     }
  - { name: Explain ,url: '/pigsty/pev.html' ,desc: 'postgres explain visualizer' }
certbot_sign: false               # sign nginx cert with certbot during setup?
certbot_email: [email protected]     # certbot email address, used for free ssl
certbot_optionss: ''               # certbot extra options

`nginx_enabled`

type: bool, level: G/I

enable nginx on this infra node? default value: true

`nginx_exporter_enabled`

type: bool, level: G/I

enable nginx_exporter on this infra node? default value: true.

Setting this to false will also disable the /nginx health check stub: If your Nginx does not support the /nginx stub, you can set this value to false to disable it.

`nginx_sslmode`

type: enum, level: G

nginx ssl mode? which could be: disable, enable, enforce, the default value: enable

disable: listen on nginx_port and serve plain HTTP only
enable: also listen on nginx_ssl_port and serve HTTPS
enforce: all links will be rendered as https:// by default
- also redirect the 80 port to 443 port for all non-default servers in nginx infra_portal

`nginx_cert_validity`

type: duration, level: G

nginx self-signed cert validity, 397d by default

Use longer validity is not recommended, as the latest browsers require the website certificate to be valid for at most 397 days, so this is the default value.

`nginx_home`

type: path, level: G

nginx web server static content dir, /www by default

Nginx root directory which contains static resource and repo resource. It’s wise to set this value same as repo_home so that local repo content is automatically served.

`nginx_port`

type: port, level: G

Nginx listening port which serves the HTTP requests, 80 by default.

If your default 80 port is occupied or unavailable, you can consider using another port, and change repo_endpoint and repo_upstream (the local entry) accordingly.

`nginx_ssl_port`

type: port, level: G

nginx ssl listen port, 443 by default

`nginx_navbar`

type: index[], level: G

nginx index page navigation links

default value:

nginx_navbar:                     # nginx index page navigation links
  - { name: CA Cert ,url: '/ca.crt'   ,desc: 'pigsty self-signed ca.crt'   }
  - { name: Package ,url: '/pigsty'   ,desc: 'local yum repo packages'     }
  - { name: PG Logs ,url: '/logs'     ,desc: 'postgres raw csv logs'       }
  - { name: Reports ,url: '/report'   ,desc: 'pgbadger summary report'     }
  - { name: Explain ,url: '/pigsty/pev.html' ,desc: 'postgres explain visualizer' }

Each record is rendered as a navigation link to the Pigsty home page App drop-down menu, and the apps are all optional, mounted by default on the Pigsty default server under http://h.pigsty/.

The url parameter specifies the URL PATH for the app, with the exception that if the ${grafana} string is present in the URL, it will be automatically replaced with the Grafana domain name defined in infra_portal.

`certbot_sign`

type: bool, level: G/A

sign nginx cert with certbot during setup? default value: false

When set to true, Pigsty will use certbot to automatically apply for free SSL certificates from Let’s Encrypt during the execution of infra.yml and install.yml playbooks (the nginx role).

In the infra_portal defined domain, if the certbot parameter is defined, Pigsty will use certbot to apply for the domain domain certificate, and the certificate name will be the value of the certbot parameter. If multiple servers/domains specify the same certbot parameter, Pigsty will merge and apply for a certificate for these domains, and use the value of the certbot parameter as the certificate name.

Enabling this option requires:

The current node can be accessed through the public domain name, and the DNS resolution has been correctly pointed to the public IP of the current node
The current node can access the Let’s Encrypt API interface

This option is disabled by default, you can manually execute the make cert command after installation to manually execute it, it actually calls the rendered /etc/nginx/sign-cert script, using certbot to update or apply certificates.

`certbot_email`

type: string, level: G/A

The email address used to receive certificate expiration reminder emails, default value: [email protected]

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

`certbot_options`

type: string, level: G/A

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

You can pass additional command line options to certbot through this parameter, for example --dry-run, then certbot will not actually apply for a certificate, but will preview and test it.

`DNS`

Pigsty will launch a default DNSMASQ server on infra nodes to serve DNS inquiry. such as h.pigsty a.pigsty p.pigsty g.pigsty and sss.pigsty for optional MinIO service.

All records will be added to infra node’s /etc/hosts.d/*.

You have to add nameserver {{ admin_ip }} to your /etc/resolv to use this dns server, and node_dns_servers will do the trick.

dns_enabled: true                 # setup dnsmasq on this infra node?
dns_port: 53                      # dns server listen port, 53 by default
dns_records:                      # dynamic dns records resolved by dnsmasq
  - "${admin_ip} h.pigsty a.pigsty p.pigsty g.pigsty"
  - "${admin_ip} api.pigsty adm.pigsty cli.pigsty ddl.pigsty lab.pigsty git.pigsty sss.pigsty wiki.pigsty"

`dns_enabled`

type: bool, level: G/I

setup dnsmasq on this infra node? default value: true

If you don’t want to use the default DNS server, you can set this value to false to disable it. And use node_default_etc_hosts and node_etc_hosts instead.

`dns_port`

type: port, level: G

dns server listen port, 53 by default

`dns_records`

type: string[], level: G

dynamic dns records resolved by dnsmasq, Some auxiliary domain names will be written to /etc/hosts.d/default on infra nodes by default

dns_records:                      # dynamic dns records resolved by dnsmasq
  - "${admin_ip} h.pigsty a.pigsty p.pigsty g.pigsty"
  - "${admin_ip} api.pigsty adm.pigsty cli.pigsty ddl.pigsty lab.pigsty git.pigsty sss.pigsty wiki.pigsty"

`PROMETHEUS`

Prometheus is used as the time-series database for metrics scrape, storage & analysis.

prometheus_enabled: true          # enable prometheus on this infra node?
prometheus_port: 9058             # prometheus listen port, 9058 by default
prometheus_clean: true            # clean prometheus data during init?
prometheus_data: /data/prometheus # prometheus data dir, `/data/prometheus` by default
prometheus_sd_dir: /etc/prometheus/targets # prometheus file service discovery directory
prometheus_sd_interval: 5s        # prometheus target refresh interval, 5s by default
prometheus_scrape_interval: 10s   # prometheus scrape & eval interval, 10s by default
prometheus_scrape_timeout: 8s     # prometheus global scrape timeout, 8s by default
prometheus_options: '--storage.tsdb.retention.time=15d' # prometheus extra server options
pushgateway_enabled: true         # setup pushgateway on this infra node?
pushgateway_options: '--persistence.interval=1m' # pushgateway extra server options
blackbox_enabled: true            # setup blackbox_exporter on this infra node?
blackbox_options: ''              # blackbox_exporter extra server options
alertmanager_enabled: true        # setup alertmanager on this infra node?
alertmanager_port: 9059           # alertmanager listen port, 9059 by default
alertmanager_options: ''          # alertmanager extra server options
exporter_metrics_path: /metrics   # exporter metric path, `/metrics` by default
exporter_install: none            # how to install exporter? none,yum,binary
exporter_repo_url: ''             # exporter repo file url if install exporter via yum

`prometheus_enabled`

type: bool, level: G/I

enable prometheus on this infra node?

default value: true

`prometheus_port`

type: port, level: G

The listening port for Prometheus, default value is 9058.

Newly added since 3.7, with previous default value changing from 9090 to 9058. Because the EL10 distro has a new default web service cockpit-ws which also uses port 9090.

`prometheus_clean`

type: bool, level: G/A

clean prometheus data during init? default value: true

`prometheus_data`

type: path, level: G

prometheus data dir, /data/prometheus by default

`prometheus_sd_dir`

type: path, level: G, default value: /etc/prometheus/targets

prometheus static file service discovery target dir, prometheus will find dynamic monitoring targets from this directory.

`prometheus_sd_interval`

type: interval, level: G, default value: 5s

Prometheus will check prometheus_sd_interval dir per 5s by default to find out new monitoring targets.

`prometheus_scrape_interval`

type: interval, level: G

prometheus scrape & eval interval, 10s by default

`prometheus_scrape_timeout`

type: interval, level: G

prometheus global scrape timeout, 8s by default

DO NOT set this larger than prometheus_scrape_interval

`prometheus_options`

type: arg, level: G

prometheus extra server options

default value: --storage.tsdb.retention.time=15d

Extra cli args for prometheus server, the default value will set up a 15-day data retention to limit disk usage.

`pushgateway_enabled`

type: bool, level: G/I

setup pushgateway on this infra node? default value: true

`pushgateway_options`

type: arg, level: G

pushgateway extra server options, default value: --persistence.interval=1m

`blackbox_enabled`

type: bool, level: G/I

setup blackbox_exporter on this infra node? default value: true

`blackbox_options`

type: arg, level: G

blackbox_exporter extra server options, default value is empty string

`alertmanager_enabled`

type: bool, level: G/I

setup alertmanager on this infra node? default value: true

`alertmanager_port`

type: port, level: G

The listening port for AlertManager, default value is 9059.

The default value change from 9093 since v3.7. Because the kafka’s default peer port is also 9093

`alertmanager_options`

type: arg, level: G

alertmanager extra server options, default value is empty string

`exporter_metrics_path`

type: path, level: G

exporter metric path, /metrics by default

`exporter_install`

type: enum, level: G

(OBSOLETE) how to install exporter? none,yum,binary

default value: none

Specify how to install Exporter:

none: No installation, (by default, the Exporter has been previously installed by the node_pkg task)
yum: Install using yum (if yum installation is enabled, run yum to install node_exporter and pg_exporter before deploying Exporter)
binary: Install using a copy binary (copy node_exporter and pg_exporter binary directly from local file dir, not recommended)

When installing with yum, if exporter_repo_url is specified (not empty), the installation will first install the REPO file under that URL into /etc/yum.repos.d. This feature allows you to install Exporter directly without initializing the node infrastructure. It is not recommended for regular users to use binary installation. This mode is usually used for emergency troubleshooting and temporary problem fixes.

<meta>:<pigsty>/files/node_exporter ->  <target>:/usr/bin/node_exporter
<meta>:<pigsty>/files/pg_exporter   ->  <target>:/usr/bin/pg_exporter

`exporter_repo_url`

type: url, level: G

(OBSOLETE) exporter repo file url if install exporter via yum

default value is empty string

Default is empty; when exporter_install is yum, the repo specified by this parameter will be added to the node source list.

`GRAFANA`

Grafana is the visualization platform for Pigsty’s monitoring system.

It can also be used as a low code data visualization environment

grafana_enabled: true             # enable grafana on this infra node?
grafana_clean: true               # clean grafana data during init?
grafana_admin_username: admin     # grafana admin username, `admin` by default
grafana_admin_password: pigsty    # grafana admin password, `pigsty` by default
loki_enabled: true                # enable loki on this infra node?
loki_clean: false                 # whether remove existing loki data?
loki_data: /data/loki             # loki data dir, `/data/loki` by default
loki_retention: 15d               # loki log retention period, 15d by default

`grafana_enabled`

type: bool, level: G/I

enable grafana on this infra node? default value: true

`grafana_clean`

type: bool, level: G/A

clean grafana data during init? default value: true

`grafana_admin_username`

type: username, level: G

grafana admin username, admin by default

`grafana_admin_password`

type: password, level: G

grafana admin password, pigsty by default

default value: pigsty

WARNING: Change this to a strong password before deploying to production environment

`LOKI`

`loki_enabled`

type: bool, level: G/I

enable loki on this infra node? default value: true

`loki_clean`

type: bool, level: G/A

whether remove existing loki data? default value: false

`loki_data`

type: path, level: G

loki data dir, default value: /data/loki

`loki_retention`

type: interval, level: G

loki log retention period, 15d by default

4 - Administration

Manage infra components, local repo, nginx portal, and domain names

Here are some admin tasks related to the INFRA module

Nginx Portal

    Nginx Portal for WebUI services

Local Repo

    Manage local APT / YUM repository

Domain Name

    Use local / public domain names

CA & Cert

    Use self-signed or real HTTPS certificates

Install INFRA

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

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

Remove INFRA

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

./infra-rm.yml  # Uninstall INFRA module from infra group

Expand INFRA

To scale out an existing INFRA deployment, first modify the infra group by adding new node IPs and assigning unique infra_seq numbers:

all:
  children:
    infra:
      hosts:
        10.10.10.10: { infra_seq: 1 } # Existing node #1
        10.10.10.11: { infra_seq: 2 } # New node #2 (fresh meat!)

Then use the infra.yml playbook to install INFRA on the new node:

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

Local Repo

Use these playbook tasks to manage local package repositories (YUM/APT) on Infra nodes :

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

./infra.yml -t repo_dir          # Create local repository directory
./infra.yml -t repo_check        # Check if local repository exists
./infra.yml -t repo_prepare      # Use existing local repository if available
./infra.yml -t repo_build        # Build local repository from upstream if not exists
./infra.yml     -t repo_upstream     # Add upstream repository/list files
./infra.yml     -t repo_remove       # Remove existing repository files if repo_remove=true
./infra.yml     -t repo_add          # Add upstream repository files to /etc/yum.repos.d (or apt)
./infra.yml     -t repo_url_pkg      # Download packages defined in repo_url_packages
./infra.yml     -t repo_cache        # Create metadata cache with yum makecache / apt update
./infra.yml     -t repo_boot_pkg     # Install bootstrap packages (createrepo_c, yum-utils, etc)
./infra.yml     -t repo_pkg          # Download packages & deps from upstream
./infra.yml     -t repo_create       # Create local repository with createrepo_c / dpkg-dev
./infra.yml     -t repo_use          # Add new repository to /etc/yum.repos.d | apt sources
./infra.yml -t repo_nginx        # Start nginx as file server if not running

Commonly used commands:

./infra.yml     -t repo_upstream     # Add upstream repositories defined in repo_upstream
./infra.yml     -t repo_pkg          # Download packages and their dependencies
./infra.yml     -t repo_create       # Create/update local YUM/APT repository

Managing Nginx

./infra.yml -t nginx                       # Reset Nginx component
./infra.yml -t nginx_index                 # Re-render Nginx homepage
./infra.yml -t nginx_config,nginx_reload   # Re-render config & expose new upstream services

If users specify a cert name in the certbot field of infra_portal, you can get free HTTPS certs with certbot:

# Get free HTTPS certificates for real domains with certbot
./infra.yml -t nginx_certbot,nginx_reload -e certbot_sign=true

Manage Infra Components

Use these playbook tasks to manage infrastructure components on Infra nodes

./infra.yml -t infra           # Configure infrastructure
./infra.yml -t infra_env       # Configure env vars: env_dir, env_pg, env_pgadmin, env_var
./infra.yml -t infra_pkg       # Install required packages: infra_pkg_yum, infra_pkg_pip
./infra.yml -t infra_user      # Setup infra OS user group
./infra.yml -t infra_cert      # Issue certs 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_exporter
./infra.yml -t prometheus      # Configure Prometheus: prometheus_clean, prometheus_dir, prometheus_config, prometheus_launch, prometheus_reload
./infra.yml -t alertmanager    # Configure AlertManager: alertmanager_config, alertmanager_launch
./infra.yml -t pushgateway     # Configure PushGateway: pushgateway_config, pushgateway_launch
./infra.yml -t blackbox        # Configure Blackbox Exporter: blackbox_launch
./infra.yml -t grafana         # Configure Grafana: grafana_clean, grafana_config, grafana_plugin, grafana_launch, grafana_provision
./infra.yml -t loki            # Configure Loki: loki_clean, loki_dir, loki_config, loki_launch
./infra.yml -t infra_register  # Register infra components to prometheus

Other useful tasks

./infra.yml -t nginx_index                        # Re-render Nginx homepage
./infra.yml -t nginx_config,nginx_reload          # Re-render config & expose new upstream services
./infra.yml -t prometheus_conf,prometheus_reload   # Re-generate Prometheus config & reload
./infra.yml -t prometheus_rule,prometheus_reload   # Re-copy rules & alerts, then reload
./infra.yml -t grafana_plugin                     # Download Grafana plugins (VPN might be needed)

5 - Playbook

control primitives

There are three playbooks related to the INFRA module:

infra.yml: Initialize Pigsty infrastructure on infra nodes
infra-rm.yml: Remove infrastructure components from infra nodes
install.yml: Perform a complete one-time installation of Pigsty on the current node

`infra.yml`

The INFRA module playbook infra.yml initializes the infrastructure module on Infra nodes defined in the infra group of your config 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 (skipped if offline packages are used or if a local repository already exists)
Incorporates the current Infra node as a common node managed by Pigsty
Deploys infrastructure components, including Prometheus, Grafana, Loki, Alertmanager, PushGateway, Blackbox Exporter, etc.

This playbook executes on the infra group by default:

Pigsty installs the INFRA module on the group named infra in the config file
During configure, Pigsty marks the current installation node as an Infra node and replaces the placeholder IP address 10.10.10.10 in the config template with the current node’s primary IP address
This node can initiate management tasks and host infrastructure components while functioning like any regular managed node

Playbook notes:

This is an idempotent playbook - repeated execution will overwrite infra components on Infra nodes
- Unless prometheus_clean is set to false, Prometheus time series metrics will be lost
- Unless loki_clean is set to false, Loki log data will be lost
- Unless grafana_clean is set to false, Grafana dashboards and configuration changes will be lost
When the local software repo /www/pigsty/repo_complete exists, this playbook skips downloading software from the internet
- Complete execution takes approximately 1 ~ 3 minutes, depending on machine configuration and network conditions
- Downloading software directly from the original upstream sources (without using offline packages) may take 5-10 minutes, depending on your network connection

Demo

Available Tasks

Here’s the list of available tasks in the infra.yml playbook:

#--------------------------------------------------------------#
# Tasks
#--------------------------------------------------------------#
# ca            : create self-signed CA in localhost files/pki
#   - ca_dir        : create CA directory
#   - ca_private    : generate CA private key: files/pki/ca/ca.key
#   - ca_cert       : sign CA certificate: files/pki/ca/ca.crt
#
# id            : generate node identity
#
# repo          : bootstrap a local YUM repository from internet or offline packages
#   - repo_dir      : create repository directory
#   - repo_check    : check repository exists
#   - repo_prepare  : use existing repository if exists
#   - repo_build    : build repository from upstream if not exists
#     - repo_upstream    : handle upstream repository files in /etc/yum.repos.d
#       - repo_remove    : remove existing repository file if repo_remove == true
#       - repo_add       : add upstream repository 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 bootstrap packages such as createrepo_c, yum-utils, etc.
#     - repo_pkg         : download packages & dependencies from upstream repository
#     - repo_create      : create a local YUM repository with createrepo_c & modifyrepo_c
#     - repo_use         : add newly built repository into /etc/yum.repos.d
#   - repo_nginx    : launch nginx for repository if no nginx is serving
#
# node/haproxy/docker/monitor : set up infra node as a common node (check node.yml)
#   - 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
#   - docker_install, docker_admin, docker_config, docker_launch, docker_image
#   - haproxy_register, node_exporter, node_register, promtail
#
# infra         : set up infra components
#   - infra_env      : env_dir, env_pg, env_pgadmin, env_var
#   - infra_pkg      : infra_pkg_yum, infra_pkg_pip
#   - infra_user     : set up infra OS user group
#   - infra_cert     : issue certificate for infra components
#   - dns            : dns_config, dns_record, dns_launch
#   - nginx          : nginx_config, nginx_cert, nginx_static, nginx_launch, nginx_certbot, nginx_reload, nginx_exporter
#   - prometheus     : prometheus_clean, prometheus_dir, prometheus_config, prometheus_launch, prometheus_reload
#   - alertmanager   : alertmanager_config, alertmanager_launch
#   - pushgateway    : pushgateway_config, pushgateway_launch
#   - blackbox       : blackbox_config, blackbox_launch
#   - grafana        : grafana_clean, grafana_config, grafana_launch, grafana_provision
#   - loki           : loki clean, loki_dir, loki_config, loki_launch
#   - infra_register : register infra components to prometheus
#--------------------------------------------------------------#

`infra-rm.yml`

The INFRA module playbook infra-rm.yml removes Pigsty infrastructure from Infra nodes defined in the infra group of your config file.

Common subtasks include:

./infra-rm.yml               # Remove the INFRA module
./infra-rm.yml -t service    # Stop infrastructure services on INFRA
./infra-rm.yml -t data       # Remove retained data on INFRA
./infra-rm.yml -t package    # Uninstall packages installed on INFRA

`install.yml`

The INFRA module playbook install.yml performs a complete one-time installation of Pigsty on all nodes.

This playbook is described in more detail in Playbook: One-Pass Deployment.

6 - Monitor

Dashboards and alerting rules for infra module

Dashboards

Alert Rules

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

InfraDown : Infrastructure components are down
AgentDown : Monitoring agent is down

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

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

    #==============================================================#
    #                       Infra Aliveness                        #
    #==============================================================#
    # infra components (prometheus,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

7 - FAQ

frequently asked questions

Which components are included in INFRA

Ansible for automation, deployment, and administration;
Nginx for exposing any WebUI service and serving the YUM/APT repository;
Self-Signed CA for SSL/TLS certificates;
Prometheus for monitoring metrics
Grafana for monitoring/visualization
Loki for logging collection
AlertManager for alerts aggregation
Chronyd for NTP time synchronization on the admin node.
DNSMasq for DNS registration and resolution.
ETCD as DCS for PostgreSQL HA (dedicated module);
PostgreSQL on meta nodes as CMDB (optional);
Docker for stateless applications & tools (optional).

How to restore Prometheus targets

If you accidentally deleted the Prometheus targets dir, you can register monitoring targets to Prometheus again with the:

./infra.yml -t register_prometheus  # register all infra targets to prometheus on infra nodes
./node.yml  -t register_prometheus  # register all node  targets to prometheus on infra nodes
./etcd.yml  -t register_prometheus  # register all etcd targets to prometheus on infra nodes
./minio.yml -t register_prometheus  # register all minio targets to prometheus on infra nodes
./pgsql.yml -t register_prometheus  # register all pgsql targets to prometheus on infra nodes

How to restore Grafana datasource

PGSQL Databases in pg_databases are registered as Grafana datasource by default.

If you accidentally deleted the registered postgres datasource in Grafana, you can register them again with

./pgsql.yml -t register_grafana  # register all pgsql database (in pg_databases) as grafana datasource

How to restore the HAProxy admin page proxy

The haproxy admin page is proxied by Nginx under the default server.

If you accidentally deleted the registered haproxy proxy settings in /etc/nginx/conf.d/haproxy, you can restore them again with

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

How to restore the DNS registration

PGSQL cluster/instance domain names are registered to /etc/hosts.d/<name> on infra nodes by default.

You can restore them with the following command:

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

How to expose a new Nginx upstream service

If you wish to expose a new WebUI service via the Nginx portal, you can add the service definition to the infra_portal parameter.

And re-run ./infra.yml -t nginx_config,nginx_launch to update & apply the Nginx configuration.

If you wish to access with HTTPS, you must remove files/pki/csr/pigsty.csr, files/pki/nginx/pigsty.{key,crt} to force re-generating the Nginx SSL/TLS certificate to include the new upstream’s domain name.

How to expose a web service through Nginx?

While you can directly access services via IP:Port, we still recommend consolidating access points by using domain names and uniformly accessing various web-based services through the Nginx portal. This approach helps centralize access, reduce the number of exposed ports, and facilitates access control and auditing.

If you wish to expose a new WebUI service through the Nginx portal, you can add the service definition to the infra_portal parameter. For example, here is the config used by the public demo site, which exposes several additional web services:

infra_portal:
  home         : { domain: home.pigsty.io }
  grafana      : { domain: g.pgsty.com ,endpoint: "${admin_ip}:3000" ,websocket: true }
  prometheus   : { domain: p.pigsty.io ,endpoint: "${admin_ip}:9058" }
  alertmanager : { domain: a.pigsty.io ,endpoint: "${admin_ip}:9059" }
  blackbox     : { endpoint: "${admin_ip}:9115" }
  loki         : { endpoint: "${admin_ip}:3100" }
  # Additional web portals
  minio        : { domain: sss.pigsty  ,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"   }
  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: "127.0.0.1:8000", websocket: true }

After completing the Nginx upstream service definition, use the following commands to register the new service with Nginx.

./infra.yml -t nginx_config           # regenerate Nginx config
./infra.yml -t nginx_launch           # update and apply nginx config

# you can reload nginx with ansible
ansible infra -b -a 'nginx -s reload'  # reload nginx with ansible

If you wish to access via HTTPS, you must delete files/pki/csr/pigsty.csr and files/pki/nginx/pigsty.{key,crt} to force the regeneration of the Nginx SSL/TLS certificate to include the new upstream domain names. If you prefer to use an SSL certificate issued by an authoritative organization instead of a certificate issued by Pigsty’s self-signed CA, you can place it in the /etc/nginx/conf.d/cert/ directory and modify the corresponding configuration: /etc/nginx/conf.d/<name>.conf.

How to manually add upstream repo files

Pigsty has a built-in wrapper script bin/repo-add, which will invoke Ansible playbook node.yml to add repository files to corresponding nodes.

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