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 keyvaults separately.

Credentials and Secrets Management in Tower#

Secrets in AWX 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 Role#

This UMN Ansible community role allows you to pull individual secrets into your playbook from Azure KeyVault. See the readme for details. Requires Azure Service Principal credential.

Galaxy Page :: Github page

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

Credentials and Credential Types#

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 }

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