Cs: Ansible

https://gist.github.com/andreicristianpetcu/b892338de279af9dac067891579cad7d

<syntaxhighlight lang="markdown">

1. An Ansible summary

Jon Warbrick, July 2014, V3.2 (for Ansible 1.7)

1. Configuration file

[intro\_configuration.html](http://docs.ansible.com/intro_configuration.html)

First one found from of

• Contents of `$ANSIBLE_CONFIG`
• `./ansible.cfg`
• `~/.ansible.cfg`
• `/etc/ansible/ansible.cfg`

Configuration settings can be overridden by environment variables - see constants.py in the source tree for names.

1. Patterns

[intro\_patterns.html](http://docs.ansible.com/intro_patterns.html)

Used on the `ansible` command line, or in playbooks.

• `all` (or `*`)
• hostname: `foo.example.com`
• groupname: `webservers`
• or: `webservers:dbserver`
• exclude: `webserver:!phoenix`
• intersection: `webservers:&staging`

Operators can be chained: `webservers:dbservers:&staging:!phoenix`

Patterns can include variable substitutions: `Modèle:Foo`, wildcards: `*.example.com` or 192.168.1.*, and regular expressions: `~(web|db).*\.example\.com`

1. Inventory files

[intro\_inventory.html](http://docs.ansible.com/intro_inventory.html), [intro\_dynamic\_inventory.html](http://docs.ansible.com/intro_dynamic_inventory.html)

'INI-file' structure, blocks define groups. Hosts allowed in more than one group. Non-standard SSH port can follow hostname separated by ':' (but see also `ansible_ssh_port` below).

Hostname ranges: `www[01:50].example.com`, `db-[a:f].example.com`

Per-host variables: `foo.example.com foo=bar baz=wibble`

• `[foo:children]`: new group `foo` containing all members if included groups
• `[foo:vars]`: variable definitions for all members of group `foo`

Inventory file defaults to `/etc/ansible/hosts`. Veritable with `-i` or in the configuration file. The 'file' can also be a dynamic inventory script. If a directory, all contained files are processed.

1. Variable files:

[intro\_inventory.html](http://docs.ansible.com/intro_inventory.html)

YAML; given inventory file at `./hosts`:

• `./group_vars/foo`: variable definitions for all members of group `foo`
• `./host_vars/foo.example.com`: variable definitions for foo.example.com

`group_vars` and `host_vars` directories can also exist in the playbook directory. If both paths exist, variables in the playbook directory will be loaded second.

1. Behavioral inventory parameters:

[intro\_inventory.html](http://docs.ansible.com/intro_inventory.html)

• `ansible_ssh_host`
• `ansible_ssh_port`
• `ansible_ssh_user`
• `ansible_ssh_pass`
• `ansible_sudo_pass`
• `ansible_connection`
• `ansible_ssh_private_key_file`
• `ansible_python_interpreter`
• `ansible_*_interpreter`

1. Playbooks

[playbooks\_intro.html](http://docs.ansible.com/playbooks_intro.html), [playbooks\_roles.html](http://docs.ansible.com/playbooks_roles.html)

Playbooks are a YAML list of one or more plays. Most (all?) keys are optional. Lines can be broken on space with continuation lines indented.

Playbooks consist of a list of one or more 'plays' and/or inclusions:

   ---
   - include: playbook.yml
   - <play>
   - ...

1. 1. Plays

[playbooks\_intro.html](http://docs.ansible.com/playbooks_intro.html), [playbooks\_roles.html](http://docs.ansible.com/playbooks_roles.htm), [playbooks\_variables.html](http://docs.ansible.com/playbooks_variables.html), [playbooks\_conditionals.html](http://docs.ansible.com/playbooks_conditionals.html), [playbooks\_acceleration.html](http://docs.ansible.com/playbooks_acceleration.html), [playbooks\_delegation.html](http://docs.ansible.com/playbooks_delegation.html), [playbooks\_prompts.html](http://docs.ansible.com/playbooks_prompts.html), [playbooks\_tags.html](http://docs.ansible.com/playbooks_tags.htm) [Forum posting](https://groups.google.com/forum/#!topic/ansible-project/F9mIAfo6orc) [Forum postinb](https://groups.google.com/forum/#!topic/Ansible-project/MU_ws7zynnI)

Plays consist of play metadata and a sequence of task and handler definitions, and roles.

   - hosts: webservers
     remote_user: root
     sudo: yes
     sudo_user: postgress
     su: yes
     su_user: exim
     gather_facts: no
     accelerate: no
     accelerate_port: 5099
     any_errors_fatal: yes
     max_fail_percentage: 30
     connection: local
     serial: 5
     vars:
       http_port: 80
     vars_files:
       - "vars.yml"
       - [ "try-first.yml", "try-second-.yml" ]
     vars_prompt:
       - name: "my_password2"
         prompt: "Enter password2"
         default: "secret"
         private: yes
         encrypt: "md5_crypt"
         confirm: yes
         salt: 1234
         salt_size: 8
     tags: 
       - stuff
       - nonsence
     pre_tasks:
       - <task>
       - ...
     roles:
       - common
       - { role: common, port: 5000, when: "bar == 'Baz'", tags :[one, two] }
       - { role: common, when: month == 'Jan' }
       - ...
     tasks:
       - include: tasks.yaml
       - include: tasks.yaml foo=bar baz=wibble
       - include: tasks.yaml
         vars:
           foo: aaa 
           baz:
             - z
             - y
       - { include: tasks.yaml, foo: zzz, baz: [a,b]}
       - include: tasks.yaml
         when: day == 'Thursday'
       - <task>
       - ...
     post_tasks:
       - <task>
       - ...
     handlers:
       - include: handlers.yml
       - <task>
       - ...

Using `encrypt` with `vars_prompt` requires that [Passlib](http://pythonhosted.org/passlib/) is installed.

In addition the source code implies the availability of the following which don't *seem* to be mentioned in the documentation: `name`, `user` (deprecated), `port`, `accelerate_ipv6`, `role_names`, and `vault_password`.

1. 1. Task definitions

[playbooks\_intro.html](http://docs.ansible.com/playbooks_intro.html), [playbooks\_roles.html](http://docs.ansible.com/playbooks_roles.html), [playbooks\_async.html](http://docs.ansible.com/playbooks_async.html), [playbooks\_checkmode.html](http://docs.ansible.com/[playbooks_checkmode.html), [playbooks\_delegation.html](http://docs.ansible.com/playbooks_delegation.html), [playbooks\_environment.html](http://docs.ansible.com/playbooks_environment.html), [playbooks\_error_handling.html](http://docs.ansible.com/playbooks_error_handling.html), [playbooks\_tags.html](http://docs.ansible.com/playbooks_tags.html) [ansible-1-5-released](http://www.ansible.com/blog/2014/02/28/ansible-1-5-released) [Forum posting](https://groups.google.com/forum/#!topic/ansible-project/F9mIAfo6orc) [Ansible examples](https://github.com/ansible/ansible-examples/blob/master/language_features/complex_args.yml)

Each task definition is a list of items, normally including at least a name and a module invocation:

   - name: task
     remote_user: apache
     sudo: yes
     sudo_user: postgress
     sudo_pass: wibble
     su: yes
     su_user: exim
     ignore_errors: True
     delegate_to: 127.0.0.1
     async: 45
     poll: 5
     always_run: no
     run_once: false
     meta: flush_handlers
     no_log: true
     environment: <hash>
     environment:
       var1: val1
       var2: val2
     tags: 
       - stuff
       - nonsence
     <module>: src=template.j2 dest=/etc/foo.conf
     action: <module>, src=template.j2 dest=/etc/foo.conf
     action: <module>
     args:
         src=template.j2
         dest=/etc/foo.conf
     local_action: <module> /usr/bin/take_out_of_pool Modèle:Inventory hostname
     when: ansible_os_family == "Debian"
     register: result
     failed_when: "'FAILED' in result.stderr"
     changed_when: result.rc != 2
     notify:
       - restart apache

`delegate_to: 127.0.0.1` is implied by `local_action:`

The forms `<module>: <args>`, `action: <module> <args>`, and `local_action: <module> <args>` are mutually-exclusive.

Additional keys `when_*`, `until`, `retries` and `delay` are documented below under 'Loops'.

In addition the source code implies the availability of the following which don't *seem* to be mentioned in the documentation: `first_available_file` (deprecated), `transport`, `connection`, `any_errors_fatal`.

1. Roles

[playbooks\_roles.html](http://docs.ansible.com/playbooks_roles.html)

Directory structure:

   playbook.yml
   roles/
      common/
        tasks/
          main.yml
        handlers/
          main.yml
        vars/
          main.yml
        meta/
          main.yml
        defaults/
          main.yml
        files/
        templates/
        library/

1. Modules

[modules.htm](http://docs.ansible.com/modules.htm), [modules\_by\_category.html](http://docs.ansible.com/modules_by_category.html)

List all installed modules with

   ansible-doc --list

Document a particular module with

   ansible-doc <module>

Show playbook snippet for specified module

   ansible-doc -i <module>

1. Variables

[playbooks\_roles.html](http://docs.ansible.com/playbooks_roles.html), [playbooks\_variables.html](http://docs.ansible.com/playbooks_variables.html)

Names: letters, digits, underscores; starting with a letter.

1. 1. Substitution examples:

• `Modèle:Var`
• `{{ var["key1"]["key2"]}}`
• `Modèle:Var.key1.key2`
• `{{ list[0] }}`

YAML requires an item starting with a variable substitution to be quoted.

1. 1. Sources:

• Highest priority:

   * `--extra-vars` on the command line

• General:

   * `vars` component of a playbook
   * From files referenced by `vars_file` in a playbook
   * From included files (incl. roles)
   * Parameters passed to includes
   * `register:` in tasks

• Lower priority:

   * Inventory (set on host or group)

• Lower priority:

   * Facts (see below)
   * Any `/etc/ansible/facts.d/filename.fact` on managed machines 
     (sets variables with `ansible_local.filename. prefix)

• Lowest priority

   * Role defaults (from defaults/main.yml)

1. 1. Built-in:

• `hostvars` (e.g. `hostvars[other.example.com][...]`)
• `group_names` (groups containing current host)
• `groups` (all groups and hosts in the inventory)
• `inventory_hostname` (current host as in inventory)
• `inventory_hostname_short` (first component of inventory_hostname)
• `play_hosts` (hostnames in scope for current play)
• `inventory_dir` (location of the inventory)
• `inventoty_file` (name of the inventory)

1. 1. Facts:

Run `ansible hostname -m setup`, but in particular:

• `ansible_distribution`
• `ansible_distribution_release`
• `ansible_distribution_version`
• `ansible_fqdn`
• `ansible_hostname`
• `ansible_os_family`
• `ansible_pkg_mgr`
• `ansible_default_ipv4.address`
• `ansible_default_ipv6.address`

1. 1. Content of 'registered' variables:

[playbooks\_conditionals.html](http://docs.ansible.com/playbooks_conditionals.html), [playbooks\_loops.html](http://docs.ansible.com/playbooks_loops.html)

Depends on module. Typically includes:

• `.rc`
• `.stdout`
• `.stdout_lines`
• `.changed`
• `.msg` (following failure)
• `.results` (when used in a loop)

See also `failed`, `changed`, etc filters.

When used in a loop the `result` element is a list containing all responses from the module.

1. 1. Additionally available in templates:

• `ansible_managed`: string containing the information below
• `template_host`: node name of the template’s machine
• `template_uid`: the owner
• `template_path`: absolute path of the template
• `template_fullpath`: the absolute path of the template
• `template_run_date`: the date that the template was rendered

1. Filters

[playbooks\_variables.html](http://docs.ansible.com/playbooks_variables.html)

• `Modèle:Var`
• `Modèle:Var`
• `Modèle:Var`
• `Modèle:Var`
• `Modèle:Var`
• `Modèle:Var`
• `Modèle:Result`
• `Modèle:Result`
• `Modèle:Result`
• `Modèle:Result`
• `Modèle:Var`
• `Modèle:Var`
• `Modèle:List1`
• `Modèle:List1`
• `Modèle:List1`
• `Modèle:List1`
• `Modèle:List1`
• `Modèle:Ver1`
• `Modèle:List`
• `Modèle:Number`
• `Modèle:Number`
• `Modèle:List`
• `Modèle:Path`
• `Modèle:Path`
• `Modèle:Path`
• `Modèle:Path`
• `Modèle:Var`
• `Modèle:Var`
• `Modèle:Filename`
• `Modèle:Var`
• `Modèle:Var`
• `Modèle:Var`
• `Modèle:Var`
• `Modèle:Var`
• `Modèle:Var`
• `Modèle:Var`
• `Modèle:Var`
• `Modèle:Var`

See also [default jinja2 filters](http://jinja.pocoo.org/docs/templates/#builtin-filters). In YAML, values starting `{` must be quoted.

1. Lookups

[playbooks\_lookups.html](http://docs.ansible.com/playbooks_lookups.html)

Lookups are evaluated on the control machine.

• `Modèle:Lookup('file', '/etc/foo.txt')`
• `Modèle:Lookup('password', '/tmp/passwordfile length=20 chars=ascii letters,digits')`
• `Modèle:Lookup('env','HOME')`
• `Modèle:Lookup('pipe','date')`
• `Modèle:Lookup('redis kv', 'redis://localhost:6379,somekey')`
• `Modèle:Lookup('dnstxt', 'example.com')`
• `Modèle:Lookup('template', './some template.j2')`

Lookups can be assigned to variables and will be evaluated each time the variable is used.

Lookup plugins also support loop iteration (see below).

1. Conditions

[playbooks\_conditionals.html](http://docs.ansible.com/playbooks_conditionals.html)

`when: <condition>`, where condition is:

• `var == "Vaue"`, `var >= 5`, etc.
• `var`, where `var` coreces to boolean (yes, true, True, TRUE)
• `var is defined`, `var is not defined`
• `<condition1> and <condition2>` (also `or`?)

Combined with `with_items`, the when statement is processed for each item.

`when` can also be applied to includes and roles. Conditional Imports and variable substitution in file and template names can avoid the need for explicit conditionals.

1. Loops

[playbooks\_loops.html](http://docs.ansible.com/playbooks_loops.html)

In addition the source code implies the availability of the following which don't *seem* to be mentioned in the documentation: `csvfile`, `etcd`, `inventory_hostname`.

1. 1. Standard:

   - user: name=Modèle:Item state=present groups=wheel
     with_items:
       - testuser1
       - testuser2
      
   - name: add several users
     user: name=Modèle:Item.name state=present groups=Modèle:Item.groups
     with_items:
       - { name: 'testuser1', groups: 'wheel' }
       - { name: 'testuser2', groups: 'root' }

     with_items: somelist
   

1. 1. Nested:

   - mysql_user: name={{ item[0] }} priv={{ item[1] }}.*:ALL                
                              append_privs=yes password=foo
     with_nested:
       - [ 'alice', 'bob', 'eve' ]
       - [ 'clientdb', 'employeedb', 'providerdb' ]
       

1. 1. Over hashes:

Given

   ---
   users:
     alice:
       name: Alice Appleworth
       telephone: 123-456-7890
     bob:
       name: Bob Bananarama
       telephone: 987-654-3210
       
   tasks:
     - name: Print phone records
       debug: msg="User Modèle:Item.key is Modèle:Item.value.name 
                        (Modèle:Item.value.telephone)"
       with_dict: users

1. 1. Fileglob:

   - copy: src=Modèle:Item dest=/etc/fooapp/ owner=root mode=600
     with_fileglob:
       - /playbooks/files/fooapp/*

In a role, relative paths resolve relative to the `roles/<rolename>/files` directory.

1. 1. With content of file:

(see example for `authorized_key` module)

   - authorized_key: user=deploy key="Modèle:Item"
     with_file:
       - public_keys/doe-jane
       - public_keys/doe-john

See also the `file` lookup when the content of a file is needed.

1. 1. Parallel sets of data:

Given

   ---
   alpha: [ 'a', 'b', 'c', 'd' ]
   numbers:  [ 1, 2, 3, 4 ]
   
   - debug: msg="Modèle:Item.0 and Modèle:Item.1"
     with_together:
       - alpha
       - numbers

1. 1. Subelements:

Given

   ---
   users:
     - name: alice
       authorized:
         - /tmp/alice/onekey.pub
         - /tmp/alice/twokey.pub
     - name: bob
       authorized:
         - /tmp/bob/id_rsa.pub
   
   - authorized_key: "user=Modèle:Item.0.name 
                      key='Modèle:Lookup('file', item.1)'"
     with_subelements:
        - users
        - authorized
        

1. 1. Integer sequence:

Decimal, hexadecimal (0x3f8) or octal (0600)

   - user: name=Modèle:Item state=present groups=evens
     with_sequence: start=0 end=32 format=testuser%02x
         
     with_sequence: start=4 end=16 stride=2
         
     with_sequence: count=4
         

1. 1. Random choice:

   - debug: msg=Modèle:Item
     with_random_choice:
        - "go through the door"
        - "drink from the goblet"
        - "press the red button"
        - "do nothing"
        

1. 1. Do-Until:

   - action: shell /usr/bin/foo
     register: result
     until: result.stdout.find("all systems go") != -1
     retries: 5
     delay: 10

1. 1. Results of a local program:

   - name: Example of looping over a command result
     shell: /usr/bin/frobnicate Modèle:Item
     with_lines: /usr/bin/frobnications_per_host 
                          --param Modèle:Inventory hostname
                          

To loop over the results of a remote program, use `register: result` and then `with_items: result.stdout_lines` in a subsequent task.

1. 1. Indexed list:

   - name: indexed loop demo
     debug: msg="at array position Modèle:Item.0 there is 
                                        a value Modèle:Item.1"
     with_indexed_items: some_list
     

1. 1. Flattened list:

   ---
   # file: roles/foo/vars/main.yml
   packages_base:
     - [ 'foo-package', 'bar-package' ]
   packages_apps:
     - [ ['one-package', 'two-package' ]]
     - [ ['red-package'], ['blue-package']]
     
   - name: flattened loop demo
     yum: name=Modèle:Item state=installed
     with_flattened:
       - packages_base
       - packages_apps      

1. 1. First found:

   - name: template a file
     template: src=Modèle:Item dest=/etc/myapp/foo.conf
     with_first_found:
       - files:
           - Modèle:Ansible distribution.conf
           - default.conf
         paths:
            - search_location_one/somedir/
            - /opt/other_location/somedir/
           

1. Tags

Both plays and tasks support a `tags:` attribute.

   - template: src=templates/src.j2 dest=/etc/foo.conf
     tags:
       - configuration

Tags can be applied to roles and includes (effectively tagging all included tasks)

   roles:
       - { role: webserver, port: 5000, tags: [ 'web', 'foo' ] }

   - include: foo.yml tags=web,foo
   

To select by tag:

   ansible-playbook example.yml --tags "configuration,packages"
   ansible-playbook example.yml --skip-tags "notification"

1. Command lines

1. 1. ansible

   Usage: ansible <host-pattern> [options]

   Options:
     -a MODULE_ARGS, --args=MODULE_ARGS
                           module arguments
     -k, --ask-pass        ask for SSH password
     --ask-su-pass         ask for su password
     -K, --ask-sudo-pass   ask for sudo password
     --ask-vault-pass      ask for vault password
     -B SECONDS, --background=SECONDS
                           run asynchronously, failing after X seconds
                           (default=N/A)
     -C, --check           don't make any changes; instead, try to predict some
                           of the changes that may occur
     -c CONNECTION, --connection=CONNECTION
                           connection type to use (default=smart)
     -f FORKS, --forks=FORKS
                           specify number of parallel processes to use
                           (default=5)
     -h, --help            show this help message and exit
     -i INVENTORY, --inventory-file=INVENTORY
                           specify inventory host file
                           (default=/etc/ansible/hosts)
     -l SUBSET, --limit=SUBSET
                           further limit selected hosts to an additional pattern
     --list-hosts          outputs a list of matching hosts; does not execute
                           anything else
     -m MODULE_NAME, --module-name=MODULE_NAME
                           module name to execute (default=command)
     -M MODULE_PATH, --module-path=MODULE_PATH
                           specify path(s) to module library
                           (default=/usr/share/ansible)
     -o, --one-line        condense output
     -P POLL_INTERVAL, --poll=POLL_INTERVAL
                           set the poll interval if using -B (default=15)
     --private-key=PRIVATE_KEY_FILE
                           use this file to authenticate the connection
     -S, --su              run operations with su
     -R SU_USER, --su-user=SU_USER
                           run operations with su as this user (default=root)
     -s, --sudo            run operations with sudo (nopasswd)
     -U SUDO_USER, --sudo-user=SUDO_USER
                           desired sudo user (default=root)
     -T TIMEOUT, --timeout=TIMEOUT
                           override the SSH timeout in seconds (default=10)
     -t TREE, --tree=TREE  log output to this directory
     -u REMOTE_USER, --user=REMOTE_USER
                           connect as this user (default=jw35)
     --vault-password-file=VAULT_PASSWORD_FILE
                           vault password file
     -v, --verbose         verbose mode (-vvv for more, -vvvv to enable
                           connection debugging)
     --version             show program's version number and exit

1. 1. ansible-playbook

   Usage: ansible-playbook playbook.yml

   Options:
     -k, --ask-pass        ask for SSH password
     --ask-su-pass         ask for su password
     -K, --ask-sudo-pass   ask for sudo password
     --ask-vault-pass      ask for vault password
     -C, --check           don't make any changes; instead, try to predict some
                           of the changes that may occur
     -c CONNECTION, --connection=CONNECTION
                           connection type to use (default=smart)
     -D, --diff            when changing (small) files and templates, show the
                           differences in those files; works great with --check
     -e EXTRA_VARS, --extra-vars=EXTRA_VARS
                           set additional variables as key=value or YAML/JSON
     -f FORKS, --forks=FORKS
                           specify number of parallel processes to use
                           (default=5)
     -h, --help            show this help message and exit
     -i INVENTORY, --inventory-file=INVENTORY
                           specify inventory host file
                           (default=/etc/ansible/hosts)
     -l SUBSET, --limit=SUBSET
                           further limit selected hosts to an additional pattern
     --list-hosts          outputs a list of matching hosts; does not execute
                           anything else
     --list-tasks          list all tasks that would be executed
     -M MODULE_PATH, --module-path=MODULE_PATH
                           specify path(s) to module library
                           (default=/usr/share/ansible)
     --private-key=PRIVATE_KEY_FILE
                           use this file to authenticate the connection
     --skip-tags=SKIP_TAGS
                           only run plays and tasks whose tags do not match these
                           values
     --start-at-task=START_AT
                           start the playbook at the task matching this name
     --step                one-step-at-a-time: confirm each task before running
     -S, --su              run operations with su
     -R SU_USER, --su-user=SU_USER
                           run operations with su as this user (default=root)
     -s, --sudo            run operations with sudo (nopasswd)
     -U SUDO_USER, --sudo-user=SUDO_USER
                           desired sudo user (default=root)
     --syntax-check        perform a syntax check on the playbook, but do not
                           execute it
     -t TAGS, --tags=TAGS  only run plays and tasks tagged with these values
     -T TIMEOUT, --timeout=TIMEOUT
                           override the SSH timeout in seconds (default=10)
     -u REMOTE_USER, --user=REMOTE_USER
                           connect as this user (default=jw35)
     --vault-password-file=VAULT_PASSWORD_FILE
                           vault password file
     -v, --verbose         verbose mode (-vvv for more, -vvvv to enable
                           connection debugging)
     --version             show program's version number and exit

1. 1. ansible-vault

playbooks_vault.html

   Usage: ansible-vault [create|decrypt|edit|encrypt|rekey] [--help] [options] file_name

   Options:
     -h, --help  show this help message and exit

   See 'ansible-vault <command> --help' for more information on a specific command.

1. 1. ansible-doc

   Usage: ansible-doc [options] [module...]

   Show Ansible module documentation

   Options:
     --version             show program's version number and exit
     -h, --help            show this help message and exit
     -M MODULE_PATH, --module-path=MODULE_PATH
                                Ansible modules/ directory
     -l, --list            List available modules
     -s, --snippet         Show playbook snippet for specified module(s)
     -v                    Show version number and exit
  

1. 1. ansible-galaxy

   Usage: ansible-galaxy [init|info|install|list|remove] [--help] [options] ...

   Options:
     -h, --help  show this help message and exit

     See 'ansible-galaxy <command> --help' for more information on a
     specific command 

1. 1. ansible-pull

   Usage: ansible-pull [options] [playbook.yml]

   ansible-pull: error: URL for repository not specified, use -h for help

</syntaxhighlight>