Este conteúdo não está disponível no idioma selecionado.
Chapter 1. Red Hat Certified, validated, and Ansible Galaxy content in automation hub
Ansible Certified Content Collections are included in your subscription to Red Hat Ansible Automation Platform. Using Ansible automation hub, you can access and curate a unique set of collections from all forms of Ansible content.
Red Hat Ansible content contains two types of content:
- Ansible Certified Content Collections
- Ansible validated content collections
You can use both Ansible Certified Content Collections or Ansible validated content collections to build your automation library. For more information on the differences between Ansible Certified Content Collections and Ansible validated content collections, see the Knowledgebase article Ansible Certified Content Collections and Ansible validated content, or Ansible validated content in this guide.
You can update these collections manually by downloading their packages.
You can use Ansible automation hub to distribute the relevant Red Hat Ansible Certified Content Collections to your users by creating a requirements file.
Before you can use a requirements file to install content, you must:
1.1. Configuring Ansible automation hub remote repositories to synchronize content Copiar o linkLink copiado para a área de transferência!
Use remote configurations to configure your private automation hub to synchronize with Ansible Certified Content Collections hosted on console.redhat.com
or with your collections in Ansible Galaxy.
Each remote configuration located in
What’s the difference between Ansible Galaxy and Ansible automation hub?
Collections published to Ansible Galaxy are the latest content published by the Ansible community and have no joint support claims associated with them. Ansible Galaxy is the recommended frontend directory for the Ansible community to access content.
Collections published to Ansible automation hub are targeted to joint customers of Red Hat and selected partners. Customers need an Ansible subscription to access and download collections on Ansible automation hub. A certified collection means that Red Hat and partners have a strategic relationship in place and are ready to support joint customers, and that the collections may have had additional testing and validation done against them.
How do I request a namespace on Ansible Galaxy?
To request a namespace through an Ansible Galaxy GitHub issue, follow these steps:
- Send an email to ansiblepartners@redhat.com
- Include the GitHub username used to sign up on Ansible Galaxy.
You must have logged in at least once for the system to validate.
After users are added as administrators of the namespace, you can use the self-serve process to add more administrators.
Are there any restrictions for Ansible Galaxy namespace naming?
Collection namespaces must follow Python module name convention. This means collections should have short, all lowercase names. You can use underscores in the collection name if it improves readability.
1.1.1. Token management in automation hub Copiar o linkLink copiado para a área de transferência!
Before you can interact with automation hub by uploading or downloading collections, you must create an API token. The automation hub API token authenticates your ansible-galaxy
client to the Red Hat automation hub server.
Automation hub does not support basic authentication or authenticating through service accounts. You must authenticate using token management.
Your method for creating the API token differs according to the type of automation hub that you are using:
- Automation hub uses offline token management. See Creating the offline token in automation hub.
- Private automation hub uses API token management. See Creating the API token in private automation hub.
- If you are using Keycloak to authenticate your private automation hub, follow the procedure for Creating the offline token in automation hub.
1.1.2. Creating the offline token in automation hub Copiar o linkLink copiado para a área de transferência!
In automation hub, you can create an offline token using Token management. The offline token is a secret token used to protect your content, so be sure to store it in a secure location.
Procedure
- Navigate to Ansible Automation Platform on the Red Hat Hybrid Cloud Console.
-
From the navigation panel, select
. - Under Offline token, click .
- Click the icon to copy the offline token.
- Paste the API token into a file and store in a secure location.
Additional resources
Your offline token expires after 30 days of inactivity. For more on obtaining a new offline token, see Keeping your offline token active.
Next step
The offline token is now available for configuring automation hub as your default collections server or for uploading collections by using the ansible-galaxy
command line tool.
1.1.3. Creating the API token in private automation hub Copiar o linkLink copiado para a área de transferência!
In private automation hub, you can create an API token using API token management. The API token is a secret token used to protect your content, so be sure to store it in a secure location.
The API token does not expire.
Prerequisites
- Valid subscription credentials for Red Hat Ansible Automation Platform.
Procedure
- Log in to your private automation hub.
-
From the navigation panel, select
. - Click .
- To copy the API token, click the icon.
- Paste the API token into a file and store in a secure location.
Next step
The API token is now available for configuring automation hub as your default collections server or uploading collections using the ansible-galaxy
command line tool.
1.1.4. Keeping your offline token active Copiar o linkLink copiado para a área de transferência!
Offline tokens expire after 30 days of inactivity. You can keep your offline token from expiring by periodically refreshing your offline token.
Keeping an online token active is useful when an application performs an action on behalf of the user; for example, this allows the application to perform a routine data backup when the user is offline.
If your offline token expires, you must obtain a new one.
Procedure
Run the following command to prevent your token from expiring:
curl https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token -d grant_type=refresh_token -d client_id="cloud-services" -d refresh_token="{{ user_token }}" --fail --silent --show-error --output /dev/null
curl https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token -d grant_type=refresh_token -d client_id="cloud-services" -d refresh_token="{{ user_token }}" --fail --silent --show-error --output /dev/null
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.1.5. Configuring the rh-certified remote repository to sync Ansible Certified Content Collections Copiar o linkLink copiado para a área de transferência!
You can edit the rh-certified remote repository to synchronize collections from automation hub hosted on console.redhat.com to your private automation hub. By default, your private automation hub rh-certified
repository includes the URL for the entire group of Ansible Certified Content Collections.
To use only those collections specified by your organization, a private automation hub administrator can upload manually-created requirements files from the rh-certified
remote.
If you have collections A
, B
, and C
in your requirements file, and a new collection X
is added to console.redhat.com that you want to use, you must add X
to your requirements file for private automation hub to synchronize it.
Prerequisites
- You have valid Modify Ansible repo content permissions. For more information on permissions, see Access management and authentication.
- You have retrieved the Sync URL and API Token from the automation hub hosted service on console.redhat.com.
- You have configured access to port 443. This is required for synchronizing certified collections. For more information, see the automation hub table in the Network ports and protocols chapter of Planning your installation.
Procedure
- Log in to your Ansible Automation Platform.
-
From the navigation panel, select
. - In the rh-certified remote repository, click .
- In the URL field, paste the Sync URL.
- In the Token field, paste the token you acquired from console.redhat.com.
- Click .
Result
You can now synchronize collections from console.redhat.com to your private automation hub.
Next steps
See Synchronizing Ansible content collections in automation hub for syncing steps.
1.1.6. Configuring the community remote repository to sync Ansible Galaxy collections Copiar o linkLink copiado para a área de transferência!
You can edit the community remote repository to synchronize chosen collections from Ansible Galaxy to your private automation hub. By default, your private automation hub community repository directs to galaxy.ansible.com/api/
.
Prerequisites
- You have Modify Ansible repo content permissions. For more information on permissions, see Access management and authentication.
You have a
requirements.yml
file that identifies those collections to synchronize from Ansible Galaxy as in the following example:Requirements.yml example
collections: # Install a collection from Ansible Galaxy. - name: community.aws version: 5.2.0 source: https://galaxy.ansible.com
collections: # Install a collection from Ansible Galaxy. - name: community.aws version: 5.2.0 source: https://galaxy.ansible.com
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Procedure
- Log in to Ansible Automation Platform.
-
From the navigation panel, select
. - In the Details tab in the Community remote, click .
-
In the YAML requirements field, paste the contents of your
requirements.yml
file. - Click .
Result
You can now synchronize collections identified in your requirements.yml
file from Ansible Galaxy to your private automation hub.
Next steps
See Synchronizing Ansible content collections in automation hub for syncing steps.
1.1.7. Configuring proxy settings Copiar o linkLink copiado para a área de transferência!
If your private automation hub is behind a network proxy, you can configure proxy settings on the remote to sync content located outside of your local network.
Prerequisites
- You have valid Modify Ansible repo content permissions. For more information on permissions, see Access management and authentication
- You have a proxy URL and credentials from your local network administrator.
Procedure
- Log in to Ansible Automation Platform.
-
From the navigation panel, select
. - In either the rh-certified or Community remote, click the icon ⋮ and select Edit remote.
- Expand the Show advanced options drop-down menu.
- Enter your proxy URL, proxy username, and proxy password in the appropriate fields.
- Click .
1.1.8. Creating a requirements file Copiar o linkLink copiado para a área de transferência!
Use a requirements file to add collections to your automation hub. Requirements files are in YAML format and list the collections that you want to install in your automation hub.
A standard requirements.yml
file contains the following parameters:
-
name
: the name of the collection formatted as<namespace>.<collection_name>
-
version
: the collection version number
Procedure
Create your requirements file.
In YAML format, collection information in your requirements file should look like this:
collections: name: namespace.collection_name version: 1.0.0
collections: name: namespace.collection_name version: 1.0.0
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Be sure to specify the collection version number, otherwise you will sync all collection versions. Syncing all versions can require more space than expected.
Next step
To sync the collections in your requirements file, follow the steps in Syncing Ansible content collections.
1.2. Synchronizing Ansible Content Collections in automation hub Copiar o linkLink copiado para a área de transferência!
To synchronize content, create and upload a requirements file to the appropriate remote. Remotes are configurations that enable you to synchronize content to your custom repositories from an external collection source.
1.2.1. Syncing Ansible content collections Copiar o linkLink copiado para a área de transferência!
You can sync certified and validated collections in Ansible automation hub on console.redhat.com.
When syncing content, keep in mind that automation hub does not check other repositories for dependencies. To avoid an error, turn off dependency downloading by editing your remote settings. See Creating a remote configuration in automation hub for more information.
Prerequisites
- You have a valid Ansible Automation Platform subscription.
- You have organization administrator permissions for console.redhat.com.
- You have created a requirements file.
The following domain names are part of either the firewall or the proxy’s allowlist. They are required for successful connection and download of collections from automation hub or Galaxy server:
-
galaxy.ansible.com
-
cloud.redhat.com
-
console.redhat.com
-
sso.redhat.com
-
Ansible automation hub resources are stored in Amazon Simple Storage. The following domain names must be in the allow list:
-
automation-hub-prd.s3.us-east-2.amazonaws.com
-
ansible-galaxy.s3.amazonaws.com
-
- SSL inspection is disabled either when using self signed certificates or for the Red Hat domains.
Before you begin your content sync, consult the Knowledgebase article Resource requirements for syncing automation content to ensure that you have the resources to sync the collections you need.
Procedure
-
From the navigation panel, select
. -
Find the remote you want to sync from and click the pencil icon
to edit.
- Find the field labeled Requirements file. There, you can either paste the contents of your requirements file, or upload the file from your hard drive by selecting the upload button.
- Click .
-
To begin synchronization, from the navigation panel select
. -
In the row containing the repository you want to sync, click the ⋮ icon and select the
Sync repository icon to initiate the remote repository synchronization to your private automation hub.
On the modal that appears, you can toggle the following options:
- Mirror: Select if you want your repository content to mirror the remote repository’s content.
- Optimize: Select if you want to sync only when no changes are reported by the remote server.
- Click to complete the sync.
Verification
The Sync status column updates to notify you whether the synchronization is successful.
-
Navigate to
to confirm that your collections content has synchronized successfully.
1.3. Collections and content signing in private automation hub Copiar o linkLink copiado para a área de transferência!
As an automation administrator for your organization, you can configure private automation hub for signing and publishing Ansible content collections from different groups within your organization.
For additional security, automation creators can configure Ansible-Galaxy CLI to verify these collections to ensure that they have not been changed after they were uploaded to automation hub.
1.3.1. Configuring content signing on private automation hub Copiar o linkLink copiado para a área de transferência!
To successfully sign and publish Ansible Certified Content Collections, you must configure private automation hub for signing.
Prerequisites
- Your GnuPG key pairs have been securely set up and managed by your organization.
- Your public-private key pair has proper access for configuring content signing on private automation hub.
Procedure
Create a signing script that accepts only a filename.
NoteThis script acts as the signing service and must generate an ascii-armored detached
gpg
signature for that file using the key specified through thePULP_SIGNING_KEY_FINGERPRINT
environment variable.The script prints out a JSON structure with the following format.
{"file": "filename", "signature": "filename.asc"}
{"file": "filename", "signature": "filename.asc"}
Copy to Clipboard Copied! Toggle word wrap Toggle overflow All the file names are relative paths inside the current working directory. The file name must remain the same for the detached signature.
Example:
The following script produces signatures for content:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow After you deploy a private automation hub with signing enabled to your Ansible Automation Platform cluster, new UI additions are displayed in collections.
Review the Ansible Automation Platform installer inventory file for options that begin with
automationhub_*
.Copy to Clipboard Copied! Toggle word wrap Toggle overflow The two new keys (automationhub_auto_sign_collections and automationhub_require_content_approval) indicate that the collections must be signed and approved after they are uploaded to private automation hub.
1.3.2. Using content signing services in private automation hub Copiar o linkLink copiado para a área de transferência!
After you have configured content signing on your private automation hub, you can manually sign a new collection or replace an existing signature with a new one. When users download a specific collection, this signature indicates that the collection is for them and has not been modified after certification.
You can use content signing on private automation hub in the following scenarios:
- Your system does not have automatic signing configured and you must use a manual signing process to sign collections.
- The current signatures on the automatically configured collections are corrupted and need new signatures.
- You need additional signatures for previously signed content.
- You want to rotate signatures on your collections.
Procedure
- Log in to Ansible Automation Platform.
-
From the navigation panel, select
. The Approval dashboard opens and displays a list of collections. - Click the thumbs up icon next to the collection you want to approve. On the modal that appears, check the box confirming that you want to approve the collection, and click .
Verification
-
Navigate to
to verify that the collections you signed and approved are displayed.
1.3.3. Downloading signature public keys Copiar o linkLink copiado para a área de transferência!
After you sign and approve collections, download the signature public keys from the Ansible Automation Platform UI. You must download the public key before you add it to the local system keyring.
Procedure
- Log in to Ansible Automation Platform.
From the navigation panel, select
. The Signature Keys dashboard displays a list of multiple keys: collections and container images. -
To verify collections, download the key prefixed with
collections-
. -
To verify container images, download the key prefixed with
container-
.
-
To verify collections, download the key prefixed with
Choose one of the following methods to download your public key:
- Click the icon to download the public key.
- Click the next to the public key you want to copy.
Verification
Use the public key that you copied to verify the content collection that you are installing.
1.3.4. Configuring Ansible-Galaxy CLI to verify collections Copiar o linkLink copiado para a área de transferência!
You can configure Ansible-Galaxy CLI to verify collections. This ensures that downloaded collections are approved by your organization and have not been changed after they were uploaded to automation hub.
If a collection has been signed by automation hub, the server provides ASCII armored, GPG-detached signatures to verify the authenticity of MANIFEST.json
before using it to verify the collection’s contents. You must opt into signature verification by configuring a keyring for ansible-galaxy
or providing the path with the --keyring
option.
Prerequisites
- Signed collections are available in automation hub to verify signature.
- Certified collections can be signed by approved roles within your organization.
- Public key for verification has been added to the local system keyring.
Procedure
To import a public key into a non-default keyring for use with
ansible-galaxy
, run the following command.gpg --import --no-default-keyring --keyring ~/.ansible/pubring.kbx my-public-key.asc
gpg --import --no-default-keyring --keyring ~/.ansible/pubring.kbx my-public-key.asc
Copy to Clipboard Copied! Toggle word wrap Toggle overflow NoteIn addition to any signatures provided by automation hub, signature sources can also be provided in the requirements file and on the command line. Signature sources should be URIs.
To verify the collection name provided on the CLI with an additional signature, run the following command:
ansible-galaxy collection install namespace.collection --signature https://examplehost.com/detached_signature.asc --signature file:///path/to/local/detached_signature.asc --keyring ~/.ansible/pubring.kbx
ansible-galaxy collection install namespace.collection --signature https://examplehost.com/detached_signature.asc --signature file:///path/to/local/detached_signature.asc --keyring ~/.ansible/pubring.kbx
Copy to Clipboard Copied! Toggle word wrap Toggle overflow You can use this option multiple times to provide multiple signatures.
Confirm that the collections in a requirements file list any additional signature sources following the collection’s signatures key, as in the following example.
Copy to Clipboard Copied! Toggle word wrap Toggle overflow When you install a collection from automation hub, the signatures provided by the server are saved along with the installed collections to verify the collection’s authenticity.
-
(Optional) If you need to verify the internal consistency of your collection again without querying the Ansible Galaxy server, run the same command you used previously using the
--offline
option.
Are there any recommendations for collection naming?
Create a collection with company_name.product
format. This format means that multiple products can have different collections under the company namespace.
How do I get a namespace on automation hub?
By default namespaces used on Ansible Galaxy are also used on automation hub by the Ansible partner team. For any queries and clarifications contact ansiblepartners@redhat.com.
1.4. Ansible validated content Copiar o linkLink copiado para a área de transferência!
Red Hat Ansible Automation Platform includes Ansible validated content, which complements existing Red Hat Ansible Certified Content.
Ansible validated content provides an expert-led path for performing operational tasks on a variety of platforms from both Red Hat and our trusted partners.
1.4.1. Configuring validated collections with the installer Copiar o linkLink copiado para a área de transferência!
When you download and run the RPM bundle installer, certified and validated collections are automatically uploaded. Certified collections are uploaded into the rh-certified
repository. Validated collections are uploaded into the validated
repository.
You can change the default configuration by using two variables:
-
automationhub_seed_collections
is a boolean that defines whether or not preloading is enabled. -
automationhub_collection_seed_repository
is a variable that enables you to specify the type of content to upload when it is set totrue
. Possible values arecertified
orvalidated
. If this variable is missing, both content sets will be uploaded.
Changing the default configuration may require further platform configuration changes for other content you may use.