Ansible Tower

Installation

• Standard setup: https://releases.ansible.com/ansible-tower/setup/: requires internet connectivity

• Bundled installer: https://releases.ansible.com/ansible-tower/setup-bundle: can install on systems disconnected from the internet

Procedure

• Downloads a compressed archive file named something like:

  • ansible-tower-setup-bundle-3.6.2-1.tar.gz

• Extract the archive file on your Linux system:

  • tar zxf ansible-tower-setup-bundle-3.6.2-1.tar.gz

• In the unpacked directory, edit the inventory file

  • Set your admin_password (will be used for the “admin” user to log in)

  • Set the pg_password and rabbitmq_password

• Run the install script in the unpacked directory

  • ./setup.sh

Configuration

User and Teams

• Users allow you to control which users can configure resources and run jobs using specific job templates and inventories.

• You can assign users to teams if a group of users all need the same access to certain resources.

• This can be useful to restrict users from using specific credentials or inventories so that they can only run jobs on specific sets of managed hosts.

• You can configure job templates so that users can just launch jobs using the template as-is, or so that they can customize the template before launching it.

User Types

• By default, the Ansible Tower installer creates an admin user account with full control of the Ansible Tower installation. Using the special admin account, an Ansible Tower administrator can log in to the web interface and create additional users.

• The three user types in Ansible Tower are:

  • System Administrator

  • System Auditor

  • Normal User

Role-Based Access Controls

• Users and teams are assigned roles that grant permissions on an object in Ansible Tower.

  • Inventories, credentials, projects, job templates, and so on.

• All users in a team inherit the permissions granted by the team's roles.

• Common roles include

  • Admin (granting administrative control over the object)

  • Read (granting read access to the object)

  • Execute (on a job template, grants permission to launch it)

Organizations

• An organization is a logical collection of teams, projects, and inventories.

• All users must belong to an organization.

• Organizations, allow you to configure a collection of users and teams to work with only those Ansible Tower resources that you want them to use.

• As part of the Red Hat Ansible Tower installation, a default organization is created.

Organization Roles

• Newly created users inherit specific roles from their organization, based on their user type.

• You can assign additional roles to a user after creation to grant permissions to view, use, or change other Ansible Tower objects.

• An organization is itself one of these objects.

• There are four roles that users can be assigned on an organization:

  • Organizational Admin

  • Auditor

  • Member

  • Read

Teams

• Teams make managing roles on objects more efficient than managing them for each user separately.

• Rather than assigning the same roles to multiple users, an administrator can assign roles to the team representing a group of users.

• In Ansible Tower, users exist as objects at an Ansible Tower-wide level.

  • Users can be assigned roles in multiple organizations.

• A team, by contrast, belongs to exactly one organization.

Team Roles

• Users can be assigned roles for a particular team.

• These roles control whether the user is considered part of that team, can administer it, or can view its membership.

• A user can be assigned one or more of the following team roles:

  • Admin

  • Member

  • Read

Inventory

Inventory Roles

Role	Description
Admin	The inventory Admin role grants users full permissions over an inventory. These permissions
include deletion and modification of the inventory. In addition, this role also grants
permissions associated with the inventory roles Use, Ad Hoc, and Update.
Use	The inventory Use role grants users the ability to use an inventory in a job template resource.
This controls which inventory is used to launch jobs using the job template's playbook.
Ad Hoc	The inventory Ad Hoc role grants users the ability to use the inventory to execute ad hoc
commands.
Update	The inventory Update role grants users the ability to update a dynamic inventory from its
external data source.
Read	The inventory Read role grants users the ability to view the contents of an inventory

Inventory Variables

• When you manage a static inventory in the Ansible Tower web UI, you may define inventory variables directly in the inventory objects.

  • Variables set in the inventory details affect all hosts in the inventory.

  • Variables set in a group's details are the equivalent of group_vars.

  • Variables set in a host's details are the equivalent of host_vars

Machine Credentials

• To securely provide the ansible_user and ansible_password setting for managed hosts, create a machine credential

• Users of Ansible Tower can use these credentials, but cannot retrieve the value of the password directly

• The machine credential’s password is stored in encrypted form in Ansible Tower

Credential Roles

Role	Description
Admin	The Credential Admin role grants Users full permissions on a Credential. These permissions include deletion and modification of the Credential, as well as the ability to use the Credential in a Job Template.
Use	The Credential Use role grants Users the ability to use a Credential in a Job Template.
Read	The Credential Read role grants Users the ability to view the details of a Credential. This still does not allow them to decrypt the secrets which belong to that Credential through the web interface.

Project

Git Repository

• Clean: This SCM update option removes local modifications to project materials on Ansible Tower before getting the latest revision from the source control repository.

• Delete on Update: This SCM option completely removes the local project repository on Ansible Tower before retrieving the latest revision from the source control repository. For large repositories, this operation takes longer than Clean.

• Update on Launch: This SCM option automatically updates the project from the source control repository each time you use the project to launch a job. Ansible Tower tracks this update as a separate job. If this option is not selected, you must update the project manually.

Project Roles

Role	Description
Admin	The Admin role grants users full access to a Project. When granted this role on a Project, a user can delete the Project and modify its properties, permissions included. In addition, this role also grants users the Use, Update, and Read roles.
Use	The Use role grants users the ability to use a Project in a Template resource. This role also grants users the permissions associated with the Project Read role.
Update	The Update role grants users the ability to manually update or schedule an update of a Project's materials from its SCM source. This role also grants users the permissions associated with the Project Read role.
Read	The Read role grants users the ability to view the details, permissions, and notifications associated with a Project.

Job Template

• A job template is used to run playbooks.

• It combines the project containing the playbook with an inventory, the machine credentials for authenticating to hosts, and parameters that control how the playbook runs.

• Once the template is created it can be reused to run the playbook again, as often as needed.

• Job templates are only set up once but run whenever a playbook is updated.

• They can also be run to ensure expected host configuration and conform to defined standards.

• The Launch button, or icon, for a job template is used to run its playbook.

Template Roles

Role	Description
Admin	The Admin role provides a user the ability to delete a Job Template or edit its properties, including its associated permissions. This role also grants permissions associated with the Job Template Execute and Read roles.
Execute	The Execute role grants users permission to execute a job using the Job Template. It also grants the Users permission to schedule a job using the Job Template. This role also grants permissions associated with the Job Template Read role.
Read	The Read role grants users read-only access to view the properties of a Job Template. It also grants access to view other information related to the Job Template, such as the list of jobs executed using the Job Template, as well as its associated permissions and notifications.

REST API

• https://$IPorName/api

Lauching a Job using API

Get parameter needed to run a job

curl -X GET --user admin:pass https://$IPorName/api/v2/job_templates/"Demo Job Template"/launch/ -k -s | json_pp

Launch a job

curl -X POST --user admin:pass https://$IPorName/api/v2/job_templates/"Demo Job Template"/launch/ -k -s | json_pp

Launching a Job Using API from an Ansible Playbook

• Ansible Tower can even run that playbook from a job template and use it to launch another job template as one of its tasks.

• In the playbook, use a task with the uri module to talk to the API.

  • This is equivalent to the curl command in the earlier example.

  • You must specify the URL for the job template, using its ID or named URL.

  • You must authenticate to Ansible Tower as a user that has permission to launch the job.

  • The task must run on a managed host that can talk to Ansible Tower, but it does not need to run on the Tower itself.

Playbook

• To access the API, Ansible requires the login credentials for a user that is allowed to launch a job from a job template.

• The playbook also requires the URL of the actual API to which Ansible must connect. This example uses the named URL of the Demo Job Template. Notice how the spaces in the job template's name have been specified using the %20 code. You can also use the urlencode filter: tower_job: "{{'Demo Job Template' | urlencode }}"

• Ansible can access the Ansible Tower API from the Ansible Tower server by using the uri module.

--- 
- name: Tower API
  hosts: localhost
  become: false

  vars: 
    tower_user: admin
    tower_pass: pass
    tower_host: demo.com
    tower_job: Demo%20Job%20Template

  tasks:
    - name: Launch a new job
      uri:
        url: https://{{tower_host}}/api/v2/job_templates/{{tower_job}}/launch/
        method: POST
        validate_certs: no
        return_content: yes
        user: "{{ tower_user }}"
        password: "{{ tower_pass }}"
        force_basic_auth: yes
        status_code: 201

Troubleshooting Ansible

Comnponents of Ansible Tower

• There are four main components managed together:

  • Nginx Provides web server for the UI and API

  • PostgreSQL Internal relational database server

  • supervisord Process control system that manages the application: running jobs, etc.

  • rabbitmq-server AMQP message broker supporting signalling by application components

• In addition, a memcached memory caching daemon is used as a local caching service.

Port Requirements

• These services communicate with each other using normal network protocols.

  • Nginx 80/tcp and 443/tcp

  • PostgreSQL 5432/tcp

  • rabbitmq-server beam listens on 5672/tcp, 15672/tcp, and 25672/tcp

• If you are running a multi-machine clustered Ansible Tower installation, these may need to be exposed to allow the different servers of your Ansible Tower cluster to talk to each other.

• This is why setting good passwords for PostgreSQL and RabbitMQ in your setup inventory is important.

• In the single-machine integrated database installation demonstrated here, you only need to expose 80/tcp and 443/tcp.

Commands to manage Tower

• ansible-tower-service status Check if the services are running properly

• ansible-tower-service start Start all services

• ansible-tower-service stop Stop all services

• ansible-tower-service restart Restart all services

• The Red Hat Ansible Tower web application is a collection of Django-based components managed by supervisord.

  • You can use supervisord status to check the status of these services: supervisord status

Change Built-in admin superuser's password:

• Log in to the Ansible Tower server as the Linux user root or awx.

• Run awx-manage changepassword admin.

Configuration and Data Files

• The main configuration files for Ansible Tower are kept in the /etc/tower directory.

  • The most important is settings.py, which specifies the locations for job output, storage, and other key directory locations.

  • You should not need to edit these manually, use setup.sh.

• A number of key data files are kept in the /var/lib/awx directory:

  • /var/lib/awx/projects is where your project files are downloaded

  • /var/lib/awx/job_status stores job status output from playbook runs

  • /var/lib/awx/public/static is the static root directory for the Django applications

  • You should not need to manage these manually either, but your Ansible Tower can have problems if the storage device for /var/lib/awx becomes full

Log Files

• The /var/log/tower directory stores logs for the key servers supporting the application:

  • tower.log The main log file for Ansible Tower.

  • task_system.log Logs various system housekeeping tasks.

  • setup*.log Log files from setup.sh when run to install, backup, or restore.

• The /var/log/supervisor directory stores logs for the Django-based applications:

  • supervisord.log The main log file for supervisord.

  • Other files contain information about the activity of various applications.

• You can configure Ansible Tower to send information to log aggregation services.

  • See https://docs.ansible.com/ansible-tower/latest/html/administration/

Common Troubleshooting Scenarios

• Problems running playbooks:

  • Playbooks are confined to /tmp on the Ansible Tower server when run.

  • This limits resources they can access and can impact tasks delegated to localhost.

• Problems connecting to managed hosts:

  • Verify that you can establish an SSH connection (or WinRM with Windows hosts) to the managed host.

  • Review your inventory file and check host names, IP addresses, and connection variables.

• Playbook in the project does not appear in the list when configuring a job template:

  • Make sure the YAML syntax of the playbook is correct and can be parsed by Ansible

  • /var/lib/awx/projects should allow user awx to view the files

• Playbook stays in "Pending" state:

  • Ensure that Ansible Tower has enough memory available.

  • Use supervisord status to make sure the Django applications are running.

  • Ensure that /var has at least 1 GB of free space.

  • Try ansible-tower-service restart

• Provided hosts list is empty ("Skipping: No Hosts Matched"):

  • Make sure the hosts declaration in your play matches the group or host names in the inventory.

  • Make sure group names have no spaces in them. Underscores are valid.

  • If you specified a limit in the job template, make sure its syntax is valid and matches something in your inventory.