Ansible Integration

Before proceeding with this section, please ensure that you have access to the secretssafe Python package, installable from a BeyondTrust provided .whl file.

Install the DevOps Secrets Safepackage

The DevOps Secrets Safe lookup plugin imports the secretssafe package and creates an instance of the client which communicates with the DevOps Secrets Safe cluster.

Install the secretssafe package to your Python environment using pip.

$ pip install secretssafe-<version_details>.whl

Configure Ansible to Discover the DevOps Secrets Safe Lookup Plugin

To use the DevOps Secrets Safe lookup plugin, you will need to either export a particular environment variable to point to the location of the plugin *.py file, or place the plugin *.py file in one of the ansible "magic" directories.

To load the plugin automatically, store it in ~/.ansible/plugins/lookup, /usr/share/ansible/plugins/lookup, or place the path to the plugin in your ansible.cfg file.

To use the plugin only in certain playbooks, store it in sub directory named lookup_plugins in the directory that contains the playbook that utilizes the plugin.

To use the environment to configure the plugin location, export the following:

$ export ANSIBLE_LOOKUP_PLUGINS=<path/to/secretssafe/lookup/plugin/directory/>

Once properly configured, validate the discovery of the plugin:

$ ansible-doc -t lookup secretssafelookup

The lookup plugin will then be invocable within a playbook similar to any other lookup plugin that come with the default Ansible installation.

Execute the Plugin with Environment Variables

The plugin allows for the usage of environment variables for the configuration of the client and authentication of the calling process, along with the keyword arguments as described in the plugin documentation. The following variables will be need to be set either on the control machine (shell where ansible is called), or within the playbook that uses the plugin:

SECRETSSAFE_HOST=<IP address or hostname of Secrets Safe instance>
SECRETSSAFE_PORT=<port of Secrets Safe instance>SECRETSSAFE_API_KEY=<pregenerated API key>
SECRETSSAFE_APP_NAME=<application name associated with API key>
SECRETSSAFE_VERIFY_CA=<true/false/path to CA certificate>

This allows you to invoke the plugin without the credential/configuration keyword arguments.

The DevOps Secrets Safe client verifies the SSL certificate presented by the DSS instance. The SECRETSSAFE_VERIFY_CA environment variable specifies the path to the CA certificate that the Secrets Safe certificate is checked against.

If no SECRETSSAFE_VERIFY_CA is specified, the default certificate bundles provided by the Python requests library are used.

Certificate verification can be disabled by setting SECRETSSAFE_VERIFY_CA=false. This is strongly discouraged for production environments.

DevOps Secrets Safe create_secret Module

This module supports creating secrets with DSS. Secrets can be read from a file on disk or an Ansible fact. Secret creation by providing a generator name is also supported. Credentials for a DSS application must be provided.

  • name: The name of the application used to create the secret
    • required: true
  • api_key: API key that corresponds to the application provided in the name option
    • required: true
  • secret_uri: The DSS URI where the secret will be saved
    • required: true
  • host: DNS or IP address of the DSS instance this secret will be saved to
    • required: true
  • verify_ca: SSL certificate verification flag; looks to publicly available CA if set to true
    • required: false
    • default: true
    • choices:
      • true
      • false
      • path to CA certificate
  • port: DSS instance port
    • required: false
    • default: 443
  • generator: Name of generator used to create secret value mutually exclusive with secret_file_path and secret_value options
    • required: false
  • secret_file_path: Path to file that will be saved as a secret mutually exclusive with generator and secret_value options
    • required: false
  • secret_value: Value, in the form of a string, that will be saved as a secret path to file that will be saved as a secret mutually exclusive with generator and secret_file_path options
    • required: false