EX407_study_notes.txt

######################################################################
## Tomas Nevar <tomas@lisenet.com>
## Study notes for EX407 Ansible Automation exam (RHEL7)
######################################################################

## Exam objectives:

* Understand core components of Ansible
  - Inventories
  - Modules
  - Variables
  - Facts
  - Plays
  - Playbooks
  - Configuration files
* Install and configure an Ansible control node
  - Install required packages
  - Create a static host inventory file
  - Create a configuration file
* Configure Ansible managed nodes
  - Create and distribute SSH keys to managed nodes
  - Configure privilege escalation on managed nodes
  - Validate a working configuration using ad-hoc Ansible commands
* Create simple shell scripts that run ad hoc Ansible commands
* Use both static and dynamic inventories to define groups of hosts
* Utilize an existing dynamic inventory script
* Create Ansible plays and playbooks
  - Know how to work with commonly used Ansible modules
  - Use variables to retrieve the results of running commands
  - Use conditionals to control play execution
  - Configure error handling
  - Create playbooks to configure systems to a specified state
* Use Ansible modules for system administration tasks that work with:
  - Software packages and repositories
  - Services
  - Firewall rules
  - File systems
  - Storage devices
  - File content
  - Archiving
  - Scheduled tasks
  - Security
  - Users and groups
* Create and use templates to create customized configuration files
* Work with Ansible variables and facts
* Create and work with roles
* Download roles from an Ansible Galaxy and use them
* Manage parallelism
* Use Ansible Vault in playbooks to protect sensitive data
* Use provided documentation to look up specific information about Ansible modules and commands

## When installed, the ansible package provides a base configuration
## file located at /etc/ansible/ansible.cfg
##
## Priority in which the configuration files are processed:
##  1) $ANSIBLE_CONFIG (an environment variable)
##  2) ./ansible.cfg (in the current directory)
##  3) ~/.ansible.cfg (the user's home directory)
##  4) /etc/ansible/ansible.cfg

#---------------------------------------------------------------------

## *** Ansible Get Started **

## To find out what config file is in use, run the following:

$ ansible --version
ansible 2.7.9
  config file = /home/ansible/ansible.cfg

## To get started, copy configuration files to the home directory:

$ cp /etc/ansible/ansible.cfg ~/ansible.cfg
$ cp /etc/ansible/hosts ~/inventory

## Note: the maximum number of simultaneous connections that Ansible
## makes is controlled by the forks parameter (ansible.cfg):

forks 5

## Example inventory configuration:

$ cat ~/inventory
[myself]
127.0.0.1 ansible_connection=local
[web]
ansible[2:3].hl.local
[db]
ansible[4:5].hl.local ansible_user=dbadmin
[lab:children]
web
db

## There is a special group named "all" that matches all managed hosts
## in the inventory.

- hosts: all

## There is also a special group named "ungrouped" which matches all
## managed hosts in the inventory that are not members of any group.

- hosts: ungrouped

## Quote host patterns used on the CLI to protect them from unwanted
## shell expansion:

- hosts: '*.hl.local'
- hosts: '10.11.1.*'

## Multiple entries in the inventory can be referenced using lists:

- hosts: web,ansible3.hl.local

## If you have static and dynamic inventory files in the same
## directory, then they are merged and treated as one inventory!

## Show inventory for all:

$ ansible "*" -i ~/inventory --list-hosts


## Privilege escalation settings:

$ vim ansible.cfg
[privilege_escalation]
become = false
become_method = sudo
become_user = root
become_ask_pass = false


## How to set the default user to use for playbooks:

$ vim ansible.cfg
remote_user = ansible

## How to set the log file:

$ vim ansible.cfg
log_path = /home/ansible/ansible.log


## If no module is defined, Ansible uses the internally predefined
## "command" module. Note that this is not a shell!
## Ad hoc command that generates one line input for each operation:

$ ansible all -m command -a /usr/bin/hostname -o

## Use the copy module to change content of a file:

$ ansible all -m copy \
  -a 'content="Host managed by Ansible\n" dest=/etc/motd' \
  -u ansible --become

## NOTE: if possible, try to avoid the command, shell and raw modules
## in playbooks! It's easy to write non-idempotent playbooks this way.

## Ansible module documentation and playbook snippets:

$ ansible-doc -l
$ ansible-doc -s <module_name>
$ ansible-doc <module_name>


## Ansible executes plays and tasks in the order they are presented!
## How to check for YAML syntax errors:

$ ansible-playbook --syntax-check <filename>.yaml

## Which host(s) the playbook applies to?

$ ansible-playbook <playbook>.yaml --list-hosts

## Whats tasks will be performed?

$ ansible-playbook <playbook>.yaml --list-tasks

## Run one task at a time:

$ ansible-playbook <playbook>.yaml --step

## Playbook dry-run:

$ ansible-playbook -C <playbook>.yaml

## Playbook step-by-step execution:

$ ansible-playbook --step <playbook>.yaml


## The beginning of each play begins with a single dash followed by a space.
## Playbook attributes:
##
## name - can be used to give a descriptive label to a play.
## hosts - must be defined in every play.
## remote_user - can be used to define the user that runs the tasks.
## become - can be used to enable privilege escalation.
## become_method - can be used to define the privilege escalation method.
## become_user - can define the user account to be used for privilege escalation.
## tasks - is defined as a list of dictionaries.
## blocks - can be used to group related tasks together.

## For each play in a playbook, you get to choose which machines in your
## infrastructure to target and what remote user to complete the steps as.
## You can use keyword "become" on a particular task instead of the play:

---
- hosts: webservers
  remote_user: ansible
  serial: 2
  tasks:
    - service:
        name: httpd
        state: started
      become: yes
      become_method: sudo

## Use the serial keyword to run the hosts through the play in batches.
## Host variables take precedence over group variables, but variables
## defined by a playbook take precedence over both.

#---------------------------------------------------------------------

## ** Including and Importing Files **

## When you include content, then Ansible processes included content
## during the run of the playbook, as content is required.

## When you import content, Ansible processes imported content when
## the playbook is initially read, before the run starts.

## Note: "include" was replaced in Ansible 2.4 with new directives such
## as include_tasks, import_tasks, and import_playbook.
## These can be used to enhance the ability to reuse tasks and playbooks:

import_playbook:
import_tasks:
include_tasks:

## Examples:

tasks:
  - name: Import task file and use variables
    import_tasks: task.yml
    vars:
      package: vsftpd
      service: vsft


  - name: Install the {{ package }} package
    yum:
      name: "{{ package }}"
      state: latest
  - name: Start the {{ service }} service
    service:
      name: "{{ service }}"
      enabled: true
      state: started

#---------------------------------------------------------------------

## *** Ansible and VIM ***

## When writing playbooks in vim editor, modify its action in response
## to Tab key entries. Add the following line to $HOME/.vimrc.
## It will perform a two space indentation when the Tab key is pressed.

autocmd FileType yaml setlocal ai ts=2 sw=2 et

## Settings explained:

ai   - autoindent (turns it on)
sw=2 - shiftwidth (indenting is 2 spaces)
et   - expandtab (do not use actual tab character)
ts=2 - tabstop (tabs are at proper location)

## Two other helpful but optional vim settings:

nu (show line number)
cursorline (line to show current cursor position)

#---------------------------------------------------------------------

## *** Ansible Vault ***

$ ansible-vault [create|decrypt|edit|encrypt|rekey|view] vaultfile.yml

## By default, Ansible uses functions from the python-crypto package to
## encrypt and decrypt vault files. To speed up decryption at startup,
## you install the python-cryptography package.

$ ansible-vault create vaultfile.yml
$ ansible-vault view vaultfile.yml

## Check syntax of a playbook that uses the vault file:

$ ansible-playbook --syntax-check --ask-vault-pass playbook.yml

## Create a password file to use for the playbook execution:

$ echo "ansible" > key
$ ansible-playbook --syntax-check --vault-password-file=key playbook.yml

#---------------------------------------------------------------------

## *** Ansible Facts ***
## The same thing as facts in Puppet. How to print facts for all hosts?

- name: Ansible fact dump
  hosts: all
  tasks:
    - name: Print all Ansible facts
      debug:
        var: ansible_facts

- name: Ansible package fact dump
  hosts: all
  tasks:
    - name: Gather package facts
      package_facts:
        manager: auto

## Before Ansible 2.5, facts were injected as individual variables
## prefixed with the string "ansible_" instead of being part of the
## ansible_facts variable.

## At the time of writing this, Ansible recognises both the new fact
## naming system (using ansible_facts) and the old pre 2.5 naming system
## where facts are injected as separate variables.

## You can use an ad hoc command to run the setup module to print the
## value of all facts:

$ ansible localhost -m setup

## Filter results:

$ ansible localhost -m setup -a 'filter=*distribution*'

## Some commonly used facts (from my experience with Puppet).
## In no particular order:

ansible_facts['hostname']
ansible_facts['fqdn']
ansible_facts['default_ipv4']['address']
ansible_facts['distribution']
ansible_facts['distribution_major_version']
ansible_facts['domain']
ansible_facts['memtotal_mb']
ansible_facts['processor_count']


## To disable fact gathering for a play, you can set the gather_facts
## keyword to "no":

gather_facts: no

## Similar to Puppet, Ansible supports custom facts. Custom facts can be
## defined in a static file, formatted as an INI file or using JSON and
## placed in /etc/ansible/facts.d and the file name must end in ".fact".
## They can also be executable scripts which generate JSON output,
## just like a dynamic inventory script.
## Note: custom fact files cannot be in YAML format!

#---------------------------------------------------------------------

## *** Ansible Loops, Conditionals and Lookups ***

## Ansible supports iterating a task over a set of items using the loop
## keyword. A simple loop iterates a task over a list of items.
## Since Ansible 2.5, the recommended way to write loops is to use the
## loop keyword. The old syntax used loops prefixed with "with_".

- name: Ensure that packages are present
  package:
    name: "{{ item }}"
    state: present
  loop:
    - firewalld
    - httpd
    - vsftpd

- name: Ensure that web server ports are open
  firewalld:
    service: "{{ item }}"
    immediate: true
    permanent: true
    state: enabled
  loop:
    - http
    - https

## Example conditionals:

Equal				|	==
Less than			|	<
Greater than 			|	>
Variable exists 		|	is defined
Variable does not exist		|	is not defined
Boolean is true			|	values of 1, True, or yes evaluate to true

## Logical AND and OR operations are supported:

when: ansible_domain == "hl.local" and ansible_distribution == "RedHat"
when: ansible_processor_cores == "1" or ansible_processor_cores == "2"

## Loops and conditionals can be combined:

- name: Ensure that packages are present on RedHat
  package:
    name: "{{ item }}"
    state: present
  loop:
    - firewalld
    - httpd
  when: ansible_distribution == "RedHat"

## Lookup plugins allow access to outside data sources. Lookups occur
## on the local computer, not on the remote computer.
## One way of using lookups is to populate variables:

vars:
  motd_value: "{{ lookup('file', '/etc/motd') }}"
tasks:
  - debug:
      msg: "motd value is {{ motd_value }}"

## *** Ansible Handlers ***
## Handlers always run in the order specified by the handlers section
## of the play. A handler called by a task in the tasks part of the
## playbook will not run until all of the tasks under tasks have been
## processed.

notify: restart httpd service

handlers:
  - name: restart httpd service
    service:
      name: httpd
      state: restarted

## If a task fails and the play aborts on that host, any handlers that
## had been notified by earlier tasks in the play will not run.
## Use the following to force execution of the handler:

force_handlers: yes

## Handlers are notified when a task reports a "changed" result.
## Handlers are not notified when it reports an "ok" or "failed" result.

## Ignore errors:

ignore_errors: yes

#---------------------------------------------------------------------

## *** Commonly Used Files Modules with Examples ***

## The file module acts like chcon when setting file contexts:

- name: Create a file
  hosts: localhost
  become: true
  tasks:
    - name: Create a file and set permissions
      file:
        path: /root/file
        owner: root
        group: root
        mode: 0640
        state: touch
        setype: user_tmp_t
    - name: SELinux type is persistently set to user_tmp_t
      sefcontext:
        target: /root/file
        setype: user_tmp_t
        state: present


- name: Copy a file
  hosts: localhost
  become: true
  tasks:
    - name: Copy a file
      copy:
        src: file
        dest: /root/file
        force: yes
        owner: root
        group: ansible
        mode: 0640


- name: Add a line to a file
  hosts: localhost
  become: true
  tasks:
    - name: Add a new line to a file
      lineinfile:
        path: /root/file
        line: "this is the new line"
        state: present


- name: Add block of text to a file
  hosts: localhost
  become: true
  tasks:
    - name: Add a block of text to an existing file
      blockinfile:
        path: /root/file
        block: |
          This is the first line to be added.
          This is the second line to be added.
        state: present


- name: Download a file from managed hosts
  hosts: localhost
  become: false
  tasks:
    - name: Fetch a file
      fetch:
        src: /etc/hosts
        dest: my-folder
        flat: no

- name: Download a file from remote host
  hosts: localhost
  become: false
    - name: Download file from URL
      get_url:
        url: http://katello.hl.local/pub/index.html
        dest: /tmp/index.html

- name: Disable SSH root login
  hosts: localhost
  become: true
  tasks:
  - name: Modify SSH server config
    lineinfile:
      dest: "/etc/ssh/sshd_config"
      regexp: "^PermitRootLogin"
      line: "PermitRootLogin no"

#---------------------------------------------------------------------

## How to generate SHA512 crypted passwords for the user module?
## The answer is taken from Ansible FAQ.

- name: Create user with password
    user:
      name: sandy
      password: "{{ user_pw | password_hash('sha512') }}"

#---------------------------------------------------------------------

## *** Jinja2 Templates ***

## Similar to Puppet. Puppet templates are based upon Ruby's ERB,
## Ansible templates are based upon Jinja2.

## A file containing a Jinja2 template does not need to have any
## specific file extension.

## Use the template module to deploy it:

- name: Use a template file
  hosts: localhost
  gather_facts: yes
  tasks:
    - name: Deploy index.html
      template:
        src: templates/index.j2
        dest: /var/www/html/index.html

$ cat templates/index.j2
The system kernel is: {{ ansible_kernel }}

#---------------------------------------------------------------------

## *** Ansible Roles ***

## Similar to Puppet modules, reusable code in a modular fashion.
## Create a role skeleton:

$ mkdir roles && cd roles
$ ansible-galaxy init my_test_role

$ tree my_test_role/
my_test_role/
├── defaults
│   └── main.yml
├── files
├── handlers
│   └── main.yml
├── meta
│   └── main.yml
├── README.md
├── tasks
│   └── main.yml
├── templates
├── tests
│   ├── inventory
│   └── test.yml
└── vars
    └── main.yml

## As of Ansible 2.4, you can use roles inline with any other tasks
## using import_role or include_role:

---
- hosts: webservers
  tasks:
  - debug:
      msg: "before we run our role"
  - import_role:
      name: example
  - include_role:
      name: example
  - debug:
      msg: "after we ran our role"

## Search for roles from the CLI:

$ ansible-galaxy search --author redhat
$ ansible-galaxy search --galaxy-tags tomcat
$ ansible-galaxy search tomcat --platforms EL

## Ansible Galaxy is a public library of Ansible roles written by users.
## Similar to Puppet Forge. Install a role from Galaxy:

$ ansible-galaxy install <author.name> -p ~/.ansible/roles

## List installed roles:

$ ansible-galaxy list -p ~/.ansible/roles/
- <author.name>, 1.9.5

## To define role source, use requirements.yml:

- src: http://katello.hl.local/pub/ansible-haproxy.tar.gz
  name: haproxy
- src: http://katello.hl.local/pub/ansible-mysql.tar.gz
  name: mysql

$ ansible-galaxy init -r requirements.yml

## The original way to use roles is via the roles: option for a play:

---
- hosts: webservers
  roles:
     - webservers

## The order of execution for your playbook is as follows:

1. Any pre_tasks defined in the play.
2. Any handlers triggered so far will be run.
3. Each role listed in roles will execute in turn (with dependencies).
4. Any tasks defined in the play.
5. Any handlers triggered so far will be run.
6. Any post_tasks defined in the play.
7. Any handlers triggered so far will be run.

## Role dependencies are always executed before the role that includes
## them, and may be recursive.

## RHEL system roles:

$ sudo yum install rhel-system-roles
$ ls /usr/share/doc/rhel-system-roles-1.0/
kdump
network
postfix
selinux
timesync

$ ansible-galaxy list
- rhel-system-roles.selinux, (unknown version)
- linux-system-roles.network, (unknown version)
- rhel-system-roles.postfix, (unknown version)
- rhel-system-roles.timesync, (unknown version)
- rhel-system-roles.kdump, (unknown version)
- linux-system-roles.timesync, (unknown version)
- linux-system-roles.kdump, (unknown version)
- linux-system-roles.postfix, (unknown version)
- rhel-system-roles.network, (unknown version)
- linux-system-roles.selinux, (unknown version)

#---------------------------------------------------------------------

## *** Ansible Variables ***

## Variables for hosts and host groups can be defined by creating two
## directories, group_vars and host_vars, in the same working directory
## as the inventory file or directory.

$ cat group_vars/webserver
my_package: httpd

$ cat group_vars/database
my_package: mariadb

## Whether or not you define any variables, you can access information
## about your hosts with the Special Variables Ansible provides,
## including "magic" variables, facts, and connection variables.

## The most commonly used magic variables are:

hostvars
groups
group_names
inventory_hostname

## The group_names variable contains a list of all the groups the
## current host is in. We can use it to install specific packages:

tasks:
  - name: Install webserver packages
    package:
      name: "{{ item }}"
      state: latest
    loop:
      - httpd
      - firewalld
    when: "'webserver' in group_names"

## The hostvars variable lets you access variables for another host,
## including facts that have been gathered about that host.

{{ hostvars['ansible2.hl.local']['ansible_default_ipv4']['address'] }}
{{ hostvars['ansible2.hl.local']['ansible_fqdn'] }}

## The inventory_hostname variable is the name of the hostname as
## configured in Ansible's inventory host file.
## The groups variable is a list of all the groups in the inventory.

when: inventory_hostname in groups["webservers"]

#---------------------------------------------------------------------

## *** meta - Execute Ansible actions ***

## Meta tasks are a special kind of task which can influence Ansible
## internal execution or state. Choices:

* flush_handlers
* refresh_inventory
* noop
* clear_facts
* clear_host_errors
* end_play
* reset_connection

## Example meta task for how to run handlers after an error occurred:

 tasks:
   - name: Attempt and graceful roll back demo
     block:
       - debug:
           msg: 'I execute normally'
         notify: run me even after an error
       - command: /bin/false
     rescue:
       - name: make sure all handlers run
         meta: flush_handlers
 handlers:
    - name: run me even after an error
      debug:
        msg: 'This handler runs even on error'

## Note: meta is not really a module as such it cannot be overwritten.

#---------------------------------------------------------------------

## *** Ansible Check Mode (Dry Run) ***

## When ansible-playbook is executed with --check it will not make any
## changes on remote systems. To modify the check mode behavior of
## individual tasks, you can use the check_mode option:

- name: this task will run under checkmode and not change the system
  lineinfile:
    line: "PermitRootLogin no"
    dest: /etc/ssh/sshd_config
    state: present
  check_mode: yes

## The above will force a task to run in check mode, even when the
## playbook is called without --check.

#---------------------------------------------------------------------

## *** Ansible Playbook Debugger ***

## Ansible includes a debugger as part of the strategy plugins.
## This debugger enables you to debug as task.

## The debugger keyword can be used on any block where you provide
## a name attribute, such as a play, role, block or task.

---
- hosts: ansible2.hl.local
  tasks:
    - unarchive:
        src: files/archive.tgz
        dest: /tmp/
        remote_src: no
    - name: archive file
      debugger: on_failed
      archive:
        path: /tmp/archive.html
        dest: /tmp/file.gz
        format: tgz

#---------------------------------------------------------------------

## *** Ansible Ignoring Failed Commands ***

## Playbooks will stop executing any more steps on a host that has a
## task fail. To ignore this behaviour, set "ignore_errors" to true:

- name: this will not be counted as a failure
  command: /bin/false
  ignore_errors: yes

## This is useful when you expect a task to fail. For example, you
## are checking if Apache website is reachable. It may be unreachable,
## but you don't want the play to fail because of that.

#---------------------------------------------------------------------

## *** Ansible Run Once ***

## There may be a need to only run a task one time for a batch of hosts:
## This can be achieved by configuring "run_once" on a task:

- command: /tmp/upgrade_database.sh
  run_once: true

#---------------------------------------------------------------------

## *** Ansible Aborting the Play ***

## There will be cases when you will need to abort the entire play on
## failure, not just skip remaining tasks for a host, to avoid breaking
## the system. The "any_errors_fatal" play option will mark all hosts
## as failed if any fails, causing an immediate abort:

- hosts: all
  any_errors_fatal: true
  roles:
    - database

#---------------------------------------------------------------------

## *** Ansible Keywords ***

## These are some of the keywords available on common playbook objects.

## Notable play keywords:

any_errors_fatal
become
become_method
become_user
check_mode
debugger
force_handlers
gather_facts
handlers
hosts
ignore_errors
name
no_log
order
port
post_tasks
pre_tasks
remote_user
roles
run_once
serial
tasks
vars
vars_files

## Notable block keywords:

always
block
rescue
when

## Notable task keywords:

loop
register

#---------------------------------------------------------------------

## *** Ansible Setting Defaults for Modules ***

## It can be useful to define default arguments for a particular module
## using the "module_defaults" attribute:

- hosts: all
  become: true
  module_defaults:
    file:
      owner: root
      group: devops
      mode: "664"
      state: touch
  tasks:
    - file:
        path: /tmp/file1
    - file:
        path: /tmp/file2
    - file:
        path: /tmp/file3

## It is a time saver when you need to use the same module repeatedly.

#---------------------------------------------------------------------

## *** Ansible Best Practices ***

## Tips for making the most of Ansible and Ansible playbooks.

1. Always mention the state. The "state" parameter is optional to a
lot of modules. Whether "state=present" or "state=absent", it is always
best to leave that parameter in your playbooks to make it clear.

2. Generous use of whitespace to break things up, and use of comments,
which start with "#", is encouraged.

3. Always name tasks. It is recommended to provide a description about
why something is being done!

4. Keep it simple. Do not attemtp to use every feature of Ansible
together, all at once. Use what works for you!

5. Ansible best practice has no limit on the amount of variable and
vault files or their names.