mirror of
https://github.com/ansible/awx.git
synced 2024-10-28 02:25:27 +03:00
102 lines
4.0 KiB
Markdown
102 lines
4.0 KiB
Markdown
## Collections
|
||
|
||
AWX supports the use of Ansible Collections. This section will give ways to use Collections in job runs.
|
||
|
||
### Project Collections Requirements
|
||
|
||
If you specify a collections requirements file in SCM at `collections/requirements.yml` of a project,
|
||
then AWX will install collections from that file to a special cache folder in project updates.
|
||
Before a job runs, the roles and/or collections will be copied from the special
|
||
cache folder to the job temporary folder.
|
||
|
||
The invocation looks like:
|
||
|
||
```
|
||
ansible-galaxy collection install -r requirements.yml -p <project cache location>/_<project #>__<project name>/stage/requirements_collections
|
||
```
|
||
|
||
Example of the resultant job `tmp` directory where job is running:
|
||
|
||
```
|
||
├── requirements_collections
|
||
│ └── ansible_collections
|
||
│ └── namespace
|
||
│ └── collection_name
|
||
│ ├── FILES.json
|
||
│ ├── MANIFEST.json
|
||
│ ├── README.md
|
||
│ ├── roles
|
||
│ │ ├── role_in_collection_name
|
||
│ │ │ ├── defaults
|
||
│ │ │ │ └── main.yml
|
||
│ │ │ ├── tasks
|
||
│ │ │ │ └── main.yml
|
||
│ │ │ └── templates
|
||
│ │ │ └── stuff.j2
|
||
│ └── tests
|
||
│ └── main.yml
|
||
└── requirements_roles
|
||
└── namespace.role_name
|
||
├── defaults
|
||
│ └── main.yml
|
||
├── meta
|
||
│ └── main.yml
|
||
├── README.md
|
||
├── tasks
|
||
│ ├── main.yml
|
||
│ └── some_role.yml
|
||
├── templates
|
||
│ └── stuff.j2
|
||
└── vars
|
||
└── Archlinux.yml
|
||
```
|
||
|
||
### Cache Folder Mechanics
|
||
|
||
Every time a project is updated as a "check" job
|
||
(via `/api/v2/projects/N/update/` or by a schedule, workflow, etc.),
|
||
the roles and collections are downloaded and saved to the project's content cache.
|
||
In other words, the cache is invalidated every time a project is updated.
|
||
That means that the `ansible-galaxy` commands are ran to download content
|
||
even if the project revision does not change in the course of the update.
|
||
|
||
Project updates all initially target a staging directory at a path like:
|
||
|
||
```
|
||
/var/lib/awx/projects/.__awx_cache/_42__project_name/stage
|
||
```
|
||
|
||
After the update finishes, the task logic will decide what id to associate
|
||
with the content downloaded.
|
||
Then the folder will be renamed from "stage" to the cache id.
|
||
For instance, if the cache id is determined to be 63:
|
||
|
||
```
|
||
/var/lib/awx/projects/.__awx_cache/_42__project_name/63
|
||
```
|
||
|
||
The cache may be updated by project syncs (the "run" type) which happen before
|
||
job runs. It will populate the cache id set by the last "check" type update.
|
||
|
||
### Galaxy Server Selection
|
||
|
||
For details on how Galaxy servers are configured in Ansible in general see:
|
||
|
||
https://docs.ansible.com/ansible/devel/user_guide/collections_using.html
|
||
(if "devel" link goes stale in the future, it is for Ansible 2.9)
|
||
|
||
You can specify a list of zero or more servers to download roles and
|
||
collections from for AWX Project Updates. This is done by associating Galaxy
|
||
credentials (in sequential order) via the API at
|
||
`/api/v2/organizations/N/galaxy_credentials/`. Authentication
|
||
via an API token is optional (i.e., https://galaxy.ansible.com/), but other
|
||
content sources (such as Red Hat Ansible Automation Hub) require proper
|
||
configuration of the Auth URL and Token.
|
||
|
||
If no credentials are defined at this endpoint for an Organization, then roles and
|
||
collections will *not* be installed based on requirements.yml for Project Updates
|
||
in that Organization.
|
||
|
||
Even when these settings are enabled, this can still be bypassed for a specific
|
||
requirement by using the `source:` option, as described in Ansible documentation.
|