Skip to content

For convenience, the DevEx team provisions key vaults for customers to use for Tower to communicate with servers but the service principal is owned by DevEx. Customers can set up their own key vaults separately.

Credentials and Secrets Management in Tower#

Secrets in Tower are configured in 'Credentials'

General guidelines for secrets management in Tower:

  1. When possible, do not store secrets directly in Tower. Use an external key store. Using an external key store makes transitioning to more cloud-based deployments simpler.
  2. When possible, use a specific Credential over a variable file. If you find yourself unable to use a specific credential and you are using the same secret in multiple files, contact the DevEx team.
  3. Secrets/keys/etc added are a one-way event, meaning you can not retrieve them once added, so make sure they are backed up to a secure location or easily rotated.
  4. Also, remember when a team member changes job responsibilities or terminates employment, or the key is compromised to rotate keys/secrets

Note: Only one credential of each credential type can be used per template.

azure-keyvault Ansible Community Plugin#

This UMN Ansible community plugin allows you to pull individual secrets into your playbook from Azure KeyVault. See the readme for details. Use the UMN Azure Key Vault Plugin credential to set the environment variables in Tower.

Galaxy Page :: Github page

collections/requirements.yml#

Text Only
---
collections:
  - umn_community.umn_rhel9_management
## NOTE: This is not required for Tower if you are using the devex-ee execution environment as it is already installed there

Playbook Example#

The required environment variables for the plugin can be set by setting up the UMN Azure Key Vault Plugin Credential in Tower and adding it to your template. The Credential will inject the following variables at runtime:

Text Only
AZURE_SP_CLIENT_ID
AZURE_SP_CLIENT_SECRET
AZURE_AKV_VAULT_URL
The plugin can be used to set variables like this:

Text Only
---
- name: Setup Secrets
  hosts: all

  vars: 
    test_var: "{{ lookup('umn_community.umn_rhel9_management.azure_keyvault', 'test') }}" # This pulls out a secret stored as 'test' in your key vault.

  tasks: 
    - name: Print Message
      debug:
        msg: "Hello World. Test: {{ test_var }}"

Credentials and Credential Types#

NOTE: Only one credential of each credential type can be added to a template.

Official Documentation Credentials are Keys, Passwords, and general secrets configured in AWX to be used in running playbook jobs.

Credential Types are configurations for specific Credentials. There is a full list of builtin Credential Types in the official documentation but some common ones are:

  • Builtin Credential types#

  • Machine: SSL Private Key or User/Pass used to connect to servers
  • Source Control: Used to connect to GitHub or other source control repos. Usually a deployment key.
  • Microsoft Azure Key Vault: Used to connect to a Microsoft Azure Key Vault
  • Vault: Decrypt password for Ansible Vault

  • UMN Custom Credential Types#

  • Single Secret Credential: A single key-value pair. Reference using: {{ single_secret }}.
  • Multiple Secret Values Credential: Multiple key-value pairs. Reference using {{ secret0 }}, {{ secret1 }}, etc.
  • Secret File: An encrypted variable file.
  • Azure Service Principal: A credential representing an Azure Service Principal id and password. Reference using {{ clientid }}, {{ clientsecret }}
  • UMN Azure Key Vault Plugin: This is to be used in tandem with the umn_community.umn_rhel9_management plugin only.
  • UMN Sectigo Credential: Contains the KID and HMAC values for using Certbot with Sectigo. Reference using {{ sectigo_eab_kid }}, {{ sectigo_eab_hmac }}

Adding a Credential to a Template#

  1. Under 'Credentials' in a Job template, select the search icon.
  2. Select the credential type of the secret you need from the 'Selected Category' dropdown.
  3. Select the credential you would like to import from the list and click the 'Select' button.
  4. Save the Job Template

Connecting to Azure Key Vault#

The Microsoft Azure Key Vault credential is what allows users to reference key-value pairs stored in Azure Key Vault.

DevEx will have created this connection for you for the vault provided to you in onboarding.

You will need: - Admin rights for your organization in AWX - Access to a KeyVault in Azure - A Service Principle/Service Account setup in Azure for your KeyVault

Setup Hashicorp Vault Credential#

WIP

Secrets File Credential#

The Secret File Credential Type is used to inject a flat secrets file into your playbook.

Setup#

  1. If you use Azure Key Vault, push your secret file to the vault using the command az keyvault secret set -n <SECRET NAME> --vault-name "<KEYVAULT NAME>" --file <SECRETFILE NAME>
  2. Under 'Credentials' click 'Add' button
  3. Name your Credential, select your Organization, and choose Secret File Credential type.
  4. Use the key icon to connect to your vault and pull it in. Other-wise add your file by pasting or browsing. NOTE: THIS FIELD IS WRITE ONLY. YOU WILL NOT BE ABLE TO SEE WHAT IS SAVED IN IT, ONLY REPLACE IT.
  5. Add a reference to the credential in your playbook by using var_files
    YAML
        vars_files:
      - "{{ secret_file }}"
  6. In your template, add the credential by clicking the search icon under credential, Select Category Secret File, and select the credential you are using. SAVE.
  7. Secrets can be referenced as normal variables in ansible using the "{{ var_name }}" format.

Ansible Vault#

Ansible Vault Official Docs

Other Helpful Tutorial

To add your encryption key, use the 'Vault' credential type and include it in your template credentials. A reference to your secrets file must be specified in your playbook like so:

Text Only
  vars_files:
    - test_secret.yml