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.
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 Status, Name, or Type. For each project listed, you can edit project properties and delete the project, using the edit and delete icons.
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):
/var/lib/awx/projects(applicable for manual or source control managed projects).
Under Actions, the following actions are available:
Projects of credential type Manual cannot update or schedule source control-based actions without being reconfigured as an SCM type credential.
To create a new project:
Each project path 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.
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.
This screen displays a list of the privileges that are currently available for a selected User. The privileges list may be sorted and searched by Name, Type, or Role.
To add permissions to a particular user:
- Click to select one or multiple checkboxes beside the name(s) of the user(s) or team(s) to select them.
The dialog expands to allow you to select the role for each resource you chose.
- Select the role from the drop-down menu list provided:
- Admin allows read, run, and edit privileges
- Use allows use of the project in a job template
- Update allows updating of project via the SCM Update
You do not have to choose between teams or users. You can assign different roles to different users or teams both at the same time to avoid having to click the button. To do so, simply go from one tab to another after making your selections without saving.
Use the Key button to display the help text for each of the roles applicable to the resource selected.
Review your role assignments for each of the Tower objects by clicking on their respective buttons in the expanded section 2 of the Add Permissions Wizard.
Click Save when done, and the Add Permissions Wizard closes to display the updated profile for the user(s) and team(s) with the roles assigned for each selected resource.
To remove Permissions for a particular resource, click the Disassociate (x) button next to its resource.
This launches a confirmation dialog, asking you to confirm the disassociation.
Clicking on Notifications allows you to review any notification integrations you have setup.
Click on the button to create a notification.
Refer to Notifications for more information.
If you have trouble adding a project path, check the permissions and SELinux context settings for the project directory and files.
If you have not added any Ansible playbook directories to the base project path, you will receive the following message from Tower:
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.
- SCM URL - See an example in the 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.
Using a Github link offers an easy way to use a playbook. To help get you started, use the
helloworld.ymlfile 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.
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.
3. To set a schedule for updating the project from SCM, click the button. This will navigate to the Schedules screen.
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:
Buttons located in the upper right corner of the Schedules screen provide the following actions:
To create a new schedule:
The SCHEDULE DESCRIPTION allows you to review the set schedule and a list of the scheduled occurrences in the selected Local Time Zone.
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.
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.
There are several actions available for schedules, under the Actions column:
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.