diff --git a/technology/tools/Ansible/Ansible.md b/technology/tools/Ansible/Ansible.md index 6972966..bc1f086 100644 --- a/technology/tools/Ansible/Ansible.md +++ b/technology/tools/Ansible/Ansible.md @@ -5,19 +5,304 @@ repo: https://github.com/ansible/ansible --- # Ansible -#wip #🐇 Ansible is an open-source automation tool that simplifies configuration management, application deployment, and task automation. ## Inventory --> https://docs.ansible.com/ansible/latest/inventory_guide/index.html +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 --> https://docs.ansible.com/ansible/latest/command_guide/index.html +### 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]` + +#### 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 --> https://docs.ansible.com/ansible/latest/playbook_guide/index.html +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 }}`. -See [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). +Example playbook: +```yml +- name: GPU Passthrough + hosts: pve + become: true + vars_prompt: + - name: pcie_hw_ids + prompt: "Enter PCIE Hardware IDs" + private: false -## Ansible Vault --> https://docs.ansible.com/ansible/latest/vault_guide/index.html + 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) \ No newline at end of file