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 newly create namespace is displayed in the Collections tab.
If you want to associate a group to the namespace, do the following:
1. Click the Access tab.
2. Click Select a group.
  The Select a group dialog appears.
3. In the Select a group area, select a group.
4. Click Next.
5. In the Select role(s) area, select from one or more of the available roles relating to managing namespaces.
6. Click Next.
7. 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. By default it has the following format:
```
https://<PAH_Host>/api/galaxy/
```
In the previous example, <PAH_Host> is the host name or IP address of the Private Automation Hub server.
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.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 page appears.
Click inside the Select file box and browse to the tar.gz file with the collection you intend to upload.
Select one of the following:
- Staging Repos: Select this to upload the version of the collection to a staging repository.
- All Repos: Select this to upload a version to another repository.
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 displays 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.
Do one of the following:
- If you have selected the Staging Repos option, and you have enabled approvals, perform the steps described in Approving Uploaded Collections.
- If you have selected the All Repos option, see Viewing and Syncing Local Repositories to find the repository where the collection is now located.

Approving Uploaded Collections

If the olpah_require_content_approval setting of the Private Automation Hub instance is set to True, 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. All collections requiring approval are in the Staging repository or in a repository with the staging pipeline enabled.
For each collection 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.

Note:
If you have more than one repository with the Approved pipeline enabled, a screen appears enabling you to choose which repository to send the approved collection to. For more information about piplines, see Creating a Local Repository.
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 and Syncing Local Repositories

To view and sync local repositories, do the following:

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

The Repositories page 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.

Labels
Any labels applied to the repository appear in this column. Repository labels can change the context in which a repository is seen. Available options are:
- Hide from searchhide_from_search This label prevents collections in this repository from appearing on the home page.
- Pipeline Valid pipelines options include:
  
  None Users require permissions to change or upload content to the repository.
  
  Approved Users can only publish to this repository if the content is approved by an authorized user.
  
  Staging Any user with upload permissions for a namespace can upload collections to this repository. Users can't view the collection in the search page unless the collection is approved for viewing.
  
  Rejected These are repositories that aren't approved.
Private

Whether the repository is private or public.

Sync status
The synchronization date shows when the repository was last syncrhonized with a remote repository, if a remote repository is configured. Possible options are:
- The date when the repository was last synchronized.
- no remote: This indicates that no remote repository is configured for the repository.
- never synced: This indicates the the repository was never synchronized with its remote repository.
Created Date

The date when the repository was created.
Select a repository to view.
Review the respository information.

The Distribution URL . It shows 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:
In Oracle Linux Automation Manager, you can configure projects to download collections from this repository distribution URL. For more information see Oracle Linux Automation Manager 2.2: User's Guide and API token management.
Click the Copy CLI Configuration button to copy the CLI configuration.

The Successfully copied to clipboard dialog appears containing 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 is 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 the Private Automation Hub account, as described in API token management.
To sync a repository with a remote repository, do the following:
1. Click Sync.
  
  The Sync repository dialog appears.
2. Enable Mirror if you want content not present in the remote repository to be removed from the local repository in addition to adding any new content.
3. Disable Mirror if you want the sync to only add new content.
4. Enable Optimize to perform the sync only if changes are detected on the remote repository.
5. Disable Optimize to force a sync regardless of whether changes exist on the remote repository.
6. Click Sync.
Note:
To monitor the progress of the sync operation, you can navigate to the Task Management page, find the sync operation in the task list and click the Task name. The the page shows the progress of each step as it completes. This can take some time depending on the size and version of collections added to the requirements.yml file configured in the Creating a Remote Repository procedure.

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 Creating a Remote Repository

Creating a Remote Repository

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 add a remote repo connection, do the following:

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

The Remotes page appears. A table displaying the community remote repo connection is displayed.
Click Add Remote.
The Add new remote page appears.
In the Name field, enter a name.
In the URL field, enter the address of the remote repository you want to download connections from. For example, the default remote community repository points to https://galaxy.ansible.com/api/.
(Optional) Enable Include all dependencies when syncing a collection, to include all dependencies when syncing a collection.
(Optional) In the Token field, enter a token for authenticating to the server URL.
(Optional) In the SSO URL field, enter an SSO URL.
(Optional) In the YAML requirements field, Click Upload and select 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
```
Note:
In the previous example, the version field indicates which version of the collection that Private Automation Hub pulls. When no version field is specified, Private Automation Hub pulls all versions of the collection.

You can also use the YAML editor to directly copy and paste in the contents of the requirements.yml file.
(Optional) In the Username field, enter a username for connecting to the remote repository.
(Optional) In the Password field, enter a password for connecting to the remote repository.
(Optional) Click Show advanced options: if you need to configure proxy server settings or perform any further authentication configuration for a connection to a chosen remote repository.
Click Save

Creating a Local Repository

To create a local repositories on the system, do the following:

Sign in Private Automation Hub.
From the Collections section, click Repositories.

The Repositories page appears.
Click Add repository.
The Add new repository page appears.
In the Name field, enter a name for the repository.
In the Description field, enter a description for the repository.
In the Retained number of versions field, enter the maximum number of versions to retain. Leaving this field blank causes all versions to be retained.
To make the repository available to users for sync, download, or search operations, enable Create a "repository_name" distribution where repository_name is the name of the repository you're creating.
From the Pipeline dropdown list, select one of the following:
- None Users require permissions to change or upload content to the repository.
- Approved Users can only publish to this repository if the content is approved by an authorized user.
- Staging Any user with upload permissions for a namespace can upload collections to this repository. Users can't view the collection in the search page unless the collection is approved for viewing.
To prevent collections in this repository from appearing on the home page, enable Hide from search. This is automatically disabled if you selected the Staging pipeline.
To make the repository private, enable Make Private.
To associate the repository with a remote repository, select a remote repository from the Remote drop down list. For more information about adding a remote repository, see Creating a Remote Repository.
Click Save.

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.

The API token 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.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.2: User's Guide