Identity Management

How does identity been managed in pigsty?

All instances have Identity, which is the metadata associated with the instance that identifies it.


Figure : Identity information with Postgres service when using Consul service discovery

Identity parameters

[identity-parameters](. /… /… /config/7-pg-provision/# identity-parameters) is a unique identifier that must be defined for any cluster and instance.

name variables type description
cluster [pg_cluster](… /… /… /config/7-pg-provision/#pg_cluster) Core identity parameters Cluster name, top-level namespace for resources within the cluster
role [pg_role](. /… /… /config/7-pg-provision/#pg_role) Core identity parameters Instance role, primary, replica, offline, …
markers [pg_seq](… /… /… /config/7-pg-provision/#pg_seq) Core identity parameters Instance serial number, positive integer, unique within the cluster.
instance pg_instance derived identity parameter ${pg_cluster}-${pg_seq}
service pg_service derived identity parameters ${pg_cluster}-${pg_role}

Identity association

After naming the objects in the system, you also need to associate identity information to specific instances.

Identity information is business-given metadata, and the database instance itself is not aware of this identity information; it does not know who it serves, which business it is subordinate to, or what number of instances it is in the cluster.

Identity assignment can take many forms, and the most rudimentary way to associate identities is Operator’s memory: the DBA remembers in his mind that the database instance on IP address is the one used for payments, while the database instance on the other one is used for user management. A better way to manage the identity of cluster members is through profile, or by using service discovery.

Pigsty offers both ways of identity management: based on [Consul](. /identity/#consul service discovery), versus [Profile](. /identity/#static file service discovery)

Parameters [prometheus_sd_method (consul|static)](… /… /… /config/4-meta/#prometheus_sd_method) controls this behavior.

  • consul: service discovery based on Consul, default configuration
  • static: service discovery based on local configuration files

Pigsty recommends using consul service discovery, where the monitoring system automatically corrects the identity registered by the target instance when a Failover occurs on the server.

Consul service discovery

Pigsty by default uses Consul service discovery to manage the services in your environment.

All services in Pigsty are automatically registered to the DCS, so metadata is automatically corrected when database clusters are created, destroyed, or modified, and the monitoring system can automatically discover monitoring targets without the need to manually maintain the configuration. The monitoring system can automatically discover the monitoring targets, eliminating the need for manual configuration maintenance.

Users can also use the DNS and service discovery mechanism provided by Consul to achieve automatic DNS-based traffic switching.


Consul uses a Client/Server architecture, and there are 1 to 5 Consul Servers ranging from 1 to 5 in the whole environment for the actual metadata storage. The Consul Agent is deployed on all nodes to proxy the communication between the native services and the Consul Server. pigsty registers the services by default by means of the local Consul configuration file.

Service Registration

On each node, there is a consul agent running, and services are registered to the DCS by the consul agent via JSON configuration files.

The default location of the JSON configuration file is /etc/consul.d/, using the naming convention of svc-<service>.json, using postgres as an example.

  "service": {
    "name": "postgres",
    "port": {{ pg_port }},
    "tags": [
      "{{ pg_role }}",
      "{{ pg_cluster }}"
    "meta": {
      "type": "postgres",
      "role": "{{ pg_role }}",
      "seq": "{{ pg_seq }}",
      "instance": "{{ pg_instance }}",
      "service": "{{ pg_service }}",
      "cluster": "{{ pg_cluster }}",
      "version": "{{ pg_version }}"
    "check": {
      "tcp": "{{ pg_port }}",
      "interval": "15s",
      "timeout": "1s"



用户可以通过Consul提供的DNS服务,或者直接调用Consul API发现注册到Consul中的服务

使用DNS API查阅consul服务的方式,请参阅Consul文档

图:查询pg-bench-1上的 pg_exporter 服务。



- job_name: pg
    - server: localhost:8500
      refresh_interval: 5s
        - pg
        - exporter






/pg/bin/pg-register $(pg-role)




详见 Prometheus服务发现

./infra.yml --tags=prometheus_targtes,prometheus_reload


# File      :   targets/all.yml
# Ctime     :   2021-02-18
# Mtime     :   2021-02-18
# Desc      :   Prometheus Static Monitoring Targets Definition
# Path      :   /etc/prometheus/targets/all.yml
# Copyright (C) 2018-2021 Ruohang Feng

#======> pg-meta-1 [primary]
- labels: {cls: pg-meta, ins: pg-meta-1, ip:, role: primary, svc: pg-meta-primary}
  targets: [,,,]

#======> pg-test-1 [primary]
- labels: {cls: pg-test, ins: pg-test-1, ip:, role: primary, svc: pg-test-primary}
  targets: [,,,]

#======> pg-test-2 [replica]
- labels: {cls: pg-test, ins: pg-test-2, ip:, role: replica, svc: pg-test-replica}
  targets: [,,,]

#======> pg-test-3 [replica]
- labels: {cls: pg-test, ins: pg-test-3, ip:, role: replica, svc: pg-test-replica}
  targets: [,,,]



这一关联,是通过 监控指标维度标签实现的。

身份参数 维度标签 取值样例
pg_cluster cls pg-test
pg_instance ins pg-test-1
pg_services svc pg-test-primary
pg_role role primary
node_ip ip

阅读下一节 监控指标 ,了解这些指标是如何通过标签组织起来的。

Last modified 2021-03-28: update en docs (f994b54)