Chapter 16. Projects
A Project is a logical collection of Ansible playbooks, represented in automation controller. You can manage playbooks and playbook directories different ways:
- By placing them manually under the Project Base Path on your automation controller server.
- By placing your playbooks into a source code management (SCM) system supported by the automation controller. These include Git, Subversion, Mercurial and Red Hat Insights.
For more information on creating a Red Hat Insights project, see Setting up insights remediations.
The Project Base Path is /var/lib/awx/projects. However, this can be modified by the system administrator. It is configured in /etc/tower/conf.d/custom.py.
Use caution when editing this file, as incorrect settings can disable your installation.
The Projects page displays the list of the projects that are currently available.
Automation controller provides you with a Demo Project that you can work with initially.
The default view is collapsed (Compact) with project name and its status, but you can use the
next to each entry to expand for more information.
For each project listed, you can get the latest SCM revision
, edit
the project, or copy
the project attributes, using the icons next to each project.
Projects can be updated while a related job is running.
In cases where you have a large project (around 10 GB), disk space on /tmp may be an issue.
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) stays in pending until it is ready to be run by the system. Possible reasons for it not being ready are:
- It has dependencies that are currently running so it has to wait until they are done.
- 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.
- 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.
-
Missing - Projects are absent from the project base path of
/var/lib/awx/projects. This is applicable for manual or source control managed projects.
Projects of credential type Manual cannot update or schedule source control-based actions without being reconfigured as an SCM type credential.
16.1. Adding a new project
You can create a logical collection of playbooks, called projects in automation controller.
Procedure
-
From the navigation panel, select
. On the Projects page, click to launch the Create Project window.
Enter the appropriate details into the following required fields:
- Name (required)
- Optional: Description
- Organization (required): A project must have at least one organization. Select one organization now to create the project. When the project is created you can add additional organizations.
- Optional: Execution Environment: Enter the name of the execution environment or search from a list of existing ones to run this project. For more information, see Migrating to Execution Environments in the Red Hat Ansible Automation Platform Upgrade and Migration Guide.
- Source Control Type (required): Select an SCM type associated with this project from the menu. Options in the following sections become available depending on the type chosen. For more information, see Manage playbooks manually or Manage playbooks using source control.
- Optional: Content Signature Validation Credential: Use this field to enable content verification. Specify the GPG key to use for validating content signature during project synchronization. If the content has been tampered with, the job will not run. For more information, see Project signing and verification.
- Click .
Additional resources
The following describe the ways projects are sourced:
16.1.1. Managing playbooks manually
Procedure
-
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 service runs as.
- Ensure that the permissions are appropriate for the playbook directories and files.
Troubleshooting
If you have not added any Ansible Playbook directories to the base project path an error message is displayed. Choose one of the following options to troubleshoot this error:
- Create the appropriate playbook directories and check out playbooks from your SCM (spell this*).
- Copy playbooks into the appropriate playbook directories.
16.1.2. Managing playbooks using source control
Choose one of the following options when managing playbooks using source control:
16.1.2.1. SCM Types - Configuring playbooks to use Git and Subversion
Procedure
In the Project Details tab, select the appropriate option (Git or Subversion) from the SCM Type menu.
Enter the appropriate details into the following fields:
- SCM URL - See an example in the tooltip .
-
Optional: SCM Branch/Tag/Commit: Enter the SCM branch, tags, commit hashes, arbitrary refs, or revision number (if applicable) from the source control (Git or Subversion) to checkout. Some commit hashes and references might not be available unless you also provide a custom refspec in the next field. If left blank, the default is
HEADwhich is the last checked out Branch, Tag, or Commit for this project. - SCM Refspec - This field is an option specific to git source control and only advanced users familiar and comfortable with git should specify which references to download from the remote repository. For more information, see Job branch overriding.
- Source Control Credential - If authentication is required, select the appropriate source control credential
Optional: SCM Update Options - select the launch behavior, if applicable:
- Clean - Removes any local modifications before performing an update.
- Delete - Deletes the local repository in its entirety before performing an update. Depending on the size of the repository this can significantly increase the amount of time required to complete an update.
-
Track submodules - Tracks the latest commit. There is more information in the tooltip
.
- Update Revision on Launch - Updates the revision of the project to the current revision in the remote source control, and caching the roles directory from Galaxy or Collections support. Automation controller ensures that the local revision matches and that the roles and collections are up-to-date with the last update. In addition, to avoid job overflows if jobs are spawned faster than the project can synchronize, selecting this enables you to configure a Cache Timeout to cache previous project synchronizations for a given number of seconds.
Allow Branch Override - Enables a job template or an inventory source that uses this project to start with a specified SCM branch or revision other than that of the project. For more information, see Job branch overriding.
- Click Save to save your project.
Using a GitHub link is an easy way to use a playbook. To help get you started, use the helloworld.yml file available here.
This link offers a very similar playbook to the one created manually in the instructions found in Automation controller User Guide. Using it will not alter or harm your system in any way.
16.1.2.2. SCM Type - Configuring playbooks to use Red Hat Insights
Procedure
- In the Project Details page, select Red Hat Insights from the SCM Type menu.
- In the Credential field, select the appropriate credential for use with Insights, as Red Hat Insights requires a credential for authentication.
Optional: In the SCM Update Options field, select the launch behavior, if applicable.
- Clean - Removes any local modifications before performing an update.
- Delete - Deletes the local repository in its entirety before performing an update. Depending on the size of the repository this can significantly increase the amount of time required to complete an update.
Update Revision on Launch - Updates the revision of the project to the current revision in the remote source control, and caches the roles directory from Ansible Galaxy support or Collections support. Automation controller ensures that the local revision matches, and that the roles and collections are up-to-date. If jobs are spawned faster than the project can synchronize, selecting this enables you to configure a Cache Timeout to cache previous project synchronizations for a certain number of seconds, to avoid job overflow.
- Click .
16.1.2.3. SCM Type - Configuring playbooks to use a remote archive
Playbooks that use a remote archive enable projects to be based on a build process that produces a versioned artifact, or release, containing all the requirements for that project in a single archive.
Procedure
- In the Project Details page, select Remote Archive from the SCM Type menu.
Enter the appropriate details into the following fields:
- SCM URL - requires a URL to a remote archive, such as a GitHub Release or a build artifact stored in Artifactory and unpacks it into the project path for use.
- SCM Credential - If authentication is required, select the appropriate SCM credential.
Optional: In the SCM Update Options field, select the launch behavior, if applicable:
- Clean - Removes any local modifications before performing an update.
- Delete - Deletes the local repository in its entirety before performing an update. Depending on the size of the repository this can significantly increase the amount of time required to complete an update.
- Update Revision on Launch - Not recommended. This option updates the revision of the project to the current revision in the remote source control, and caches the roles directory from Ansible Galaxy support or Collections support.
Allow Branch Override - Not recommended. This option enables a job template that uses this project to launch with a specified SCM branch or revision other than that of the project’s.
NoteSince this SCM type is intended to support the concept of unchanging artifacts, it is advisable to disable Galaxy integration (for roles, at a minimum).
- Click .
16.2. Updating projects from source control
Procedure
-
From the navigation panel, select
. Click the sync
icon next to the project that you want to update.
NoteImmediately after adding a project setup to use source control, a sync starts that fetches the project details from the configured source control.
Click the project’s status under the Status column for further information about the update process. This brings you to the Output tab of the Jobs section.
16.3. Work with permissions
The set of permissions assigned to a project (role-based access controls) that provide the ability to read, change, and administer projects, inventories, job templates, and other elements are privileges.
To access the project permissions, select the Access tab of the Projects page. This screen displays a list of users that currently have permissions to this project.
You can sort and search this list by Username, First Name, or Last Name.
16.3.1. Adding project permissions
Manage the permissions that users and teams have to access a project.
Procedure
-
From the navigation panel, select
. - Select the project that you want to update and click the Access tab.
- Click .
- Select a user or team to add and click .
- Select one or more users or teams from the list by clicking the checkbox next to the name to add them as members.
- Click .
Select the roles you want the selected users or teams to have. Be sure to scroll down for a complete list of roles. Different resources have different options available.
Click to apply the roles to the selected users or teams and to add them as members. The updated roles assigned for each user and team are displayed.
16.3.2. Removing permissions from a project
Remove roles for a particular user.
Procedure
-
From the navigation panel, select
. - Select the project that you want to update and click the Access tab.
-
Click the
icon next to the user role in the Roles column.
- Click in the confirmation window to confirm the disassociation.
16.4. Ansible Galaxy support
At the end of a project update, automation controller searches for the requirements.yml file 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 enables you to reference Ansible Galaxy roles or roles within other repositories which can be checked out in conjunction with your own project. The addition of Ansible Galaxy access eliminates the need to create git submodules to achieve this result. Given that SCM projects, along with roles or 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 Settings window:
The cache directory is a subdirectory inside the global projects folder. The content can be copied from the cache location to <job private directory>/requirements_roles.
By default, automation controller has a system-wide setting that enables you to dynamically download roles from the roles/requirements.yml file for SCM projects. You can turn off this setting in the Jobs settings screen of the Settings menu by switching the Enable Role Download toggle button to Off.
Whenever a project synchronization runs, automation controller determines if the project source and any roles from Galaxy or Collections are out of date with the project. Project updates download the roles inside the update.
If jobs need to pick up a change made to an upstream role, updating the project ensures that 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 have to push a new commit to the playbooks repository. You must 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 automation controller 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 repository.
Jobs download the most recent roles before every job run. Roles and collections are locally cached for performance reasons. You must 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 identifies errors and details faster and in a more logical location.
For more information and examples on the syntax of the requirements.yml file, see the role requirements section in the Ansible documentation.
If there are any directories that must be specifically exposed, you can specify those in the Jobs section of the Settings screen in Paths to Expose to Isolated Jobs. You can also update the following entry in the settings file:
AWX_ISOLATION_SHOW_PATHS = ['/list/of/', '/paths']
If your playbooks need to use keys or settings defined in AWX_ISOLATION_SHOW_PATHS, you must add AWX_ISOLATION_SHOW_PATHS to /var/lib/awx/.ssh.
If you made changes in the settings file, be sure to restart services with the automation-controller-service restart command after your changes have been saved.
In the UI, you can configure these settings in the Jobs settings window.
16.5. Collections support
Automation controller supports project-specific Ansible collections in job runs. If you specify a collections requirements file in the SCM at collections/requirements.yml, automation controller installs collections in that file in the implicit project synchronization before a job run.
Automation controller has a system-wide setting that enables collections to be dynamically downloaded from the collections/requirements.yml file for SCM projects. You can turn off this setting in the Jobs settings 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 select Update Revision on Launch in the project SCM Update Options to ensure this:
If you also have collections installed in your execution environment, the collections specified in the project’s requirements.yml file will take precedence when running a job. This precedence applies regardless of the version of the collection. For example, if the collection specified in requirements.yml is older than the collection within the execution environment, the collection specified in requirements.yml is used.
16.5.1. Using collections with automation hub
Before automation controller can use automation hub as the default source for collections content, you must create an API token in the automation hub UI. You then specify this token in automation controller.
Use the following procedure to connect to private automation hub or automation hub, the only difference is which URL you specify.
Procedure
- Go to https://console.redhat.com/ansible/automation-hub/token.
- Click .
-
Click the copy
icon to copy the API token to the clipboard.
Create a credential by choosing one of the following options:
To use automation hub, 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://console.redhat.com/api/automation-hub/ -
AUTH SEVER URL =
https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
-
Galaxy Server URL =
To use private automation hub, create an automation hub credential using a token retrieved from the Repo Management dashboard of your private automation hub and pointing to the published repository URL as shown:
You can create different repositories with different namespaces or collections in them. For each repository in automation hub you must create a different credential.
Copy the Ansible CLI URL from the 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 Create Credential form:
For UI specific instructions, see Red Hat Certified, validated, and Ansible Galaxy content in automation hub.
Go to the organization for which you want to synchronize content from and add the new credential to the organization. This enables you to associate each organization with the credential, or repository, that you want to use content from.
Example
You have two repositories:
-
Prod:
Namespace 1andNamespace 2, each with collectionAandBso:namespace1.collectionA:v2.0.0andnamespace2.collectionB:v2.0.0 Stage:
Namespace 1with only collectionAso:namespace1.collectionA:v1.5.0on , you have a repository URL for Prod and Stage.You can create a credential for each one.
Then you can assign different levels of access to different organizations. For example, you can create a
Developersorganization that has access to both repository, while an Operations organization just has access to the Prod repository only.For UI specific instructions, see Configuring user access for container repositories in private automation hub.
-
Prod:
If automation hub has self-signed certificates, use the toggle to enable the setting Ignore Ansible Galaxy SSL Certificate Verification. For automation hub, which uses a signed certificate, use the toggle to disable it instead. This is a global setting:
Create a project, where the source repository specifies the necessary collections in a requirements file located in the
collections/requirements.ymlfile. For information about the syntax to use, see Using Ansible collections in the Ansible documentation.
-
In the Projects list view, click the sync
icon to update this project. Automation controller fetches the Galaxy collections from the
collections/requirements.ymlfile and reports it as changed. The collections are installed for any job template using this project.
If updates are required 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 large project (around 10 GB), disk space on /tmp may be an issue.
Additional resources
For more information about collections, see Using Collections.
For more information about how Red Hat publishes one of these official collections, which can be used to automate your install directly, see the AWX Ansible Collection documentation.
