Ansible

Ansible is a server automation framework that allows you to provision an entire infrastructure, manage configuration, and deploy applications.

Ansible 2.8 includes a built-in Manifold credential lookup plugin that enables you to access resource credentials managed by Manifold. Using Manifold for credential management means you don’t have to hard-code secrets and configuration variables in your Ansible environment config files.

For an end-to-end example of how to inject secrets from Manifold into an existing Ansible playbook, see our blog.

Prerequisites

Before you integrate, make sure you have:

Configuration

To configure the Ansible integration, perform the following tasks:

Once configured, the lookup plugin ensures that the latest secrets are fetched from Manifold when you run the Ansible playbook.

Provision a resource

When you provision a new resource in Manifold, the resource provider creates credentials for connecting to that resource. Manifold automatically fetches and stores these credentials for you to use in Ansible.

To learn how to provision a new resource, see our Quickstart Guide.

Create an API token

An API token is required for securely accessing credentials from Manifold. Create an API token with the Manifold CLI and grant it the read-credentials role.

To get started with API tokens, refer to the Authentication documentation.

Fetch the credentials

Use the Manifold lookup plugin to retrieve resource credentials from Manifold. The plugin returns a dictionary of credentials ready to be consumed as environment variables. The method of handling the return value depends on how you want to inject secrets into your Ansible playbook. For example, you can:

  • Store the credentials in an environment file, so you can inject the secrets during service startup
  • Generate a config file from a Jinja2 template file with the secrets embedded (see Templating (Jinja2) in the Ansible documentation)
  • Directly export the secrets as an environment variable in your task

Example

ansible-fetch-creds

This example:

  • uses set_fact to save the result of lookup to the manifold_secrets variable
  • uses the manifold_secrets variable to create an app.env file using the app.env.j2 template, which loops over the “manifold_secrets” dictionary

Usage

The plugin returns credentials ready to be consumed as environment variables.

Call the Manifold lookup plugin to fetch credentials:

set_fact:
     env_vars: {{ lookup('manifold', api_token='SecretToken') }}

Parameters

resources: List of resource labels to look up on Manifold.co. If no resources are specified, all matched resources will be returned. Optional.

api_token: Manifold API token. This parameter is required unless Ansible is run with the MANIFOLD_API_TOKEN environment variable set.

project: The project label you want to get the resource for. Optional.

team: The team label you want to get the resource for. Optional.

If multiple resources define the same environment variable(s), the last one returned by the Manifold API will take precedence. Use our CLI tool with manifold alias to rename credentials as desired.

Examples

Usage examples

Get credentials for all available resources:

- name: all available resources
    debug: msg="{{ lookup('manifold', api_token='SecretToken') }}"

Get credentials for all available resources for a specific project in a specific team:

- name: all available resources for a specific project in specific team
    debug: msg="{{ lookup('manifold', api_token='SecretToken', project='project-1', team='team-2') }}"

Get credentials for two specific resources:

- name: two specific resources
    debug: msg="{{ lookup('manifold', 'resource-1', 'resource-2') }}"

Output example

example.yml:

- name: all available resources
  debug: msg="{{ lookup('manifold', api_token='SecretToken') }}"
$ ansible-playbook example.yml
  PLAY [localhost] **********************************************************
  TASK [debug] **************************************************************
  ok: [localhost] => {
      "msg": {
          "RESOURCE_URL": "https://lgn:pswd@cluster123.example.com", 
          "ANOTHER_RESOURCE_TOKEN": "smplet0k3n"
      }
  }
  PLAY RECAP ****************************************************************
  localhost                  : ok=1    changed=0    unreachable=0    failed=0  

See also

For an example showing how to use Manifold with Ansible, check out our blog.

See https://docs.ansible.com/ansible/2.8/plugins/lookup/manifold.html for more information on the Manifold Lookup Plugin.