Ansible Concepts

External

• https://docs.ansible.com/ansible/latest/reference_appendices/playbooks_keywords.html
• http://docs.ansible.com/ansible/glossary.html

Internal

• Ansible

Overview

Ansible is a configuration management and provisioning tool, similar to Chef, Puppet or Salt. What sets it aside is that it does not require agents on the hosts it configures - it only requires ssh access and sudo. The target hosts are specified in an inventory file, located on the Ansible host, the machine that is use to conduct operations from. Ansible executes on the Ansible host. During the execution, Ansible connects via SSH to the target hosts, gets the context and executes tasks on the target hosts, while being cognizant of the context. Being context-aware allows tasks to be idempotent. In the beginning, the inventory can be probed for availability for running a ping module:

ansible -i ./hosts.yaml <group-name|all> -m ping

The idempotence of tasks comes from the idempotence of their components, the modules. Modules are aware of the facts of the context.

Multiple tasks are grouped together in playbooks. A playbook is executed with the ansible-playbook command.

Playground Example

https://github.com/ovidiuf/playground/tree/master/ansible/sample

Hosts

Ansible Host

The host that executes the ansible or ansible-playbook command and that connects via SSH to other hosts to be managed with Ansible.

Target Host

The target hosts are specified in the inventory file. If there is no inventory file, localhost is implied. This document refers to target hosts as "systems".

localhost

The local host can be explicitly referred to as localhost.

Ansible Files

Ansible works with the following files, which are in YAML format:

• Inventory file
• Playbook file
• To be continued.

"#" can be used to comment in files.

Inventory File

https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html

Ansible works against multiple target hosts at the same time. It does this by selecting all or some of the target hosts listed in Ansible’s inventory file. The default location of the inventory file is /etc/ansible/host, but it can be placed anywhere and referred from the command line with -i <path-to-inventory-file>.

The conventional name is hosts.yaml.

Inventory File Structure

host1.example.com

[webservers]
web1.example.com
web2.example.com

[dbservers]
db1.example.com
db2.example.com

The inventory file can also be used to define inventory file variables, as group variables or host variables.

Groups

The headings in brackets are group names, which are arbitrary strings used in classifying systems and deciding what systems you are controlling at what times and for what purpose. A host can be part of more than one group.

Also see group variables below.

Default Groups

There are two default groups: "all" and "ungrouped". "all" contains every host. "ungrouped" contains all hosts that don’t have another group aside from "all".

Recursive Groups

Recursive groups are declared with the [<group-name>:children]:

[A]
host1
host2
 
[B]
host3
host4
 
[AandB:children]
A
B
 
[AandB:vars]
something=something-else

Dynamic Inventory

https://docs.ansible.com/ansible/latest/user_guide/intro_dynamic_inventory.html

Playbooks and Plays

https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html

Playbooks are YAML files that contain one or more plays in an ordered list. Each play executes part of the overall goal of the playbook. Each play includes at minimum two things:

• the managed hosts to target, declared with the keyword hosts:.

Optionally, a playbook may include:

• One or more tasks to be executed against the target hosts, listed under the tasks: keyword. A noop playbook may include no task and it will still execute. The reason for a playbook to exists is to declare tasks, which are executed in sequence at runtime, as part of the playbook.
• Variables, under the vars: subtree.
• Roles, under the roles: subtree. All roles specified here are are assigned to the configured hosts. If a list of roles is provided in a play, it is said that the roles are used "at the play" level, meaning that their tasks are added to the play. The name of roles specified under roles: keyword represent names of directories that contain the corresponding role's components. If a role name is specified in the play, the corresponding role directory, whose name is identical with the role name, is expected to be present in the following locations:
  • A roles subdirectory of the directory that contains the playbook.
  • In the directory that contains the playbook.
  • $HOME/.ansible/roles
  • /usr/share/ansible/roles
  • /etc/ansible/roles
• 'become' keywords.
• remote_users
• pre_tasks
• Other playbooks, imported with import_playbook.

Playbook File

---
- name: play one
  hosts: all # For the local host, use 'localhost'
  become: yes
  become_user: root
  vars:
    some_var: something
  pre_tasks:
    - import_tasks: tasks/some_tasks.yml
  roles:
    - kubernetes-local-storage
  tasks:
    - name: Install Nginx
      apt:
        name: nginx
        state: installed
        update_cache: true
- name: play two
  hosts: ...
  tasks:
    - ...

import_playbook

A playbook can include other playbooks:

---
- import_playbook: some-other-playbook.yml

ansible-playbook

A playbook is executed with the ansible-playbook command. For more details see:

ansible-playbook

Task

https://docs.ansible.com/ansible/latest/reference_appendices/playbooks_keywords.html#task

A task gives a name to an action, which consists of a module and its arguments.

The task may optionally specify an execution condition.

The task may also optionally specify that the action should be executed in a loop, if looping directives are present.

The task may register a variable which, upon execution, contains the task status and module execution result data.

- name: some task
  <module-name>:             #
    <module-arg-1>: value 1  #
    <module-arg-2>: value 2  # this is the action
    <module-arg-3>: value 3  #
    ...                      #
  when: <conditional> 
  register: <variable-name>
  <loop-construct>

Example:

- name: Create some directories
  file:
    path: "{{ item }}"
    state: directory
    owner: ec2-user
  when: inventory_hostname in groups['blue']
  become: true
  register: some_var
  with_items:
    - "/tmp/a"
    - "/tmp/b"
    - "{{ some_dir_variable }}"

Handlers are also tasks, but they do not run unless they are notified by name when a task reports an underlying change on a target host.

Playbooks exist to declare tasks, which are then executed at runtime as part of the playbook.

Task Idempotence

Ansible tasks are idempotent, they can be safely run repeatedly. Idempotence is achieved by the fact that ansible first gathers the context, which consists of facts, before running the tasks. Ansible "checks the facts" first to decide whether it needs to change anything. If the outcome it seeks is already achieved, the task is not executed.

Importing Tasks

Tasks can be imported recursively in where? with import_tasks:

---
- import_tasks: some-file-that-contains-tasks.yaml
- import_tasks: some-dir/some-other-file-that-contains-tasks.yaml

Task Configuration

https://docs.ansible.com/ansible/latest/reference_appendices/playbooks_keywords.html#task

name

A task identifier that can be used for documentation. Gives a user-friendly name for the action executed as part of this task.

register

Specifies the name of the variable that will reference the module return value. See:

Module Return Value

vars

A map of variables.

args

A secondary way to add arguments into a task. Takes a dictionary in which the keys are the underlying module's valid argument names, while the values are the corresponding argument values. For example, if the module car has color as an argument, it can be configured this way:

- name: an example
  car:
  args:
    color: blue

This is equivalent with:

- name: an example
  car:
    color: blue

If both args and the module's argument are specified, the module's argument takes precedence. In this example:

- name: an example
  car:
    color: red
  args:
    color: blue

the "car" is configured to "red".

Loops

Looping directives: with_items, loop, loop_control, with_<lookup_plugin>:

Task Looping Directives

when - Conditional Task Execution

https://docs.ansible.com/ansible/latest/user_guide/playbooks_conditionals.html

Tasks can be conditionally executed based on facts, registered variables or playbook or inventory variables. The conditional is introduced by the task configuration keyword when:.

- name: Download Amazon Corretto
  get_url:
    url: https://corretto.aws/downloads/latest/amazon-corretto-11-x64-macos-jdk.pkg
    dest: /tmp
  when: java_vendor == "Amazon"

- name: Install Nginx
    apt:
      pkg: nginx
      state: installed
      update_cache: true
    when: ppastable|success
    notify:
     - Start Nginx

become Keywords

become

Boolean that controls if privilege escalation is used or not on task execution. Implemented by the become plugin.

- name: Some task
  become: true
  [...]

become_exe

The path of the executable used to elevate privileges. Implemented by the become plugin.

become_flags

A string of flag(s) to pass to the privilege escalation program when become is true.

become_method

Which method of privilege escalation to use (such as sudo or su).

- name: Some task
  become_method: sudo
  [...]

become_user

User that you ‘become’ after using privilege escalation. The remote/login user must have permissions to become this user.

Action

An action is a module and its arguments. The action is part of a task. A task can have one and only one action.

Module

Modules are the "verbs" in Ansible, they do things, like install software, copy files, use templates and so on. Modules can use available context (facts) in order to determine what actions, if any, need to be done to accomplish a task. Thus, they insure idempotence of the tasks that execute them.

A module can be executed individually, on command line, in the same way as it would be executed as part of a playbook.

ansible -m <module-name> -a "arg1 arg2 ..."

Example:

ansible -m shell -a "echo {{ a_global_variable }} > /tmp/test.txt"

A module is declared as follows:

- name: This is a descriptive name of what the module execution will achieve
  <module-name>: ...
  ...

Example:

- name: This is a descriptive name of what the module execution will achieve
  shell: echo {{ openshift_dns_ip }} > /etc/origin/node/openshift-dns-ip
  args:
    executable: /bin/bash

For more details on module and task syntax, see Task above.

Modules by Category

Module collections: https://docs.ansible.com/ansible/latest/collections/index.html#list-of-collections

Ansible built-in modules: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/index.html#plugins-in-ansible-builtin

Ansible utils modules: https://docs.ansible.com/ansible/latest/collections/ansible/utils/index.html#plugins-in-ansible-utils

Category	Modules
Setting facts	set_fact
Troubleshooting and diagnostics	debug assert
Voluntary failure	fail
Arbitrary command execution	command shell script
Installers	homebrew homebrew_cask yum
File manipulation	template copy file: manage file and directory properties: create files, set attributes, remove files fileglob: return all files in a single directory, non-recursively, that match a pattern find lineinfile stat
Archive handling	unarchive
Download from an URL	get_url
XML handling	xpath xml
Low-level filesystem manipulation	mount: mount and unmount devices while synchronizing the corresponding /etc/fstab state) filesystem: make a filesystem on a block device
Miscellanea	service

Module Return Value

Module Return Value

Block

https://docs.ansible.com/ansible/latest/user_guide/playbooks_blocks.html

Tasks can be grouped together in logical groups with the block keyword. Blocks also offer ways to handle task errors, similar to exception handling in many programming languages.

tasks:
  - name: A block containing a logically-related group of tasks
    block:
      - name: Task 1
        <module-name>: ...
      - name: Task 2
        <module-name>: ...
      ...
    when: ...
    ignore_errors: yes

Blocks can be executed conditionally the same way a task is, and accept other task configuration elements. From this perspective, a block can be thought of as a task that is made of sub-tasks.

Handler

A handler is similar to a regular tasks, in that it can do anything a task can, but it will only run when called by another tasks: handles are only run if the task contains a notify directive and also indicates that it changed something. They can be though as part of an event-based system: a handler will take an action when called by an event it listens for. This is useful for "secondary" actions that might be required after running a task, such as starting a new service after installation or reloading a service after a configuration change. For example, if a config file is changed, then the task referencing the config file templating operation may notify a service restart handler. This means services can be bounced only if they need to be restarted. Handlers can be used for things other than service restarts, but service restarts are the most common usage.

- hosts: all
  become: yes
  become_user: root
  tasks:
   - name: Install Nginx
     apt:
       name: nginx
       state: installed
       update_cache: true
     notify:
      - Start Nginx

  handlers:
   - name: Start Nginx
     service:
       name: nginx
       state: started

Role

https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html

Roles are units of organization that are good for organizing multiple, related tasks and encapsulating data needed to accomplish those tasks. Assigning a role to a group of hosts implies that they should implement a specific behavior. A role may include applying certain variable values, certain tasks, and certain handlers. Roles are redistributable units that allow you to share behavior among playbooks. A playbook includes its roles typically in a 'roles' directory. Conventionally, the elements associated with a role are stored in a directory named after the role:

roles
 ├─ role1
 │   ├─ defaults
 │   │    └─ main.yaml
 │   ├─ files
 │   ├─ handlers
 │   ├─ meta
 │   ├─ tasks
 │   ├─ templates
 │   └─ vars
 │
 ├─ role2
 ├─ role3
 ...

Within each directory, Ansible will search for and automatically read any Yaml file called main.yml.

Roles can be created with the following command:

cd .../roles
ansible-galaxy init <role-name>

Role Structure

Role Files

The files directory contains files that we want copied into target hosts via the copy module. There is no main.yaml file here.

Role Handlers

Example of handlers/main.yaml:

---
- name: Start Nginx
  service:
    name: nginx
    state: started

- name: Reload Nginx
  service:
    name: nginx
    state: reloaded

Role Meta

The main.yml file within the meta directory contains role metadata, including dependencies on another role:

---
dependencies:
  - { role: ssl }

Role Tasks

tasks/main.yml contains the role's tasks.

---
#
# tasks file for kubernetes-local-storage
#

- name: format ESB block storage device
  filesystem:
    fstype: xfs
    dev: /dev/xvdb
    force: no

- name: create local storage mount point
  file:
    path: "{{ item }}"
    state: directory
    owner: root 
  with_items:
    - "/mnt/ebs0"
  when:
    - inventory_hostname in groups['kube-node']

- name: mount storage and update /etc/fstab
  mount:
    state: mounted
    path: /mnt/ebs0
    src: /dev/xvdb
    fstype: xfs

- name: create volume directories
  file:
    path: "/mnt/ebs0/{{ item }}"
    state: directory
    owner: root
  with_items:
    - "local-pv0"
    - "local-pv1"
    - "local-pv2"

Role Templates

Template files can contain template variables, based on Python's Jinja2 template engine. Files in here should end in .j2, but can otherwise have any name. Similar to files, we won't find a main.yml file within the templates directory.

Role Vars

The vars directory contains a main.yaml file that lists variables to use. This provides a convenient place for us to change configuration-wide settings.

---
domain: example.com
ssl_key: /etc/ssl/sfh/sfh.key
ssl_crt: /etc/ssl/sfh/sfh.crt

Using Roles

Using Roles at Play Level

https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html#using-roles-at-the-play-level

If a list of roles is provided in a play, it is said that the roles are used "at the play" level. This is the classic way to use roles. If a role is specified in the play's roles: list, then the tasks from roles/<role-name>/tasks/main.yaml are added to the play. Note that usually main.yaml imports other tasks, coming from other files, for modularization.

- hosts: servers
  roles:
     - common
     - webservers

- hosts: servers
  roles:
     - { role: username.rolename, x: 42 }

In what order are the tasks executed? Is the listing order honored?

Variables

https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html

Places where to Define Variables

Variables can be defined in:

• Inventory.
• Playbooks, as playbook variables, declared under the vars: subtree in the playbook.
• Reusable files.
• Roles (as role variables).
• On the the command line.

Undefined Variables

If a variable is not defined, and it is referenced, Ansible raises an "undefined variable" error and fails. When appropriate, this behavior can be avoided by providing a default value for the missing variable with the default() filter. If working with role, the same effect can be achieved by declaring the default variable value in the role's defaults/main.yaml.

In case there are a lot of undefined variables, Ansible can be configured to ignore them and only some specific variables can be made mandatory with the mandatory() filter.

Variable Precedence

https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#understanding-variable-precedence

TODO.

Variable Types

Simple Variables

https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#simple-variables

Simple variable can be declared as such:

amazon_corretto_package_name: amazon-corretto-11-x64-macos-jdk.pkg

jdk:
  version: 11

parameterized_amazon_corretto_package_name: amazon-corretto-{{ jdk.version }}-x64-macos-jdk.pkg

and can be used by enclosing them in double curly braces {{ ... }}:

- name: Download the latest Amazon Corretto {{ jdk.version }}
  get_url:
    url: https://corretto.aws/downloads/latest/{{ amazon_corretto_package_name }}
    dest: /tmp/{{ amazon_corretto_package_name }}

Registered Variables

https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#registering-variables

Variables can be created from the output of Ansible tasks. The entire output of a task can be referred to from a variable. The association of the output with a variable is done with the register: keyword, followed by the name of the variable. Note that the variables registered as such point to complex maps, and can be used by any task that executes later in the play. Registered variables may be simple variables, list variables, dictionary variables, or complex nested data structures. Registered variables are stored in memory. Registered variables cannot be cached for use in future plays. Registered variables are only valid on the host on which the playbook runs, for the rest of the current playbook run and this is why they're called host-level variables.

Examples:

Registering Variables as Results of Command Execution

Inventory File Variables

These variables are declared in the inventory file.

Group Variables

Group variables are declared under [<group-name>:vars] tag in the inventory file. If they are declared this way, the variables apply to an entire group at once.

[group-A]
host1
host2

[group-A:vars]
something=something-else

Host Variables

Variables that apply to a specific host are declared in the inventory file after the host name:

[group1]
host1 http_port=80 maxRequestsPerChild=808
host2 http_port=303 maxRequestsPerChild=909

Fact

http://docs.ansible.com/ansible/glossary.html#term-facts

Before running any tasks, Ansible will gather information about the system it is provisioning. These are called facts. Facts are pieces of information about target hosts: system and environment information. Facts are used in playbooks, tasks and templates just like variables, but they are inferred, rather than set, during automatic discovery when running plays, by executing the internal setup module on the remote host. Ansible facts all start with anisble_ and are globally available for use any place variables can be used: variable files, tasks, and templates.

Facts can also be explicitly with the set_fact module:

set_fact

Filter

Ansible Filters

Template

A template is a file to be installed on the target host after the declared variables are substituted with actual values. Variable values may come from the inventory file, host variables, group variables, or facts. Templates use the Jinja2 template engine and can also include logical constructs like loops and if statements.

In case of a role declaration, template files are stored into a fixed location, the role's templates directory.

Jinja2 Templating

https://docs.ansible.com/ansible/latest/user_guide/playbooks_templating.html

Privilege Escalation

Keywords: become, sudo, su, root:

Ansible Privilege Escalation

Plugins

Define the relationship between plugins and modules.

Become Plugins

Privilege Escalation | Become Plugins