↓Skip to main content

Ansible Collections: Create, Install and Use Git Based Ansible Collections

761 words·
Ansible Ansible Collections Git GitLab
Table of Contents

Git Based Ansible Collection
#

Clone Git Repository
#

Create a new Git repository, clone it to your local machine and use it as the location for the Ansible collection:

# Clone a git repository that will be use for the Ansible collection
git clone git@gitlab.jklug.work:ansible/ansible-collections.git && cd ansible-collections

Create New Ansible Collection
# 

# Create a new Ansible collection in current directory: Syntax
ansible-galaxy collection init --init-path . namespace.collectionname

# Create a new Ansible collection in current directory: Example
ansible-galaxy collection init --init-path . jkw.collection1

The file and folder structure of the Ansible collection looks like this:

# ansible-collections.git
└── jkw
    └── collection1
        ├── docs
        ├── galaxy.yml
        ├── meta
        │   └── runtime.yml
        ├── plugins
        │   └── README.md
        ├── README.md
        └── roles


# Adapt the galaxy file
vi jkw/collection1/galaxy.yml

namespace: jkw
name: collection1
version: 1.0.0
readme: README.md

authors:
- JKW <juergen@jklug.work>

description: Some Ansible roles
dependencies: {}

repository: https://gitlab.jklug.work/ansible/ansible-collections.git
documentation: https://gitlab.jklug.work/ansible/ansible-collections
homepage: https://gitlab.jklug.work/ansible/ansible-collections
issues: https://gitlab.jklug.work/ansible/ansible-collections/-/issues

build_ignore: []

Create Ansible Roles
#

Version1: Ansible Galaxy Init Command
# 

# Use the following command to create a role with default structure
ansible-galaxy init --init-path jkw/collection1/roles example_role1

Version2: Manually
# 

# Manually create a role
mkdir -p jkw/collection1/roles/example_role2/{meta,tasks}

# Create a meta file
vi jkw/collection1/roles/example_role2/meta/main.yml

galaxy_info:
  author: your name
  description: your role description
  company: your company (optional)

  # If the issue tracker for your role is not on github, uncomment the
  # next line and provide a value
  # issue_tracker_url: http://example.com/issue/tracker

  # Choose a valid license ID from https://spdx.org - some suggested licenses:
  # - BSD-3-Clause (default)
  # - MIT
  # - GPL-2.0-or-later
  # - GPL-3.0-only
  # - Apache-2.0
  # - CC-BY-4.0
  license: license (GPL-2.0-or-later, MIT, etc)


# Create an example task
vi jkw/collection1/roles/example_role2/tasks/main.yml

---
- name: Ensure file exists
  ansible.builtin.copy:
    dest: /tmp/example-file
    content: |
      some text
      more text      
    owner: debian
    group: debian

File and Folder Structure
#

The file and folder structure of the Ansible collection with the roles looks like this:

# ansible-collections.git
└── jkw
    └── collection1
        ├── docs
        ├── galaxy.yml
        ├── meta
        │   └── runtime.yml
        ├── plugins
        │   └── README.md
        ├── README.md
        └── roles
            ├── example_role1
            │   ├── defaults
            │   │   └── main.yml
            │   ├── files
            │   ├── handlers
            │   │   └── main.yml
            │   ├── meta
            │   │   └── main.yml
            │   ├── README.md
            │   ├── tasks
            │   │   └── main.yml
            │   ├── templates
            │   ├── tests
            │   │   ├── inventory
            │   │   └── test.yml
            │   └── vars
            │       └── main.yml
            └── example_role2
                ├── meta
                │   └── main.yml
                └── tasks
                    └── main.yml



Install Ansible Collection
#

Create Ansible Project
#

Create a new Ansible project that will use the Ansible collection:

# Create project folder
mkdir -p ansible-example-project/playbooks && cd ansible-example-project

Requirements
# 

# Create a requirements configuration file
vi requirements.yml

collections:
  - name: "jkw.collections"
    source: git+ssh://git@gitlab.jklug.work/ansible/ansible-collections.git#jkw/collection1
    version: main
    type: git

Note, it’s important to correctly reference the Git repository URL like this:

# Git repository URL:
git@gitlab.jklug.work:ansible/ansible-collections.git

# Git repository reference in requirements.yml
git@gitlab.jklug.work/ansible/ansible-collections.git

Install Collection
#

Install the Ansible collection via the requirements.yml file.

# Install collection
ansible-galaxy collection install -r requirements.yml

# Shell output:
Starting galaxy collection install process
Process install dependency map
Cloning into '/home/debian/.ansible/tmp/ansible-local-39344dfhl7b8w/tmpenqkl383/ansible-collectionsrm83q70m'...
remote: Enumerating objects: 39, done.
remote: Counting objects: 100% (39/39), done.
remote: Compressing objects: 100% (21/21), done.
remote: Total 39 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0)
Receiving objects: 100% (39/39), 7.53 KiB | 2.51 MiB/s, done.
Resolving deltas: 100% (1/1), done.
Already on 'main'
Your branch is up to date with 'origin/main'.
Starting collection install process
Installing 'jkw.collection1:1.0.0' to '/home/debian/.ansible/collections/ansible_collections/jkw/collection1'
Created collection for jkw.collection1:1.0.0 at /home/debian/.ansible/collections/ansible_collections/jkw/collection1
jkw.collection1:1.0.0 was installed successfully

Verify Collection / List Collections
# 

# List installed collecitons
ansible-galaxy collection list

# Shell output:
# /home/debian/.ansible/collections/ansible_collections
Collection                               Version
---------------------------------------- -------
jkw.collection1                          1.0.0

# /usr/lib/python3/dist-packages/ansible_collections
Collection                               Version
---------------------------------------- -------
amazon.aws                               8.2.1
ansible.netcommon                        6.1.3
ansible.posix                            1.6.2
...

Uninstall Collection
# 

# Delete Collection
rm -rf ~/.ansible/collections/ansible_collections/jkw/collection1



Reference Ansible Collection
#

Ansible Configuration
#

  • ansible.cfg
[defaults]
roles_path = ./roles
collections_path = .ansible/collections:~/.ansible/collections

Inventory
#

  • inventory
[example_hosts]
192.168.30.161 ansible_user=debian

Create Playbook
#

Create a playbook that references the role of the Ansible collection:

  • playbooks/example_playbook.yml
---
- name: Example Playbook
  hosts: example_hosts
  become: true
  gather_facts: false
  roles:
    - role: jkw.collection1.example_role2

Run Playbook
# 

# Run the playbook
ansible-playbook playbooks/example_playbook.yml -i inventory

# Shell output:
PLAY [Example Playbook] *******************************************************************************************************************************************************************************************

TASK [jkw.collection1.example_role2 : Ensure file exists] *********************************************************************************************************************************************************
[WARNING]: Platform linux on host 192.168.30.161 is using the discovered Python interpreter at /usr/bin/python3.11, but future installation of another Python interpreter could change the meaning of that path.
See https://docs.ansible.com/ansible-core/2.17/reference_appendices/interpreter_discovery.html for more information.
changed: [192.168.30.161]

PLAY RECAP ********************************************************************************************************************************************************************************************************
192.168.30.161             : ok=1    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0