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.

Projecten: c2platform/ansible , c2platform.core

Probleem

Ansible Automation Platform mist 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 inventarisprojecten die Git als basis gebruiken voor AAP / AWX-uitrollen, wat vaak leidt tot updatefouten omdat je geen Ansible Vault-geheim kunt configureren voor zulke projecten.

AAP / AWX vermijdt ingebouwde Vault-ondersteuning om blootstelling van versleutelde geheimen aan platformgebruikers of interfaces te voorkomen. Deze blootstelling zou de vertrouwelijkheid van gevoelige gegevens kunnen compromitteren, omdat gebruikers onbedoeld toegang zouden kunnen krijgen tot ontsleutelde geheimen tijdens job-uitvoering of sjabloonbeheer. Daarom moeten geheimen extern of via aangepaste oplossingen worden beheerd om de beveiliging te behouden.

Context

Het beheren van geheimen is essentieel in Ansible-projecten, en Ansible Vault biedt een standaard, ingebouwde oplossing. Echter, het effectief gebruiken ervan in AAP / AWX vereist specifieke instellingen en overwegingen om compatibiliteit te garanderen.

In Ansible- en automatiseringsprojecten—met name in omgevingen zoals de Nederlandse overheid—is een speciaal hulpmiddel voor geheimenbeheer niet altijd beschikbaar. In zulke gevallen is Ansible Vault een eenvoudige, praktische keuze. Het integreert naadloos met Ansible (geen extra kosten of licenties) en is gemakkelijk te vervangen als een geavanceerdere oplossing later beschikbaar komt.

Oplossing

Om geheimen veilig te beheren in AAP / AWX zonder ingebouwde Vault-ondersteuning, gebruik een aangepaste map voor met Vault versleutelde bestanden en een speciale Ansible-rol om ze dynamisch te laden. Deze aanpak voorkomt het opslaan van geheimen in group_vars, wat synchronisatiefouten kan veroorzaken in inventarisprojecten vanwege het onvermogen om een Vault-wachtwoord te verstrekken.

Volg deze richtlijnen:

  1. Maak een Aangepaste Map voor Geheimen: Vermijd de standaard group_vars-map, omdat deze niet betrouwbaar werkt met AAP / AWX (je kunt geen Vault-wachtwoord opgeven aan inventarisprojecten. Maak in plaats daarvan een map genaamd secret_vars om met Vault versleutelde bestanden in op te slaan. Deze naamconventie is intuïtief en helpt teams het doel ervan te begrijpen.

  2. Ontwikkel een Ansible “Secrets”-Rol: Bouw een generieke rol (bijv. c2platform.core.secrets) die geheimen laadt uit secret_vars met taken zoals include_vars. Zorg ervoor dat de rol flexibel is voor zowel Ansible CLI- als AAP / AWX-omgevingen. Configureer deze met een lijst zoals secrets_dirs om meerdere locaties te ondersteunen.

  3. Gebruik Vault in de Ontwikkeling: Begin met het gebruik van Ansible Vault zelfs in ontwikkelomgevingen. Voor open-source setups (bijv. met eenvoudige wachtwoorden zoals secret), neem vereiste wachtwoorden vroegtijdig op in de vault. Dit identificeert noodzakelijke geheimen voor andere omgevingen zonder de beveiliging in gevaar te brengen.

  4. Stel een Procedure in voor het Bijwerken van de Vault: Om mergeconflicten te voorkomen (aangezien Git versleutelde bestanden niet kan mergen), dwing een teambrede branching-procedure af:

    • Maak een tijdelijke branch (bijv. vault) vanaf de laatste master.
    • Werk geheimen bij in secret_vars op deze branch.
    • Merge onmiddellijk terug naar master via een merge-commit.
    • Synchroniseer naar omgevingsspecifieke branches (bijv. test) indien nodig.
  5. Los Mergeconflicten Lokaal Op: Als conflicten optreden (bijv. door schendingen van het proces), los ze handmatig op:

    • Clone de conflicterende branch lokaal.
    • Ontsleutel en vergelijk vault-inhoud van je branch en master met een diff-tool.
    • Maak een opgeloste versie, versleutel deze terug in de vault.
    • Haal de laatste wijzigingen op, commit en push om het conflict op te lossen.

Deze methode zorgt voor beveiliging, voorkomt accidentele blootstelling en behoudt compatibiliteit over omgevingen heen. Alleen geautoriseerde gebruikers mogen vault-operaties uitvoeren, met wachtwoorden veilig beheerd.

Voordelen

  • Verbetert de beveiliging door geheimen te isoleren en blootstelling in AAP / AWX-interfaces te vermijden.
  • Verbetert de onderhoudbaarheid van het project door mergeconflicten te voorkomen met gestructureerde procedures.
  • Biedt flexibiliteit voor zowel CLI- als platformgebaseerde workflows zonder afhankelijkheid van ingebouwde Vault-ondersteuning.
  • Vereenvoudigt onboarding, omdat de secret_vars-conventie duidelijk en gemakkelijk over te nemen is.

Alternatieven (Optioneel)

Hoewel externe tools zoals HashiCorp Vault of AWS Secrets Manager kunnen worden gebruikt voor geavanceerder geheimenbeheer, wordt Ansible Vault geprefereerd vanwege zijn eenvoud en zero-cost integratie in omgevingen zonder speciale tools. Het dient als een opstap die gemakkelijk te migreren is later.

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.15: Merge branch 'master' into phx (f4ae99a)