# Ansible > Get started with basic ansible concepts --- Pigsty implements admin controllers with [Ansible](https://docs.ansible.com/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**](/docs/install/start#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. ```bash tab="Default" cd ~/pigsty; ./bootstrap ``` ```bash tab="Debian / Ubuntu" sudo apt install -y ansible python3-jmespath ``` ```bash tab="EL 10" sudo dnf install -y ansible python-jmespath ``` ```bash tab="EL 8/9" sudo dnf install -y ansible python3.12-jmespath ``` ```bash tab="EL 7" sudo yum install -y ansible python-jmespath ``` ```bash tab="macOS" brew install ansible pip3 install jmespath ``` Beware that el10 epel does not offer the `ansible` package, which is fixed by [Pigsty PGDG](https://pgext.cloud/repo/pgsql) el10 repo ### macOS Ansible is available on macOS too. You can install Ansible on your Mac with [**Homebrew**](https://brew.sh/). 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**](/docs/admin/playbook). 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: ```bash {title="~/pigsty"} ./node.yml # run infra playbook on all nodes ./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**](#limit-host) | `-l\|--limit ` | Limit execution target on specific group/host/pattern | | [**What**](#limit-task) | `-t\|--tags ` | Only run tasks with specific tags | | [**How**](#extra-vars) | `-e\|--extra-vars ` | Extra command line arguments | | [**Config**](#designate-inventory) | `-i\|--inventory ` | Using a specific inventory file | -------- ## Limit Host The **execution target** of a playbook can be limited with `-l|--limit `. It is handy when trying to run playbooks on a specific host/node or group/clusters. Here are some examples of host limits: ```bash ./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](https://docs.ansible.com/ansible/latest/inventory_guide/intro_patterns.html) **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 `. If specified, tasks with given tags will be executed instead of the ENTIRE playbook. Here are some task limit examples: ```bash ./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`: ```bash ./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**](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#understanding-variable-precedence). Extra command-line args can be passed via `-e|--extra-vars KEY=VALUE`, it can be used multiple times: ```bash # 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: ```bash # 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 ` parameter to specify a different [**Inventory**](/docs/config/inventory) file path. ```bash ./pgsql.yml -i conf/rich.yml # initialize a single node with all extensions downloaded according to rich config ./pgsql.yml -i conf/ha/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`](https://github.com/pgsty/pigsty/blob/v3.7.0/ansible.cfg#L6).