--- obj: application website: https://www.ansible.com repo: https://github.com/ansible/ansible --- # Ansible Ansible is an open-source automation tool that simplifies configuration management, application deployment, and task automation. ## Inventory The inventory contains all the host. The simplest inventory is a single file with a list of hosts and groups. The default location for this file is `/etc/ansible/hosts`. You can specify a different inventory file at the command line using the `-i ` option or in configuration using `inventory`. Example: ```toml mail.example.com [webservers] foo.example.com bar.example.com [dbservers] one.example.com two.example.com three.example.com ``` You can specify variables for the hosts: ```toml [atlanta] host1 host2 [atlanta:vars] ntp_server=ntp.atlanta.example.com proxy=proxy.atlanta.example.com ``` ## Command Line Tools ### ansible Define and run a single task ‘playbook’ against a set of hosts #### Options | Option | Description | | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--become-method ` | privilege escalation method to use (default=sudo), use ansible-doc -t become -l to list valid choices. | | `--become-password-file , --become-pass-file ` | Become password file | | `--become-user ` | run operations as this user (default=root) | | `--list-hosts` | outputs a list of matching hosts; does not execute anything else | | `--playbook-dir ` | Since this tool does not use playbooks, use this as a substitute playbook directory. This sets the relative path for many features including roles/ group_vars/ etc. | | `--private-key , --key-file ` | use this file to authenticate the connection | | `--vault-password-file, --vault-pass-file` | vault password file | | `-J, --ask-vault-password, --ask-vault-pass` | ask for vault password | | `-K, --ask-become-pass` | ask for privilege escalation password | | `-b, --become` | run operations with become (does not imply password prompting) | | `-e, --extra-vars` | set additional variables as key=value | | `-i, --inventory` | specify inventory host path or comma separated host list | | `-k, --ask-pass` | ask for connection password | | `-l , --limit ` | further limit selected hosts to an additional pattern | | `-m , --module-name ` | Name of the action to execute (default=command) | | `-t , --tree ` | log output to this directory | | `-u , --user ` | connect as this user (default=None) | ### ansible-playbook Runs Ansible playbooks, executing the defined tasks on the targeted hosts. Usage: `ansible-playbook [option]... [playbook]` > **Note**: You can run a playbook on an individual host with `ansible-playbook playbook.yml -i , -l ` #### Options | Option | Description | | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | | `--become-method ` | privilege escalation method to use (default=sudo), use ansible-doc -t become -l to list valid choices. | | `--become-password-file , --become-pass-file ` | Become password file | | `--become-user ` | run operations as this user (default=root) | | `--list-hosts` | outputs a list of matching hosts; does not execute anything else | | `--list-tasks` | list all tasks that would be executed | | `--private-key , --key-file ` | use this file to authenticate the connection | | `--vault-password-file, --vault-pass-file` | vault password file | | ` -J, --ask-vault-password, --ask-vault-pass` | ask for vault password | | `-K, --ask-become-pass` | ask for privilege escalation password | | `-b, --become` | run operations with become (does not imply password prompting) | | `-e, --extra-vars` | set additional variables as key=value | | `-i, --inventory` | specify inventory host path or comma separated host list | | `-k, --ask-pass` | ask for connection password | | `-l , --limit ` | further limit selected hosts to an additional pattern | | `-t , --tree ` | log output to this directory | | `-u , --user ` | connect as this user (default=None) | | ` --syntax-check` | perform a syntax check on the playbook, but do not execute it | ### ansible-vault encryption/decryption utility for Ansible data files. Ansible vault gives you the ability to securely store sensitive information besides your playbooks and use them normally as variables if you have the encryption key. Usage: `ansible-vault [action] [options]...` #### create This command creates a new ansible vault file. Usage: `ansible-vault create [--vault-password-file, --vault-pass-file] vault.yml` #### decrypt decrypt the supplied file using the provided vault secret. Usage: `ansible-vault decrypt [--vault-password-file, --vault-pass-file] --output out.yml vault.yml` #### encrypt encrypt the supplied file using the provided vault secret. Usage: `ansible-vault encrypt [--vault-password-file, --vault-pass-file] --output vault.yml in.yml` #### edit open and decrypt an existing vaulted file in an editor, that will be encrypted again when closed. Usage: `ansible-vault edit [--vault-password-file, --vault-pass-file] vault.yml` #### view open, decrypt and view an existing vaulted file using a pager using the supplied vault secret. Usage: `ansible-vault view [--vault-password-file, --vault-pass-file] vault.yml` ## Playbooks Playbooks are automation blueprints, in [YAML](../../files/YAML.md) format, that Ansible uses to deploy and configure nodes in an inventory. You can use variables with this syntax `{{ result.stdout | from_json }}`. Example playbook: ```yml - name: GPU Passthrough hosts: pve become: true vars_prompt: - name: pcie_hw_ids prompt: "Enter PCIE Hardware IDs" private: false tasks: - name: Enable iommu (amd) ansible.builtin.lineinfile: dest: /etc/default/grub regexp: .*GRUB_CMDLINE_LINUX_DEFAULT.* line: | GRUB_CMDLINE_LINUX_DEFAULT="quiet amd_iommu=on iommu=pt pcie_acs_override=downstream,multifunction nofb nomodeset video=vesafb:off video=efifb:off" register: grub_cfg - name: Enable vfio modules ansible.builtin.blockinfile: dest: /etc/modules block: | vfio vfio_iommu_type1 vfio_pci vfio_virqfd - name: Set vfio configuration ansible.builtin.copy: dest: /etc/modprobe.d/vfio.conf owner: root mode: "0644" content: | options vfio-pci ids={{ pcie_hw_ids }} - name: Blacklist drivers become: true ansible.builtin.copy: dest: /etc/modprobe.d/gpu-blacklist.conf content: | blacklist radeon blacklist nouveau blacklist nvidia blacklist amdgpu blacklist snd_hda_intel - name: Update grub ansible.builtin.shell: cmd: grub-mkconfig -o /boot/grub/grub.cfg when: grub_cfg.changed ``` ### Playbook fields - **`name`**: A human-readable description for the task. ```yml - name: My Playbook hosts: all tasks: - name: My Task ... ``` - **`hosts`**: Specifies the target hosts or groups from inventory on which the tasks should be executed. ```yml - name: My Playbook hosts: web_servers tasks: ... ``` - **`gather_facts`**: A boolean indicating whether Ansible should gather facts about the target hosts before executing tasks. ```yml - name: My Playbook hosts: all gather_facts: true tasks: ... ``` - **`become`**: Indicate that tasks should be executed with escalated privileges (sudo). ```yml - name: My Playbook hosts: all become: true tasks: ... ``` - **`become_user`**: Specify the user to become when using privilege escalation. ```yml - name: My Playbook hosts: all become: true become_user: someuser tasks: ... ``` - **`vars`**: Define variables that can be used in the playbook. ```yml - name: My Playbook hosts: all vars: my_variable: "value" tasks: ... ``` - **`vars_files`**: Include external variable files. ```yml - name: My Playbook hosts: all vars_files: - my_vars.yml tasks: ... ``` - **`vars_prompt`**: Get info from user. ```yml - hosts: all vars_prompt: - name: username prompt: What is your username? private: false - name: password prompt: What is your password? tasks: - name: Print a message ansible.builtin.debug: msg: 'Logging in as {{ username }}' ``` - **`include`** or **`import`**: Include or import other playbooks. ```yml - name: My Playbook hosts: all tasks: - include: other_playbook.yml ``` - **`include_vars`**: Include external variable files dynamically. ```yml - name: Include external variables include_vars: file: external_vars.yml ``` - **`tasks`**: A list of tasks to be executed. Each task is defined as a dictionary. ```yml - name: My Playbook hosts: all tasks: - name: Task 1 ... - name: Task 2 ... ``` - **`environment`**: Set environment variables for a task. ```yml - name: Run a command with a specific environment command: echo $MY_VARIABLE environment: MY_VARIABLE: "some_value" ``` - **`when`**: Specifies a condition for executing a task. ```yml tasks: - name: Shut down Debian flavored systems ansible.builtin.command: /sbin/shutdown -t now when: ansible_facts['os_family'] == "Debian" ``` - **`register`**: Save the result of a task into a variable for later use. ```yml - name: Execute a command and register the output command: echo "Hello, World!" register: command_output - name: Display the registered output debug: var: command_output.stdout ``` - **`loop`**: Execute module multiple times ```yml - name: Add several users ansible.builtin.user: name: "{{ item }}" state: present groups: "wheel" loop: - testuser1 - testuser2 ``` See these pages for usage in your playbooks.: - [Ansible Filters](filters/Ansible%20Filters.md) - [Ansible Lookup Plugins](lookups/Ansible%20Lookup%20Plugins.md) - [Ansible Modules](modules/Ansible%20Modules.md) - [Ansible Test Plugins](tests/Ansible%20Test%20Plugins.md)