Ansible Tower Quick Setup Guide v3.8.0

Thank you for your interest in Ansible Tower. Ansible Tower is a commercial offering that helps teams manage complex multi-tier deployments by adding control, knowledge, and delegation to Ansible-powered environments.

The Ansible Automation Platform Quick Setup Guide covers basic steps for using Ansible Tower and running your first playbook. This document has been updated to include information for the latest release of Ansible Tower v3.8.0.

We Need Feedback!

If you spot a typo in this documentation, or if you have thought of a way to make this manual better, we would love to hear from you! Please send an email to: docs@ansible.com

If you have a suggestion, try to be as specific as possible when describing it. If you have found an error, please include the manual’s title, chapter number/section number, and some of the surrounding text so we can find it easily. We may not be able to respond to every message sent to us, but you can be sure that we will be reading them all!

Ansible Tower Version 3.8.0; November 18, 2020; https://access.redhat.com/

Index

1. Quick Start

Welcome to the Ansible Tower Quick Start Guide. At the end of the Quick Start, you will have a functioning Tower application that you can use to launch more sophisticated playbooks. You can expect the Quick Start process to take less than thirty minutes.

To begin, you must install Ansible Automation Platform and you must choose a target system where an initial playbook can be deployed (provided by Ansible Tower). This first playbook executes simple Ansible tasks, while teaching you how to use Tower, as well as ensuring its proper setup. This can be any sort of system manageable by Ansible, as described at: http://docs.ansible.com/intro_installation.html.

Note
Ansible Automation Platform is offered on a subscription basis. These subscriptions vary in price and support-levels. For more information about subscriptions and features, refer to Licensing, Updates, and Support in the Ansible Automation Platform Installation and Reference Guide.

2. Login as a Superuser

Using the login information provided after your installation completed, open a web browser and log in to Tower by browsing to the Tower server URL at: https://<TOWER_SERVER_NAME>/

Refer to ir_setuplaybook in the Tower Installation and Reference Guide for more information.

Note
Tower installs a self-signed certificate for HTTPS communication which may require acceptance in your browser. Refer to the General Installation Notes in the Tower Installation and Reference Guide for help with replacing this certificate if needed.

Once the Tower UI is accessible, use the credentials specified during the installation process to login. The default username is admin. The password for admin is the value specified for admin_password in your inventory file.

These defaults can be changed later by clicking the Users (users-icon) icon from the left navigation bar.

3. Import a Subscription

Starting with 3.8, Ansible Tower uses available subscriptions or a subscription manifest to authorize the use of Tower. Previously, Tower used a license key and a JSON dictionary of license metadata. Even if you already have valid licenses from previous versions, you must still provide your credentials or a subscriptions manifest again upon upgrading to Ansible Tower 3.8. To obtain your Tower subscription, you can either:

  1. Provide your Red Hat or Satellite username and password on the license page.

  2. Obtain a subscriptions manifest from your Subscription Allocations page on the customer portal. See Obtaining a subscriptions manifest for more detail.

If you have a Red Hat Ansible Automation Platform subscription, use your Red Hat customer credentials when you launch Tower to access your subscription information (see instructions below).

If you do not have a Red Hat Ansible Automation Platform subscription, you can request a trial subscription here or click Request Subscription and follow the instructions to request one.

Disconnected environments with Satellite will be able to use the login flow on vm-based installations if they have configured subscription manager on the Tower instance to connect to their Satellite instance. Recommended workarounds for disconnected environments without Satellite include [1] downloading a manifest from access.redhat.com in a connected environment, then uploading it to the disconnected Tower instance, or [2] connecting to the Internet through a proxy server.

If you have issues with the subscription you have received, please contact your Sales Account Manager or Red Hat Customer Service at https://access.redhat.com/support/contact/customerService/.

When Tower launches for the first time, the Tower Subscription screen automatically displays. Use your Red Hat credentials (username and password) to retrieve and import your subscription, or upload a subscription manifest you received from Red Hat.

  1. Enter your Red Hat customer credentials (username and password) and click Get Subscriptions.

Alternatively, if you have a subscriptions manifest, click the Browse button and navigate to the location where the file is saved to upload it. The subscription manifest is in a zipfile format. See Obtaining a subscriptions manifest for more detail.

  1. The authentication method you use determines how your certificate(s) are stored:

  • If it is a subscriptions manifest, Tower will pull out the appropriate entitlement certificate(s), asks you to choose your subscription, and stores that certificate in the database.

  • If you entered your credential information (username/password), Tower retrieves your configured subscription service. Then it prompts you to choose the subscription you want to run (the example below shows multiple subscriptions) and generates a certificate, which will be stored in the database. You can log in over time and retrieve new subscriptions if you have renewed.

  1. Proceed by checking the End User License Agreement.

  2. The bottom half of the license screen involves analytics data collection. This helps Red Hat improve the product by delivering you a much better user experience. For more information about data collection, refer to Usability Analytics and Data Collection. This option is checked by default, but you may opt out of any of the following:

  • User analytics collects data from the Tower User Interface.

  • Automation analytics provides a high level analysis of your automation with Ansible Tower, which is used to help you identify trends and anomalous use of Tower. For opt-in of Automation Analytics to have any effect, your instance of Ansible Tower must be running on Red Hat Enterprise Linux. See instructions described in the Automation Analytics section.

Note
At this time, Automation Insights is not supported when Ansible Tower is running in the OpenShift Container Platform. You may change your analytics data collection preferences at any time, as described in the Usability Analytics and Data Collection section.
  1. After you have specified your tracking and analytics preferences, click Submit.

Once your subscription has been accepted, Tower briefly displays the license screen and navigates you to the Dashboard of the Ansible Tower interface. For later reference, you can return to the license screen by clicking the Settings (settings) icon from the left navigation bar and select the License tab from the Settings screen.

4. Examine the Tower Dashboard

The Tower Dashboard offers a friendly graphical framework for your IT orchestration needs. Along the left side of the Tower Dashboard is the navigation menu, where you can quickly navigate to your ProjectsInventoriesJob Templates, and Jobs. Access to these elements are no longer in the settings (settings) menu.

Click on the Menu menu icon at the top of the left navigation and the navigation bar expands to show icons and labels; and collapses to show only the icons. View the labels without expanding the menu by hovering over the icons.

The very last item in the navigation bar is the Settings (settings) icon, which provides access to the Tower configuration Settings.

The Settings page allows administrators to configure authentication, jobs, system-level attributes and customize the user interface. Previous versions of Ansible Tower (3.2.x and older) provide the Settings menu at the top of the interface next to the user and logout buttons. Refer to Tower Configuration section for more detail. Additionally, you can now access the product license information from this page.

On the main Tower Dashboard screen, a summary appears listing your current Job Status. Also available for review are summaries of Recently Used Templates and Recent Job Runs.

Regardless of the window or action you’re performing, the very top of each page next to the your user icon is the About (about) icon, which provides you the versions of Ansible Tower and Ansible you are currently running.

Note
Keep in mind that the goal of this Quick Start is to launch a simple playbook. To do this, a number of configuration options must be setup. Completing the quick start configuration tasks now ensures that Tower is configured properly and allows for easier executions of more involved playbooks later on.

5. The Settings Page

To enter the Settings window for Ansible Tower, click the Settings settings icon at the bottom of the left navigation bar. This page allows you to modify your Tower’s configuration, such as settings associated with authentication, jobs, system, user interface, and view or import your license.

For more information on configuring these settings, refer to Tower Configuration section of the Ansible Tower Administration Guide.

6. Review the Organization

An organization is a logical collection of users, teams, projects, and inventories. It is the highest level object in the Tower object hierarchy.

From the left navigation bar, click the Organizations (organizations-icon) icon.

Note
Ansible Tower creates a default organization automatically. Users of Tower with a Self-support level license only have the default organization available and should not delete it. Users of older versions of Tower (prior to 2.2) will not see this default organization.

A default organization has been automatically created and is available to all users of Ansible Tower. It can be used as is or edited later as needed.

For the purpose of this Quick Start Guide, leave the default organization as is and click Save.

Note
If you are using Ansible Tower with a Basic license, you must use the default organization. Only Enterprise or Premium Tower licenses have the ability to add new organizations beyond the default.

To edit the default organization later, expand its ‘Properties’ by clicking on the Edit (edit) button and entering the appropriate details, then save your changes.

Enterprise and Premium Tower license users who want to add a new organization should refer to the Organizations section in the Tower User Guide.

7. Add a User to the Organization

Expand the Users details by clicking on the Users tab of the default organization you just saved (not from the left navigation bar).

  1. To add a user, click the add button.

  1. Since other users have not yet been created, the “admin” user is the only user listed. Select the checkbox beside the “admin” user to select it for this organization. Doing so expands the lower part of the Wizard to assign roles to the selected user.

Click from the drop-down menu to select one or more roles for that user.

Note
For help on what the roles mean, click the Key button. For more information, refer to the Roles section of this guide.

In this example, the admin user has been selected and assigned the admin role within this organization.

  1. When done, click Save.

After saving, the organization’s user information becomes available for viewing and the new user you created appears on the list.

8. Create a new Inventory and add it to the Organization

An inventory is a collection of hosts managed by Tower. Inventories are assigned to organizations, while permissions to launch playbooks against inventories are controlled at the user and/or team level. For more information, refer to InventoriesUsers – Permissions, and Teams – Permissions in the Ansible Tower User Guide.

To review existing inventories:

  1. Click the Inventories (inventories-icon) icon from the left navigation bar.

  1. Click the add button and select Inventory from the drop-down menu list. Smart Inventories are described in further detail in Smart Inventories.

Ansible Tower provides a demo inventory for you to use as you learn how Tower works. Click on the “Demo Inventory” link for the stock inventory provided by Ansible Tower.

8.1. Groups and Hosts

Note that inventories are divided into groups and hosts. A group might represent a particular environment (e.g. “Datacenter 1” or “Stage Testing”), a server type (e.g. “Application Servers” or “DB Servers”), or any other representation of your environment. The groups and hosts that belong to the Demo inventory are shown in the Groups and Hosts tabs, respectively.

In the Groups tab, click the add button to add groups to the inventory.

Similarly, in the Hosts tab, click the add button to add hosts to groups.

Note
Prior to Ansible Tower 2.2, hosts could not be added to the Web Servers inventory before adding a group. If you are using an older version of Tower, click the “Plus” button above the ‘Groups’ section to add a group before adding a host. For this example, suppose that the organization you created earlier has a group of web server hosts supporting the corporate CMS application. To add these hosts to the Web Servers inventory, create a “CMS Web” group. Click the Save button to create the group.

For the purposes of this Quick Start and to test that Tower is setup properly, a local host has been added for your use.

Click Cancel (if no changes were made) or use the breadcrumb navigational links at the top of the Ansible Tower browser to return to the Inventories overview screen. Clicking Save does not exit the edit dialog.

9. Create a Credential

Credentials authenticate the Tower user to launch Ansible playbooks, which can include passwords and SSH keys, against inventory hosts. You can also require the Tower user to enter a password or key phrase when a playbook launches using the credentials feature of Tower.

Create a new credential by clicking the Credentials (credentials-icon) icon from the left navigation bar.

Note
When setting up additional credentials, keep in mind that the user you assign must have root access or be able to use SSH to connect to the host machine.

For the purpose of this Quick Start, a demo credential has been provided for your use.

Click on the “Demo Credential” link name or the Edit (edit) button to review or edit this credential.

10. Setting up a Project

A Project is a logical collection of Ansible playbooks, represented in Tower.

You can manage playbooks and playbook directories by either placing them manually under the Project Base Path on your Tower server, or by placing your playbooks into a source code management (SCM) system supported by Tower, including Git, Subversion, and Mercurial.

Note
It is recommended that, whenever possible, you use source control to manage your playbooks. This type of best practice provides the ability to treat your infrastructure as code and is in line with DevOps ideals. While this Quick Start Guide uses lightweight examples to get you up and running, we suggest using source control to manage playbook for production purposes.

To review existing projects or to create a new one, click the Projects (projects-icon) icon from the left navigation bar.

Ansible Tower simplifies the getting started process by providing you with a Demo Project to work with initially.

Click on the “Demo Project” name link or click on the Edit (edit) button to review the stock project provided by Ansible Tower.

Ansible Tower simplifies the getting started process by providing you with a Demo Project to work with initially.

Click on the “Demo Project” name link or click on the Edit (edit) button to review the stock project provided by Ansible Tower.

Click Cancel (if no changes were made) or use the breadcrumb navigational links at the top of the Ansible Tower browser to return to the Inventories overview screen. Clicking Save does not exit the edit dialog.

Before this project can be used in a job template, you must manually start an SCM sync for this project. Update the SCM-based demo project by clicking the sync button under the project’s available Actions:

Note
Please note that immediately after adding new projects setup to use source control, a “sync” automatically starts that fetches the project details from the configured source control. Because the “Demo” project is pre-stocked, however, you must manually start the inventory sync in order for this project to be used in a job template.

Notice that the status dot beside the name of the project, the revision, and the last run information updates once the sync has completed.

11. Create a new Job Template

A job template combines an Ansible playbook from a project and the settings required to launch it. Review existing jobs or create a new job template by clicking the Templates (templates-icon) icon from the left navigation bar.

For the purpose of this Quick Start, a Demo Job Template has been created for your initial use.

Click on the “Demo Job Template” name link or click on the Edit (edit) button to review the stock job template provided by Ansible Tower.

Click Cancel (if no changes were made) or use the breadcrumb navigational links at the top of the Ansible Tower browser to return to the Templates overview screen. Clicking Save does not exit the edit dialog.

12. Launch it!

From the Job Templates overview screen, click the Launch (launch) button to run this Job Template.

The initial job launch returns a status page which updates automatically using Tower’s Live Event feature until the job is complete.

Once complete, the job results look like the following:

For more details on the job results, refer to Jobs.

Congratulations! Your Tower installation is officially setup and running properly. To learn more about these Tower features or to learn about administration tasks, the Tower API, etc., refer to the following documentation sets: