Geheimen Beheren met Ansible Vault in AAP / AWX

Richtlijn voor het beheren van geheimen met behulp van Ansible Vault in Ansible-projecten, met een focus op Ansible Automation Platform (AAP) en AWX.

Probleem

Ansible Automation Platform (AAP)/AWX heeft geen ingebouwde ondersteuning voor Ansible Vault  , wat uitdagingen met zich meebrengt bij het integreren van met Vault versleutelde bestanden in de group_vars-map. Deze beperking beïnvloedt inventarisatieprojecten die Git als basis gebruiken voor AAP / AWX-uitrollen, wat leidt tot updatefouten door het onvermogen om een Ansible Vault-geheim voor zulke projecten te configureren. Het is essentieel om dit probleem aan te pakken en een oplossing te vinden.

Context

Het beheren van geheimen is een kritieke taak in Ansible-projecten, en Ansible Vault biedt een standaard en eenvoudige oplossing. Echter, het effectief gebruiken van Ansible Vault binnen de context van AAP / AWX vereist specifieke instellingen en overwegingen.

In Ansible- en automatiseringsprojecten, met name in omgevingen zoals de Nederlandse overheid, is een speciaal hulpmiddel voor geheimenbeheer niet altijd direct beschikbaar. In zulke gevallen is Ansible Vault een eenvoudige en praktische keuze. Het is geen punt van no return, omdat Ansible Vault is ingebouwd in Ansible (zonder extra kosten of licenties) en eenvoudig genoeg is om te vervangen als een geavanceerdere oplossing voor geheimenbeheer later beschikbaar komt.

Oplossing

Een Aangepaste Map voor Geheimen Gebruiken

De kern van de oplossing is om te voorkomen dat geheimen worden opgeslagen in de standaard group_vars-map. Deze aanpak werkt alleen betrouwbaar met de Ansible CLI en niet met AAP / AWX, omdat je geen Vault-wachtwoord kunt opgeven aan het inventarisatieproject in AAP / AWX—en deze beperking is opzettelijk. Als gevolg daarvan zal het synchroniseren van een inventarisatieproject dat een group_vars-map met Vault-versleutelde bestanden bevat, mislukken vanwege het ontbrekende Vault-wachtwoord. Het is niet mogelijk om een Vault-wachtwoord direct op een inventarisatieproject te configureren, wat helpt om accidentele blootstelling van geheimen te voorkomen.

Maak in plaats daarvan een aparte map om deze geheimen op te slaan. In het C2 Platform gebruiken we de conventie om deze map secret_vars te noemen. Deze naam is intuïtief en duidelijk, waardoor het gemakkelijk is voor teams om het doel ervan te begrijpen. Door Vault-versleutelde bestanden naar secret_vars te verplaatsen, omzeil je de beperkingen van AAP / AWX-inventarisatieprojecten terwijl je nog steeds Ansible Vault gebruikt voor versleuteling. Deze map kan vervolgens dynamisch worden geladen met Ansible-taken, zoals include_vars, in een aangepaste rol. Dit zorgt voor compatibiliteit in CLI- en AAP / AWX-omgevingen zonder de beveiliging in gevaar te brengen.

Ansible Secrets-Rol

Ontwikkel een generieke en flexibele Ansible “Secrets”-rol die de secret_vars-map kan gebruiken. Deze rol moet compatibel zijn met zowel AAP als de Ansible CLI. Maak een aangepaste map genaamd secret_vars aan om geheimen in op te slaan die kunnen worden opgenomen met include_vars. Deze map dient als alternatief voor het opslaan van geheimen in de standaard group_vars-map.

Start in de Ontwikkeling

Naast de bovenstaande oplossing wordt aanbevolen om Ansible Vault ook tijdens de ontwikkeling te gebruiken, omdat het beheren van geheimen integraal deel uitmaakt van inventarisatieprojecten.

Bijvoorbeeld, in de aanpak van het C2 Platform is de primaire ontwikkelomgeving open source, en wachtwoorden worden eenvoudig gehouden voor gemak—meestal altijd secret, of Supersecret! als het hulpmiddel sterkere wachtwoorden vereist. Aangezien alle wachtwoorden open zijn en niet veilig hoeven te zijn (omdat alles open source en open data is), wordt een vault nog steeds gebruikt tijdens het ontwikkelproces. Dit komt omdat ontwikkeling typisch identificeert welke wachtwoorden nodig zijn. Door ze onmiddellijk in de vault op te nemen, wordt het duidelijk voor andere omgevingen welke wachtwoorden vereist zijn.

Zelfs als de ontwikkelomgeving gemakkelijk te onthouden wachtwoorden gebruikt, zoals de praktijk binnen de ontwikkelomgeving van het C2 Platform, wordt Ansible Vault nog steeds gebruikt.

Bied een Procedure voor het Bijwerken van de Vault

Het belangrijkste punt hier is om ervoor te zorgen dat het hele team zich bewust is van het feit dat de vault een versleuteld bestand is en dat Git versleutelde bestanden niet kan mergen. Dus, zonder een procedure waar het hele team van op de hoogte is, zal dit mergeconflicten veroorzaken die erg moeilijk en tijdrovend zijn om op te lossen. Het voorkomen van mergeconflicten is essentieel, en de onderstaande procedure helpt daarbij.

Om mergeconflicten te voorkomen bij het wijzigen van geheimen in de vault, introduceer een aanbevolen branching-procedure voor het project, vergelijkbaar met:

  1. Maak een tijdelijke branch genaamd vault aan vanaf de laatste commit van de master-branch. Dit zorgt ervoor dat je werkt op de meest actuele versie zonder lopend werk te beïnvloeden.
  2. Voeg de geheimen toe of werk ze bij in de secret_vars-map op deze vault-branch. Gebruik Ansible Vault om te versleutelen of opnieuw te versleutelen indien nodig.
  3. Merge de vault-branch onmiddellijk terug in master met een merge-commit. Dit integreert de wijzigingen snel en minimaliseert de kans op conflicten.
  4. Als de geheimen bedoeld zijn voor een specifieke omgeving (bijv. test), synchroniseer dan de bijgewerkte master-branch naar de omgevingsbranch (bijv. test) via een merge of rebase, afhankelijk van je Git-workflow.

Dit proces isoleert updates van geheimen, waardoor het risico op conflicten door parallelle wijzigingen in andere branches wordt verminderd. Zorg er altijd voor dat alleen geautoriseerde gebruikers vault-operaties uitvoeren en dat vault-wachtwoorden veilig worden beheerd.

Mergeconflicten in de Vault Oplossen

In gevallen waarin mergeconflicten optreden in de vault—vaak vanwege accidentele wijzigingen buiten de aanbevolen procedure (bijv. iemand wijzigt de vault op een feature-branch, in strijd met het proces)—moeten ze handmatig en lokaal worden opgelost. Dit kan niet via de GitLab-webinterface. Volg in plaats daarvan deze procedure om het conflict lokaal op te lossen:

  1. Clone de branch met het conflict lokaal.
  2. Om op te lossen, ontsleutel en vergelijk de vault-inhoud handmatig:
    • Op je branch, ontsleutel het vault-bestand en sla de inhoud op in een tijdelijk lokaal bestand (bijv. temp_mybranch.yml).
    • Schakel over naar de master-branch, ontsleutel het vault-bestand en sla de inhoud op in een ander tijdelijk bestand (bijv. temp_master.yml).
    • Gebruik een diff-tool om temp_mybranch.yml en temp_master.yml te vergelijken. Maak handmatig een opgeloste versie van de vault-inhoud op basis van de diff.
  3. Haal nu de laatste wijzigingen van master op en pull ze in je lokale branch. Dit activeert het mergeconflict lokaal.
  4. Versleutel de opgeloste inhoud terug in het vault-bestand op je branch.
  5. Commit de wijzigingen en push de branch.
  6. Nu zou de merge request of pull naar master moeten slagen zonder conflicten.

Deze methode zorgt ervoor dat conflicten veilig worden afgehandeld zonder geheimen bloot te stellen. Benadruk aan het team het belang van het volgen van de updateprocedure om zulke situaties te vermijden.

Voorbeelden en implementatie

Raadpleeg de Ansible “Secrets”-rol c2platform.core.secrets  binnen de c2platform.core collectie voor een implementatievoorbeeld. Deze vault wordt opgenomen via include_vars in deze rol:

 roles/secrets/tasks/main.yml

20    - name: Include secrets
21      ansible.builtin.include_vars:
22        dir: "{{ secrets_dir_item['secrets_dir_item'] }}"
23      loop: >-
24        {{ secrets_dirs_stats['results']
25        | selectattr('stat.exists', 'equalto', True) }}        
26      loop_control:
27        label: "{{ secrets_dir_item['secrets_dir_item'] }}"
28        loop_var: secrets_dir_item
29      when: secrets_dir_item.stat.exists

De rol maakt gebruik van de secrets_dirs-lijst, die kan worden geconfigureerd met meerdere locaties voor de secret_vars-map. Het volgende voorbeeld werkt voor zowel de Ansible CLI als AAP / AWX. Bij gebruik van AAP plaatst AAP de vault op de specifieke locatie, bijvoorbeeld /runner/project/secret_vars/development. Bij het testen van Ansible-playbooks op een Ansible-ontwikkeldesktop, wordt de vault gevonden door de secrets-rol in secret_vars/development.

 group_vars/all/secrets.yml

1---
2secrets_dirs:
3  - "{{ inventory_dir }}/secret_vars/{{ px_env }}"
4  - "/runner/project/secret_vars/{{ px_env }}"  #  awx / aap

Aanvullende Informatie



Laatst gewijzigd 2025.09.05: guidelines using alert C2-872 (41b9396)