Setup on PIGSTY

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Install Pigsty with 4 steps: Prepare, Download, Configure and Install.

Also check offline installation if you don’t have the Internet access.

Short Version

Prepare a fresh Linux x86_64 node that runs compatible OS, then run as a sudo-able user:

curl -L https://get.pigsty.cc/install | bash -s v2.7.0

It will download Pigsty source to your home, then perform configure and install to finish the installation.

cd ~/pigsty   # get pigsty source and entering dir
./bootstrap   # download bootstrap pkgs & ansible [optional]
./configure   # pre-check and config templating   [optional]
./install.yml # install pigsty according to pigsty.yml

A pigsty singleton node will be ready with Web Interface on port 80/443 and Postgres service on port 5432. You can add more nodes into Pigsty and deploy modules on them.

Offline Install

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty’s Standard Installation process requires Internet access, but production database servers are often isolated from the Internet.

Therefore, Pigsty offers an offline installation feature, allowing you to complete the installation and deployment in an environment without internet access.

If you have internet access, downloading the pre-made Offline Package in advance can help speed up the installation process and enhance the certainty and reliability of the installation.

Short Version

You have to download the Pigsty source tarball and the Offline Package in addition to the Standard Installation.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty treats Infra & Database as Code. You can describe the infrastructure & database clusters through a declarative interface. All your essential work is to describe your need in the inventory, then materialize it with a simple idempotent playbook.

Inventory

Each pigsty deployment has a corresponding config inventory. It could be stored in a local git-managed file in YAML format or dynamically generated from CMDB or any ansible compatible format. Pigsty uses a monolith YAML config file as the default config inventory, which is pigsty.yml, located in the pigsty home directory.

Preparation

Mon, 01 Jan 0001 00:00:00 +0000

Node

Pigsty supports the Linux kernel and x86_64/amd64 arch, applicable to any node.

A “node” refers to a resource that is SSH accessible and offers a bare OS environment, such as a physical machine, a virtual machine, or an OS container equipped with systemd and sshd.

Deploying Pigsty requires at least 1 node. The minimum spec requirement is 1C1G, but it is recommended to use at least 2C4G, with no upper limit: parameters will automatically optimize and adapt.

Planning

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty v2.7 planning starts by selecting a deployment topology and preparing the matching hosts, operating systems, network, and administrator access.

Planning Checklist

Choose a single-node, monitoring-only, or highly available topology from the provisioning guide and configuration examples.
Verify CPU architecture, operating-system release, storage, and network requirements in Prepare and the compatibility matrix.
Reserve stable node addresses, hostnames, required ports, and passwordless administrator SSH/sudo access before installation.
Decide between online and offline installation and prepare the corresponding software source or offline package.
Review the inventory in Configuration and the security checklist before running playbooks.

The exact cluster, user, database, service, and backup settings remain in the linked v2.7 pages; this page is only the historical planning entry point.

Playbooks

Mon, 01 Jan 0001 00:00:00 +0000

Playbooks are used in Pigsty to install modules on nodes.

To run playbooks, just treat them as executables. e.g. run with ./install.yml.

Playbooks

Here are default playbooks included in Pigsty.

Playbook	Function
`install.yml`	Install Pigsty on current node in one-pass
`infra.yml`	Init pigsty infrastructure on infra nodes
`infra-rm.yml`	Remove infrastructure components from infra nodes
`node.yml`	Init node for pigsty, tune node into desired status
`node-rm.yml`	Remove node from pigsty
`pgsql.yml`	Init HA PostgreSQL clusters, or adding new replicas
`pgsql-rm.yml`	Remove PostgreSQL cluster, or remove replicas
`pgsql-user.yml`	Add new business user to existing PostgreSQL cluster
`pgsql-db.yml`	Add new business database to existing PostgreSQL cluster
`pgsql-monitor.yml`	Monitor remote postgres instance with local exporters
`pgsql-migration.yml`	Generate Migration manual & scripts for existing PostgreSQL
`redis.yml`	Init redis cluster/node/instance
`redis-rm.yml`	Remove redis cluster/node/instance
`etcd.yml`	Init etcd cluster (required for patroni HA DCS)
`minio.yml`	Init minio cluster (optional for pgbackrest repo)
`cert.yml`	Issue cert with pigsty self-signed CA (e.g. for pg clients)
`docker.yml`	Install docker on nodes
`mongo.yml`	在节点上安装 Mongo/FerretDB

One-Pass Install

Provisioning

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty runs on nodes, which are Bare Metals or Virtual Machines. You can prepare them manually, or using terraform & vagrant for provisioning.

Sandbox

Pigsty has a sandbox, which is a 4-node deployment with fixed IP addresses and other identifiers. Check demo.yml for details.

The sandbox consists of 4 nodes with fixed IP addresses: 10.10.10.10, 10.10.10.11, 10.10.10.12, 10.10.10.13.

There’s a primary singleton PostgreSQL cluster: pg-meta on the meta node, which can be used alone if you don’t care about PostgreSQL high availability.

Security

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty already provides a secure-by-default authentication and access control model, which is sufficient for most scenarios.

But if you want to further strengthen the security of the system, the following suggestions are for your reference:

Confidentiality

Important Files

Secure your pigsty config inventory

pigsty.yml has highly sensitive information, including passwords, certificates, and keys.
You should limit access to admin/infra nodes, only accessible by the admin/dba users
Limit access to the git repo, if you are using git to manage your pigsty source.

Secure your CA private key and other certs

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

How to install Docker ？

Install with the docker.yml playbook, targeting at any node managed by Pigsty.

./docker.yml -l <selector>

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

What is the impact of ETCD failure?

ETCD availability is critical for the PGSQL cluster’s HA, which is guaranteed by using multiple nodes. With a 3-node ETCD cluster, if one node is down, the other two nodes can still function normally; and with a 5-node ETCD cluster, two-node failure can still be tolerated. If more than half of the ETCD nodes are down, the ETCD cluster and its service will be unavailable. Before Patroni 3.0, this could lead to a global PGSQL outage; all primary will be demoted and reject write requests.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Which components are included in INFRA

Ansible for automation, deployment, and administration;
Nginx for exposing any WebUI service and serving the yum/apt repo;
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 sync on the admin node.
DNSMasq for DNS registration and resolution.
ETCD as DCS for PGSQL 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:

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Fail to launch multi-node / multi-driver MinIO cluster.

In Multi-Driver or Multi-Node mode, MinIO will refuse to start if the data dir is not a valid mount point.

Use mounted disks for MinIO data dir rather than some regular directory. You can use the regular directory only in the single node, single drive mode.

How to deploy a multi-node multi-drive MinIO cluster?

Check Create Multi-Node Multi-Driver MinIO Cluster

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Install mongosh

cat > /etc/yum.repos.d/mongo.repo <<EOF
[mongodb-org-7.0]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/$releasever/mongodb-org/7.0/x86_64/
gpgcheck=0
enabled=1
EOF

yum install -y mongodb-mongosh

# or just install via rpm & links
rpm -ivh https://mirrors.tuna.tsinghua.edu.cn/mongodb/yum/el7/RPMS/mongodb-mongosh-1.9.1.x86_64.rpm

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

How to configure NTP service?

If NTP is not configured, use a public NTP service or sync time with the admin node.

If your nodes already have NTP configured, you can leave it there by setting node_ntp_enabled to false.

Otherwise, if you have Internet access, you can use public NTP services such as pool.ntp.org.

If you don’t have Internet access, at least you can sync time with the admin node with the following:

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

ABORT due to existing redis instance

use redis_clean = true and redis_safeguard = false to force clean redis data

This happens when you run redis.yml to init a redis instance that is already running, and redis_clean is set to false.

If redis_clean is set to true (and the redis_safeguard is set to false, too), the redis.yml playbook will remove the existing redis instance and re-init it as a new one, which makes the redis.yml playbook fully idempotent.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

If you have any unlisted questions or suggestions, please create an Issue or ask the community for help.

How to Get the Pigsty Source Package?

Use the following command to install Pigsty with one click: bash -c "$(curl -fsSL https://get.pigsty.cc/install)" -- v2.7.0

This command will automatically download the latest stable version pigsty.tgz and extract it to the ~/pigsty directory. You can also manually download a specific version of the Pigsty source code from the following locations.