/docs/MyDocs

Variables

=========

 - Variables (are called facts) and defined in

    + Ansible inventory

    + 'defaults/main.yml' of the roles

    + Ansible also collects facts about the system which can be queried with 

        ansible nodes -m setup -i inventory.erb

    + Set in the roles, includes, and current play-book

    + Also playbooks can install additional facts into the '/etc/ansible/facts.d/'

 

 - Defining variables

    a: 5                                                                - In .yml

    a=5                                                                 - In erb

    a=[1,2,3]                                                           - list

    a={a: 1, b: 2]                                                      - hash

    

 - Accessing variables

    "{{ fact_name }}"                                                   - accessing fact value

     {{ fact_name | filter }}                                           - accessing the filtered fact value

        hash[0]                                                         - accessing list elements

        hpst[0:3]                                                       - first two elements (yes, 3 is not included of the list), will properly return a single element for single-element lists.

        hash["key"] / hash.key                                          - accessing hashes, key could be a variable if needed

 

 

 - Global variables

    hostvars                                                            - allows access to facts about other hosts {{ hostvars['test.example.com']['ansible_distribution'] }}

    groups                                                              - names of all node groups defined in inventory 

                                                                            accessing parameter of first node in a group {{ hostvars[groups['servers'][0]]['ansible_distribution'] }}

                                                                            getting a list of parameters from all group members {{ groups['servers']|map('extract', hostvars, 'ansible_distribution')|list }}

    group_names                                                         - list of all the groups the current host is in

    play_hosts                                                          - list of hostnames that are in scope for the current play

    delegate_to                                                         - inventory name of current host doing delegated job

    playbook_dir                                                        - path to current playbook directory

    inventory_dir / inventory_file                                      - path to current inventory

    inventory_hostname                                                  - the hostname of the host executing task as specified in the inventry

    

 

 - Environmental variables

     {{ lookup('env','HOME') }}                                         - on the local (management) node

     ansible_env.SOME_VARIABLE                                          - on the remote system

         

 - Accessing variables from other hosts

    hostvars[hostname][fact]

 

Priorities

==========

        role defaults [1]                                               - least priority

        inventory INI or script group vars [2]

        inventory group_vars/all

        playbook group_vars/all

        inventory group_vars/*

        playbook group_vars/*

        inventory INI or script host vars [2]

        inventory host_vars/*

        playbook host_vars/*

        host facts

        play vars

        play vars_prompt

        play vars_files

        role vars (defined in role/vars/main.yml)

        block vars (only for tasks in block)

        task vars (only for the task)

        role (and include_role) params

        include params

        include_vars

        set_facts / registered vars

        extra vars (always win precedence)                              - max priority

 

 

Working with variables

======================

    string1 ~ string2                                                   - concatenation (all types are converted to strings if need be)

    var | <filter>                                                      - executes filter

    var.func()                                                          - executes function

    var is <test>                                                       - applies test

 

Tests

=====

 - Standard

    var                                                                 - if var is true, list/hash is not empty

    var is defined/undefined                                            - check if the var is already defined

    var in []                                                           - var is contained in array

 

    var == "string"                                                     - simple string comparison

    not <condition>

    cond1 or/and cond2

    

 - Advanced

    var is number/sequence/mapping/iterable

    var is even/odd/divisibleby(num)

    

 

Functions

=========

 - Strings

    string.split('/')                                                   - split strings into the array

    string.find("all systems go")  != -1                                - find substring in the string, return -1 if not found

    string.lower/upper()

 

 - Lists

    list.index('element')                                               - index of the element in the list (will fail if not found)

 

 - Dicts

    dict.keys/values()

 

Filters                                                                 - more builtin filters from Jinja2 is possible to use

=======

 - Filters

    var | int,list                                                      - checks if variable of the specified type and performs type conversion, use int(base=16) to parse hexdecimal strings

    var | type_debug                                                    - display actual type of variable (2.3 only)

    var | default(5)                                                    - set value if variable is undefined

    var | version_compare('version', '>=')                              - version test

    var | to_uuid,hash('md5|blowfish),password_hash('sha256|sha512')    - generate uuid, hashes of variable

    cond | ternary('true', 'false')                                     - operator '?'

 

 - Math

    var | +,-,/,//,%,*,**                                               - // integer division

    var | log,root,pow(x)                                               - math

    var | round(precision, 'common/ceil/floor')                         - rounds number to the specified number of digits after point

 

 - Strings

    var | quote                                                         - add quotes for shell usage

    var | trim                                                          

    var | truncate(length, killwords, end, leeway)

    var | repalce(word, replacement)

    var | regex_replace('^re$', 'replacement')                          - backreferences are \\1 or \\g<name> if grouped with (?P<name>...)

    var | regex_escape()                                                - escape special characters in the regex

 

 - List Filters

    var | length,last                                                   - number of elements in the list or get last element on the list

    var | join(",")                                                     - join elements of the list into the string using specified separator

    var | min,max                                                       - minimum or maximum in the list

    var | unique                                                        - uniq subset from the list

    var | reverse, shuffle                                              - list reordering

    var | sort(attribute)                                               - sorts the list of strings, or of arbitrary elements by the specified attribute

    var | union,intersect,difference,symmetric_difference(var2)         - combine two lists

    var | issubset,issuperset(var2)                                     - checks if list is subset/superset of anotehr list

    var | random                                                        - gets random element of the list

    var | slice(#)                                                      - slices list into the list of sublist with each sublist containing the specified number of elements

    var | sum('<iterable>', attribute=<name>, start=#|[])               - sums up the elements or joins arrays (hashes is not possible)

    var | map(attribute='name') | list                                  - extracts the specified attribute for all members of the list

    var | map('<filter>', <parameters>) | list                          - applies 'filter' with 'parameters' to each element of the list (filter is anything from here)

                                                                            for each element 'item' of 'var' list, 'item | filter(parameters)' will be executed and result stored

        extract, <list|hash>, key                                       - var should contain indeces/keys of the list/hash supplied in parameters and the 'map' will return appropriate values

 

 - Hash Filters

   var | combine(var2, recursive=true)                                  - combine two hashes

    

 - System Types

    path | basename,dirname,realpath                                    - gets filename/directory from the path or dereference the link

    path | expanduser                                                   - expands ~ to proper home path

    path | splitext                                                     - splits extension of the filename and returns it as list of 2 elements

    path | exists,is_abs,is_dir,is_file,is_link,ismount                 - checks if the path exists, is absolute or rellative, and if it is of a specified type (I guess checked locally)

    path | samefile(var2)                                               - checks if two paths are linked to the same file

    

    cidr | ipaddr,ipv4,ipv6                                             - tests if the variable is CIDR (i.e. ip, network, etc.)

    cidr | ipaddr('public|private')                                     - check if IP is in private or public range

    cidr | ipaddr('address|network|netmask')                            - extracts address or network from CIDR

    cidr | ipaddr('net') | ipaddr('size')                               - get number of IP addresses in the specified range

    cidr | ipaddr('net') | ipaddr('0|1|-1')                             - get first, second, or the last IP address from the range

 

 - Format, Export/Import, and Queries

    var | filesizeformat(binary)                                        - formats number as human readable size (using power of two if binary set to true)

    var | b64encode,b64decode                                           - encode/decode variable to base64

    var | to/from_json/yaml, to_nice_json/yaml(indent=2)                - format and import variables, for instance

                                                                            set_fact: myvar="{{ result.stdout | from_json }}")

    var | json_query('query')                                           - if var is a variable with complex structure, the query allows to extract a list of elements from it (kind of XMLPath)

        path.to.items.item[*].name                                      - extracts names of all elements with name 'item*' under the 'path.to.items'

        path.to.items.list[?key=='value']                               - from the list 'path.to.items.list' return all items which are of type hash and have 'key' equal to 'value'

        list[?key=='value'].{key1: key1, key2: key2}                    - extract multiple parameters (key1 & key2) from the selected items and return them as hash with keys (key1 & key2)

                                                                        actually, query should be passed trough the 'var' to avoid YaML parser confusion

        path[*].more.path.*                                             - list of lists (last asterix iterates dictionary, but returns its values as list)