11. Custom Credential Types¶

11.1. Backwards-Compatible API Considerations¶

Support for version 2 of the API (api/v2/) means a one-to-many relationship for Job Templates to credentials (including multi-cloud support). Version 1 of the API (api/v1/) has been discontinued as of Ansible Tower version 3.6, and therefore no backward-compatibility exists.

In older versions of Ansible Tower, credentials could be filtered on their “kind” using the (now unsupported) v1 API:

$ curl "https://tower.example.org/api/v1/credentials/?kind=aws"

Starting in Ansible Tower version 3.6, credentials can be filtered in a similar manner using the v2 API:

$ curl "https://tower.example.org/api/v2/credentials/?credential_type__namespace=aws"

In the V2 CredentialType model, the relationships are defined as follows:

Custom type creation and modification are limited to cloud and network kinds.

11.2. Getting Started with Credential Types¶

Access the Credentials from clicking the Credential Types () icon from the left navigation bar. If no custom credential types have been created, the Credential Types view will not have any to display and will prompt you to add one:

If credential types have been created, this page displays a list of all existing and available Credential Types. It can be sorted and searched by Name and Kind.

To view more information about a credential type, click on its name or the Edit () button from the Actions column.

Each credential type displays its own unique configurations in the Input Configuration field and the Injector Configuration field, if applicable. Both YAML and JSON formats are supported in the configuration fields.

11.3. Create a New Credential Type¶

To create a new credential type:

1. Click the button located in the upper right corner of the Credential Types screen.

2. Enter the appropriate details in the Name and Description field.

3. In the Input Configuration field, specify an input schema which defines a set of ordered fields for that type. The format can be in YAML or JSON, as shown:

YAML

fields:
  - type: string
    id: username
    label: Username
  - type: string
    id: password
    label: Password
    secret: true
required:
  - username
  - password

View more YAML examples at http://www.yaml.org/start.html.

JSON

{
"fields": [
  {
  "type": "string",
  "id": "username",
  "label": "Username"
  },
  {
  "secret": true,
  "type": "string",
  "id": "password",
  "label": "Password"
   }
  ],
 "required": ["username", "password"]
}

View more JSON examples at www.json.org.

The configuration in JSON format below show each field and how they are used:

{
  "fields": [{
    "id": "api_token",               # required - a unique name used to
                                     # reference the field value

    "label": "API Token",            # required - a unique label for the
                                     # field

    "help_text": "User-facing short text describing the field.",

    "type": ("string" | "boolean")   # defaults to 'string'

    "choices": ["A", "B", "C"]       # (only applicable to `type=string`)

    "format": "ssh_private_key"      # optional, can be used to enforce data
                                     # format validity for SSH private key
                                     # data (only applicable to `type=string`)

    "secret": true,                  # if true, the field value will be encrypted

    "multiline": false               # if true, the field should be rendered
                                     # as multi-line for input entry
                                     # (only applicable to `type=string`)
},{
    # field 2...
},{
    # field 3...
}],

"required": ["api_token"]            # optional; one or more fields can be marked as required
},

When type=string, fields can optionally specify multiple choice options:

{
  "fields": [{
      "id": "api_token",          # required - a unique name used to reference the field value
      "label": "API Token",       # required - a unique label for the field
      "type": "string",
      "choices": ["A", "B", "C"]
  }]
},

4. In the Injector Configuration field, enter environment variables or extra variables that specify the values a credential type can inject. The format can be in YAML or JSON (see examples in the previous step). The configuration in JSON format below show each field and how they are used:

{
  "file": {
      "template": "[mycloud]\ntoken={{ api_token }}"
  },
  "env": {
      "THIRD_PARTY_CLOUD_API_TOKEN": "{{ api_token }}"
  },
  "extra_vars": {
      "some_extra_var": "{{ username }}:{{ password }}"
  }
}

Credential Types can also generate temporary files to support .ini files or certificate/key data:

{
  "file": {
      "template": "[mycloud]\ntoken={{ api_token }}"
  },
  "env": {
      "MY_CLOUD_INI_FILE": "{{ tower.filename }}"
  }
}

In this example, Tower will write a temporary file that contains:

[mycloud]\ntoken=SOME_TOKEN_VALUE

The absolute file path to the generated file will be stored in an environment variable named MY_CLOUD_INI_FILE.

An example of referencing multiple files in a custom credential template is as follows:

Inputs

{
  "fields": [{
    "id": "cert",
    "label": "Certificate",
    "type": "string"
  },{
    "id": "key",
    "label": "Key",
    "type": "string"
  }]
}

Injectors

  {
    "file": {
      "template.cert_file": "[mycert]\n{{ cert }}",
      "template.key_file": "[mykey]\n{{ key }}"
  },
  "env": {
      "MY_CERT_INI_FILE": "{{ tower.filename.cert_file }}",
      "MY_KEY_INI_FILE": "{{ tower.filename.key_file }}"
  }
}

5. Click Save when done.

6. Scroll down to the bottom of the screen and your newly created credential type appears on the list of credential types:

Click to modify or to remove the credential type options under the Actions column.

Note

If deleting a credential type that is being used by a credential, you must delete the credential type from all the credentials that use it before you can delete it. Below is an example of such a message:

7. Verify that the newly created credential type can be selected from the Credential Type selection window when creating a new credential:

For details on how to create a new credential, see Credentials.