Ansible is an automation language and automation engine that lets you describe end-to-end IT application environments with a playbook. Ansible's simple, human-readable language allows orchestration of your application lifecycle no matter where it's deployed.


See Secure Ansible Playbook Secrets with Conjur to use our fully-interactive tutorial on securing Ansible automation by keeping unsecured secrets out of Playbooks with Conjur open source secrets management.

How Ansible works with Conjur

Instead of all secrets moving through the Ansible Controller, each Ansible-managed remote node is responsible using its own identity to retrieve secrets from Conjur.

Granting a Conjur identity to Ansible hosts

The Ansible role can be used to configure a host with Conjur machine identity. Using security policy, the Ansible host can be granted least-privilege access to securely retrieve only the secrets it needs. Restricting the secrets accessible to each Ansible host reduces the administrative power of each Ansible host and prevents the hosts from becoming high value targets. Integrating with Conjur provides additional benefits, including storing security policy as code and simplified secret rotation.

To grant your Ansible host a Conjur identity, you first must install the Conjur Ansible Role in your playbook directly.

  • For Ansible 2.8, we recommend you install the standalone Conjur Ansible Role.

  • For Ansible 2.9 and higher, we recommend you install the Community Conjur Ansible Collection, which includes both the Conjur Ansible Role and the Conjur Lookup Plugin.

Ansible 2.8

ansible-galaxy install cyberark.conjur-host-identity

Ansible 2.9+

$ ansible-galaxy collection install cyberark.conjur

Once you've done this, you can configure each Ansible node with a Conjur identity by including a section like the example below in your Ansible playbook:

- hosts: servers
    - role: cyberark.conjur.conjur-host-identity
      conjur_appliance_url: '',
      conjur_account: 'myorg',
      conjur_host_factory_token: "{{ lookup('env', 'HFTOKEN') }}",
      conjur_host_name: "{{ inventory_hostname }}"
      conjur_ssl_certificate: "{{ lookup('file', '/path/to/conjur.pem') }}"
      conjur_validate_certs: yes

Ansible 2.8 users who leverage the standalone role instead of the collection, should reference the role as: cyberark.conjur-host-identity instead.

This example:

  • Registers the host with Conjur, adding it into the layer specific to the provided host factory token.

  • Installs Summon with the Summon Conjur provider for secret retrieval from Conjur.

For more information on the supported Conjur Ansible Role variables, see our GitHub documentation.

Retrieving secrets from Conjur

Using Summon

When you configure the Ansible node with a Conjur identity using the Ansible role, you also install Summon and the Summon-Conjur Provider on the Ansible host.

With Summon installed, using Conjur with a Service Manager (like SystemD) is straightforward. Here's a simple example of a SystemD file connecting to Conjur:


ExecStart=/usr/local/bin/summon --yaml 'DB_PASSWORD: !var staging/demoapp/database/password' /usr/local/bin/myapp

The above example uses Summon to retrieve the password stored in Conjur at staging/myapp/database/password, set it to an environment variable DB_PASSWORD, and provide it to the demo application process. Using Summon, the secret is kept off disk. If the service is restarted, Summon retrieves the password as the application is started.

Using the conjur_variable lookup plugin

Ansible 2.8 comes built-in with the conjur_variable lookup plugin, and when you install the collection in Ansible 2.9 and higher, you also install the conjur_variable lookup plugin. The lookup plugin can be used to retrieve secrets from Conjur using the controlling host's Conjur identity.

In general, lookup plugins allow Ansible to access data from outside sources. They can be used in a play, in a variables file, or in a Jinja2 template for the template module.

To invoke the conjur_variable lookup plugin:

Ansible 2.8

  database_url: "{{ lookup('conjur_variable', '/path/to/secret') }}"

Ansible 2.9+

  database_url: "{{ lookup('cyberark.conjur.conjur_variable', '/path/to/secret') }}"