Ansible

Pigsty implements admin controllers with Ansible, which is an open source automation tool for managing large-scale infrastructure in an Infra-as-Code (IaC) manner. Widely used in the industry by operators.

Install

Pigsty will try its best to install ansible and its dependencies during bootstrap. But you can always install it manually, it is available on most OS's official repos and can be installed with one command.

Install Ansible

Playbooks also require a weak dependency: the jmespath python package.

cd ~/pigsty; ./bootstrap

sudo apt install -y ansible python3-jmespath

sudo dnf install -y ansible python3.12-jmespath

sudo yum install -y ansible python-jmespath

brew install ansible
pip3 install jmespath

macOS

Ansible is available on macOS too. You can install Ansible on your Mac with Homebrew. And use it as the admin node to manage remote cloud server. It's convenient if you are deploying a single-node pigsty on cloud VPS. But not recommended for production use.

Basics

Knowledge about Ansible is good but NOT REQUIRED. You only need to know how to run Ansible Playbooks. Playbooks are executable YAML files that contain a series of tasks to be executed.

Running the ./node.yml playbook essentially translates to ansible-playbook node.yml. The hashbang at the top of the file makes it directly executable. And you can use Args to control the playbook execution:

~/pigsty

./node.yml                         # run infra playbook on all hosts
./pgsql.yml -l pg-test             # run pgsql playbook on pg-test cluster
./infra.yml -t repo                # run subtask repo of infra.yml
./pgsql-rm.yml -e pg_rm_pkg=false  # remove pgsql, but keep packages

The following 4 parameters need your attention to use ansible effectively:

Purpose	Parameter	Description
Where	`-l\|--limit <pattern>`	Limit execution target on specific group/host/pattern
What	`-t\|--tags <tags>`	Only run tasks with specific tags
How	`-e\|--extra-vars <vars>`	Extra command line arguments
Config	`-i\|--inventory <path>`	Using a specific inventory file

Limit Host

The execution target of a playbook can be limited with -l|--limit <selector>. It is handy when trying to run playbooks on a specific host/node or group/clusters. Here are some examples of host limits:

./pgsql.yml                              # run on all hosts (dangerous!)
./pgsql.yml -l pg-test                   # run on pg-test cluster
./pgsql.yml -l 10.10.10.10               # run on single host 10.10.10.10
./pgsql.yml -l pg-*                      # run on host/group matching glob pattern `pg-*`
./pgsql.yml -l '10.10.10.11,&pg-test'    # run on 10.10.10.11 of group pg-test
./pgsql-rm.yml -l 'pg-test,!10.10.10.11' # run on pg-test, except 10.10.10.11
./pgsql.yml -l pg-test                   # Execute the pgsql playbook against the hosts in the pg-test cluster

Check all details in the ansible docs: Patterns: targeting hosts and groups

Running playbook without host limit can be Dangerous!

Missing this value could be dangerous, since most playbooks will execute on all hosts. DO USE WITH CAUTION.

Limit Task

The execution tasks can be controlled with -t|--tags <tags>. If specified, tasks with given tags will be executed instead of the ENTIRE playbook. Here are some task limit examples:

./infra.yml -t repo          # create repo
./node.yml  -t node_pkg      # install node packages
./pgsql.yml -t pg_install    # install pg packages & extensions
./etcd.yml  -t etcd_purge    # nuke the etcd cluster
./minio.yml -t minio_alias   # write minio cli config

To run multiple tasks, specify multiple tags and separate with comma: -t tag1,tag2:

./node.yml  -t node_repo,node_pkg   # add repo, then install packages
./pgsql.yml -t pg_hba,pg_reload     # config, then reload pg hba rules

Extra Vars

You can override config param at runtime with cli args, it has the highest precedence.

Extra command-line args can be passed via -e|--extra-vars KEY=VALUE, it can be used multiple times:

# create admin with another admin user
./node.yml -e ansible_user=admin -k -K -t node_admin

# init a specific redis instance: 10.10.10.11:6379
./redis.yml -l 10.10.10.10 -e redis_port=6379 -t redis

# remove postgres, but keeps packages and data
./pgsql-rm.yml -e pg_rm_pkg=false -e pg_rm_data=false

for complex parameters, JSON string can be used:

# add repo and install package
./node.yml -t node_install -e '{"node_repo_modules":"infra","node_packages":["duckdb"]}'

Designate Inventory

The default config file is pigsty.yml in the pigsty home directories.

You can use the -i <path> parameter to specify a different Inventory file path.

./pgsql.yml -i conf/rich.yml            # initialize a single node with all extensions downloaded according to rich config
./pgsql.yml -i conf/full.yml            # initialize a 4-node cluster according to full config
./pgsql.yml -i conf/app/supa.yml        # initialize a 1-node Supabase deployment according to supa.yml config

Change Default Inventory File

To permanently change the default config file, change the inventory parameter in the ansible.cfg.