Ansible is an amazing tool for infrastructure automation. Its use cases range from setting up servers to configuring networking equipment.

However, managing sensitive credentials is a different story. While Ansible vault has been around since 2014, it might not necessarily fit into your existing secret management strategy, and there is always a chance that a sensitive file ends up in Git.

This article will explain how to set up Infisical, the open-source secrets management platform, to pass sensitive information to your Ansible playbooks.

What is Infisical?

For the uninitiated, Infisical is an open-source platform for securely managing application secrets, certificates, SSH keys, and configurations across your infrastructure.

This is important because you often have more than one type/set of credentials to manage. For instance, you might have access keys for AWS, SSH keys for virtual machine instances, and API keys for your application.

Managing each of these individually comes with its own tradeoffs and headaches, whether using AWS KMS or a third-party password manager. With Infisical, you can consolidate all your credentials into a single platform, giving you better control over usage.

In December 2023, Infisical announced native support for Ansible. This allowed you to fetch and inject secrets directly from Infisical into your Ansible playbooks.

Why not just use Ansible Vault?

Introduced in 2014, Ansible Vault lets you encrypt variables, files, and entire playbooks with a shared password or password file. By running ansible-vault encrypt and supplying a password, Vault ensures that sensitive data—API keys, certificates, SSH credentials—never appears in plaintext on disk. At a small scale, this model works well; you keep one (or a few) vault passwords, share them with your team, and commit only the encrypted artefacts to Git.

As your infrastructure and team grow, that simplicity starts to break down. You might need separate Vault passwords for different environments (dev, staging, prod) per application, role or even unique credentials per team.

Suddenly, you’re managing dozens of Vault files and passwords: distributing them securely, rotating them regularly, and updating CI/CD pipelines to handle the right secrets in the right place. And remember, encrypted files in Git are still files in Git. If a Vault password leaks or isn’t rotated promptly, you’ve gained a false sense of security.

In highly regulated or zero‑trust environments, encrypted sensitive material is often forbidden in version control.

Prerequisites.

With some context as to why you’d want to use Infisical to manage your Ansible secrets, let's dive into a practical demonstration. This tutorial assumes some working knowledge of Ansible. Additionally, you will need the following installed in order to proceed:

• Ansible:  This demo uses Ansible version 2.18.4
• Infisical CLI and an Infisical account, you can sign up for free here
• An Ubuntu virtual machine with SSH keys set up
• Python: This demonstration uses version 3.12.3. Consider using pyenv to manage multiple versions of Python.

Install the Infisical Ansible collection

Begin by installing the Ansible collection for Infisical; this contains the necessary configuration to pull in secrets from your account.  Using ansible-galaxy, run the following command in your terminal.

Install Ansible collection:

1ansible-galaxy collection install infisical.vault

The output is similar to:

The Infisical Ansible collection depends on the Infisical Python package, which is not installed by default.

Install the dependency using PIP:

python3 -m pip install --user --break-system-packages --upgrade infisical-python infisicalsdk

The command above uses  --break-system-packages because in order for Ansible to make use of the module, it needs to be a global package; however --user ensures it is installed only for the current user.

Note: Troubleshooting the Python interpreter version error

In case you run into the following error:

        --- stderr
        error: the configured Python interpreter version (3.13) is newer than PyO3's maximum supported version (3.12)
        = help: please check if an updated version of PyO3 is available. Current version: 0.20.3

‍

Consider installing pyenv and setting your global Python version to 3.12.3

Upon success, your output should look like this:

Create secrets

Next,  create a directory which will house your Ansible configuration; this directory will also house your Infisical config file, which links a local project to your Infisical account. In your terminal, run the following:

mkdir infisical-ansible && cd infisical-ansible && infisical init

With a project initialized, you can set secrets; this demonstration will walk you through creating a Linux user and a file with a sensitive value. In this demo, assume it is your application's API key.

Run the following command:

infisical secrets set ANSIBLE_USER_PASSWORD='superSecurePassword123!' ANSIBLE_API_KEY='abc123xyz'

The command above sets two demo secrets, ANSIBLE_USER_PASSWORD and ANSIBLE_API_KEY, which will be leveraged in the next section.

Universal Authentication with Infisical

Universal Auth is Infisical's platform-agnostic authentication mechanism designed for non-interactive environments, such as CI pipelines and virtual machines. Instead of logging in with a personal identity or storing a long-lived token, you create a Client ID and Client Secret tied to a specific machine or service. These credentials authenticate securely with Infisical to retrieve secrets without requiring any interaction.

In this setup, your local laptop might be configured with a client named local-dev-machine, while your CI system or deployment runner could use a more descriptive label, such as ansible-playbook-runner or infrastructure-provisioner-prod. The key idea here is to bind the credentials to the context they're used in so they can be scoped, rotated, and revoked independently.

Infisical has great documentation on how to create a universal auth client. The important part here is to store your universal auth Client Secret and Client ID.

Create an Ansible playbook for Infisical

With secrets set, the next step is to create an Ansible playbook that uses the secrets you just set. Create a file named playbook.yaml in your project directory and add the following code:

---
- name: Create user with Infisical-managed secret
  hosts: all
  vars:
    user_password: "{{ lookup('infisical.vault.read_secrets', universal_auth_client_id='your client_id', universal_auth_client_secret='<your client secret>', project_id='your project id', path='/', env_slug='dev', secret_name='ANSIBLE_USER_PASSWORD', url='https://app.infisical.com') }}"
    
    api_key: "{{ lookup('infisical.vault.read_secrets', universal_auth_client_id='your client_id', universal_auth_client_secret='<your client secret>', project_id='your project id', path='/', env_slug='dev', secret_name='ANSIBLE_API_KEY', url='https://app.infisical.com') }}"

  tasks:
    - name: Ensure app user exists with a password
      user:
        name: appuser
        password: "{{ user_password.value | password_hash('sha512') }}"
        shell: /bin/bash
        state: present

    - name: Create config file with API key
      copy:
        dest: /home/appuser/config.json
        content: |
          {
            "api_key  ": "{{ api_key.value }}" 
          }
        owner: appuser
        group: appuser
        mode: '0600'

‍

The playbook above uses the Infisical vault module you installed earlier to load in your secrets. Be sure to replace universal_auth_client_secret and universal_auth_client_id with your own client ID and secret.

Additionally, the playbook will create a user using the password that was obtained and create a sample config.json file in the new user's home directory to simulate a configuration file for an app you might have deployed.

Next,  create a hosts file, which will contain the IP of the instance you want Ansible to connect to:

Create a file called  inventory.ini and add the following configuration, replacing the IP with your instance’s IP address or hostname:

[all]
<yourinstance ip e.g 10.10.10.10>

‍

Run the playbook using the following command:

ansible-playbook playbook.yaml -i inventory -u <your VM user> -b

The output is similar to:

Verify changes

To check if the changes were actually applied, SSH into your target VM and run the following commands.

Check for appuser:

su appuser 

When prompted for a password, enter the password you created earlier:

Your output should be similar to the image above.  

Check the config file:

cat ~/config.json

The output is similar to:

Scaling secrets

Managing secrets at scale brings a unique set of challenges, and Ansible secrets are no different. In this post, we walked through using the Infisical Ansible integration to securely load secrets into your playbooks.

If you are looking to learn more about Ansible, here are more blogs:

• Ansible Architecture: Key Components Overview
• Using Ansible apt Module to Manage Packages
• How to Use Ansible For DevOps? Hands-On Tutorial

‍