Skip to content

Latest commit

 

History

History
119 lines (77 loc) · 6.33 KB

ansiblegalaxy_user_documentation.md

File metadata and controls

119 lines (77 loc) · 6.33 KB

Ansible Galaxy Configuration

Table Of Contents

Overview

Ansible Galaxy provides a way to install community collections and roles for Ansible.

Full documentation on installing ansible-galaxy can be found on the Ansible Galaxy project website.

You can create a proxy repository in Nexus Repository Manager (NXRM) that will cache packages from a remote Ansible Galaxy repository, like https://galaxy.ansible.com/.

You can also create a hosted repository to handle your own collections.

Then, you can make the ansible-galaxy client use your Nexus Repository instead of the remote repository.

Installation

Ensure the plugin is installed in your Nexus environment (see installing the plugin).

Repository configuration

To create an Ansible Galaxy repository, you simply create a new 'ansiblegalaxy (proxy)' or 'ansiblegalaxy (hosted)' as documented in Repository Management in detail. Minimal configuration steps are:

  • Define 'Name' - e.g. ansiblegalaxy-proxy
  • Define URL for 'Remote storage' - e.g. https://galaxy.ansible.com/ => only for proxy
  • Select a Blob store for Storage

Configuring the ansible-galaxy client

You must set the Galaxy API endpoint/server when using the client, either by:

  • provide the -s API_SERVER or --server API_SERVER argument for each installation command.
  • configure GALAXY_SERVER configuration value or ANSIBLE_GALAXY_SERVER environment variable.

If you have multiple hosted repositories or one hosted and one proxy, you can set multiples repositories in your config file ansible.cfg Then the first one owning the desired package will be used

example:

[galaxy]
server_list = my_org_hub,proxy

[galaxy_server.my_org_hub]
url=http://127.0.0.1:8081/repository/ansible-hosted/

[galaxy_server.proxy]
url=http://127.0.0.1:8081/repository/ansible-proxy/

See the following resources for additional detail:

Usage

Using the ansible-galaxy client, you can now download packages from your NXRM Ansible Galaxy:

ansible-galaxy collection install azure.azcollection -s http://localhost:8081/repository/ansible/

The command above tells ansible-galaxy to fetch (and install) packages from your NXRM Ansible Galaxy proxy. The NXRM Ansible Galaxy proxy will download any missing packages from the remote Ansible Galaxy repository, and cache the packages and the metadata on the NXRM Ansible Galaxy proxy.
The next time any client requests the same package from your NXRM Ansible Galaxy proxy, the already cached package will be returned to the client. No other call are made to the galaxy proxied instance

Browsing Repository Packages

You can browse Composer repositories in the user interface inspecting the components and assets and their details, as described in Browsing Repositories and Repository Groups.

Publishing Packages

If you are authoring your own packages and want to distribute them to other users in your organization, you have to upload them to a hosted repository on the repository manager. The consumers can then download it via the repository.

An AnsibleGalaxy package should consist of a tar.gz archive of the sources containing a MANIFEST.json file. The file is automatically generated when you build a collection. This file is generated from the file galaxy.yml which is in your source code in your collection skeleton.

With this information known, the package can be uploaded to your hosted repository (replacing the credentials, source filename, and , , and path segments to match your particular distributable):

curl -v --user 'user:pass' --upload-file example.tar.gz http://localhost:8081/repository/ansible-hosted/<namespace>-<collectionname>-<version>.tar.gz

*Note that the path segments should be the same as your collection manifest.

Role installation support

Due to a bug in Ansible prior to version 2.12, ansible-galaxy would download roles directly from Github.com, even if the download_url for the role specified a different location. This resulted in artifacts not being downloaded through Nexus when using this repository format.

The fix was merged and released in Ansible 2.12.0. Please be sure to use version 2.12.0 (or later) to avoid the issue, or adjust your infrastructure accordingly.