14. Projects¶

14.1. Add a new project¶

To create a new project:

1. Click the button, which launches the Create Project window.

2. Enter the appropriate details into the following required fields:

• Name

• Description (optional)

• Organization - A project must have at least one organization. Pick one organization now to create the project, and then after the project is created you can add additional organizations.

• Ansible Environment (optional) - Select from the drop-down menu list a custom virtual environment on which to run this project. This field is only present if custom environments were previously created. See Using virtualenv with Ansible Tower in the Ansible Tower Upgrade and Migration Guide.

• SCM Type - Select from the drop-down menu list an SCM type associated with this project. The options in the subsequent section become available depend on the type you choose. Refer to Manage playbooks manually or Manage playbooks using source control in the subsequent sections for more detail.

14.2. Updating projects from source control¶

1. Update an existing SCM-based project by selecting the project and clicking the button.

Note

Please note that immediately after adding a project setup to use source control, a “Sync” starts that fetches the project details from the configured source control.

2. Click on the dot under Status (far left, beside the name of the Project) to get further details about the update process.

14.3. Work with Permissions¶

The set of Permissions assigned to this project (role-based access controls) that provide the ability to read, modify, and administer projects, inventories, job templates, and other Tower elements are Privileges.

You can access the project permissions via the Permissions tab next to the Details tab. This screen displays a list of users that currently have permissions to this project. The list may be sorted and searched by User, Role, or Team Role.

14.3.1. Add Permissions¶

The Permissions tab allows you to review, grant, edit, and remove associated permissions for users as well as team members. To assign permissions to a particular user for this resource:

1. Click the Permissions tab.

2. Click the button to open the Add Users/Teams window.

3. Specify the users or teams that will have access then assign them specific roles:

1. Click to select one or multiple check boxes beside the name(s) of the user(s) or team(s) to select them.

Note

You can select multiple users and teams at the same time by navigating between the Users and Teams tabs without saving.

After selections are made, the window expands to allow you to select a role from the drop-down menu list for each user or team you chose.

The example above shows options associated with inventories. Different resources have different options available:

• Admin allows read, run, and edit privileges (applies to all resources)

• Use allows use of a resource in a job template (applies all resources except job templates)

• Update allows updating of project via the SCM Update (applies to projects and inventories)

• Ad Hoc allows use of Ad Hoc commands (applies to inventories)

• Execute allows launching of a job template (applies to job templates)

• Read allows view-only access (applies to all resources)

Tip

Use the Key button in the roles selection pane to display a description of each of the roles. For more information, refer to the Roles section of this guide.

2. Select the role to apply to the selected user or team.

Note

You can assign roles to multiple users and teams by navigating between the Users and Teams tabs without saving.

4. Review your role assignments for each user and team.

5. Click Save when done, and the Add Users/Teams window closes to display the updated roles assigned for each user and team.

   

To remove Permissions for a particular user, click the Disassociate (x) button next to its resource.

This launches a confirmation dialog, asking you to confirm the disassociation.

14.4. Work with Notifications¶

Clicking the Notifications tab allows you to review any notification integrations you have setup.

Use the toggles to enable or disable the notifications to use with your particular project. For more detail, see Enable and Disable Notifications.

If no notifications have been set up, click the NOTIFICATIONS link from inside the gray box to create a new notification.

Refer to Notification Types for additional details on configuring various notification types.

14.5. Work with Job Templates¶

Clicking on Job Templates allows you to add and review any job templates or workflow templates associated with this project. Click Expanded to view details about each template, including the statuses of the jobs that ran using that template, and other useful information. You can sort this list by various criteria, and perform a search to filter the templates of interest.

From this view, you can also launch (), copy (), or delete () the template configuration. Note, the example above shows the expanded view.

14.6. Work with Schedules¶

Clicking on Schedules allows you to review any schedules set up for this project.

14.7. Ansible Galaxy Support¶

At the end of a Project update, Tower searches for a file called requirements.yml in the roles directory, located at <project-top-level-directory>/roles/requirements.yml. If this file is found, the following command automatically runs:

ansible-galaxy role install -r roles/requirements.yml -p <project-specific cache location>/requirements_roles -vvv

This file allows you to reference Galaxy roles or roles within other repositories which can be checked out in conjunction with your own project. The addition of this Ansible Galaxy support eliminates the need to create git submodules for achieving this result. Given that SCM projects (along with roles/collections) are pulled into and executed from a private job environment, a <private job directory> specific to the project within /tmp is created by default. However, you can specify another Job Execution Path based on your environment in the Jobs Settings tab of the Configure Tower window:

The cache directory is a subdirectory inside the global projects folder. The content may be copied from the cache location to <job private directory>/requirements_roles location.

By default, Ansible Tower has a system-wide setting that allows roles to be dynamically downloaded from the roles/requirements.yml file for SCM projects. You may turn off this setting in the Jobs tab of the Settings () menu by switching the Enable Role Download toggle button to OFF.

Whenever a project sync runs, Tower determines if the project source and any roles from Galaxy and/or Collections are out of date with the project. Project updates will download the roles inside the update.

If jobs need to pick up a change made to an upstream role, updating the project will ensure this happens. A change to the role means that a new commit was pushed to the provision-role source control. To make this change take effect in a job, you do not need to push a new commit to the playbooks repo, but you do need to update the project, which downloads roles to a local cache. For instance, say you have two git repositories in source control. The first one is playbooks and the project in Tower points to this URL. The second one is provision-role and it is referenced by the roles/requirements.yml file inside of the playbooks git repo.

In short, jobs would download the most recent roles before every job run. Roles and collections are locally cached for performance reasons, and you will need to select Update Revision on Launch in the project SCM Update Options to ensure that the upstream role is re-downloaded before each job run:

The update happens much earlier in the process than the sync, so this surfaces errors and details faster and in a more logic place.

For more information and examples on the syntax of the requirements.yml file, refer to the role requirements section in the Ansible documentation.

If there are any directories that should specifically be exposed, you can specify those in the Configure Tower screen in the Paths to Expose to Isolated Jobs or by updating the following entry in the settings file:

AWX_PROOT_SHOW_PATHS = ['/list/of/', '/paths']

Note

The primary file you may want to add to AWX_PROOT_SHOW_PATHS is /var/lib/awx/.ssh, if your playbooks need to use keys or settings defined there.

If you made changes in the settings file, be sure to restart services with the ansible-tower-service restart command after your changes have been saved.

In the Tower User Interface, you can configure these settings in the Jobs settings window.

14.8. Collections Support¶

Tower supports project-specific Ansible collections in job runs. If you specify a collections requirements file in the SCM at collections/requirements.yml, Tower will install collections in that file in the implicit project sync before a job run. To specify a collections requirement:

ansible-galaxy collection install -r requirements.yml -p <job tmp location>

By default, Ansible Tower has a system-wide setting that allows collections to be dynamically downloaded from the collections/requirements.yml file for SCM projects. You may turn off this setting in the Jobs tab of the Settings () menu by switching the Enable Collections Download toggle button to OFF.

Roles and collections are locally cached for performance reasons, and you will need to select Update Revision on Launch in the project SCM Update Options to ensure this:

14.8.1. Using Collections in Tower¶

Before Tower can use Automation Hub as the default source for collections content, you need to create an API token in the Automation Hub UI so that it could be specified in Ansible Tower. You may connect to a private Automation Hub or a public Automation Hub collection, the only difference is which URL you specify.

1. Navigate to https://cloud.redhat.com/ansible/automation-hub/token and click Load token.

2. Click the copy icon to copy the API token to the clipboard.

3. To use the public Automation Hub in Tower, create an Automation Hub credential using the copied token and pointing to the URLs shown in the Server URL and SSO URL fields of the token page:

• Galaxy Server URL = https://cloud.redhat.com/api/automation-hub/

• AUTH SEVER URL = https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token

4. To use a private Automation Hub in Tower, create an Automation Hub credential using a token retrieved from the Repo Management dashboard of your local Automation Hub and pointing to the published repo URL as shown:

You can create different repos with different namespaces/collections in them. But for each repo in Automation Hub you need to create a different Automation Hub credential. Copy the Ansible CLI URL from the Automation Hub UI in the format of https://$<hub_url>/api/galaxy/content/<repo you want to pull from> into the Galaxy Server URL field of the Tower Create Credential form:

Note

The token generated in private Automation Hub is used for all content. Repositories such as rh-certified and community do not have dedicated tokens. You should use the token generated for all appropriate ansible-galaxy definitions in the ansible.cfg file. See Locate and configure the Ansible configuration file in the Ansible Tower Administration Guide for detail.

Refer to Managing Red Hat Certified and Ansible Galaxy Collections in Ansible Hub for Automation Hub UI-specific instructions.

5. Navigate to the organization for which you want to be able to sync content from Automation Hub and add the new Automation Hub credential to the organization. This step allows you to associate each organization with the Automation Hub credential (i.e. repo) that you want to be able to use content from.

Note

Suppose you have two repos:

• Prod: Namespace 1 and Namespace 2, each with collection A and B so: namespace1.collectionA:v2.0.0 and namespace2.collectionB:v2.0.0

• Stage: Namespace 1 with only collection A so: namespace1.collectionA:v1.5.0 on Automation Hub, you will have a repo URL for Prod and Stage.

You can create an Automation Hub credential for each one. Then you can assign different levels of access to different organizations. For example, you can create a Developers organization has access to both repos, while an Operations organization just has access to the Automation Hub Prod repo only.

Refer to Managing User Access in Ansible Hub for Automation Hub UI-specific instructions.

6. If the Automation Hub has self-signed certificates, click the toggle to enable the Tower setting Ignore Ansible Galaxy SSL Certificate Verification. For public Automation Hub, which uses a signed certificate, click the toggle to disable it instead. Note this is a global setting:

7. Create a project, where the source repository specifies the necessary collections in a requirements file located in the collections/requirements.yml file. Refer to the syntax described in the Ansible documentation: https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#install-multiple-collections-with-a-requirements-file.

8. In the Projects list view, click to run an update against this project. Tower fetches the Galaxy collections from the collections/requirements.yml file and report it as changed; and the collections will now be installed for any job template using this project.

Note

If updates are needed from Galaxy or Collections, a sync is performed that downloads the required roles, consuming that much more space in your /tmp file. In cases where you have a big project (around 10 GB), disk space on /tmp may be an issue.

For more information on collections, refer to Using Collections. For more information on how Red Hat itself publishes one of these official collections, which can be used to automate your Tower install directly, refer to the AWX Ansible Collection documentation. This page is accessible with your Red Hat customer credentials as part of your Red Hat Ansible Automation Platform subscription.