Collection #

Role adalah cara mengemas dan berbagi konfigurasi Ansible. Tapi role punya batasan — ia hanya bisa berisi tasks, handlers, templates, dan variabel. Ia tidak bisa mengemas module custom, filter plugin, atau inventory plugin bersama-sama. Ansible Collection hadir untuk menyelesaikan keterbatasan ini: satu unit distribusi yang bisa berisi role, module, plugin, playbook, dan dokumentasi — semuanya dengan versi yang jelas dan dependency yang terdeklarasi.

Struktur Collection #

my_namespace/
└── my_collection/
    ├── galaxy.yml              # Metadata collection (wajib)
    ├── README.md
    ├── CHANGELOG.rst
    ├── docs/                   # Dokumentasi
    ├── plugins/
    │   ├── modules/            # Custom modules
    │   │   └── app_config.py
    │   ├── module_utils/       # Shared utilities untuk modules
    │   │   └── api_client.py
    │   ├── lookup/             # Lookup plugins
    │   │   └── company_cmdb.py
    │   ├── filter/             # Filter plugins
    │   │   └── company_filters.py
    │   ├── callback/           # Callback plugins
    │   │   └── deployment_notifier.py
    │   └── inventory/          # Inventory plugins
    │       └── cmdb.py
    ├── roles/
    │   ├── webserver/          # Role dalam collection
    │   └── database/
    └── playbooks/
        └── deploy.yml

Membuat Collection Baru #

# Buat struktur collection dari template
ansible-galaxy collection init my_namespace.my_collection

cd my_namespace/my_collection

galaxy.yml: Metadata Collection #

File galaxy.yml adalah jantung collection — mendefinisikan identitas, versi, dan dependency:

# galaxy.yml
namespace: my_company
name: infrastructure
version: 2.1.0
readme: README.md
description: >
  Collection untuk infrastruktur internal My Company — berisi role, module,
  dan plugin yang digunakan di seluruh tim SRE.  

authors:
  - Tim SRE <[email protected]>

license:
  - GPL-2.0-or-later

tags:
  - infrastructure
  - deployment
  - monitoring

repository: https://github.com/mycompany/ansible-infrastructure
documentation: https://docs.mycompany.internal/ansible
issues: https://github.com/mycompany/ansible-infrastructure/issues

# Dependency ke collection lain
dependencies:
  community.general: ">=7.0.0"
  amazon.aws: ">=7.0.0"
  community.docker: ">=3.4.0"

Menggunakan Module dari Collection #

Setelah collection diinstal, module dan plugin diakses menggunakan Fully Qualified Collection Name (FQCN):

# FQCN: namespace.collection.module_name
- name: Set konfigurasi aplikasi
  my_company.infrastructure.app_config:
    name: max_connections
    value: "100"
    api_url: "{{ api_url }}"
    api_token: "{{ vault_api_token }}"
    state: present

# Role dalam collection
- name: Setup web server
  import_role:
    name: my_company.infrastructure.webserver
  vars:
    nginx_port: 443

Membangun dan Menginstal Collection #

# Build collection menjadi archive
ansible-galaxy collection build

# Output: my_company-infrastructure-2.1.0.tar.gz

# Instal dari file lokal
ansible-galaxy collection install my_company-infrastructure-2.1.0.tar.gz

# Instal dari Galaxy
ansible-galaxy collection install my_company.infrastructure

# Instal dengan versi spesifik
ansible-galaxy collection install my_company.infrastructure:==2.1.0

requirements.yml untuk Manajemen Dependency #

Proyek yang menggunakan beberapa collection sebaiknya mendefinisikan semuanya di satu file:

# requirements.yml
---
collections:
  # Collection dari Ansible Galaxy
  - name: community.general
    version: ">=7.0.0,<8.0.0"

  - name: community.docker
    version: "3.4.6"          # Pin ke versi exact di production

  - name: amazon.aws
    version: ">=7.0.0"

  - name: kubernetes.core
    version: "2.4.0"

  # Collection private dari Automation Hub internal
  - name: my_company.infrastructure
    version: "2.1.0"
    source: https://automation-hub.mycompany.internal/api/galaxy/

roles:
  - name: geerlingguy.nginx
    version: "3.2.0"
    src: https://github.com/geerlingguy/ansible-role-nginx

# Instal semua dependency sekaligus
ansible-galaxy install -r requirements.yml
ansible-galaxy collection install -r requirements.yml

# Atau keduanya sekaligus (Ansible >= 2.10)
ansible-galaxy install -r requirements.yml

Private Automation Hub #

Untuk collection internal yang tidak boleh dipublikasikan ke Galaxy publik, gunakan Private Automation Hub atau serve via server HTTP sederhana:

# ansible.cfg
[galaxy]
server_list = automation_hub, galaxy

[galaxy_server.automation_hub]
url = https://automation-hub.mycompany.internal/api/galaxy/
auth_url = https://automation-hub.mycompany.internal/auth/token/
token = {{ lookup('env', 'AUTOMATION_HUB_TOKEN') }}

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

# Publish collection ke private hub
ansible-galaxy collection publish \
  my_company-infrastructure-2.1.0.tar.gz \
  --server automation_hub

Testing Collection #

# molecule/default/molecule.yml untuk testing collection
---
dependency:
  name: galaxy
  options:
    requirements-file: requirements.yml

driver:
  name: docker

platforms:
  - name: ubuntu22
    image: geerlingguy/docker-ubuntu2204-ansible:latest
    pre_build_image: true

provisioner:
  name: ansible
  playbooks:
    converge: converge.yml
  inventory:
    links:
      group_vars: ../../../inventory/group_vars

Ringkasan #

Collection adalah unit distribusi Ansible yang lengkap — berisi role, module, plugin, dan playbook dalam satu paket dengan versi yang jelas.
Struktur direktori collection mengikuti konvensi ketat: plugins/modules/, plugins/filter/, roles/, dll. — Ansible menemukan komponen berdasarkan lokasi, bukan konfigurasi.
galaxy.yml mendefinisikan identitas, versi, dan dependency collection — selalu pin dependency ke versi minimum atau range yang ditest.
Gunakan FQCN (Fully Qualified Collection Name) saat menggunakan module dari collection — my_company.infrastructure.app_config, bukan hanya app_config.
requirements.yml untuk mendefinisikan semua collection dependency di satu tempat — gunakan ansible-galaxy collection install -r requirements.yml di CI/CD.
Untuk collection internal, gunakan Private Automation Hub atau repository internal — jangan publish kode internal ke Galaxy publik.

← Sebelumnya: Dynamic Inventory Berikutnya: Jinja2 Lanjutan →