Working with Ansible Galaxy

1. Installing Roles

Command	Description	Options
ansible-galaxy role install	Installs a role from Ansible Galaxy	`-p` to specify path, `--force` to overwrite existing roles

Example: Install a role

ansible-galaxy role install geerlingguy.nginx

Example: Install a role to a specific path

ansible-galaxy role install -p ./roles geerlingguy.nginx

Note: Roles are installed into the roles/ directory by default in your playbook directory.

2. Creating Roles

Example: Basic Role Structure

my_role/
├── defaults/
│   └── main.yml
├── files/
├── handlers/
│   └── main.yml
├── meta/
│   └── main.yml
├── tasks/
│   └── main.yml
├── templates/
├── vars/
│   └── main.yml
└── README.md

Directory	Description	Usage
defaults/main.yml	Default variables for the role	Used to define default values that can be overridden
files/	Static files to be copied to the target	Use `src` in tasks to reference files
handlers/main.yml	Handlers that can be triggered by tasks	Used for actions like restarting services
meta/main.yml	Role dependencies and supported platforms	Defines what other roles this one depends on
tasks/main.yml	Main set of tasks to execute	Core logic of the role
templates/	Template files to be rendered with variables	Use `src` in tasks to reference templates
vars/main.yml	Variables specific to this role	Used for variables that are not defaults
README.md	Documentation for the role	Describes how to use and configure the role

Note: The tasks/main.yml file is required for a role to be valid, even if it's empty.

Example: Defining Variables in defaults/main.yml

---
app_name: "myapp"
app_port: 8080
app_user: "appuser"

Example: Using Templates in a Role

- name: "Deploy config file"
  template:
    src: app.conf.j2
    dest: /etc/{{ app_name }}/app.conf

3. Listing Installed Roles

Command	Description	Options
ansible-galaxy role list	Lists all installed roles	`-p, --path` - Specify the path to search for roles `--format` - Output format (json, yaml)

Example: Listing installed roles

ansible-galaxy role list

Example: Listing roles in a specific path

ansible-galaxy role list -p /etc/ansible/roles

4. Removing Roles

Command	Description	Notes
ansible-galaxy role remove	Removes a role from the local system	Must specify the role name and collection if applicable

Example: Removing a Role

ansible-galaxy role remove my_namespace.my_role

Note: This command only removes the role from the local system. It does not affect roles installed in other environments or those managed by version control.

5. Using Requirements File

Field	Description	Example
src	Source of the collection or role	`https://github.com/ansible-collections/community.docker`
name	Name of the collection or role	`community.docker`
version	Version of the collection or role to install	`>=1.0.0`
type	Type of resource (collection or role)	`collection`

Example: requirements.yml file

---
collections:
  - name: community.docker
    version: ">=2.0.0"
  - name: ansible.posix
    version: "1.4.0"
roles:
  - src: https://github.com/geerlingguy/ansible-role-docker
    version: "v1.0.0"

Note: The requirements.yml file is used with ansible-galaxy collection install -r requirements.yml and ansible-galaxy role install -r requirements.yml.

6. Installing from Requirements

Option	Values	Description
requirements.yml	`collections:`	List of collections to install
requirements.yml	`roles:`	List of roles to install

Example: requirements.yml content

collections:
  - name: community.docker
    version: "3.10.2"
  - name: community.kubernetes
    version: "2.4.0"
roles:
  - name: geerlingguy.nginx
    version: "2.2.1"

Example: Installing from requirements.yml

ansible-galaxy install -r requirements.yml

Note: The ansible-galaxy install command will install collections and roles listed in the requirements file, including their dependencies.

7. Searching Galaxy

Field	Description	Example
galaxy.search	Search term to use in Galaxy	`web server`
galaxy.collection	Collection name to search for	`community.general`
galaxy.role	Role name to search for	`nginx`

Example: Search for collections

ansible-galaxy search web server</code>
</pre>
</div>
</div>
<div class="example">
<h2 id="example-search-for-roles">Example: Search for roles<a href="#example-search-for-roles" class="toc__headingLink" aria-label="Link to this section"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg></a></h2>
<div class="codeBlock" data-language="bash">
<pre><code>ansible-galaxy search --role nginx</code>
</pre>
</div>
</div>
<div class="note">
<strong>Note:</strong> Search results may vary depending on the Galaxy server and available content.
</div>
<h2 id="8-setting-galaxy-server">8. Setting Galaxy Server<a href="#8-setting-galaxy-server" class="toc__headingLink" aria-label="Link to this section"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg></a></h2>
<table>
<tbody>
<tr>
<th>Configuration Option</th>
<th>Description</th>
<th>Default Value</th>
<th>Notes</th>
</tr>
<tr>
<td class="property">galaxy_server</td>
<td>URL of the Galaxy server to use for collections and roles</td>
<td><code>https://galaxy.ansible.com/api/</code></td>
<td>Can be overridden to point to a custom or private Galaxy server</td>
</tr>
<tr>
<td class="property">galaxy_server_token</td>
<td>Authentication token for the Galaxy server</td>
<td>None</td>
<td>Required for authenticated operations (e.g., publishing collections)</td>
</tr>
</tbody>
</table>

<div class="example">
<h2 id="example-configure-galaxy-server-in-ansiblecfg">Example: Configure Galaxy Server in ansible.cfg<a href="#example-configure-galaxy-server-in-ansiblecfg" class="toc__headingLink" aria-label="Link to this section"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg></a></h2>
<div class="codeBlock" data-language="ini">
<pre><code>[galaxy]
server = https://galaxy.ansible.com/api/
server_token = <your_token>

Note: The galaxy_server setting can be overridden via the -i flag or environment variables for specific commands.

Warning: Ensure that the galaxy_server_token is securely stored and not exposed in logs or version control.

9. Installing Collections

Command	Description	Example
ansible-galaxy collection install	Installs a collection from Ansible Galaxy or a local path	`ansible-galaxy collection install community.docker`
ansible-galaxy collection install --collections-path	Installs collections to a specific directory	`ansible-galaxy collection install community.docker --collections-path /opt/ansible/collections`
ansible-galaxy collection install --force	Reinstalls a collection even if it's already installed	`ansible-galaxy collection install --force community.docker`
ansible-galaxy collection install --requirements-file	Installs collections based on a requirements file	`--- collections: - name: community.docker version: "3.4.0" - name: ansible.posix version: "1.4.0"`

Example: Installing a collection from Ansible Galaxy

ansible-galaxy collection install community.docker

Example: Installing a specific version of a collection

ansible-galaxy collection install community.docker:3.4.0

Note: Collections are installed in the default collections path, typically ~/.ansible/collections or /etc/ansible/collections.

10. Specifying Versions

Field	Description	Example
version	Specifies the version of the collection or role to install	`2.0.0`
source	Source of the collection or role (e.g., Galaxy, Git, local path)	`https://galaxy.ansible.com/api/`
scm	Source control management (e.g., git) for version control	`git+https://github.com/ansible-collections/community.docker.git`

Example: Installing a specific version from Ansible Galaxy

- name: Install a specific version of a collection
  ansible.builtin.import_role:
    name: ansible.posix
    version: 1.4.0

Example: Using Git for version control

- name: Install collection from Git
  ansible.builtin.import_role:
    name: community.docker
    scm: git
    src: https://github.com/ansible-collections/community.docker.git
    version: v2.0.0

11. Installing from Git

Option	Values	Notes
src	`https://github.com/ansible/ansible-examples.git`	Git repository URL
version	`main`	Branch, tag, or commit hash to install
type	`git`	Must be set to `git` for Git repositories

Example: Installing from Git

- name: Install collection from Git
  ansible.builtin.galaxy:
    src: https://github.com/ansible/ansible-examples.git
    version: main
    type: git

12. Setting Install Path

Option	Values	Notes
ansible_galaxy_install_path	`~/.ansible`	Default installation path for collections and roles
ansible_galaxy_collection_path	`~/.ansible/collections`	Path where collections are installed
ansible_galaxy_role_path	`~/.ansible/roles`	Path where roles are installed

Example: Setting Galaxy Install Path in ansible.cfg

[galaxy]
install_path = /opt/ansible/galaxy

Note: The ansible_galaxy_install_path setting overrides the default directory structure for collections and roles.