Ansible Collections verpakt als Ansible Execution Environments
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 AEEDaarom 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/
├── 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.
---
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.
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:devBuild 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 voorbeeldstages:
- 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.
- 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.
ArchitectuurZelf 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$ 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.
- Een GitLab runner die Podman in een container kan draaien (podman-in-podman), met
ansible-builderdaarop gericht via--container-runtime podman. Dat is de.gitlab-ci.ymlhierboven. - Buildah, zonder geneste Podman.
ansible-builder createschrijft de build context en deContainerfilezonder iets te bouwen, en Buildah bouwt en pusht die context zonder daemon in de container van de CI-job.
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_TAGConclusie
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.