Search
SupportConsoleDevelopersStart a trialContact

Chapter 2. Managing collections in automation hub

download PDF

As a content creator, you can use namespaces in automation hub to curate and manage collections. For example, you can:

  • Create teams with permissions to curate namespaces and upload collections to private automation hub
  • Add information and resources to the namespace to help end users of the collection in their automation tasks
  • Upload collections to the namespace
  • Review the namespace import logs to determine the success or failure of uploading the collection and its current approval status

For information on creating content, see the Developing automation content.

2.1. Using namespaces to manage collections in automation hub

Namespaces are unique locations in automation hub to which you can upload and publish content collections. Access to namespaces in automation hub is governed by teams with permission to manage the content and related information that appears there.

You can use namespaces in automation hub to organize collections developed within your organization for internal distribution and use.

If you are working with namespaces, you must have a team that has permissions to create, edit and upload collections to namespaces. Collections uploaded to a namespace require administrative approval before you can publish them and make them available for use.

2.1.1. Creating a new team for content curators

You can create a new team in Ansible Automation Platform designed to support content curation in your organization. This team can contribute internally-developed collections for publication in private automation hub.

To help content developers create a namespace and upload their internally developed collections to private automation hub, you must first create and edit a team and assign the required permissions.

Prerequisites

  • You have administrative permissions in Ansible Automation Platform and can create teams.

Procedure

  1. Log in to your Ansible Automation Platform.
  2. From the navigation panel, select Access Management Teams and click Create team.
  3. Enter Content Engineering as a Name for the team.
  4. Select an Organization for the team.
  5. Click Create team. You have created the new team and the team Details page opens.
  6. Select the Roles tab and then select the Automation Content tab.
  7. Click Add roles.
  8. Select Namespace from the Resource type list and click Next.
  9. Select the namespaces that will receive the new roles and click Next.
  10. Select the roles to apply to the selected namespaces and click Next.
  11. Review your selections and click Finish.

  12. Click Close to complete the process.

    The new team is created with the permissions that you assigned. You can then add users to the team.

  13. Click the Users tab on the Teams page.
  14. Click Add users.
  15. Select users and click Add users.

For further instructions on managing access with teams, see Teams in the Access management and authentication guide.

2.1.2. Creating a namespace

You can create a namespace to organize collections that your content developers upload to automation hub. When creating a namespace, you can assign a team in automation hub as owners of that namespace.

Prerequisites

  • You have Add Namespaces and Upload to Namespaces permissions.

Procedure

  1. Log in to your Ansible Automation Platform.
  2. From the navigation panel, select Automation Content Namespaces.
  3. Click Create namespace and enter a Name for your namespace.
  4. Optional: enter a description, company, logo URL, resources, or useful links in the appropriate fields.
  5. Click Create namespace.
  6. Select the Team Access tab and click Add roles to assign roles to your namespace.
  7. Select the team to which you want to grant a role, then click Next.
  8. Select the roles you want to apply to the selected team, and then click Next.
  9. Review your selections and click Finish.
  10. Click Close to complete the process.

Your content developers can now upload collections to your new namespace and allow users in teams assigned as owners to upload collections.

2.1.3. Adding additional information and resources to a namespace

You can add information and provide resources for your users to accompany collections included in the namespace. For example, you can add a logo and a description, and link users to your GitHub repository, issue tracker, or other online assets. You can also enter markdown text in the Resources field to include more information. This is helpful to users who use your collection in their automation tasks.

Prerequisites

  • You have Change Namespaces permissions.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation Content Namespaces.
  3. Select the namespace you want to edit.
  4. Click the Edit namespace.
  5. Enter the relevant information in the fields.
  6. Optional: enter markdown information in the Resources field.
  7. Click Save namespace.

Your content developers can now upload collections to your new namespace, or allow users in teams assigned as owners to upload collections.

When you create a namespace, teams with permissions to upload to it can start adding their collections for approval. Collections in the namespace appear in the Published repository after approval.

2.1.4. Uploading collections to your namespaces

You can upload internally developed collections in tar.gz file format to your private automation hub namespace for review and approval by an automation hub administrator. When approved, the collection moves to the Published content repository where automation hub users can view and download it.

Note

Format your collection file name as follows: <my_namespace-my_collection-1.0.0.tar.gz>

Prerequisites

  • You have a namespace to which you can upload the collection.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation Content Namespaces and select a namespace.
  3. Select the Collections tab.
  4. Click Upload collection.
  5. Click Browse next to the Collection file field.
  6. Select the collection to upload.

  7. Select one of the following options:

    • Staging repos
    • Repositories without pipeline
  8. Click Upload collection.

Verification

To verify whether the collection uploaded successfully or if it failed, navigate to Automation Content Namespaces and click the More Actions icon ⋮, then select Imports. There you will find a summary of tests indicating whether the import was successful.

2.1.5. Reviewing your namespace import logs

You can review the status of collections uploaded to your namespaces to evaluate success or failure of the process.

Imported collections information includes:

Status
completed or failed
Approval status
waiting for approval or approved
Version
the version of the uploaded collection
Import log
activities executed during the collection import

Prerequisites

  • You have access to a namespace to which you can upload collections.

Procedure

  1. Log in to your Ansible Automation Platform.
  2. From the navigation panel, select Automation Content Namespaces.
  3. Select a namespace.
  4. Click the More Actions icon ⋮ and select Imports.
  5. Use the search field or locate an imported collection from the list.
  6. Click the imported collection.
  7. Review collection import details to determine the status of the collection in your namespace.

2.1.6. Deleting a namespace

You can delete unwanted namespaces to manage storage on your automation hub server. You must first ensure that the namespace you want to delete does not contain a collection with dependencies.

Prerequisites

  • The namespace you are deleting does not have a collection with dependencies.
  • You have Delete namespace permissions.

Procedure

  1. Log in to your Ansible Automation Platform.
  2. From the navigation panel, select Automation Content Namespaces.
  3. Click the namespace to be deleted.

  4. Click the More Actions icon ⋮, then click Delete namespace.

    Note

    If the Delete namespace button is disabled, the namespace contains a collection with dependencies. Review the collections in this namespace, and delete any dependencies.

The namespace that you deleted, as well as its associated collections, is now deleted and removed from the namespace list view.

2.2. Managing the publication process of internal collections in Automation Hub

Use automation hub to manage and publish content collections developed within your organization. You can upload and group collections in namespaces. They need administrative approval to appear in the Published content repository. After you publish a collection, your users can access and download it for use.

You can also reject submitted collections that do not meet organizational certification criteria.

2.2.1. About Approval

You can manage uploaded collections in automation hub by using the Collection Approvals feature located in the navigation panel.

Approval Dashboard
By default, the Approval dashboard lists all collections with Needs Review status. You can check these for inclusion in your Published repository.
Viewing collection details
You can view more information about the collection by clicking the Version number.
Filtering collections
Filter collections by Namespace, Collection, or Repository to locate content and update its status.

2.2.2. Approving collections for internal publication

You can approve collections uploaded to individual namespaces for internal publication and use. All collections awaiting review are located in Automation Content Collection Approvals.

Prerequisites

  • You have Modify Ansible repo content permissions.

Procedure

  1. From the navigation panel, select Automation Content Collection Approvals.

    Collections requiring approval have the status Needs review.

  2. Find the collection you want to review in the list. You can also filter collections by Namespace, Repository, and Status using the search bar.
  3. Click the thumbs up icon to approve and sign the collection. Confirm your choice in the modal that appears.

Approved collections are moved to the Published repository where users can view and download them for use.

2.2.3. Rejecting collections uploaded for review

You can reject collections uploaded to individual namespaces. All collections awaiting review are located in Automation Content Collection Approvals.

Collections requiring approval have the status Needs review.

Prerequisites

  • You have Modify Ansible repo content permissions.

Procedure

  1. From the navigation panel, select Automation Content Collection Approvals.
  2. Find the collection you want to review in the list. You can also filter collections by Namespace, Repository, and Status using the search bar.
  3. Click the thumbs down icon to reject the collection. Confirm your choice in the modal that appears.

Collections you decline for publication are moved to the Rejected repository.

2.3. Repository management with automation hub

As a platform administrator, you can create, edit, delete, and move automation content collections between repositories.

2.3.1. Types of repositories in automation hub

In automation hub you can publish collections to two types of repositories, depending on whether you want your collection to be verified:

Staging repositories
Any user with permission to upload to a namespace can publish collections into these repositories. Collections in these repositories are not available in the search page. Instead, they are displayed on the approval dashboard for an administrator to verify. Staging repositories are marked with the pipeline=staging label.
Custom repositories
Any user with write permissions on the repository can publish collections to these repositories. Custom repositories can be public where all users can see them, or private where only users with view permissions can see them. These repositories are not displayed on the approval dashboard. If the repository owner enables search, the collection can appear in search results.

By default, automation hub includes one staging repository that is automatically used when a repository is not specified for uploading collections. Users can create new staging repositories during repository creation.

2.3.2. Approval pipeline for custom repositories in automation hub

In automation hub you can approve collections into any repository marked with the pipeline=approved label. By default, automation hub includes one repository for approved content, but you have the option to add more from the repository creation screen. You cannot directly publish into a repository marked with the pipeline=approved label. A collection must first go through a staging repository and be approved before being published into a 'pipleline=approved' repository.

Auto approval
When auto approve is enabled, any collection you upload to a staging repository is automatically promoted to all of the repositories marked as pipeline=approved.
Approval required

When auto approve is disabled, the administrator can view the approval dashboard and see collections that have been uploaded into any of the staging repositories. Sorting by Approved displays a list of approved repositories. From this list, the administrator can select one or more repositories to which the content should be promoted.

If only one approved repository exists, the collection is automatically promoted into it and the administrator is not prompted to select a repository.

Rejection
Rejected collections are automatically placed into the rejected repository, which is pre-installed.

2.3.3. Role based access control to restrict access to custom repositories

Use Role Based Access Control (RBAC) to restrict user access to custom repositories by defining access permissions based on user roles. By default, users can view all public repositories in their automation hub, but they cannot modify a repository unless their role allows them access to do so. The same logic applies to other operations on the repository. For example, you can remove a user’s ability to download content from a custom repository by changing their role permissions. See Access management and authentication for information about managing user access to automation hub.

2.3.4. Creating a custom repository in automation hub

When you use Red Hat Ansible Automation Platform to create a repository, you can configure the repository to be private or hide it from search results.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation Content Repositories.
  3. Click Create repository.
  4. Enter a Name for your repository.
  5. In the Description field, describe the purpose of the repository.

  6. To retain previous versions of your repository each time you make a change, enter a figure in the field labeled Retained number of versions. The number of retained versions can range anywhere between 0 and unlimited. To save all versions, leave this set to null.

    Note

    If you have a problem with a change to your custom repository, you can revert to a different repository version that you have retained.

  7. In the Pipeline field, select a pipeline for the repository. This option defines who can publish a collection into the repository.

    Staging
    Anyone is allowed to publish automation content into the repository.
    Approved
    Collections added to this repository are required to go through the approval process by way of the staging repository. When auto approve is enabled, any collection uploaded to a staging repository is automatically promoted to all of the approved repositories.
    None
    Any user with permissions on the repository can publish to the repository directly, and the repository is not part of the approval pipeline.
  8. Optional: To hide the repository from search results, select Hide from search.
  9. Optional: To make the repository private, select Make private. This hides the repository from anyone who does not have permissions to view the repository.
  10. To sync the content from a remote repository into this repository, in the Remote field select the remote that contains the collections you want included in your custom repository. For more information, see Repository sync.
  11. Click Create repository.

Next steps

  • After the repository is created, the details page is displayed.

    From here, you can provide access to your repository, review or add collections, and work with the saved versions of your custom repository.

2.3.5. Providing access to a custom automation hub repository

By default, private repositories and the automation content collections are hidden from all users in the system. Public repositories can be viewed by all users, but cannot be modified. Use this procedure to provide access to your custom repository.

Procedure

  1. Log in to private automation hub.
  2. From the navigation panel, select Automation Content Repositories.
  3. Click into your repository in the list and select the Team Access tab.
  4. Click Add roles.
  5. Select the team to which you want to grant a role, then click Next.
  6. Select the roles you want to apply to the selected team, and then click Next.
  7. Review your selections and click Finish.
  8. Click Close to complete the process.

See Access management and authentication for more information about implementing user access.

2.3.6. Adding collections to an automation hub repository

After you create your repository, you can begin adding automation content collections to it.

Procedure

  1. From the navigation panel, select Automation Content Repositories.
  2. Click into your repository in the list.
  3. Select the Collection versions tab.
  4. Click Add Collections and select the collections that you want to add to your repository.
  5. Click Select.

2.3.7. Revert to a different automation hub repository version

When automation content collections are added or removed from a repository, a new version is created. If a change to your repository causes a problem, you can revert to a previous version. Reverting is a safe operation and does not delete collections from the system, but rather, changes the content associated with the repository. The number of versions saved is defined in the Retained number of versions setting when a repository is created.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation Content Repositories.
  3. Click into your repository in the list and then select the Versions tab.
  4. Locate the version you want to revert to and click the More Actions icon ⋮, and select Revert to this version.
  5. Check the box confirming your selection, and then click Revert to repository version.

2.3.8. Managing remote configurations in automation hub

You can set up remote configurations to any server that is running automation hub. Remote configurations allow you to sync content to your custom repositories from an external collection source.

2.3.8.1. Creating a remote configuration in automation hub

You can use Red Hat Ansible Automation Platform to create a remote configuration to an external collection source. Then, you can sync the content from those collections to your custom repositories.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation Content Remotes.
  3. Click Create Remote.
  4. Enter a Name for the remote configuration.

  5. Enter the URL for the remote server, including the path for the specific repository.

    Note

    To find the remote server URL and repository path, navigate to Automation Content Repositories, select the More Actions icon ⋮, and select Copy CLI configuration.

  6. Configure the credentials to the remote server by entering a Token or Username and Password required to access the external collection.

    Note

    To generate a token from the navigation panel, select Automation Content API token, click Load token and copy the token that is loaded.

  7. To access collections from console.redhat.com, enter the SSO URL to sign in to the identity provider (IdP).

  8. Select or create a Requirements file to identify the collections and version ranges to synchronize with your custom repository. For example, to download only the kubernetes and AWS collection versions 5.0.0 or later the requirements file would look like this: 

    Collections:
 	  - name: community.kubernetes
	  - name: community.aws
 		version:”>=5.0.0”
    Note

    All collection dependencies are downloaded during the Sync process.

  9. Optional: To configure your remote further, use the options available under Show advanced options:

    1. If there is a corporate proxy in place for your organization, enter a Proxy URL, Proxy Username and Proxy Password.
    2. Enable or disable transport layer security using the TLS validation checkbox.
    3. If digital certificates are required for authentication, enter a Client key and Client certificate.
    4. If you are using a self-signed SSL certificate for your server, enter the PEM encoded client certificate used for authentication in the CA certificate field.
    5. To accelerate the speed at which collections in this remote can be downloaded, specify the number of collections that can be downloaded in tandem in the Download concurrency field.

    6. To limit the number of queries per second on this remote, specify a Rate Limit.

      Note

      Some servers can have a specific rate limit set, and if exceeded, synchronization fails.

2.3.8.2. Providing access to a remote configuration

After you create a remote configuration, you must provide access to it before anyone can use it.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation Content Remotes.
  3. Click into your repository in the list, and then select the Team Access tab.
  4. Click Add roles.
  5. Select the team to which you want to grant a role, then click Next.
  6. Select the roles you want to apply to the selected team, and then click Next.
  7. Review your selections and click Finish.
  8. Click Close to complete the process.

2.3.9. Synchronizing repositories in automation hub

You can distribute relevant automation content collections to your users by synchronizing repositories from one automation hub to another. To ensure you have the latest collection updates, synchronize your custom repository with the remote regularly.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation Content Repositories.

  3. Locate your repository in the list and click More Actions icon ⋮, then select Sync repository.

    All collections in the configured remote are downloaded to your custom repository. To check the status of the collection sync, select Automation Content Task Management from the navigation panel.

    Note

    To limit repository synchronization to specific collections within a remote, you can identify specific collections to be pulled by using a requirements.yml file. See Create a remote for more information.

Additional resources

For more information about using requirements files, see Creating a requirements file.

2.3.10. Exporting and importing collections in automation hub

Ansible automation hub stores automation content collections within repositories. These collections are versioned by the automation content creator. Many versions of the same collection can exist in the same or different repositories at the same time.

Collections are stored as .tar files that can be imported and exported. This storage format ensures that the collection you are importing to a new repository is the same one that was originally created and exported.

2.3.10.1. Exporting an automation content collection in automation hub

After collections are finalized, you can import them to a location where they can be distributed to others across your organization.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation Content Collections. The Collections page displays all collections across all repositories. You can search for a specific collection.
  3. Click into the collection that you want to export. The collection details page opens.
  4. From the Install tab, select Download tarball. The .tar file is downloaded to your default browser downloads folder. You can now import it to the location of your choosing.

2.3.10.2. Importing an automation content collection in automation hub

As an automation content creator, you can import a collection to use in a custom repository. To use a collection in your custom repository, you must first import the collection into your namespace so the automation hub administrator can approve it.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation Content Namespaces. The Namespaces page displays all of the namespaces available.
  3. Select the namespace to which you want to add your collection.
  4. Select the Collections tab.
  5. Click Upload Collection.
  6. Enter or browse to select a collection file.
  7. Select the repository pipeline to add the collection. The choices are Staging repos and Repositories without pipeline.

  8. Click Upload collection.

    The Imports screen displays a summary of tests and notifies you if the collection upload is successful or has failed. To find your imports, on your namespace click the More Actions icon ⋮ and select Imports.

    Note

    If the collection is not approved, it is not displayed in the published repository.

Additional resources

  • See Approval pipeline for more information about collection and repository approvals.
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.