Search
SupportConsoleDevelopersStart a trialContact

Chapter 11. Projects

download PDF

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 Red Hat Insights for Red Hat Ansible Automation Platform Remediations.

Note

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.

A Demo Project is provided that you can work with initially.

The default view is collapsed (Compact) with project name and its status, but you can use the Arrow next to each entry to expand for more information.

For each project listed, you can get the latest SCM revision Refresh , edit Edit the project, or copy 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.
Note

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

11.1. Adding a new project

You can create a logical collection of playbooks, called projects in automation controller.

Procedure

  1. From the navigation panel, select Automation Execution Projects.
  2. On the Projects page, click Create project to launch the Create Project window.

  3. 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 Creating and using execution environments.
    • 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 Managing playbooks manually or Managing 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.
  4. Click Create project.

Additional resources

The following describe the ways projects are sourced:

11.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 (Source code management) SCM.
    • Copy playbooks into the appropriate playbook directories.

11.1.2. Managing playbooks using source control

Choose one of the following options when managing playbooks using source control:

11.1.2.1. SCM Types - Configuring playbooks to use Git and Subversion

Procedure

  1. From the navigation panel, select Automation Execution Projects.
  2. Click the project name you want to use.
  3. In the project Details tab, click Edit project.
  4. Select the appropriate option (Git or Subversion) from the Source control type menu.

  5. Enter the appropriate details into the following fields:

    • Source control URL - See an example in the tooltip .
    • Optional: Source control 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 give a custom refspec in the next field. If left blank, the default is HEAD which is the last checked out Branch, Tag, or Commit for this project.
    • Source control 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.

  6. Optional: 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 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 Ansible Galaxy support 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.
  7. Click Save project.

11.1.2.2. SCM Type - Configuring playbooks to use Red Hat Insights

Procedure

  1. From the navigation panel, select Automation Execution Projects.
  2. Click the project name you want to use.
  3. In the project Details tab, click Edit project.
  4. Select Red Hat Insights from the Source Control Type menu.
  5. In the Insights credential field, select the appropriate credential for use with Insights, as Red Hat Insights requires a credential for authentication.

  6. Optional: In the 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.
  7. Click Save project.

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

  1. From the navigation panel, select Automation Execution Projects.
  2. Click the project name you want to use.
  3. In the project Details tab, click Edit project.
  4. Select Remote Archive from the Source control type menu.

  5. Enter the appropriate details into the following fields:

    • Source control 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.
    • Source control credential - If authentication is required, select the appropriate source control credential.

  6. Optional: In the 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.

      Note

      Since this source control type is intended to support the concept of unchanging artifacts, it is advisable to disable Galaxy integration (for roles, at a minimum).

  7. Click Save project.

11.2. Updating projects from source control

Procedure

  1. From the navigation panel, select Automation Execution Projects.

  2. Click the sync Sync icon next to the project that you want to update.

    Note

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

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

11.3.1. Adding project permissions

Manage the permissions that users and teams have to access a project.

Procedure

  1. From the navigation panel, select Automation Execution Projects.
  2. Select the project that you want to update and click the User Access or Team Access tab.
  3. Click Add roles.
  4. Select a user or team to add and click Next.
  5. Select one or more users or teams from the list by clicking the checkbox next to the name to add them as members.
  6. Click Next.
  7. Select the roles you want the selected users or teams to have. Different resources have different options available.
  8. Click Finish 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.

11.3.2. Removing permissions from a project

Remove roles for a particular user.

Procedure

  1. From the navigation panel, select Automation Execution Projects.
  2. Select the project that you want to update and click the User Access or Team Access tab.
  3. Click the Disassociate icon next to the user role in the Roles column.
  4. Click Delete in the confirmation window to confirm the disassociation.

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

The cache directory is a subdirectory inside the global projects folder. You can copy the content 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 Job Settings screen from the navigation panel Settings Job, by switching the Enable Role Download toggle 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 Options to ensure that the upstream role is re-downloaded before each job run:

update-on-launch

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 Job Settings screen from the navigation panel Settings Job, 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']
Note

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.

Configure jobs

11.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 Job Settings screen from the navigation panel Settings Job, by switching the Enable Collection(s) Download toggle button to Off.

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

Note

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.

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

  1. Go to https://console.redhat.com/ansible/automation-hub/token.
  2. Click Load token.
  3. Click the copy Copy icon to copy the API token to the clipboard.

  4. Create a credential by choosing one of the following options:

    1. To use automation hub, create an automation hub credential by using the copied token and pointing to the URLs shown in the Server URL and SSO URL fields of the token page:

    2. 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:

      image

      You can create different repositories with different namespaces or collections in them. For each repository in automation hub you must create a different credential.

    3. 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 Create Credential:

      For UI specific instructions, see Red Hat Certified, validated, and Ansible Galaxy content in automation hub.

  5. 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 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 , 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 Developers organization 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.

  6. If automation hub has self-signed certificates, use the toggle to enable the setting Ignore Ansible Galaxy SSL Certificate Verification in Job Settings. For automation hub, which uses a signed certificate, use the toggle to disable it instead. 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. For information about the syntax to use, see Using Ansible collections in the Ansible documentation.
  8. In the Projects list view, click the sync Update icon to update this project. Automation controller fetches the Galaxy collections from the collections/requirements.yml file and reports it as changed. The collections are installed for any job template using this project.
Note

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

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.