Akeyless API Collection
A collection of Ansible modules and lookup plugins for interacting with Akeyless.
It allows you to securely manage secrets and access them within your Ansible playbooks.
Requirements
Tested with ansible-core >= 2.16 (AAP 2.7 execution environments) and Python >= 3.11.
Python dependencies for execution environments are declared in requirements.txt
(akeyless, akeyless-cloud-id, cryptography).
Installation
The akeyless.secrets_management collection can be installed with Ansible Galaxy command-line tool:
ansible-galaxy collection install akeyless.secrets_management
On Ansible Automation Platform, install the certified collection from Automation Hub.
Support
If you need assistance with this certified collection, please open a support case via the
Create issue button on the collection page in
Red Hat Automation Hub.
For product documentation, see Akeyless Docs.
For other support requests, contact support@akeyless.io.
Authentication Methods
This plugin supports the following Authentication Methods:
Authentication
API Key
-- name: API Key Authentication
hosts: localhost
tasks:
- name: Get temp token using api_key auth method
akeyless.secrets_management.login:
akeyless_api_url: 'https://api.akeyless.io'
access_type: 'api_key'
access_id: '<Access ID>'
access_key: '<Access Key>'
register: auth_res
AWS
-- name: AWS Authentication
hosts: localhost
tasks:
- name: Get temp token using aws_iam auth method
akeyless.secrets_management.login:
akeyless_api_url: 'https://api.akeyless.io'
access_type: 'aws_iam'
access_id: '<Access ID>'
register: auth_res
Azure
-- name: Azure Authentication
hosts: localhost
tasks:
- name: Get temp token using azure_ad auth method
akeyless.secrets_management.login:
akeyless_api_url: 'https://api.akeyless.io'
access_type: 'azure_ad'
access_id: '<Access ID>'
register: auth_res
GCP
-- name: GCP Authentication
hosts: localhost
tasks:
- name: Get temp token using gcp auth method
akeyless.secrets_management.login:
akeyless_api_url: 'https://api.akeyless.io'
access_type: 'gcp'
access_id: '<Access ID>'
register: auth_res
Universal Identity API modules
These modules mirror the Akeyless CLI Universal Identity operations (uid-generate-token, uid-rotate-token, uid-create-child-token, uid-list-children, uid-revoke-token). Each accepts the standard connection and authentication options, plus the parameters documented on the module.
uid_generate_token — generate a new root token for a Universal Identity auth method.uid_rotate_token — rotate a token, optionally fork a child (fork: true), or use manual ack fields.uid_create_child_token — create a child token from a parent uid_token, or from auth_method_name + uid_token_id with admin JWT.uid_list_children — list the token hierarchy (auth_method_name with JWT, or uid_token as appropriate for your flow).uid_revoke_token — revoke with revoke_token and revoke_type (revokeSelf / revokeAll).
Equivalent lookup plugins exist with the same names for use in Jinja (lookup('namespace.name.uid_generate_token', ...)).
Stored certificate items
Use get_certificate_value to retrieve certificate-type items (stored PEM material via the get-certificate-value API). For issuing a new certificate from a PKI issuer, continue to use get_pki_certificate.
Creating certificate-type items (create-certificate)
create_certificate matches the CLI create-certificate flow: controller-side files via certificate_path / private_key_path, or inline certificate_data / key_data (already base64, like --certificate-data / --key-data), optional PKCS#12 passphrase (requires the cryptography package locally), formatting hints via certificate_format, plus tags, description, expiration_event_in, protection key, and delete_protection. Lookup create_certificate accepts the certificate name/path as its first lookup term.
Examples
Create a Static Secret using Ansible Playbook:
-- name: Create Static Secret
hosts: localhost
tasks:
- name: Get temp token using api_key auth method
akeyless.secrets_management.login:
akeyless_api_url: 'https://api.akeyless.io'
access_type: 'api_key'
access_id: '<Access ID>'
access_key: '<Access Key>'
register: auth_res
- name: create static secret item
akeyless.secrets_management.create_static_secret:
akeyless_api_url: 'https://api.akeyless.io'
name: '/Ansible/MyStaticSecret'
value: "AnsibleSecret"
token: '{{ auth_res.data.token }}'
register: response
Where:
-
name: the name of the Static Secret.
-
value: the value of the Static Secret.
-
type: The Secret type [generic or password].
-
format: The Secret format [text | json | key-value].
Fetch a Static Secret using Ansible Playbook:
-- name: Get secret value
hosts: localhost
tasks:
- name: Get temp token using api_key auth method
akeyless.secrets_management.login:
akeyless_api_url: 'https://api.akeyless.io'
access_type: 'api_key'
access_id: '<Access ID>'
access_key: '<Access Key>'
register: auth_res
- name: Get item secret value by name
akeyless.secrets_management.get_static_secret_value:
akeyless_api_url: 'https://api.akeyless.io'
names: '/Ansible/MyStaticSecret'
token: '{{ auth_res.data.token }}'
register: response
- name: Display the results
debug:
msg: "Secret Value: {{ response.data }}"
Where:
For a full list of the possible actions, press this link.
Dynamic Secret Example
The following will fetch a Dynamic Secret named Ansible/MyDynamicSecret:
```yaml dynamic_secret.yaml
- name: Get secret value
hosts: localhost
tasks:
- name: Get temp token using api_key auth method
akeyless.secrets_management.login:
akeyless_api_url: 'https://api.akeyless.io'
access_type: 'api_key'
access_id: ''
access_key: ''
register: auth_res
- name: Get item secret value by name
akeyless.secrets_management.get_dynamic_secret_value:
akeyless_api_url: 'https://api.akeyless.io'
name: '/Ansible/MyDynamicSecret'
token: '{{ auth_res.data.token }}'
register: response
- name: Display the results
debug:
msg: "Secret Value: {{ response.data }}"
Additional parameters for this module can be found in the [official Ansible Repository](https://github.com/akeylesslabs/akeyless-ansible/blob/main/akeyless_ansible/plugins/modules/get_dynamic_secret_value.py)
## Rotated Secret Example
The following will fetch a [Rotated Secret](https://docs.akeyless.io/docs/rotated-secrets) named `Ansible/MyRotatedSecret`:
```yaml rotated_secret.yaml
- name: Get secret value
hosts: localhost
tasks:
- akeyless.secrets_management.name: Get temp token using api_key auth method
login:
akeyless_api_url: 'https://api.akeyless.io'
access_type: 'api_key'
access_id: '<Access ID>'
access_key: '<Access Key>'
register: auth_res
- name: Get item secret value by name
akeyless.secrets_management.get_rotated_secret_value:
akeyless_api_url: 'https://api.akeyless.io'
name: '/Ansible/MyRotatedSecret'
token: '{{ auth_res.data.token }}'
register: response
- name: Display the results
debug:
msg: "Secret Value: {{ response.data }}"
SSH Certificate Example
The following will issue and fetch an SSH Certificate:
```yaml SSH Certificate
- name: Get certificate value
hosts: localhost
tasks:
- name: Get temp token using api-key auth method
akeyless.secrets_management.login:
akeyless_api_url: 'https://api.akeyless.io'
access_type: 'api_key'
access_id: ''
access_key: ''
register: auth_res
- name: Get SSH certificate
akeyless.secrets_management.get_ssh_certificate:
akeyless_api_url: 'https://api.akeyless.io'
cert_issuer_name: "/Ansible/cert_issuer_name"
cert_username: "<Username>"
public_key_data: "<public_key_data>"
token: '{{ auth_res.data.token }}'
register: result
- name: Display the RSA key
debug:
msg: "{{ result.data.data }}"
Where:
- `akeyless_api_url`: Gateway URL API V2 endpoint i.e. `https://Your_GW_URL:8000/api/v2`.
- `cert_issuer_name`: The name of the **SSH Certificate Issuer**.
- `cert_username`: The username to sign in the SSH certificate.
- `public_key_data`: SSH Public Key.
- `ttl`: **Optional**, Updated certificate lifetime in seconds (must be less than the Certificate Issuer default TTL).
- `legacy_signing_alg_name`: **Optional**, Set this option to output legacy `ssh-rsa-cert-v01@openssh.com` signing algorithm name in the certificate.
## PKI Certificate Example
The following will issue and fetch a PKI certificate:
```yaml PKI Certificate.yaml
- name: Get certificate value
hosts: localhost
tasks:
- name: Get temp token using api_key auth method
akeyless.secrets_management.login:
akeyless_api_url: 'https://api.akeyless.io'
access_type: 'api_key'
access_id: '<Access ID>'
access_key: '<Access Key>'
register: auth_res
- name: Get PKI certificate
akeyless.secrets_management.get_pki_certificate:
akeyless_api_url: 'https://api.akeyless.io'
cert_issuer_name: "/Ansible/pki_issuer_name"
csr_data_base64: "<csr_data_base64>"
token: '{{ auth_res.data.token }}'
register: result
- name: Display the result of the operation
debug:
msg: "{{ result }}"
- name: Display the RSA key
debug:
msg: "{{ result.data.data }}"
Where:
-
akeyless_api_url: Gateway URL API V2 endpoint i.e. https://Your_GW_URL:8000/api/v2.
-
cert_issuer_name: The name of the PKI Certificate Issuer.
-
csr_data_base64: Certificate Signing Request contents encoded in base64 to generate the certificate with.
Additional parameters for this module can be found in the official Ansible Repository.
Running unit tests
python -m pytest
LICENSE
Licensed under MIT, see LICENSE
