Documentation

13. Projects

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, Mercurial, and Red Hat Insights. To create a Red Hat Insights project, refer to Setting up an Insights Project.

Note

By default, the Project Base Path is /var/lib/awx/projects, but this may have been modified by the Tower administrator. It is configured in /etc/tower/settings.py. Use caution when editing this file, as incorrect settings can disable your installation.

This menu displays a list of the projects that are currently available. The list of projects may be sorted and searched by any of the table headers displayed.

Projects - home with example project

Status indicates the state of the project and may be one of the following (note that you can also filter your view by specific status types):

  • Pending - The source control update has been created, but not queued or started yet. Any job (not just source control updates) will stay in pending until it’s actually ready to be run by the system. Reasons for it not being ready because it has dependencies that are currently running so it has to wait until they are done, or there is not enough capacity to run in the locations it is configured to.
  • Waiting - The source control update is in the queue waiting to be executed.
  • Running - The source control update is currently in progress.
  • Successful - The last source control update for this project succeeded.
  • Failed - The last source control update for this project failed.
  • Error - The last source control update job failed to run at all. (To be deprecated.)
  • Canceled - The last source control update for the project was canceled.
  • Never updated - The project is configured for source control, but has never been updated.
  • OK - The project is not configured for source control, and is correctly in place. (To be deprecated.)
  • Missing - Projects are absent from the project base path of /var/lib/awx/projects (applicable for manual or source control managed projects).

For each project listed, you can edit (edit-icon) project properties, copy the project attributes (copy), get the latest SCM revision (refresh), or delete (delete-icon) the project, using the respective icons under the Actions column.

Note

Projects of credential type Manual cannot update or schedule source control-based actions without being reconfigured as an SCM type credential.

Note

If deleting items that are used by other work items, a message opens listing the items are affected by the deletion and prompts you to confirm the deletion. Some screens will contain items that are invalid or previously deleted, so they will fail to run. Below is an example of such a message:

_images/warning-deletion-dependencies.png

13.1. Add a new project

To create a new project:

  1. Click the add button, which launches the Create Project dialog.

Projects - create new project

  1. 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.
  • SCM Type - Select from the drop-down menu list an SCM type associated with this project. Refer to Manage playbooks manually and Manage playbooks using Source Control in the subsequent sections for more detail.

Note

If adding a manual project, each project path inside of the project root folder can only be assigned to one project. If you receive the following message, ensure that you have not already assigned the project path to an existing project:

All of the project paths have been assigned to existing projects, or there are no directories found in the base path. You will need to add a project path before creating a new project.
  1. Click Save when done.

13.1.1. Manage playbooks manually

  • Create one or more directories to store playbooks under the Project Base Path (for example, /var/lib/awx/projects/)
  • Create or copy playbook files into the playbook directory.
  • Ensure that the playbook directory and files are owned by the same UNIX user and group that the Tower service runs as.
  • Ensure that the permissions are appropriate for the playbook directories and files.

If you have trouble adding a project path, check the permissions and SELinux context settings for the project directory and files.

Warning

If you have not added any Ansible playbook directories to the base project path, you will receive the following message from Tower:

Projects - create new warning

Correct this issue by creating the appropriate playbook directories and checking out playbooks from your SCM or otherwise copying playbooks into the appropriate playbook directories.

13.1.2. Manage playbooks using Source Control

  1. Select the appropriate option from the SCM Type drop-down menu list.
  2. Enter the appropriate details into the following fields:
  • SCM URL - See an example in the help help text.
  • SCM Branch - Optionally enter the SCM branch for Mercurial, or the SCM branch, tag, or revision for Git
  • Revision # - Optionally enter the Revision # for Subversion
  • SCM Credential - If authentication is required, select the appropriate SCM credential
  • SCM Update Options:
  • Clean - Remove any local modifications prior to performing an update.
  • Delete on Update - Delete the local repository in its entirety prior to performing an update. Depending on the size of the repository this may significantly increase the amount of time required to complete an update.
  • Update on Launch - Each time a job runs using this project, perform an update to the local repository prior to starting the job. To avoid job overflows if jobs are spawned faster than the project can sync, selecting this allows you to configure a Cache Timeout to cache prior project syncs for a certain number of seconds.

Projects - create SCM project

  1. Click Save to save your project.

Tip

Using a Github link offers an easy way to use a playbook. To help get you started, use the helloworld.yml file available at: https://github.com/ansible/tower-example.git

This link offers a very similar playbook to the one created manually in the instructions found in the Ansible Tower Quick Start Guide. Using it will not alter or harm your system in anyway.

13.1.2.1. Updating projects from source control

  1. Update an existing SCM-based project by selecting the project and clicking the update 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.

projects - list all

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

Project - update status

13.2. 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.

Projects - permissions list for example project

13.2.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 add button to open the Add Users/Teams window.
Add Permissions Form
  1. Specify the users or teams that will have access then assign them specific roles:
  1. Click to select one or multiple checkboxes 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.

Roles Assignment for Selected Users

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)

Tip

Use the Key button in the roles selection pane to display a description of each of the roles.

  1. 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.
Add Permissions - Examples of users and teams selected
  1. Review your role assignments for each user and team.
Add Permissions - Examples of roles applied
  1. Click Save when done, and the Add Users/Teams window closes to display the updated roles assigned for each user and team.

    Permissions tab with Role Assignments

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

_images/permissions-disassociate.png

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

_images/permissions-disassociate-confirm.png

13.3. Work with Notifications

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

_images/projects-notifications-example-list.png

To create a new notification, click the NOTIFICATIONS link from the upper-right side of the notifications list view. If no notifications have been set up, click the NOTIFICATIONS link from above or inside the gray box to add a new notification to create a notification.

Refer to Notifications for more information.

_images/job-template-completed-notifications-view.png

13.4. Work with Job Templates

Clicking on Job Templates allows you to review any job templates or workflow templates associated with this project.

_images/projects-templates-example-list.png

From this view, you can launch or copy the template configuration.

13.5. Work with Schedules

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

_images/projects-schedules-example-list.png

From this view, you can select schedules to edit, turn on or off, or select multiple schedules to delete.

This screen displays a list of the schedules that are currently available for the selected Project. The schedule list may be sorted and searched by Name.

The list of schedules includes:

  • Name: Clicking the schedule name opens the Edit Schedule dialog
  • First Run: The first scheduled run of this task
  • Next Run: The next scheduled run of this task
  • Final Run: If the task has an end date, this is the last scheduled run of the task
  • Last Modified: The last time this schedule was modified

13.5.1. Add a new schedule

To create a new schedule:

  1. Click the add button, which opens the Add Schedule dialog.

Projects - create new schedule

  1. Enter the appropriate details into the following fields:
  • Name (required)
  • Start Date (required)
  • Start Time (required)
  • Local Time Zone - The entered Start Time should be in this timezone
  • UTC Start Time - Calculated from Start Time + Local Time Zone
  • Repeat Frequency - Appropriate scheduling options are displayed depending on the frequency you select

The SCHEDULE DESCRIPTION allows you to review the set schedule and a list of the scheduled occurrences in the selected Local Time Zone.

Caution

Jobs are scheduled in UTC. Repeating jobs that run at a specific time of day may move relative to a local timezone when Daylight Savings Time shifts occur. Essentially, Tower resolves the local time zone based time to UTC when the schedule is saved. To ensure your schedules are correctly set, you should set your schedules in UTC time.

  1. Once done, click Save.

You can use the ON/OFF toggle button to stop an active schedule or activate a stopped schedule.

The schedules overview screen for the project also shows you when the first, next, and final runs are scheduled.

Projects - newly created schedule

13.5.2. 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 install -r roles/requirements.yml -p ./roles/ --force

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.

For more information and examples on the syntax of the requirements.yml file, refer to Advanced Control Over Role Requirements in the Ansible documentation.