ConfigSeeder Lookup Plugin for Ansible

1. Introduction

With the ConfigSeeder® lookup plugin, configuration data stored in ConfigSeeder can be used in Ansible playbooks.

2. Quickstart

2.1. Introduction

2.1.1. Content of the quickstart manual

This quickstart guide gives an introduction to the use of the Configseeder Ansible lookup-plugin.

You will understand, how configuration data stored in configseeder can be used in ansible

This quickstart guide also offers links to more detailed information.

2.1.2. Preconditions

ConfigSeeder up and running
Connectivity from the Linxu/Windows VM running Ansible and the ConfigSeeder lookup Plugin to the ConfigSeeder

2.2. Prepare configuration groups in ConfigSeeder

Create a Configuration Group ansible-quickstart (the name of the Configuration Group can be chosen as desired)

When creating the Configuration Group, just enable the filter columns Environment and Context and leave the security options on their default values.
Create the two environments TEST and PROD (the name of the Environments can be chosen as desired)
Create an API Key with permission to access the Configuration Group oansible-quickstart and to all environments.

2.3. Install the plugin

Execute the following steps to install the plugin:

Download the plugin from http://download.configseeder.com/ansible-plugin/lookup/0.1.0/configseeder.py
Copy Plugin to one of the locations where Ansible will pick it up
- ~/.ansible/plugins/lookup/ for use by a single user / prototyping
- Normally /usr/share/ansible/plugins/modules/lookup/ for system wide use

2.4. Prepare Playbook

Create the playbook.yaml:

- name: Quickstart Playbook
  hosts: localhost
  tasks:

  - name: ConfigSeeder Lookup Value with default filter
    debug: msg={{ lookup('configseeder', 'key') }}

  - name: ConfigSeeder Lookup Value for environment PROD
    debug: msg={{ lookup('configseeder', 'key', environmentKey='PROD') }}

  - name: ConfigSeeder Lookup Value for context 'context'
    debug: msg={{ lookup('configseeder', 'key', context='context') }}

Create run-playbook.sh:

CONFIGSEEDER_URL=https://staging-postgres-config-seeder.oneo.cloud \
CONFIGSEEDER_CONFIGURATIONGROUPKEYS=ansible-quickstart \
CONFIGSEEDER_TENANTKEY=default \
CONFIGSEEDER_ENVIRONMENTKEY=TEST \
CONFIGSEEDER_APIKEY=<api-key> \
\
ansible-playbook playbook.yaml

Run the playbook with the following commands:

> chmod +x run-playbook.sh
> ./run-playbook.sh

The following output should be created:

PLAY [Quickstart Playbook] **************************************************************************************************************

TASK [Gathering Facts] ******************************************************************************************************************
ok: [localhost]

TASK [ConfigSeeder Lookup Value with default filter] ************************************************************************************
ok: [localhost] => {
    "msg": "value test"
}

TASK [ConfigSeeder Lookup Value for environment PROD] ***********************************************************************************
ok: [localhost] => {
    "msg": "value prod"
}

TASK [ConfigSeeder Lookup Value for context 'context'] **********************************************************************************
ok: [localhost] => {
    "msg": "value test and context"
}

PLAY RECAP ******************************************************************************************************************************
localhost                  : ok=4    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

3. Configuration Options

3.1. Ways to configure the Plugin

This section describes every available configuration option available for the lookup plugin.

There are three ways to configure the plugin:

Configuration by file (lowest priority)

Add the following section in your ansible configuration (normally ~/ansible.cfg)
```
[configseeder]
url = https://staging-postgres-config-seeder.oneo.cloud
apiKey = <api-key>
configurationGroupKeys = ansible-quickstart
tenantKey = default
environmentKey = TEST
```
You can choose which keys you want to declare in this section. All keys defined in this section can be overwritten later on.

Configuration by environment variables

without exporting the environment variables:

Declare the variables in a shell script, like shown in the quickstart.

CONFIGSEEDER_URL=https://staging-postgres-config-seeder.oneo.cloud \
CONFIGSEEDER_CONFIGURATIONGROUPKEYS=ansible-quickstart \
CONFIGSEEDER_TENANTKEY=default \
CONFIGSEEDER_ENVIRONMENTKEY=TEST \
CONFIGSEEDER_APIKEY=<api-key> \
\
ansible-playbook playbook.yaml

with exporting the environment variables

export CONFIGSEEDER_URL=https://staging-postgres-config-seeder.oneo.cloud
export CONFIGSEEDER_CONFIGURATIONGROUPKEYS=ansible-quickstart
export CONFIGSEEDER_TENANTKEY=default
export CONFIGSEEDER_ENVIRONMENTKEY=TEST
export CONFIGSEEDER_APIKEY=<api-key>

Configure directly in Playbook (highest priority)
- No parameters/filters: {{ q('configseeder', 'key') }}
- Search in environment: {{ q('configseeder', 'key', environmentKey='PROD') }}
- Search in configuratin groups: {{ q('configseeder', 'key', configurationGroupKeys='ansible') }}
- Search with context: {{ q('configseeder', 'key', context='context') }}

It is possible to mix the different ways to configure the plugin. You probably want to configure the url and tenant by file and provide the API Key with an environment variable so it isn’t readable by anyone. Depending on your playbook it could make sense to provide the used configuration groups per file or environment variable and override where required in the playbook.

Priorities of ways to configure the connector

A parameter configured by file can be overwritten by environment variable and in the playbook
A parameter configured by environment variable can be overwritten in the playbook
You probably don’t want to specify the api key in the playbook.

3.2. Configuration Options

The lookup plugin can be configured by the following options:

Key Mandatory Value

Key	Mandatory	Value
`apiKey`	yes	API Key used by Connector to access ConfigSeeder. Can be set with key `apiKey` in the `ansible.cfg`, section `configseeder` Can be set with the environment variable `CONFIGSEEDER_APIKEY`
`configurationGroupKeys`	yes	Defines which configuration groups should be read by the Connector. Can be set with key `configurationGroupKeys` in the `ansible.cfg`, section `configseeder` Can be set with the environment variable `CONFIGSEEDER_CONFIGURATIONGROUPKEYS`
`context`	no	Optional for filtering configuration values by context. Can be set with key `context` in the `ansible.cfg`, section `configseeder` Can be set with the environment variable `CONFIGSEEDER_CONTEXT`
`dateTime`	no	Optional for filtering configuration values by validFrom & validTo. Defaults to now. Can be set with key `dateTime` in the `ansible.cfg`, section `configseeder` Can be set with the environment variable `CONFIGSEEDER_DATETIME`
`environmentKey`	yes	Environment for which the plugin requests data. Can be set with key `environmentKey` in the `ansible.cfg`, section `configseeder` Can be set with the environment variable `CONFIGSEEDER_ENVIRONMENTKEY`
`tenantKey`	no	ConfigSeeder tenant, which should be accessed. Defaults to `default` Can be set with key `tenantKey` in the `ansible.cfg`, section `configseeder` Can be set with the environment variable `CONFIGSEEDER_TENANTKEY`
`url`	yes	URL under which ConfigSeeder can be reached. Can be set with key `url` in the `ansible.cfg`, section `configseeder` Can be set with the environment variable `CONFIGSEEDER_URL`
`timeout`	no	Optional timeout for accessing ConfigSeeder. Defaults to 2 seconds Can be set with key `timeout` in the `ansible.cfg`, section `configseeder` Can be set with the environment variable `CONFIGSEEDER_TIMEOUT`
`version`	no	Optional for filtering configuration values by versionFrom & versionTo Can be set with key `version` in the `ansible.cfg`, section `configseeder` Can be set with the environment variable `CONFIGSEEDER_VERSION`

apiKey

yes

API Key used by Connector to access ConfigSeeder.

Can be set with key apiKey in the ansible.cfg, section configseeder
Can be set with the environment variable CONFIGSEEDER_APIKEY

configurationGroupKeys

yes

Defines which configuration groups should be read by the Connector.

Can be set with key configurationGroupKeys in the ansible.cfg, section configseeder
Can be set with the environment variable CONFIGSEEDER_CONFIGURATIONGROUPKEYS

context

Optional for filtering configuration values by context.

Can be set with key context in the ansible.cfg, section configseeder
Can be set with the environment variable CONFIGSEEDER_CONTEXT

dateTime

Optional for filtering configuration values by validFrom & validTo.

Defaults to now.
Can be set with key dateTime in the ansible.cfg, section configseeder
Can be set with the environment variable CONFIGSEEDER_DATETIME

environmentKey

yes

Environment for which the plugin requests data.

Can be set with key environmentKey in the ansible.cfg, section configseeder
Can be set with the environment variable CONFIGSEEDER_ENVIRONMENTKEY

tenantKey

ConfigSeeder tenant, which should be accessed.

Defaults to default
Can be set with key tenantKey in the ansible.cfg, section configseeder
Can be set with the environment variable CONFIGSEEDER_TENANTKEY

url

yes

URL under which ConfigSeeder can be reached.

Can be set with key url in the ansible.cfg, section configseeder
Can be set with the environment variable CONFIGSEEDER_URL

timeout

Optional timeout for accessing ConfigSeeder.

Defaults to 2 seconds
Can be set with key timeout in the ansible.cfg, section configseeder
Can be set with the environment variable CONFIGSEEDER_TIMEOUT

version

Optional for filtering configuration values by versionFrom & versionTo

Can be set with key version in the ansible.cfg, section configseeder
Can be set with the environment variable CONFIGSEEDER_VERSION

4. Configuration Options

4.1. Using the Plugin

The ConfigSeeder Ansible lookup plugin can be used like another Ansible lookup plugin, see https://docs.ansible.com/ansible/latest/plugins/lookup.html#invoking-lookup-plugins-with-query.

4.1.1. Retrieving single values

A single configuration value can be retrieved like this:

- name: ConfigSeeder: Lookup value with default filter
  debug: msg={{ lookup('configseeder', 'key') }}

The default filters (can be defined in ansible.cfg and by environment variables) can be overridden like this (see previous section for all configuration parameters):

- name: ConfigSeeder Lookup Value for environment PROD
  debug: msg={{ lookkup('configseeder', 'key', environmentKey='PROD') }}

- name: ConfigSeeder Lookup Value for context 'context'
  debug: msg={{ lookup('configseeder', 'key', context='context') }}

So if a file should be created with a content and filename both stored in ConfigSeeder, this could be achieved like this:

- name: Create file with content
  copy:
    dest: "{{ lookup('configseeder', 'lookup.demo.filename') }}"
    content: "{{ lookup('configseeder', 'lookup.demo.content') }}"

The lookup plugin doesn’t cache data retrieved from ConfigSeeder. This means that every time a {{ lookup('configseeder', … ) }} is executed, the plugin accesses ConfigSeeder.

4.1.2. Retrieving multiple values

Retrieving multiple values works similar like retrieving a single value. There are two differences:

Retrieve the values with query() (or q()) instead of with lookup()
Specify a second (and third, …) key

A single configuration value can be retrieved like this:

- name: ConfigSeeder Lookup multiple value with default filter
  debug: msg={{ q('configseeder', 'key', 'key2') }}

4.1.3. Retrieving and caching multiple values

The following example shows how the number of calls to ConfigSeeder can be reduces by storing the retrieved value as an Ansible fact:

- name: Playbook with storing data in ansible
  hosts: localhost
  tasks:

  - name: ConfigSeeder Lookup 'Context host-a'
    set_fact:
      cs_host_a={{ q('configseeder', context='host-a') }}

  - name: Create Private Key for Host A
    copy:
      dest: "{{ cs_host_a['privatekey.name'] }}"
      content: "{{ cs_host_a['privatekey.content'] }}"

5. Configuration Options

5.1. Debugging

The ConfigSeeer Ansible lookup plugin logs via the Ansible logging mechanism. So to get a detailed log, execute ansible-playbook with the parameter -v or even -vvv.