How-to

Use this when automation must create, update, archive, or delete IdM vaults through an explicit module surface.

Boundary: Mutating
Authority: idm, collection, ansible
Evidence: command-output

Manage IdM vault lifecycle

When To Use This

Use this when automation must create, update, archive, or delete IdM vaults through an explicit module surface.

Required Authority

IdM owns vault state. The module changes vault lifecycle only when invoked with the requested state.

Safety Boundary

This workflow is mutating. Confirm that this is the intended boundary before placing it in a scheduled job or AAP workflow.

Secret Handling

Do not print payload material. Use no_log: true on payload-bearing tasks. Review artifacts should redact secret values, and payload manifest rendering should be opt-in.

Inputs

Vault name, scope, and type
IdM credentials allowed to manage vaults
Check-mode plan for review before mutation

Steps

Run the module in check mode with the intended state.
Review the predicted change and member changes.
Run without check mode only after the requested lifecycle action is clear.

- name: Ensure shared application vault exists
  eigenstate.ipa.vault_write:
    name: app-db-password
    scope: shared
    state: present
    vault_type: standard
    description: Application database credential
  check_mode: true

Example Vault Lifecycle Playbook

This playbook creates a shared vault if needed, archives a new value, and keeps secret-bearing tasks redacted.

manage-vault.yml

---
- name: Create and archive a shared IdM vault value
  hosts: localhost
  gather_facts: false
  vars:
    ipa_server: idm-01.example.com
    ipa_keytab: /runner/env/ipa/automation.keytab
    new_database_password: "{{ lookup('env', 'NEW_DATABASE_PASSWORD') }}"
  tasks:
    - name: Ensure the shared vault exists
      eigenstate.ipa.vault_write:
        name: database-password
        state: present
        shared: true
        description: Password consumed by database maintenance jobs.
        server: "{{ ipa_server }}"
        kerberos_keytab: "{{ ipa_keytab }}"

    - name: Archive the rotated value
      eigenstate.ipa.vault_write:
        name: database-password
        state: archived
        shared: true
        data: "{{ new_database_password }}"
        server: "{{ ipa_server }}"
        kerberos_keytab: "{{ ipa_keytab }}"
      no_log: true

Run It

export NEW_DATABASE_PASSWORD="$(secret-tool lookup app database-password)"
ansible-playbook manage-vault.yml

Expected Evidence

A captured live validation archived a value, read it back, and classified negative-path failures without exposing payload material. The hash is a sanitized example of the evidence field shape:

{
  "vault_artifact": {
    "read_back_verified": true,
    "missing_failure_class": "vault_not_found",
    "mismatch_failure_class": "digest_mismatch",
    "sha256": "e57691568be539495e554041efba1b046effca98de5b309c275ff1f24f7e06c1"
  }
}

Troubleshooting

Permission denied: verify IdM vault management ACLs.
Archive changed unexpectedly: check vault type and archive semantics.
Member drift: use members and members_absent deliberately.