Documentation

11. 自定义凭证类型

作为具有超级用户访问权限的 Tower 管理员,您可以使用类似于 YAML/JSON 定义,以标准格式定义自定义凭证类型,允许将新凭证类型分配给作业和清单更新。这样,您可以定义一个与现有凭证类型原理相似的自定义凭证类型。例如,您可以创建一个自定义凭证类型,将第三方 Web 服务的 API 令牌注入环境变量,以供 playbook 或清单脚本使用。

自定义凭证支持以下注入身份验证信息的方法:

  • 环境变量

  • Ansible 额外变量

  • 基于文件的模板(例如生成包含凭证值的 .ini.conf 文件)

您可以为作业模板附加一个 SSH 和多个云凭证。每个云凭证必须是不同的类型。换句话说,只允许使用一个 AWS 凭证、一个 GCE 凭证等。在 Ansible Tower 3.2 及更新版本中,vault 凭证和机器凭证是单独的实体。

注解

在创建新凭证类型时,您需要避免在 extra_varsenv 和文件命名空间中发生冲突。另外,还需避免使用以 ANSIBLE_ 开头的环境变量或额外变量名称,因为它们是保留的。您必须具有 Superuser 权限才能创建和编辑凭证类型 (CredentialType),以及查看 CredentialType.injection 字段。

11.1. 后向兼容 API 注意事项

支持对 API 版本 2 (api/v2/) 意味着作业模板与凭证为一对多的关系(包括多云支持)。API 版本 1 (api/v1/) 从 Ansible Tower 版本 3.6 起已停用,因此不存在向后兼容性。

在更旧版本的 Ansible Tower 中,可以使用 v1 API(现在不支持)根据凭证的“种类”对凭证进行过滤:

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

从 Ansible Tower 版本 3.6 开始,可使用 v2 API 以类似的方式对凭证进行过滤:

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

在 V2 CredentialType 模型中,关系定义如下:

机器

SSH

Vault

Vault

网络

设置环境变量(例如 ANSIBLE_NET_AUTHORIZE

SCM

源控制

EC2、AWS

很多其他服务

Insights

Insights

自定义类型创建和修改仅限于云和网络种类。

11.2. 凭证类型入门

点击左侧导航栏中的 Credential Types (credential-types-icon) 图标访问 Credentials。如果没有创建自定义凭证类型,Credential Types 视图将不会显示任何自定义凭证类型,并会提示您添加一个:

Credential Types - home empty

如果创建了凭证类型,本页会显示所有现有和可用凭证类型的列表。可按 NameKind 对其进行排序和搜索。

Credential Types - home with example credential types

要查看有关凭证类型的更多信息,请点击其名称或 Actions 栏中的编辑 (edit) 按钮。

如果适用,每个凭证类型都会在 Input Configuration 字段和 Injector Configuration 字段显示自己的唯一配置。配置字段中支持 YAML 和 JSON 两种格式。

11.3. 创建新凭证类型

要创建新凭证类型,请执行以下操作:

  1. 点击 Credential Types 屏幕右上角的 add 按钮。

Create new credential type

  1. NameDescription 字段中输入正确的详情。

注解

在创建新凭证类型时,请不要为 INPUTINJECTOR 名称和 ID 使用以 ANSIBLE_ 开头的保留变量名称,因为它们对于自定义凭证类型无效。

  1. Input Configuration 字段中,指定为该类型定义一组排序字段的输入 schema。格式可以是 YAML 或 JSON,如下所示:

YAML

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

要查看更多 YAML 示例,请访问 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"]
}

要查看更多 JSON 示例,请访问 www.json.org

以下 JSON 格式的配置显示每个字段以及它们的使用方式:

{
  "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
},

type=string 时,字段可以选择性地指定多个选择选项:

{
  "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"]
  }]
},
  1. Injector Configuration 字段中,输入环境变量或额外变量来指定凭证类型可注入的值。格式可以为 YAML 或 JSON(请参阅上一步中的示例)。以下 JSON 格式的配置显示每个字段以及它们的使用方式:

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

凭证类型还可生成临时文件来支持 .ini 文件或证书/密钥数据:

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

在这个示例中,Tower 将编写包含以下内容的临时文件:

[mycloud]\ntoken=SOME_TOKEN_VALUE

所生成文件的绝对文件路径将存储在名为 MY_CLOUD_INI_FILE 的环境变量中。

以下是在自定义凭证模板中引用多个文件的示例:

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 }}"
  }
}
  1. 完成后请点击 Save

  2. 向下滚动到屏幕底部,您新创建的凭证类型会出现在凭证类型列表中:

New credential type

点击 editdelete 分别可修改或删除 Actions 列下的凭证类型选项。

注解

如果要删除凭证正在使用的凭证类型,您必须先从所有使用该凭证类型的凭证中删除它,然后才能将它删除。以下是此类消息的示例:

_images/credential-types-delete-confirmation.png
  1. 验证在创建新凭证时是否可从 Credential Type 选择窗口中选择新创建的凭证类型:

Verify new credential type

有关如何创建新凭证的详情,请参阅 凭证