BlogOktober 20267 min lezenAutomationPlatform Engineering

Ansible Collections verpakt als Ansible Execution Environments

Develop lokaal Build GitLab CI Publish Galaxy + registry Run in een orchestrator 1 Collection ontwikkelen roles + modules 2 Image definiëren base + deps 3 Lokaal testen ansible-navigator 4 Release taggen git tag 1.4.0 5 Image bouwen ansible-builder 6 Image + collection allebei 1.4.0 7 Image tag pinnen rollback 8 Playbook draaien met inventory

Met Ansible automatiseer ik onder andere platforms, services en operating systems. Elk daarvan heeft modules met hun eigen Python-packages, en vroeg of laat willen twee daarvan een andere versie van hetzelfde package. Mijn oplossing: één Ansible Execution Environment (AEE) per product, gebouwd uit de collection die bij dat product hoort.

Werk je met Ansible Automation Platform (AAP), dan ken je execution environments al: elke job draait erin. Het image is de runtime, inclusief Ansible zelf. In dit project gebruikte ik dezelfde images ook lokaal: playbooks draaien met ansible-navigator en roles testen met Molecule. Voor de orchestration gebruikte ik Argo Workflows.

Eén omgeving voor alles

De voor de hand liggende start is één generieke AEE met alle collections erin. Dat gaat goed totdat twee modules een andere versie van hetzelfde package nodig hebben. pip kan ze niet allebei installeren, dus de build faalt of een product draait op een versie die niemand getest heeft. Je kunt dat omzeilen door de requirements van de collection of role tijdens een run te laten installeren, maar dan moet elke run bij een package index kunnen. In een offline of air-gapped omgeving kan dat niet. En een wijziging in de dependencies van één product betekent nog steeds dat het image voor alle producten opnieuw gebouwd en getest moet worden.

Generieke AEE
In één generieke AEE vraagt kubernetes_platform package X 1.x en nutanix_platform package X 2.x: een conflict. In één generieke AEE vraagt kubernetes_platform package X 1.x en nutanix_platform package X 2.x: een conflict.

Daarom heb ik het opgesplitst: één image per collection, met dezelfde versie als die collection. Een nieuw product krijgt een eigen image en laat de rest met rust.

Develop

Een collection per product

Elk product heeft een eigen collection (kubernetes_platform, nutanix_platform, rhel_platform) met een eigen galaxy.yml en versienummer. De roles volgen de objecten van het product. Voor Kubernetes zijn dat cluster, namespace en hardening; elke role gebruikt de modules die met het cluster praten en brengt het in de desired state.

In de repo staat de collection in het default path dat ansible-galaxy voor een collection gebruikt: ansible_collections/<namespace>/<naam>. Alles wat bij de collection hoort staat in die map; de playbooks staan ernaast, in de root van de repo.

kubernetes_platform/ voorbeeld
kubernetes_platform/
├── ansible_collections/
│   └── automation/
│       └── kubernetes_platform/
│           ├── galaxy.yml
│           ├── README.md
│           ├── meta/
│           │   └── runtime.yml
│           ├── plugins/
│           │   └── modules/
│           ├── roles/
│           │   ├── cluster/
│           │   ├── namespace/
│           │   └── hardening/
│           ├── requirements.txt
│           └── bindep.txt
├── playbooks/
│   └── deploy_cluster.yml
├── execution-environment.yml
└── .gitlab-ci.yml

Collection en image komen allebei in private automation hub (Galaxy), zodat AAP en de rest dezelfde versie van één plek halen.

Develop

Het image bouwen

De execution-environment.yml beschrijft het image en verder niets: een RHEL-based EE base image uit de eigen registry van het project, Python, ansible-core, ansible-runner en de collection. De map ansible_collections en de playbooks gaan zoals ze zijn mee in de build. Galaxy installeert de collection vanaf dat path, samen met de collections die als dependency in galaxy.yml staan, en de playbooks komen in /playbooks.

execution-environment.yml voorbeeld
---
version: 3

images:
  base_image:
    name: registry.example.com/automation/ee-minimal-rhel9:latest

dependencies:
  python_interpreter:
    package_system: python3.11
    python_path: /usr/bin/python3.11
  ansible_core:
    package_pip: ansible-core>=2.16,<2.17
  ansible_runner:
    package_pip: ansible-runner
  galaxy:
    collections:
      - name: /build/ansible_collections/automation/kubernetes_platform
        type: dir

additional_build_files:
  - src: ansible_collections
    dest: ansible_collections
  - src: playbooks
    dest: playbooks

additional_build_steps:
  append_final:
    - COPY _build/playbooks /playbooks

options:
  package_manager_path: /usr/bin/microdnf

Python- en systeempackages blijven bij de collection die ze nodig heeft. ansible-builder leest de requirements.txt en bindep.txt van elke collection die ansible-builder installeert. kubernetes_platform hangt af van vier collections, en elk daarvan brengt de eigen dependencies mee: kubernetes.core de Python-client kubernetes, ansible.utils packages als netaddr en jsonschema, community.hashi_vault de hvac-client voor Vault, en community.crypto systeempackages als OpenSSL. kubernetes_platform zelf vermeldt geen van die packages.

galaxy.yml voorbeeld
namespace: automation
name: kubernetes_platform
version: 1.4.0
readme: README.md
authors:
  - Platform team <platform@example.com>
dependencies:
  kubernetes.core: ">=5.0.0"
  ansible.utils: ">=5.0.0"
  community.hashi_vault: ">=6.0.0"
  community.crypto: ">=2.0.0"

Develop

Lokaal testen

Voordat er iets naar de pipeline gaat, bouw ik het image lokaal vanuit hetzelfde bestand en draai ik er een playbook in met ansible-navigator. Een wijziging in een role wordt zo getest tegen de runtime die de pipeline straks bouwt, en niet tegen de Python die toevallig in mijn eigen omgeving staat.

ansible-builder build -f execution-environment.yml -t kubernetes-ee:dev
ansible-navigator run playbooks/deploy_cluster.yml --eei kubernetes-ee:dev

Build en publish

De pipeline

GitLab CI bouwt het image op een Git-tag. Voor de build is een container runtime nodig, en die moet binnen de container van de CI-job zelf draaien. Dat werkt niet zomaar (meer daarover bij Uitdagingen). De job pusht het image naar een registry, in dit project private automation hub (Galaxy), Harbor of de GitLab Container Registry. Een tweede job publiceert de collection.

.gitlab-ci.yml voorbeeld
stages:
  - build
  - publish

build-ee:
  stage: build
  image: registry.example.com/automation/ansible-buildkit:latest
  tags:
    - podman-in-podman
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - ansible-builder build --container-runtime podman
        -f execution-environment.yml
        -t $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
    - echo "$CI_REGISTRY_PASSWORD" |
        podman login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
    - podman push $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG

# Publish the collection with the same version as the image
publish-collection:
  stage: publish
  image: registry.example.com/automation/ansible-buildkit:latest
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - ansible-galaxy collection build
        ansible_collections/automation/kubernetes_platform
    - ansible-galaxy collection publish
        automation-kubernetes_platform-$CI_COMMIT_TAG.tar.gz
        --server "$AH_SERVER_URL" --api-key "$AH_API_TOKEN"

De tag is de versie uit galaxy.yml, dus collection kubernetes_platform 1.4.0 draait in kubernetes-ee:1.4.0. Terug naar een eerdere release betekent de eerdere tag pinnen.

Run

In productie

Hier deed Argo Workflows de orchestration. Een workflow step verwijst naar een gepinde image tag en draait een playbook uit /playbooks. De inventory zit niet in het image; Argo geeft de inventory mee als input artifact.

Argo Workflows-step voorbeeld
- name: deploy-cluster
  inputs:
    artifacts:
      - name: inventory
        path: /runner/inventory
  container:
    image: registry.example.com/automation/kubernetes-ee:1.4.0
    command: [ansible-playbook]
    args: ["-i", "/runner/inventory", "/playbooks/deploy_cluster.yml"]

Met AAP werkt het hetzelfde. Push het image naar private automation hub (Galaxy), stel het in als execution environment van een job template, en AAP levert de inventory.

Architectuur
Lokale machine ansible-builder ansible-navigator molecule GitLab repo met de collection CI-runner ansible-builder Platforms, services en operating systems Kubernetes KVM RHEL Private automation hub kubernetes-ee:1.4.0 collection 1.4.0 Orchestrator Argo Workflows AAP git push + tag push publish pull pull playbook + inventory

Zelf proberen

De opbouw, de execution-environment.yml en de GitLab-pipeline uit deze post staan als werkende repo in ansible-ee-example. Die repo gebruikt een publiek UBI 9 base image in plaats van het private image, hangt alleen af van kubernetes.core, en de roles zijn lege placeholders: het gaat om de execution environment, niet om de automation erin. Het playbook ee_info laat zien met welke Python, ansible-core en kubernetes-client de run echt draaide. Het is er vooral om de discussie "maar welke Python was dat dan?" te beslechten voordat die begint.

git clone https://github.com/wsslhllmn/ansible-ee-example.git
cd ansible-ee-example
ansible-builder build -f execution-environment.yml -t kubernetes-ee:dev
ansible-navigator run playbooks/ee_info.yml \
  --eei kubernetes-ee:dev --mode stdout
ee_info output (verwacht)
$ ansible-navigator run playbooks/ee_info.yml \
  --eei kubernetes-ee:dev --mode stdout

PLAY [Show which runtime this playbook runs with] **********************

TASK [Collect runtime information] *************************************
ok: [localhost]

TASK [Show it] *********************************************************
ok: [localhost] => {
    "msg": [
        "Python 3.11.13 (/usr/bin/python3.11)",
        "ansible-core 2.16.19",
        "kubernetes 37.0.1"
    ]
}

PLAY RECAP *************************************************************
localhost : ok=2  changed=0  unreachable=0  failed=0  skipped=0  rescued=0
ignored=0

Build

Uitdagingen

Probleemansible-builder heeft een container runtime nodig om het image te bouwen, en die build draait in de container van de GitLab CI-job zelf. De runtime moet dus genest in een container draaien, en dat werkt niet zomaar.

OplossingTwee manieren die allebei werken.

  1. Een GitLab runner die Podman in een container kan draaien (podman-in-podman), met ansible-builder daarop gericht via --container-runtime podman. Dat is de .gitlab-ci.yml hierboven.
  2. Buildah, zonder geneste Podman. ansible-builder create schrijft de build context en de Containerfile zonder iets te bouwen, en Buildah bouwt en pusht die context zonder daemon in de container van de CI-job.
.gitlab-ci.yml voorbeeld (Buildah)
build-ee:
  stage: build
  image: registry.example.com/automation/ansible-buildkit:latest
  variables:
    BUILDAH_ISOLATION: chroot
    STORAGE_DRIVER: vfs
  script:
    - ansible-builder create -f execution-environment.yml
    - buildah build -f context/Containerfile
        -t $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG context
    - echo "$CI_REGISTRY_PASSWORD" |
        buildah login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
    - buildah push $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG

Conclusie

Eén execution environment per collection lost de dependency-conflicten op: elk product krijgt de Python- en systeempackages die het nodig heeft, zonder te botsen met de andere. Collection en image delen één versienummer, dus elke run is te herleiden tot een tag, en terug naar een vorige release betekent de vorige tag pinnen.

Lokaal test ik tegen hetzelfde image dat in productie draait, en omdat het image een gewone container is, draait het in elke orchestrator, van Argo Workflows tot AAP. Code delen betekent niet meer naar een repo verwijzen: de collection wordt gepubliceerd, het image staat in een registry, en wie ze pullt krijgt precies hetzelfde.

Het kost een build pipeline per collection en een registry voor de images. Staan die eenmaal, dan is een nieuw product gewoon één extra collection en één extra image, en blijft de rest precies zoals het is.