Structureren van Ansible-projecten

Probleem

In Nederlandse overheidsorganisaties beginnen teams vaak Ansible automatisering met beperkte kennis en geen duidelijke structuur voor het organiseren van projectartefacten. Dit leidt tot ongeorganiseerde inventarissen, gedupliceerde inspanningen, moeilijkheden bij het hergebruiken van code over omgevingen heen, en uitdagingen bij het schalen naarmate projecten complexer worden.

Context

Ansible-project kunnen worden gecategoriseerd in typen zoals Ansible-inventarisproject voor het beheren van hosts en desired state configuration, Ansible-collecties projecten voor het verpakken van herbruikbare Ansible-content zoals Ansible-rol, en Uitvoeringsomgeving projecten voor het bundelen van afhankelijkheden. Het begrijpen van deze typen helpt teams om eenvoudig te starten en progressief meer geavanceerde structuren aan te nemen. Dit is vooral relevant in overheidscontexten waar beveiliging, naleving en samenwerking cruciaal zijn, vaak in lijn met GitOps praktijken voor versiegecontroleerde uitrollen.

Oplossing

Volg een gefaseerde aanpak om je Ansible-project te structureren, beginnend van basisopzetten en vorderend naarmate de behoeften groeien:

1. Begin met een Ansible-inventarisproject: Creëer een Ansible-inventarisproject als je startpunt. Definieer hosts in een inventarisbestand (bijv., hosts.ini) en schrijf eenvoudige playbook die taak direct bevatten. Gebruik groepsvariabelen en hostvariabelen om configuraties op te slaan.

2. Introduceer rollen lokaal: Naarmate playbooks groeien, extraheer herbruikbare logica in Ansible-rol. Plaats ze in een roles/ directory binnen het Ansible-inventarisproject voor gemakkelijke opname in playbooks.

3. Overgang naar collecties: Zodra rollen volwassen zijn, creëer een apart Ansible-collecties project. Verplaats rollen naar de structuur van de collectie (bijv., roles/ binnen de collectie). Zet een dedicated release-pipeline op (bijv. via GitLab CI/CD) om versies te publiceren naar Ansible Galaxy of een privé-repository, gescheiden van de Ansible-inventarisproject’s GitOps pipeline.

4. Centraliseer rolontwikkeling: Verplaats alle rolontwikkeling naar het collectie project(en). Verwijder de roles/ directory uit het Ansible-inventarisproject, en verwijs in plaats daarvan naar gepubliceerde collecties via requirements.yml.

5. Optimaliseer met uitvoeringsomgevingen: Voor verdere efficiëntie, creëer een Uitvoeringsomgeving project om Python, Ansible Core, en afhankelijkheden in een containerimage te verpakken. Vorder in stappen:

   • Start met alleen de Python en Ansible runtime.
   • Voeg community-collecties toe.
   • Neem je eigen collecties op. Dit zorgt voor consistente, geïsoleerde uitvoeringen, vooral in Ansible Automation Platform opzetten.

   Opmerking: Het integreren van aangepaste uitvoeringsomgevingen kan pure GitOps workflows uitdagen. Voor oplossingen, raadpleeg de volgende informatie

   • GitOps Pipeline voor een Execution Environment (EE) met Ansible Collections

Neem Git-repositories aan voor elk projecttype, gebruik merge request voor wijzigingen en zorg ervoor dat documentatie Ansible-standaarden volgt.

Voordelen

• Schaalbaarheid: Start eenvoudig en voeg complexiteit toe als nodig, vermijd het overweldigen van beginners.
• Herbruikbaarheid: Collecties maken het delen van inhoud over projecten en teams mogelijk, reducerend duplicatie.
• Efficiëntie: Gescheiden pipelines voor releases en uitrollen stroomlijnen workflows.
• Consistentie: Uitvoeringsomgevingen zorgen voor reproduceerbare runs, minimaliserend afhankelijkheidsproblemen.
• Samenwerking: Gestructureerde projecten faciliteren teamwork in overheids- settings met versiecontrole en duidelijke richtlijnen.

Alternatieven (optioneel)

Hoewel standalone Ansible-rol projecten bestaan, zijn ze verouderd ten gunste van collecties voor betere organisatie en versiebeheer. Vermijd het verspreiden van inhoud over ongestructureerde repositories; consolideer in plaats daarvan in dedicated projecttypen voor onderhoudbaarheid.

Voorbeelden en implementatie

Voorbeeldstructuur van inventarisproject

In het Ansible-inventarisproject voor C2 Platform  c2platform/c2/ansible-inventory is er een roles directory die een bestand requirements.yml bevat. Dit bestand wordt gebruikt door Ansible Automation Platform om Ansible-rol te downloaden van Ansible Galaxy

 roles/requirements.yml

---
- src: ajsalminen.hosts
# version: N.A.
- src: arillso.logrotate
  version: 1.6.1
- src: geerlingguy.apache
  version: 3.2.0
- src: geerlingguy.git
  version: 3.0.0
- src: galaxyproject.postgresql
  version: 1.1.0
- src: geerlingguy.docker
  version: 4.2.2
- src: lean_delivery.weblogic
  version: 1.0.0
- src: racqspace.microk8s
  version: 2.2.1
- src: geerlingguy.gitlab
  version: 3.2.0
- src: robertdebock.gitlab_runner
  version: 5.1.4

Je kunt Ansible-rollen creëren binnen deze directory. Creëer bijvoorbeeld een nieuwe Ansible-rol my_local_role. Neem het dan op in een voorbeeld-playbook (bijv. plays/site.yml):

Voor meer informatie over het opzetten van het Ansible-inventarisproject raadpleeg:

• Ansible-inventarisproject: Een gestructureerde verzameling bestanden die worden gebruikt voor het beheren van hosts en configuraties. Het omvat doorgaans inventarisbestanden, playbooks, hostconfiguraties, groepsvariabelen en Ansible Vault-bestanden.

Overgang naar een collectie

Raadpleeg de C2 Platform Core-collectie  c2platform.core voor een voorbeeld. Het bevat bijvoorbeeld de Linux-rol  c2platform.core.linux. Deze Core-collectie bevat een GitLab CI/CD-pipeline die publiceert naar Galaxy, zoals je kunt zien in het voorbeeld hieronder.

 .gitlab-ci.yml

82
83publish:
84  stage: galaxy
85  needs: [prepare, build, yamllint, ansible-lint]
86  script:
87    - cat README-GALAXY.md > README.md  # readme property in galaxy.yml is ignored by galaxy website
88    - ansible-galaxy collection build . --force
89    - ansible-galaxy collection publish $C2_NAMESPACE-$C2_NAME-$C2_VERSION.tar.gz --api-key $GALAXY_API_KEY
90  when: manual

In het Ansible-inventarisproject voor C2 Platform  c2platform/c2/ansible-inventory is er ook een collections/requirements.yml bestand, dat een afhankelijkheid bevat op de Core-collectie.

 collections/requirements.yml

1---
2collections:
3  - name: c2platform.core
4    version: 1.0.24  # TODO 1.0.25

Voorbeeld van uitvoeringsomgeving

Raadpleeg het volgende voor meer informatie:

• Beheer van de RWS Ansible Uitvoeringsomgeving: Deze handleiding biedt stapsgewijze instructies over hoe de RWS Ansible Uitvoeringsomgeving te beheren, waarbij compatibiliteit met de nieuwste versies van Python en Ansible wordt gewaarborgd, samen met de vereiste Ansible-collecties.
• GitOps Pipeline voor een Execution Environment (EE) met Ansible Collections: Leer hoe je een GitOps Pipeline kunt realiseren met een EE die Ansible Collections bevat.

Aanvullende informatie

• Ansible Projecten: Ansible Inventory, Ansible Collection, Ansible Role en Ansible Execution Environment zijn verschillende soorten projecten gerelateerd aan Ansible. Deze sectie biedt een overzicht van elk projecttype en hun betekenis binnen het Ansible-ecosysteem.
• Ansible-inventarisproject: Een gestructureerde verzameling bestanden die worden gebruikt voor het beheren van hosts en configuraties. Het omvat doorgaans inventarisbestanden, playbooks, hostconfiguraties, groepsvariabelen en Ansible Vault-bestanden.
• Ansible-mirror-inventarisproject: Een open-source gespecialiseerd Ansible-inventarisproject dat Vagrant-functionaliteit integreert om real-world infrastructuur lokaal te simuleren voor ontwikkeling en testen.
• Ansible-collectieproject: Een Ansible Collectieproject is een uitgebreide eenheid die modules, plugins, rollen en documentatie combineert om de automatiseringstaal te verbeteren en infrastructuren te beheren. Het dient als een herbruikbaar en verspreidbaar pakket van Ansible-inhoud.
• Ansible-uitvoeringsomgevingproject: Het Ansible Execution Environment-project biedt een gestandaardiseerde omgeving voor het uitvoeren van Ansible playbooks en rollen.
• Ansible-rolproject (verouderd): Een Ansible Rol project is een gestructureerde en herbruikbare verzameling van taken, variabelen en configuraties die specifieke functionaliteit bieden.
• Beheer van de RWS Ansible Uitvoeringsomgeving: Deze handleiding biedt stapsgewijze instructies over hoe de RWS Ansible Uitvoeringsomgeving te beheren, waarbij compatibiliteit met de nieuwste versies van Python en Ansible wordt gewaarborgd, samen met de vereiste Ansible-collecties.
• GitOps Pipeline voor een Execution Environment (EE) met Ansible Collections: Leer hoe je een GitOps Pipeline kunt realiseren met een EE die Ansible Collections bevat.