Working with Namespaces and Collections

Creating NameSpaces

Before you can upload a collection into Private Automation Hub, you must first create a namespace for the collection. This namespace must match the namespace defined in the collection you want to upload.

Typically, the namespace for a collection represents the company or group that produced the namespace. For example, the oracle is the namespace for the Oracle Cloud Infrastructure OCI collection. The namespace plus collection format is often found in the name of the collection tar file that you download. However, the tar file naming convention does not always reflect the namespace defined in the collection. To ensure you have the correct namespace, you can download a collection, expand it, and find the MANFEST.json where the namespace is defined.

To create a namespace, do the following:

Log into Private Automation Hub.
From the Collections section, click Namespaces.

The Namespaces page appears.
Click the Create button.

The Create a new namespace form appears.
In the Name field, enter the name of the namespace for the collection you want to upload.
Click Create.
The Namepace owners tab appears for the namespace you created.
If you want to associate a group to the namespace, do the following:
1. Click Select a group.
  The Select a group page appears.
2. In the Select a group area, select a group from the list.
3. Click Next.
4. In the Select a role(s) area, select from one or more of the available roles relating to managing namespaces.
5. Click Next.
6. In the Preview area, review the permissions relating to the roles you selected, then click Add.
Click the CLI configuration tab.
A URL for the namespace you have created appears that you can use with the Private Automation Hub CLI to upload new collections to the namespace.
Click the Collections tab.
The Upload Collections button appears that you can use to upload a manually downloaded collection tar file. For more information, see Uploading Collections.

Uploading Collections

Private Automation Hub enables you to upload collections archived in tar.gzfiles.

Depending upon the olpah_require_content_approval setting of your Private Automation Hub instance, an uploaded collection might require approval before it is moved to the published content repository. The possible settings for olpah_require_content_approval are as follows:

olpah_require_content_approval = False

This is the default. No approval is required. Collections are uploaded directly to the published repository and appear under their respective Namespaces in Private Automation Hub.
olpah_require_content_approval = True

Under this setting, uploaded collections are initially uploaded to the staging repository and appear in the Approval dashboard where a user with the appropriate permissions can approve or reject them. Upon approval, collections are moved to the published repository and appear under their respective Namespaces. Conversely, rejected collections are moved to the rejected repository,

For more information on setting the value of olpah_require_content_approval, see Oracle Linux Automation Manager 2: Private Automation Hub Installation Guide.

To upload a collection, do the following:

Log into Private Automation Hub.
From the Collections section, click Namespaces.

The Namespaces page appears.
Locate the namespace whose name matches the namespace of the collection you intend to upload.

Click View Collections.

A page displaying published collections for the namespace appears.
Click Upload collection.

The New collection form appears.
Click inside the Select file box and browse to the tar.gz file with the collection you intend to upload.
Select the file and click Upload.

The My imports page appears displaying the import log so you can follow the progress of the import. The log will display the success or failure of the operation.
You can click Task Management from the main navigation menu to see the status of the tasks relating to your collection upload.

Approving Uploaded Collections

If the olpah_require_content_approval setting of your Private Automation Hub instance is set to True, you will need to review the uploaded collections listed in the Approval dashboard and decide whether to approve or reject them.

To approve an uploaded collection in the Approval dashboard, do the following:

Log into Private Automation Hub.
From the Collections section, click Approval.

The Approval dashboard page appears and displays a list of collections in a table.
Review the collections with a Needs review status in their status column.
For each collection you wish to approve, click the Approve button.

The approved collections are moved from the staging to the published repository where users can download and use them.
Verify the collections you have approved now appear in the Collections page.
You can click Task Management from the main navigation menu to see the status of the move_content operation that has moved the collection from the staging to the published repository.

Rejecting Uploaded Collections

If the olpah_require_content_approval setting of your Private Automation Hub instance is set to True, you will need to review the uploaded collections listed in the Approval dashboard and decide whether to approve or reject them.

To reject an uploaded collection in the Approval dashboard, do the following:

Log into Private Automation Hub.
From the Collections section, click Approval.

The Approval dashboard page appears and displays a list of collections in a table.
Review the collections with a Needs review status in their status column.
For each collection you wish to reject, do the following:
1. Click the Actions button at the end of the row in which the collection is listed.
  
  A menu appears.
2. Click the Reject option on the menu.
  
  The rejected collections are moved from the staging to the rejected repository.
You can click Task Management from the main navigation menu to see the status of the move_content operation that has moved the collection from the staging to the rejected repository.

Working With Repositories

This chapter describes how Private Automation Hub enables you to view and manage your local and remote collection repositories.

Viewing the Local Repositories

To view the local repositories in your system, do the following:

Log into Private Automation Hub.
From the Collections section, click Repository Management.

The Repo Management page appears. Select the Local tab if it is not already selected.

A table listing your local repositories appears.

The table listing the local repositories includes the following columns:

Repository name

The name of the repository.

For more information on the local repositories and their roles see The Purposes of the Different Local Repositories.

Collection count

The number of collections in the repository.

Last updated

The time elapsed since the repository was last updated.

Distribution URL

The URL to use when uploading and downloading collections to and from a repository from an environment from outside of the Private Automation Hub GUI.

The Distribution URL has a format similar to the following:

https://private_automation_hub/api/galaxy/content/repository_name/.

Note:

Configuring Oracle Linux Automation Manager Projects to Download Collections from a Repository Distribution URL

To configure a project in Oracle Linux Automation Manager to download a collection from a repository do the following:

Log in to Oracle Linux Automation Manager.
Create a Private Automation Hub credential.
Set the credential’s Galaxy Server URL field to the repository’s Distribution URL.
Set the credential’s API token field to the value of the API Token of your Private Automation Hub account.
Add the credential to the organization the project is associated with.

For more information see Oracle Linux Automation Manager 2: User's Guide and API token management

CLI configuration

The CLI configuration column contains a sample configuration template to help you configure an ansible.cfg file on a host from which you need to run ansible-galaxy commands against a repository.

The contents of the CLI configuration column for repository repository_name will look similar to the following:

[galaxy]
server_list = published_repo
[galaxy_server.published_repo]
url= https://private_automation_hub/api/galaxy/content/repository_name/
token=<put your token here>

The token in the preceding example refers to the API token you generate for your Private Automation Hub account, as described in API token management.

The Purposes of the Different Local Repositories

The following list describes the purposes of the different local repositories:

staging: The staging repository contains uploaded collections that are awaiting review before being approved or rejected.

Note:

If olpah_require_content_approval is set to False in your configuration, collections go straight to the published repository without any need for approval. See Uploading Collections for more information about the approval process.
published: Once a collection is approved, it is moved to the published repository and is available for download.
rejected: Collections that have been reviewed and rejected are moved to the rejected repository.
community: The local community repository contains collections downloaded from a remote repository as configured by a remote repo connection (also named community) on the remote tab of the Repo Management page. By default, the remote community repo connection directs to https://galaxy.ansible.com/api/. For more information see Remote Repository Configuration

Remote Repository Configuration

Private Automation Hub enables you to sync collections from a remote repository down to your local community repository by configuring a remote repo connection (also called community).

To Configure the remote repo connection, do the following:

Log onto Private Automation Hub.
From the Collections section, click Repository Management.

The Repo Management page appears. Select the Remote tab if it is not already selected.
A table displaying the community remote repo connection is displayed.

The table’s Last synced column tells you the last time the collection was synced, and the sync status column tells you current completion status of the most recent sync operation.
Click the Actions button at the end of the row.

A menu appears.
Click Edit on the menu.

A modal form appears.
The modal form displays a number of fields, including the ones described in the list below:
- URL:
  
  Enter the address of the remote repository you wish to download connections from. By default, the URL is https://galaxy.ansible.com/api/.
- YAML requirements:
  
  Click Browse… and upload a requirements.yml file that identifies the collections to synchronize from the remote repository. The following provides an example of what a requirements.yml file might contain:
```
collections:
  - name: amazon.aws
    source: https://galaxy.ansible.com
    version: 1.2.1
  - name: junipernetworks.junos
    source: https://galaxy.ansible.com
  - name: f5networks.f5_modules
    source: https://galaxy.ansible.com
  - name: oracle.oci
    source: https://galaxy.ansible.com
```
Username:

Enter the username, if required, to be used for authentication when syncing from the remote repository.
Password:

Enter the Password, if required, to be used for authentication when syncing from the remote repository.
Show advanced options:

Click Show advanced options if you need to configure proxy server settings or carry out any further authentication configuration for a connection to your chosen remote repository.
Click Save

Remote Repository Syncing

To sync the collections from the remote repository, as configured in your remote community repo connection, to your local community repository, do the following:

Log into Private Automation Hub.
From the Collections section, click Repository Management.

The Repo Management page appears. Select the Remote tab if it is not already selected.
A table displaying the community remote repo connection is displayed.

The table’s Last synced column tells you the last time the collection was synced, and the sync status column tells you current completion status of the most recent sync operation.
Click the Sync button.

The Sync status column will change to read Running.
The sync status changes to Completed once the operation has completed..

Note:

To monitor the progress of the sync operation, you can navigate to the Task Management page, locate the sync operation in the task list and click on the Task name: the page displayed will show progress of each step as it completes.

API token management

You can generate an API token for your Private Automation Hub account to enable you to authenticate your connection to the API from outside of the application GUI, for example in one of the following scenarios:

You might need to run command-line ansible-galaxy commands to upload and download collections to and from repositories in Private Automation Hub. In such scenarios you would typically add your API token to your ansible.cfg file.
You might need to set up an Oracle Linux Authentication Manager instance to download collections from a local repository in your Private Automation Hub. In such a scenario you would add your API token to a credential resource in Oracle Linux Authentication Manager.

Providing your user account has the necessary privileges in Private Automation Hub, your account’s API token will provide you the access needed in the preceding example scenarios.

To generate an API token for your account, do the following:

WARNING:

Loading a new token will delete your previous token, and any configurations using the previous token will therefore have to be updated with the new token value.

Log into Private Automation Hub.
From the Collections section, click API token management.

The API token management page appears.
Click Load token to generate and load a new token to be used for authenticating to Private Automation Hub.
The token is generated and displayed.
WARNING:
- Store the API token securely. It protects your content.
- The token is displayed once only. The token will never be displayed again.
Update any configurations that used your previous account's API token with the new token value.

Accessing Private Automation Hub Collections from Oracle Linux Automation Manager

You can set up Oracle Linux Automation Manager to access ansible collections from the following Private Automation Hub resources:

Custom Execution Environments

See for Creating Custom Execution Environments more information about creating custom execution environments that contain ansible collections.
Collection Repositories

See Working With Repositories for more information on working with collection repositories.

The following sections give an overview of how you set up SCM projects in Oracle Linux Automation Manager to access the resources in the preceding list.

Accessing Collections in Private Automation Hub Custom Execution Environments

To access collections in an execution environment in Private Automation Hub, you need to create a resource by the same name in Oracle Linux Automation Manager and set its properties as follows:

Name:

Choose a name for you execution environment in Oracle Linux Automation Manager, for example, My_Access_To_Private_Auto_Hub_EE.
Image:

The full container image location, including the container registry, image name, and version tag, for example:
```
https://private_automation_hub/my_custom_exe_environment:latest
```
Organization:

Select the organization whose projects need to have access to the custom execution environment referenced in the Image property.
Registry credential:

This is a Container Registry type of credential and contains the Private Automation Hub API token that has the necessary access to the custom execution environment you wish to access. This token allows the Oracle Linux Automation Manager credential to authenticate itself to Private Automation Hub.

For more information on creating execution environments and projects in Oracle Linux Automation Manager, see Oracle Linux Automation Manager 2: User's Guide

Accessing Collections Contained in Private Automation Hub Repositories

Oracle Linux Automation Manager provides the Ansible Galaxy/Automation Hub API Token credential type to set up SCM projects with access to specific repositories in Private Automation Hub. The Ansible Galaxy/Automation Hub API Token credential has the following fields to enable this access to be set up:

Galaxy Server URL:

This is the URL to the Private Automation Hub repository you wish the SCM project to access its collections from. The URL will be of the following format:
```
https://private_automation_hub/api/galaxy/content/published/
```
API Token:

This is the Private Automation Hub API token that has necessary access to the repository in question. This token allows the Oracle Linux Automation Manager credential to authenticate itself to Private Automation Hub.

You can add one or more such credentials to an organization resource in your Oracle Linux Automation Manager instance. Any projects added to an organization with such credentials will access collections from the locations that the credentials point to.

Note:

The order in which you add credentials to an organization is important:

The order in which you add the credentials to an organization determines the order in which repositories are searched when collections are to be downloaded for a project assigned to that organization.

For more information on Setting up credentials, organizations and projects, see Oracle Linux Automation Manager 2: User's Guide