ER Model

• 1: E-R Model of Infra Cluster
• 2: E-R Model of PostgreSQL Cluster
• 3: E-R Model of Etcd Cluster
• 4: MINIO Cluster Model
• 5: E-R Model of Redis Cluster

A deployment is the largest entity in Pigsty. This entity-relationship diagram shows its main entities and their relationships:

A deployment is also an environment. Examples include Production (Prod), User Acceptance Testing (UAT), Staging, Testing, and Development (Devbox). Each environment has a Pigsty inventory that describes all its entities and attributes.

An environment usually has shared infrastructure (INFRA). This includes ETCD for the HA DCS and MINIO for centralized backup storage. Infrastructure serves multiple PostgreSQL clusters and other database modules. Deployments without infrastructure are also possible.

Pigsty organizes almost all database modules into clusters. Each cluster is an Ansible group with node resources. PostgreSQL HA, Redis, Etcd, and Silo use this model. An environment can contain multiple clusters.

• PostgreSQL Cluster
• ETCD Cluster
• MinIO Cluster
• Redis Cluster
• INFRA Nodes

1 - E-R Model of Infra Cluster

The INFRA module is a management hub made of infrastructure nodes, rather than a traditional cluster. It provides core services for the deployment. Each node is an autonomous service unit that runs components such as Nginx, Grafana, and VictoriaMetrics. Together, these nodes provide observability and management for database clusters.

There are two core entities in Pigsty’s INFRA module:

• Node: A server that runs infrastructure components. It can be a physical server, VM, container, or Pod.
• Component: An infrastructure service on a node, such as Nginx, Grafana, or VictoriaMetrics.

INFRA nodes usually also serve as administration nodes, which form the Pigsty control plane.

Component Composition

Each INFRA node runs the following core components:

These components together form Pigsty’s observability infrastructure.

Examples

This example defines a two-node INFRA deployment:

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

The configuration defines these entities:

For production, use at least two INFRA nodes for component redundancy.

Identity Parameters

The INFRA_ID parameter group assigns deterministic identities to INFRA entities. One parameter is required:

Set the node sequence number at node level. Pigsty generates unique identifiers with these rules:

INFRA assigns infra-N identifiers to distinguish infrastructure nodes in monitoring. This does not change their hostname or system identity. Nodes retain their existing hostname or IP address for identification.

Service Portal

INFRA nodes provide web access through Nginx. infra_portal defines the services that Nginx exposes.

The default configuration only defines the home server:

infra_portal:
  home : { domain: i.pigsty }

Pigsty configures reverse proxy endpoints for enabled components, including Grafana, VictoriaMetrics, and AlertManager. To access them through separate domains, add explicit configuration:

infra_portal:
  home         : { domain: i.pigsty }
  grafana      : { domain: g.pigsty, endpoint: "${admin_ip}:3000", websocket: true }
  prometheus   : { domain: p.pigsty, endpoint: "${admin_ip}:8428" }   # VMUI
  alertmanager : { domain: a.pigsty, endpoint: "${admin_ip}:9059" }

Use domain names to access Pigsty services where possible, instead of an IP address and port.

Deployment Scale

The number of INFRA nodes depends on deployment scale and HA requirements:

In a single-node deployment, INFRA shares a node with PGSQL, ETCD, and other modules. Small deployments usually use INFRA nodes as the administration node, backup administration node, and local software repository (/www/pigsty). Larger deployments can assign these responsibilities to dedicated nodes.

Monitoring Label System

Pigsty collects metrics from INFRA components themselves. Unlike database modules, INFRA treats each component as a separate monitoring object. The cls (class) label distinguishes component types.

A two-node INFRA deployment with infra_seq: 1 and infra_seq: 2 uses these component labels:

All INFRA component metrics have job="infra". The cls label distinguishes components:

nginx_up{cls="nginx", ins="nginx-1", ip="10.10.10.10", job="infra"}
grafana_info{cls="grafana", ins="grafana-1", ip="10.10.10.10", job="infra"}
vm_app_version{cls="vmetrics", ins="vmetrics-1", ip="10.10.10.10", job="infra"}
vlogs_rows_ingested_total{cls="vlogs", ins="vlogs-1", ip="10.10.10.10", job="infra"}
alertmanager_alerts{cls="alertmanager", ins="alertmanager-1", ip="10.10.10.10", job="infra"}

2 - E-R Model of PostgreSQL Cluster

PGSQL organizes PostgreSQL as clusters. Each cluster is a logical group of database instances connected through primary-replica relationships.

Each cluster is an autonomous business unit with at least one primary instance. It exposes database capabilities through services.

There are four core entities in Pigsty’s PGSQL module:

• Cluster: An autonomous PostgreSQL business unit and the top-level namespace for other entities.
• Service: A named abstraction that exposes capabilities and routes traffic through node ports.
• Instance: One PostgreSQL server, including its running processes and database files, on one node.
• Node: A hardware resource that runs Linux and Systemd. It can be a physical server, VM, container, or Pod.

Two business entities, Database and Role, complete this logical model:

Examples

The following two examples show the model. The four-node Pigsty sandbox contains a three-node pg-test cluster:

    pg-test:
      hosts:
        10.10.10.11: { pg_seq: 1, pg_role: primary }
        10.10.10.12: { pg_seq: 2, pg_role: replica }
        10.10.10.13: { pg_seq: 3, pg_role: replica }
      vars: { pg_cluster: pg-test }

This configuration defines a high-availability PostgreSQL cluster with these entities:

Identity Parameters

The PG_ID parameter group assigns deterministic identities to PGSQL entities. Three parameters are required:

Set the cluster name at cluster level. Set each instance number and role at instance level. Pigsty generates unique identifiers with these rules:

Pigsty uses an exclusive 1:1 mapping between nodes and PostgreSQL instances. By default, the node inherits its PostgreSQL instance identifier through node_id_from_pg. Set nodename to override this name. Alternatively, disable nodename_overwrite to retain the current default.

Sharding Identity Parameters

To serve one business with multiple PostgreSQL clusters (sharding), use two additional identity parameters: pg_shard and pg_group.

These clusters share one pg_shard name. Each has its own pg_group number, as in this Citus cluster:

A pg_cluster name usually combines {{ pg_shard }}{{ pg_group }}, for example pg-citus0 or pg-citus1.

all:
  children:
    pg-citus0: # citus shard 0
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars: { pg_cluster: pg-citus0 , pg_group: 0 }
    pg-citus1: # citus shard 1
      hosts: { 10.10.10.11: { pg_seq: 1, pg_role: primary } }
      vars: { pg_cluster: pg-citus1 , pg_group: 1 }
    pg-citus2: # citus shard 2
      hosts: { 10.10.10.12: { pg_seq: 1, pg_role: primary } }
      vars: { pg_cluster: pg-citus2 , pg_group: 2 }
    pg-citus3: # citus shard 3
      hosts: { 10.10.10.13: { pg_seq: 1, pg_role: primary } }
      vars: { pg_cluster: pg-citus3 , pg_group: 3 }

Pigsty has dedicated dashboards for horizontally sharded clusters. Use this naming convention to compare shard performance and load in those dashboards.

Other identity parameters support specific uses:

• pg_upstream: Set the upstream for a backup cluster or cascading replication.
• gp_role: Identify a Greenplum cluster role.
• pg_exporters: Define external monitoring instances.
• pg_offline_query: Define offline query instances.

See the PG_ID parameter documentation.

Monitoring Label System

The built-in monitoring system uses these identity parameters to identify PostgreSQL entities.

pg_up{cls="pg-test", ins="pg-test-1", ip="10.10.10.11", job="pgsql"}
pg_up{cls="pg-test", ins="pg-test-2", ip="10.10.10.12", job="pgsql"}
pg_up{cls="pg-test", ins="pg-test-3", ip="10.10.10.13", job="pgsql"}

The labels cls, ins, and ip identify the cluster name, instance name, and node IP. They accompany job in all native VictoriaMetrics metrics and VictoriaLogs log streams.

These job values are fixed:

• pgsql: PostgreSQL metrics.
• pgrds: Remote PostgreSQL instance metrics.
• postgres: PostgreSQL CSV logs.
• pgbackrest: pgBackRest logs.

Other PostgreSQL components collect logs through job: syslog.

Specific entity metrics also have these identity labels:

• datname: Database name, if a metric belongs to a specific database.
• relname: Table name, if a metric belongs to a specific table.
• idxname: Index name, if a metric belongs to a specific index.
• funcname: Function name, if a metric belongs to a specific function.
• seqname: Sequence name, if a metric belongs to a specific sequence.
• query: Query fingerprint, if a metric belongs to a specific query.

3 - E-R Model of Etcd Cluster

The ETCD module organizes production ETCD into clusters. A cluster is a logical entity whose ETCD instances coordinate through the Raft consensus protocol.

Each cluster is an autonomous distributed key-value store with at least one ETCD instance. It provides services through client ports.

There are three core entities in Pigsty’s ETCD module:

• Cluster: An autonomous ETCD service unit and the top-level namespace for other entities.
• Instance: One ETCD server process on a node, participating in Raft consensus.
• Node: An implicitly declared hardware resource that runs Linux and Systemd.

The ETCD model has no Service entities or complex Role distinctions, unlike PostgreSQL. All ETCD instances are functionally equivalent. Raft elects one Leader; the others become Followers. Non-voting Learner members are also permitted during intermediate scale-out states.

Examples

This example defines a three-node ETCD cluster:

etcd:
  hosts:
    10.10.10.10: { etcd_seq: 1 }
    10.10.10.11: { etcd_seq: 2 }
    10.10.10.12: { etcd_seq: 3 }
  vars:
    etcd_cluster: etcd

The configuration defines these entities:

Identity Parameters

The ETCD parameter group assigns deterministic identities to ETCD entities. Two parameters are required:

Set the cluster name at cluster level and the instance number at instance level. Pigsty generates unique identifiers with these rules:

ETCD does not assign a separate identity to host nodes. It uses their existing hostname or IP address.

Ports & Protocols

Each ETCD instance listens on the following two ports:

ETCD clusters enable TLS encryption and RBAC authentication by default. Clients need the correct certificates and passwords to access ETCD.

Cluster Size

ETCD cluster size determines availability. More than half the nodes, called a quorum, must be alive to maintain this distributed coordination service.

ETCD supports even member counts. However, they tolerate no more failures than the next smaller odd count. They also increase deployment and quorum costs. Production clusters therefore usually have one, three, or five members. Clusters with more than five members are uncommon.

Monitoring Label System

The built-in monitoring system uses these identity parameters to identify ETCD entities.

etcd_up{cls="etcd", ins="etcd-1", ip="10.10.10.10", job="etcd"}
etcd_up{cls="etcd", ins="etcd-2", ip="10.10.10.11", job="etcd"}
etcd_up{cls="etcd", ins="etcd-3", ip="10.10.10.12", job="etcd"}

The labels cls, ins, and ip identify the cluster name, instance name, and node IP. They accompany job in all ETCD metrics collected by VictoriaMetrics. The ETCD metrics job is always etcd.

4 - MINIO Cluster Model

MINIO is the compatibility module name for object storage. Pigsty v4.5.0 deploys Silo with minio_type: silo. It groups object storage instances into a cluster.

Each cluster is an autonomous S3-compatible object store with at least one instance. It exposes services through the S3 API port.

There are three core entities in Pigsty’s MINIO module:

• Cluster: An autonomous object storage service unit and the top-level namespace for other entities.
• Instance: One Silo server process on a node, managing local disks.
• Node: An implicitly declared hardware resource that runs Linux and Systemd.

Silo also retains the Storage Pool concept for expansion.

Deployment Modes

Silo supports Pigsty’s three inventory deployment modes:

For a quick SNSD experiment, you can use a regular directory. For multiple drives, use real disk mount points. Otherwise, Silo refuses to start.

Examples

This example explicitly selects Silo, the current default backend, and defines a four-node cluster with multiple drives:

minio:
  hosts:
    10.10.10.10: { minio_seq: 1 }
    10.10.10.11: { minio_seq: 2 }
    10.10.10.12: { minio_seq: 3 }
    10.10.10.13: { minio_seq: 4 }
  vars:
    minio_cluster: minio
    minio_type: silo
    minio_data: '/data{1...4}'
    minio_node: '${minio_cluster}-${minio_seq}.pigsty'

The configuration defines four Silo nodes with four disks each. Instance identifiers retain MINIO compatibility names:

Identity Parameters

The MINIO parameter group assigns deterministic identities to MINIO entities. Two parameters are required:

Set the cluster name at cluster level and the instance number at instance level. Pigsty generates unique identifiers with these rules:

MINIO uses the existing hostname or IP address as the host node identity. It does not assign another identity. minio_node generates internal Silo node names for cluster discovery in /etc/hosts. These names do not identify the host node.

Roles find members throughout the inventory by minio_cluster. The Ansible group name can differ from the cluster name. The retained backend selector minio_type currently must be silo.

Core Configuration Parameters

These parameters are also critical for Silo cluster configuration:

These parameters determine minio_volumes, which the role writes to Silo’s MINIO_VOLUMES:

• SNSD: Direct minio_data value, e.g., /data/minio
• SNMD: Expanded minio_data directories, e.g., /data{1...4}
• MNMD: Combined minio_node and minio_data, e.g., https://minio-{1...4}.pigsty:9000/data{1...4}

Ports & Services

Each object-storage instance listens on the following ports:

MINIO enables HTTPS by default through minio_https. For the default pgBackRest S3 repository configuration, keep HTTPS enabled and install the Pigsty CA correctly.

Clients can reach a multi-node Silo cluster through any member. For a stable entry point, use a load balancer such as HAProxy with a VIP.

Resource Provisioning

After deployment, Pigsty creates these Silo resources. minio_provision controls this step:

Default Buckets (defined by minio_buckets):

Default Users (defined by minio_users):

These public default credentials are only for demonstrations and local development. Replace them before production deployment.

pgbackrest serves PostgreSQL cluster backups. The reserved users s3user_meta and s3user_data are not actively used.

Monitoring Label System

Pigsty uses these identity parameters to identify object storage entities. This example shows a Silo availability series:

minio_up{cls="minio", ins="minio-1", ip="10.10.10.10", job="minio"}
minio_up{cls="minio", ins="minio-2", ip="10.10.10.11", job="minio"}
minio_up{cls="minio", ins="minio-3", ip="10.10.10.12", job="minio"}
minio_up{cls="minio", ins="minio-4", ip="10.10.10.13", job="minio"}

cls, ins, and ip identify the cluster name, instance name, and node IP. For monitoring compatibility, job="minio" remains unchanged. The current backend label is flavor=silo. See the metric list for details.

5 - E-R Model of Redis Cluster

The Redis module organizes production Redis into clusters. A cluster is a logical entity with Redis instances on one or more nodes.

Each cluster is an autonomous, high-performance cache or storage unit with at least one Redis instance. It exposes services through ports.

There are three core entities in Pigsty’s Redis module:

• Cluster: An autonomous Redis service unit and the top-level namespace for other entities.
• Instance: One Redis server process using a specific port on a node.
• Node: An implicitly declared hardware resource that runs Linux and Systemd. It can host multiple Redis instances.

Redis usually runs multiple instances per node, unlike PostgreSQL. This uses multiple CPU cores on a physical server or VM. Nodes and instances therefore have a 1:N relationship. For production, Redis instances with more than 12 GB of memory are generally discouraged.

Operating Modes

redis_mode selects one of three Redis modes:

• Standalone: The default mode. Set replication with replica_of. HA requires a separate Sentinel cluster.
• Sentinel: Monitor standalone clusters and provide automatic failover. Sentinel stores no business data. Multiple nodes provide HA for Sentinel itself.
• Native Cluster: Automatically shard data across multiple primaries. Each primary can have multiple replicas. Built-in HA removes the need for Sentinel.

Examples

The following examples show each mode.

Standalone Cluster

Classic master-replica on a single node:

redis-ms:
  hosts:
    10.10.10.10:
      redis_node: 1
      redis_instances:
        6379: { }
        6380: { replica_of: '10.10.10.10 6379' }
  vars:
    redis_cluster: redis-ms
    redis_password: 'redis.ms'
    redis_max_memory: 64MB

Sentinel Cluster

This example puts three Sentinel instances on one node. redis_sentinel_monitor specifies the standalone clusters they monitor:

redis-sentinel:
  hosts:
    10.10.10.11:
      redis_node: 1
      redis_instances: { 26379: {}, 26380: {}, 26381: {} }
  vars:
    redis_cluster: redis-sentinel
    redis_password: 'redis.sentinel'
    redis_mode: sentinel
    redis_max_memory: 16MB
    redis_sentinel_monitor:
      - { name: redis-ms, host: 10.10.10.10, port: 6379, password: redis.ms, quorum: 2 }

Native Cluster

This native distributed cluster has two nodes and six instances: the minimum specification of three primaries and three replicas.

redis-test:
  hosts:
    10.10.10.12: { redis_node: 1, redis_instances: { 6379: {}, 6380: {}, 6381: {} } }
    10.10.10.13: { redis_node: 2, redis_instances: { 6379: {}, 6380: {}, 6381: {} } }
  vars:
    redis_cluster: redis-test
    redis_password: 'redis.test'
    redis_mode: cluster
    redis_max_memory: 32MB

This creates a 3 primary 3 replica native Redis cluster.

Identity Parameters

The REDIS parameter group assigns deterministic identities to Redis entities. Three parameters are required:

Set the cluster name at cluster level. Set the node number and instance definitions at node level. Pigsty generates these unique identifiers:

Redis uses the existing hostname or IP address as the host node identity. It does not assign another identity. redis_node names instances, not host nodes.

Instance Definition

redis_instances is a JSON object. Each key is a port number; its value is the instance configuration:

redis_instances:
  6379: { }                                      # Primary instance, no extra config
  6380: { replica_of: '10.10.10.10 6379' }       # Replica, specify upstream primary
  6381: { replica_of: '10.10.10.10 6379' }       # Replica, specify upstream primary

Each Redis instance must use a unique port on its node. Avoid reserved ports below 1024 and conflicts with Pigsty ports. In standalone mode, replica_of defines replication. Use format '<ip> <port>' to specify the upstream primary address and port.

Each Redis node also runs Redis Exporter to collect metrics from all local instances:

The Redis deployment model has these limits:

• Node Exclusive: A node can belong to only one Redis cluster at a time.
• Port Unique: Instances on the same node must use different ports.
• Password Shared: Instances on the same node must share a password because of a redis_exporter limitation.
• Manual HA: Standalone clusters require additional Sentinel configuration for automatic failover.

Monitoring Label System

The built-in monitoring system uses these identity parameters to identify Redis entities.

redis_up{cls="redis-ms", ins="redis-ms-1-6379", ip="10.10.10.10", job="redis"}
redis_up{cls="redis-ms", ins="redis-ms-1-6380", ip="10.10.10.10", job="redis"}

The labels cls, ins, and ip identify the cluster name, instance name, and node IP. They accompany job in all Redis metrics collected by VictoriaMetrics. The Redis metrics job is always redis.