Skip to Content
How-To GuidesInstalling Ansible Collections from Depot

Installing Ansible Collections from Depot

CIQ Depot can serve Ansible collections through a read-only Ansible Galaxy v3 API, so you can install entitled collections with the standard ansible-galaxy client using the same CIQ credentials you already use for Depot. No separate Galaxy server or account is required.

Prerequisites

  • An active subscription to the product that includes the collection you want to install
  • Your username and access token from https://portal.ciq.com/token
  • ansible-core installed (the ansible-galaxy command; version 2.13 or newer)

Configuring the Galaxy Server

Point ansible-galaxy at Depot by adding a galaxy server entry to your ansible.cfg. Create or edit ansible.cfg in your project directory:

[galaxy]
server_list = depot

[galaxy_server.depot]
url=https://depot.ciq.com/api/galaxy/<repo_id>/
username=YOUR_USERNAME
password=YOUR_TOKEN

Replace <repo_id> with the repository that holds the collection, and YOUR_USERNAME and YOUR_TOKEN with the credentials from portal.ciq.com/token.

Example: RLC Pro Hardened

Customers entitled to RLC Pro Hardened install the ctrliq.rlch9_lockdown collection (STIG/CIS/CUI hardening playbooks) from the galaxy-rlc-pro-hardened-9 repository:

[galaxy_server.depot]
url=https://depot.ciq.com/api/galaxy/galaxy-rlc-pro-hardened-9/
username=YOUR_USERNAME
password=YOUR_TOKEN

ansible-galaxy collection install ctrliq.rlch9_lockdown
Protect your token

ansible.cfg contains your access token. Restrict its permissions and keep it out of version control:

chmod 600 ansible.cfg

Installing a Collection

With the galaxy server configured, install a collection by name:

ansible-galaxy collection install <namespace>.<name>

ansible-galaxy resolves the highest available version, verifies the artifact checksum, and installs any dependencies the collection declares. To pin a specific version or choose an install path:

# Install a specific version
ansible-galaxy collection install <namespace>.<name>:1.2.3

# Install into a project-local path
ansible-galaxy collection install <namespace>.<name> -p ./collections

# Upgrade an already-installed collection to the latest version
ansible-galaxy collection install <namespace>.<name> --upgrade
Explicit config path

If you keep ansible.cfg outside the current directory, point Ansible at it explicitly:

ANSIBLE_CONFIG=/path/to/ansible.cfg ansible-galaxy collection install <namespace>.<name>

Resolving Dependencies

Collections can declare dependencies on other collections. When those dependencies are published to the same Depot repository as the collection, the server_list = depot configuration above resolves everything from Depot with no extra setup. This keeps the whole supply chain behind your single Depot entitlement and is the recommended setup for air-gapped or egress-restricted environments.

If a collection depends on content that is not published to Depot, ansible-galaxy reports a dependency resolution error:

ERROR! Failed to resolve the requested dependencies map.

In that case, add the public Ansible Galaxy server as a fallback so the missing dependencies resolve from there:

[galaxy]
server_list = depot, published

[galaxy_server.depot]
url=https://depot.ciq.com/api/galaxy/<repo_id>/
username=YOUR_USERNAME
password=YOUR_TOKEN

[galaxy_server.published]
url=https://galaxy.ansible.com/

ansible-galaxy walks the servers in order, so the collection installs from Depot and any dependencies it cannot find there are pulled from public Galaxy. This path requires outbound access to galaxy.ansible.com. To skip dependency resolution entirely, add --no-deps to the install command and install the dependencies yourself.

Using AWX or Ascender

The Depot Galaxy endpoint also works with the AWX / Ascender "Ansible Galaxy" credential type. Create a Galaxy credential whose server URL is https://depot.ciq.com/api/galaxy/<repo_id>/ and whose token is your CIQ username and token in the form USERNAME:TOKEN, then attach it to your Organization. Project collection installs and requirements resolution then pull from Depot.

Troubleshooting

Authentication Failed (401)

Problem: ansible-galaxy reports a 401 Unauthorized.

Solutions:

  • Confirm the username and password in ansible.cfg match your current credentials from portal.ciq.com/token
  • Regenerate the token in the Portal if it may have been rotated
  • Test the credentials directly: 
    curl -u 'YOUR_USERNAME:YOUR_TOKEN' https://depot.ciq.com/api/galaxy/<repo_id>/v3/collections/

Access Forbidden (403)

Problem: Credentials are accepted but installation returns 403 Forbidden.

Solutions:

  • A 403 means the credentials are valid but your subscription does not include the product that grants access to this collection. Confirm your entitlement under My Products at portal.ciq.com
  • Contact CIQ Support if you believe you should have access

Collection or Version Not Found (404)

Problem: ansible-galaxy cannot find the collection or a requested version.

Solutions:

  • Verify the <namespace>.<name> spelling and that the <repo_id> in the URL is correct
  • List what the server offers: 
    curl -u 'YOUR_USERNAME:YOUR_TOKEN' https://depot.ciq.com/api/galaxy/<repo_id>/v3/collections/
  • If you pinned a version, confirm that version is published

Dependency Resolution Failed

Problem: Installation fails with Failed to resolve the requested dependencies map, naming a dependency collection such as ansible.posix or community.general.

Solutions:

  • The collection depends on another collection that none of the servers in your server_list provide. If the dependency should come from Depot, confirm it is published to the same repository; otherwise add the public Ansible Galaxy server as a fallback (see Resolving Dependencies)
  • To install without resolving dependencies, add --no-deps and install the dependencies separately: 
    ansible-galaxy collection install <namespace>.<name> --no-deps

See Also

Integrating CIQ Repositories with Red Hat Satellite