====== AWX ======

Ansible Tower is centered around the idea of organizing Projects (which run your playbooks via Jobs) and Inventories (which describe the servers on which your playbooks should be run) inside of Organizations. Organizations can then be set up with different levels of access based on Users and Credentials grouped in different Teams.

http://awx.cm.in.tum.de
===== Configuration =====
==== LDAP Authentication ====
  - Go to ''Settings->Authentication'' and choose ''LDAP'' as sub category
  - Set the LDAP Server URI <code>ldaps://ldap.in.tum.de:636</code>
  - Set Group type to PosixGroupType
  - If you wish to restrict logins to a certain group set LDAP require group to the DN: <code> cn=il11admin,ou=Gruppen,ou=IN,o=TUM,c=DE </code>
  - Tell AWX how to search for users and groups by setting the User and group search options respectively <code>[
 "ou=Personen, ou=IN, o=TUM, c=de",
 "SCOPE_SUBTREE",
 "(uid=%(user)s)"
]
</code><code>
[
 "ou=Gruppen, ou=IN, o=TUM, c=de",
 "SCOPE_SUBTREE",
 "(objectClass=posixGroup)"
]
</code>The first line is the base DN, the second line tells awx to search subtrees and the third line filters the results.
  - Tell AWX which groups have superuser access <code>
{
 "is_superuser": "cn=il11admin,ou=Gruppen,ou=IN, o=TUM,c=DE"
}</code>
  - Map groups to Organizations and Teams. The following example adds all users in il11 to the Organization I11 with all users in il11admins being added to the organizations admins as well as the Admin Team within the organization:<code>
{
 "I11": {
  "admins": "cn=il11admin,ou=Gruppen,ou=IN, o=TUM,c=DE",
  "remove_users": false,
  "remove_admins": false,
  "users": "cn=il11,ou=Gruppen,ou=IN,o=TUM,c=DE"
 }
}
</code><code>
{
 "Admin": {
  "organization": "I11",
  "users": "cn=il11admin,ou=Gruppen,ou=IN,o=TUM,c=DE",
  "remove": true
 }
}</code>

==== SSL and Reverse Proxy ====
The default awx Port listens to 8080. In order to access awx on the standard ports an nginx proxy is used to relay the traffic from 80/443 to 8080. Also ssl certificates can be configured in nginx to secure the traffic.

For callbacks to work with this proxy setup a configuration option needs to be enabled:
  * Go to Settings -> System
  * Under "Remote Host Headers" the entry should look like this <code>HTTP_X_FORWARDED_FOR, REMOTE_ADDR, REMOTE_HOST</code>
  * Callbacks can now be made with remote_host and remote_addr in the post header <code>
curl -H "remote-host: <host>" -H "remote-ip: $(ip addr show | grep 'inet ' | head -2 | tail -1 | awk '{print $2}' | cut -f1 -d'/')" --noproxy "*" -k -XPOST --data "host_config_key=d1d1092f-1638-4ac3-aca6-a76dd5156fc9" https://awx.cm.in.tum.de/api/v2/job_templates/16/callback/  </code>

==== Building custom docker images ====
In order to use some ansible modules it may be necessary to install extra packages in the awx_task container. The best way to do this is to build custom images for the containers, which can be done with the official installer:
  - edit the ''inventory'' file in ''awx/installer'' directory (where ''awx'' is the root of the cloned awx repository) and remove the following line: <code> dockerhub_base=ansible </code>
  - add packages to be installed in ''awx/installer/roles/image_build/templates/Dockerfile.j2''. Note that as AWX uses centos for its base image package names may differ from those in Ubuntu.
  - For additional python modules follow the instructions in ''awx/requirements/README'' and add the modules to ''awx/requirements/requirements_ansible.in'' before executing pip-compile
  - in ''awx/installer'' execute the following <code> # ansible-playbook -i inventory install.yml </code>
==== Inventory Scripts ====
AWX can use scripts to automatically update inventories. They can be written in any scripting language installed in the ''awx_task'' container and must produce output in json format:
<code>
{
  "_meta": {
    "hostvars": {
      "host1": {
        "var1": "value1",
        "var2": "value2"
      },
      "host2": ...
    }
  },
  "group1": [
    "host1",
    "host2",...
  ],
  "group2": ...
}
</code>
To use an inventory script add it as a source to an existing regular inventory.
==== Custom credential types ====
AWX does not provide credential types for all services. It is however possible to create new custom types under ''Credential Types->+''
  - Specify the input fields. typically this will be username and password. Fields marked as secret will get a password entry textfield while others get a regular entry. Required fields must be listed separately.<code>
fields:
  - id: username
    type: string
    label: Username
  - id: password
    type: string
    label: Password
    secret: true
required:
  - username
  - password
</code>
  - Specify how the credentials will be injected. This can be done using either environment variables or awx extra vars.<code>
env:
  MARIADB_PASSWORD: '{{ password }}'
  MARIADB_USER: '{{ username }}'
extra_vars:
  MARIADB_PASSWORD: '{{ password }}'
  MARIADB_USER: '{{ username }}'
</code>

===== Backup & Restore =====
  * Install ansible-tower-cli tool <code>sudo pip3 install ansible-tower-cli</code>
  * Configure Tower-cli for usage with untrusted hosts (wrong certificate)<code>sudo vim /home/i11/.tower_cli.cfg
---
[general]
host = one-awx.cm.in.tum.de
insecure = True
verify_ssl = False </code>
  * Don't forget to unset the local proxy variables, otherwise the connection times out <code>
unset http_proxy HTTP_PROXY https_proxy HTTPS_PROXY </code>
  * Login as user <code>tower-cli login cmadmin</code>
  * Get Backup from AWX object as json (takes some minutes) <code> tower-cli receive --all > awx_backup.json</code>
  * Change the host and delete the token from the config file, login on the host where to restore the backup
  * Restore to another AWX host with <code>tower-cli send awx_backup.json</code>

===== Develop New Playbook =====
Developing new playbooks and roles includes a lot of testing. AWX uses git to get the latest project / file changes. During development it is unfeasible to commit every small change to git, therefore a different procedure and pipeline is used.

  * Main: awx.cm.in.tum.de
  * Development: dev-awx.cm.in.tum.de

The project on dev-awx.cm.in.tum.de is checked out manually on the VM itself. Log in on the VM dev-awx and go to the project directory ''/var/lib/awx/projects/manual-ansible-scripts'' and check out the latest changes: <code>sudo git fetch origin
sudo git merge origin/master </code>

Now you can locally make changes to the project on the VM and immediately start playbooks on dev-awx that use/test these changes. After you are finished adopt the changes to the project on your laptop/pc and commit them to git.