Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 2. Vault integration

2.1. About the Vault integration
Copy link

The integration of Red Hat Ansible Automation Platform and IBM HashiCorp Vault provides fully automated lifecycle management for Vault.

2.1.1. Introduction
Copy link

Vault lets you centrally store and manage secrets securely. The Ansible Automation Platform certified hashicorp.vault collection provides fully automated Key/Value V1 and V2 (KV1 and KV2) secret lifecycle management for Vault. You can create, update, and delete secrets through playbooks.

  • Existing community.hashi_vault users: The hashicorp.vault solution is intended to replace unsupported community.hashi_vault collection. Use the migration path to keep your existing playbooks. For more information about migrating, see Migrating from community.hashi_vault.
  • New Vault users: The hashicorp.vault collection is included in the supported execution environment from automation hub.
Note

Although the hashicorp.vault and hashi.terraform collections work independently of each other and are designed for different tasks, you can use them together in advanced workflows.

2.2. Authenticating to hashicorp.vault
Copy link

After you install or migrate to the hashicorp.vault collection, authentication is configured in the Ansible Automation Platform user interface. An administrator creates a custom credential type to authenticate to Vault. Users create credentials (based on the credential type) to use with job templates in Ansible Automation Platform.

2.2.1. Authentication architecture
Copy link

The hashicorp.vault collection manages authentication through environment variables and client initialization. This approach enhances security by preventing sensitive credentials from being passed directly as module parameters within playbook tasks.

The hashicorp.vault collection injects credentials into job templates with environment variables, so you get simpler, cleaner task definitions while ensuring that authentication details remain secure.

The following authentication types are supported:

  • appRole authentication: Use either one of the following methods when using appRole authentication:

    • Set the VAULT_APPROLE_ROLE_ID and VAULT_APPROLE_SECRET_ID environment variables. When you use environment variables, you must also create a custom credential type and credentials that will be passed to the job template.

    • Directly pass the role_id and secret_id parameters to the tasks, for example: 

      - name: Create a secret with AppRole authentication
  hashicorp.vault.kv2_secret:
    url: https://vault.example.com:8200
    auth_method: approle
    role_id: "{{ vault_role_id }}"
    secret_id: "{{ vault_secret_id }}"
    path: myapp/config
    data:
      api_key: secret-api-key
      Copy to Clipboard Toggle word wrap

  • Token authentication: Set the VAULT_TOKEN environment variable.

    Optionally, you can configure parameters for the token. If parameters are not provided, then the module uses environment variables.

2.2.2. Creating a custom credential type
Copy link

As an admin, you create a secure credential type in Ansible Automation Platform, which is used to authenticate to Vault.

You can configure role-based (appRole) authentication or allow users to directly provide a token.

Prerequisites

Do one of the following:

  • New users: Install the Ansible Automation Platform certified hashicorp.vault collection from Automation hub.
  • community.hashi_vault collection users: Migrate from community.hashi_vault. For more information, see Migrating from community.hashi_vault.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation Execution Infrastructure Credential Types.
  3. Click Create a credential type. The Create Credential Type page opens.
  4. Enter a name and a description in the corresponding fields.

  5. If you want to configure token authentication for individual users:

    1. For Input configuration, enter: 

      fields:
 - id: vault_token
   type: string
   label: Hashicorp Vault Token
   secret: true
      Copy to Clipboard Toggle word wrap

    2. For Injector configuration, enter: 

      env:
   VAULT_TOKEN: '{{ vault_token }}'
      Copy to Clipboard Toggle word wrap

  6. If you want to configure appRole authentication using role_id and secret_id:

    1. For Input configuration, enter: 

      fields:
  - id: vault_approle_role_id
    type: string
    label: Hashicorp Vault appRole Role ID
    secret: true
  - id: vault_approle_secret_id
    type: string
    label: Hashicorp Vault appRole Secret ID
    secret: true
      Copy to Clipboard Toggle word wrap

    2. For Injector configuration, enter: 

      env:
    VAULT_APPROLE_ROLE_ID: '{{ vault_approle_role_id }}'
    VAULT_APPROLE_SECRET_ID: '{{ vault_approle_secret_id }}'
      Copy to Clipboard Toggle word wrap
  7. Click Create credential type.

Next step

Additional resources

2.2.3. Creating a custom credential
Copy link

Vault users must create a custom credential to use with job templates in Ansible Automation Platform.

Prerequisite

  • Your administrator has created a Vault credential type.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation Execution Infrastructure Credentials, and then select Create credential.
  3. Enter a name and a description in the corresponding fields.
  4. (Optional) From the Organization list, select an organization.
  5. From the Credential type list, select a Vault credential type. The fields that display depend on the credential type.

  6. Do one of the following:

    1. For the token authentication, add your Vault token and edit any fields as needed.
    2. For the appRole authentication method, enter the IDs in the appRole Role ID and appRole Secret ID fields. Edit any other fields as needed.
  7. Click Save credential. You are ready to use the credential in a job template.

2.3. Migrating from community.hashi_vault
Copy link

If you are using the community.hashi_vault collection, you can migrate your existing playbooks to the hashicorp.vault collection.

2.3.1. Configuring KV1 modules
Copy link

If you are using KV1 with community.hashi_vault collection, configure the corresponding modules in the hashicorp.vault collection.

Configuring this module is not required for migration because there are no corresponding modules in community.hashi_vault. However, you might want to configure something other than the defaults for auth_method and state after the migration. You can use the examples on Ansible automation hub for reference.

The hashicorp.vault.kv1_secret_info module reads KV1 secrets.

The corresponding community.hashi_vault modules are:

  • community.hashi_vault.vault_kv1_get: Retrieves secrets from the HashiCorp Vault KV version 1 secret store.
  • community.hashi_vault.vault_kv1_get lookup: Retrieves secrets from the HashiCorp Vault KV version 1 secret store.

Procedure

  1. Replicate the community.hashi_vault modules to the following hashicorp.vault.kv1_secret_secret_info parameters. 

      engine_mount_point:
    description: KV secrets engine mount point.
    default: secret
    type: str
    aliases: [secret_mount_path]
  path:
    description:
      - Specifies the path of the secret.
    required: true
    type: str
    aliases: [secret_path]
extends_documentation_fragment:
  - hashicorp.vault.vault_auth.modules
    Copy to Clipboard Toggle word wrap
  2. (Required) Configure the path parameter. This is the path to the secret in the community.hashi_vault.hashi_vault modules. Alias: secret_path
  3. If needed, configure the optional parameters.

Next step

The hashicorp.vault.kv1_secret_get lookup plugin module reads KV1 secrets.

The corresponding community.hashi_vault modules are:

  • community.hashi_vault.hashi_vault: Retrieves secrets from HashiCorp Vault.
  • community.hashi_vault.vault_kv1_get lookup: Gets secrets from the HashiCorp Vault KV version 1 secret store.

Procedure

  1. Replicate the community.hashi_vault modules to the following hashicorp.vault.kv1_secret_get parameters. 

    auth_method:
  description: Authentication method to use.
  choices: ['token', 'approle']
  default: token
  type: str
engine_mount_point:
  description:
    - The KV secrets engine mount point.
  default: secret
  type: str
  aliases: ['mount_point', 'secret_mount_path']
secret:
  description:
    - The Vault path to the secret being requested.
  required: true
  type: str
  aliases: ['secret_path']
    Copy to Clipboard Toggle word wrap
  2. (Required) Configure the secret parameter. This maps to secret in the community.hashi_vault.hashi_vault modules. Alias: secret_path
  3. If needed, configure the optional parameters.

Next step

The following example shows before and after configurations for the hashicorp.vault.kv1_secret_info module.

Example:

Before (community.hashi_vault) 

- name: Read a kv1 secret from Vault (community collection)
  community.hashi_vault.vault_kv1_get:
    url: https://vault:8201
    token: "{{ vault_token }}"
    path: hello
  register: response
Copy to Clipboard Toggle word wrap

After (hashicorp.vault) 

- name: Read a kv1 secret from Vault (hashicorp.vault collection)
  hashicorp.vault.kv1_secret_info:
    url: https://vault.example.com:8201
    token: "{{ vault_token }}"
    path: sample
Copy to Clipboard Toggle word wrap

The following example shows the KV1 secret get lookup.

Example:

Before (community.hashi_vault) 

- name: Retrieve a secret from the Vault
  ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.vault_kv1_get', 'hello', url='https://vault:8201') }}"
Copy to Clipboard Toggle word wrap

After (hashicorp.vault) 

- name: Retrieve a secret from the Vault
  ansible.builtin.debug:
    msg: "{{ lookup('hashicorp.vault.kv1_secret_get',
                    secret='hello',
                    url='https://myvault_url:8201') }}"
Copy to Clipboard Toggle word wrap

2.3.2. Configuring KV2 modules
Copy link

If you are using KV2 with community.hashi_vault collection, configure the corresponding modules in the hashicorp.vault collection.

The hashicorp.vault.kv2_secret module performs Create, Update, and Delete (CRUD) operations on KV2 secrets through a unified interface.

The corresponding community.hashi_vault modules are:

  • community.hashi_vault.vault_kv2_write - Write KV2 secrets.
  • community.hashi_vault.vault_kv2_delete - Delete KV2 secrets.

Prerequisites

  • Install the Ansible Automation Platform certified hashicorp.vault collection.

Procedure

  1. Replicate your automation tasks from both of the community.hashi_vault modules to the following hashicorp.vault.kv2_secret parameters. The hashicorp.vault.kv2_secret parameters are similar to community.hashi_vault. 

    auth_method:
 description: Authentication method to use
 type: str
 choices: [token, approle]
 default: token
 required: false

cas:
 description: Perform a check-and-set operation.
 type: int
 required: false

data:
 description: KV2 secret data to write.
 type: dict
 required: true

engine_mount_point:
 description: The path where the secret backend is mounted.
 type: str
 default: secret
 required: false
 aliases: [secret_mount_path]

namespace:
 description: Vault namespace where secrets reside.
 type: str
 default: admin
 aliases: [vault_namespace]

path:
 description: Vault KVv2 path to be written to.
 type: str
 required: true
 aliases: [secret_path]

url:
 description: URL of the Vault service
 type: str
 aliases: [vault_address]
 required: true

versions:
 description: One or more versions of the secret to delete.
 type: list of int
 required: false

state:
 description: Desired state of the secret
 type: str
 choices: [present, absent]
 default: present
    Copy to Clipboard Toggle word wrap

  2. You must add the state parameter to the hashicorp.vault.kv2_secret module, as shown above. Valid options are:

    • present: This is the equivalent of create or update in the community.hashi_vault.vault_kv2 modules.
    • absent: This is the equivalent of delete secret in the community.hashi_vault.vault_kv2 modules.

Next step

The hashicorp.vault.kv2_secret_info module reads KV2 secrets.

The corresponding community.hashi_vault module is:

  • community.hashi_vault.vault_kv2_get: Gets secrets from the HashiCorp Vault KV version 2 secret store.

Procedure

  1. Replicate the community.hashi_vault modules to the following hashicorp.vault.kv2_secret_info parameters. 

      engine_mount_point:
    description: KV secrets engine mount point.
    default: secret
    type: str
    aliases: [secret_mount_path]
  path:
    description: Path to the secret.
    required: true
    type: str
    aliases: [secret_path]
  version:
    description: The version to retrieve.
    type: int
extends_documentation_fragment:
  - hashicorp.vault.vault_auth.modules
    Copy to Clipboard Toggle word wrap

  2. Configure the required parameters:

    • path: The path where the secret is located in the community.hashi_vault.hashi_vault modules. Alias: secret_path
    • url: Maps to url in the community.hashi_vault.hashi_vault modules. Uses the same aliases as vault_address.
  3. If needed, configure the optional parameters.

Next step

The hashicorp.vault.kv2_secret_get lookup plugin module reads KV2 secrets.

The corresponding community.hashi_vault modules are:

  • community.hashi_vault.hashi_vault: Retrieves secrets from HashiCorp Vault.
  • community.hashi_vault.vault_kv2_get lookup: Gets secrets from the HashiCorp Vault KV version 2 secret store.

Procedure

  1. Replicate the community.hashi_vault modules to the following hashicorp.vault.kv2_secret_get parameters. 

    auth_method:
 description: Authentication method to use
 type: str
 choices: [token, approle]
 default: token
 required: false

mount_point:
 description: Vault mount point
 type: str
 required: false
 aliases: [secret_mount_path]

namespace:
 description: Vault namespace where secrets reside.
 type: str
 default: admin
 aliases: [vault_namespace]
secret:
 description: Vault path to the secret being requested in the format path[:field]
 type: str
 required: true
 aliases: [secret_path]

url:
 description: URL of the Vault service
 type: str
 aliases: [vault_address]
 required: true

version:
 description: Specifies the version to return. If not set the latest is returned.
 type: int
 required: false
    Copy to Clipboard Toggle word wrap

  2. Use the following guidance to configure the hashicorp.vault.kv2_secret_get parameters:

    • auth_method: Maps identically to auth_method in the community.hashi_vault.hashi_vault modules.
    • mount_point: Maps to mount_point in the community.hashi_vault.hashi_vault modules. Alias: secret_mount_path.
    • namespace: Maps to namespace in the community.hashi_vault.hashi_vault modules. Alias: vault_namespace.
    • secret: Maps to secret in the community.hashi_vault.hashi_vault modules.
    • url: Maps to url in the community.hashi_vault.hashi_vault modules. Uses the same aliases as vault_address.
    • version: Maps identically to version in the community.hashi_vault.hashi_vault modules.

Next step

The following examples show basic before and after configurations for the hashicorp.vault.kv2_secret module.

Note

KV2 delete operations are soft-delete.

Example 1: Basic Secret Write/Create

Before (community.hashi_vault): 

- name: Write/create a secret
  community.hashi_vault.vault_kv2_write:
    url: https://vault:8200
    path: hello
    data:
      foo: bar
Copy to Clipboard Toggle word wrap

After (hashicorp.vault): 

- name: Write/create a secret
  hashicorp.vault.kv2_secret:
    url: https://vault:8200
    path: hello
    data:
      foo: bar
Copy to Clipboard Toggle word wrap

Example 2: Basic Secret Delete

Before (community.hashi_vault): 

- name: Delete the latest version of the secret/mysecret secret.
  community.hashi_vault.vault_kv2_delete:
    url: https://vault:8201
    path: secret/mysecret
Copy to Clipboard Toggle word wrap

After (hashicorp.vault): 

- name: Delete the latest version of the secret/mysecret secret.
  hashicorp.vault.kv2_secret:
    url: https://vault:8201
    path: secret/mysecret
    state: absent
Copy to Clipboard Toggle word wrap

Example 3: Secret Delete - specific version

Before (community.hashi_vault): 

- name: Delete versions 1 and 3 of the secret/mysecret secret.
  community.hashi_vault.vault_kv2_delete:
    url: https://vault:8201
    path: secret/mysecret
    versions: [1, 3]
Copy to Clipboard Toggle word wrap

After (hashicorp.vault): 

- name: Delete versions 1 and 3 of the secret/mysecret secret.
  hashicorp.vault.kv2_secret:
    url: https://vault:8201
    path: secret/mysecret
    versions: [1, 3]
    state: absent
Copy to Clipboard Toggle word wrap

The following examples show before and after configurations for the hashicorp.vault.kv2_secret_info module.

Example 1: Read a secret with token authentication

Before (community.hashi_vault) 

- name: Read the latest version of a kv2 secret from Vault  community.hashi_vault.vault_kv2_get:
    url: https://vault.example.com:8200
    token: "{{ vault_token }}"
    path: myapp/config
  register: response
Copy to Clipboard Toggle word wrap

After (hashicorp.vault) 

- name: Read a secret with token authentication
  hashicorp.vault.kv2_secret_info:
    url: https://vault.example.com:8200
    token: "{{ vault_token }}"
    path: myapp/config
Copy to Clipboard Toggle word wrap

Example 2: Read a secret with a specific version

Before (community.hashi.vault) 

- name: Read version 5 of a secret from kv2
  community.hashi_vault.vault_kv2_get:
    url: https://vault.example.com:8200
    path: myapp/config
    version: 5
Copy to Clipboard Toggle word wrap

After (hashicorp.vault) 

- name: Read a secret with a specific version
  hashicorp.vault.kv2_secret_info:
    url: https://vault.example.com:8200
    path: myapp/config
    version: 1
Copy to Clipboard Toggle word wrap

The following example shows the KV2 secret get lookup for retrieving the latest version.

Example:

Before (community.hashi_vault) 

- name: Return latest KV v2 secret from path
  ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.hashi_vault', 'secret=secret/data/hello
  token=my_vault_token
  url=http://myvault_url:8200') }}"
Copy to Clipboard Toggle word wrap

After (hashicorp.vault) 

name: Return latest KV v2 secret from path
  ansible.builtin.debug:
    msg: "{{ lookup('hashicorp.vault.kv2_secret_get', 'secret=secret/data/hello
  url=http://myvault_url:8200') }}"
Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat