Documentation

5. 多凭证分配

从版本 3.3 开始,Ansible Tower 支持为一个作业模板分配零个或多个凭证。

5.1. 背景

Ansible Tower 3.3 之前,作业模板对凭证有一定的要求:

  • 所有作业模板(和作业)都必须只有*一个*机器/SSH 或 Vault 凭证(或两者)。

  • 所有作业模板(和作业)都可有零个或多个“额外”凭证。

  • 额外凭证代表“云”和“网络”凭证,可用于通过环境变量(如 AWS_ACCESS_KEY_ID)提供外部服务身份验证。

这个模型需要各种不连接接口来指定作业模板上的凭证,而且它无法将多个 Vault 凭证与 playbook 运行相关联,这是 Ansible 2.4 之后的 Ansible 内核支持的一个用例。

这个模型还为特定的 playbook 执行工作流造成障碍,如必须将“虚拟”机器/SSH 凭证附加到作业模板中以满足要求。

5.2. 重要更改

作业模板现在有一个用于凭证分配的接口,API 端点:

GET /api/v2/job_templates/N/credentials/

您可以使用 POST 请求关联和解除凭证关联,类似于已弃用的 extra_credentials 端点中的行为:

POST /api/v2/job_templates/N/credentials/ {'associate': true, 'id': 'X'}
POST /api/v2/job_templates/N/credentials/ {'disassociate': true, 'id': 'Y'}

在此模型下,即使 *没有*分配了凭证,作业模板也被视为有效。此模型也让用户可以为作业模板分配多个 Vault 凭证。

5.3. 启动时间注意事项

在 Ansible Tower 3.3 之前,作业模板有一个可配置的属性 ask_credential_on_launch。这个值在启动时用来决定哪个缺少的凭证值是启动所必需的——这主要用于指定 机器/SSH 凭证,以满足最低凭证要求。

在新的统一凭证列表模型下,此属性仍然存在,但它不再“需要”凭证。现在,ask_credential_on_launchTrue。它表示如果需要,您可以在启动时指定一个凭证列表来覆盖作业模板中定义的凭证。例如:

POST /api/v2/job_templates/N/launch/ {'credentials': [A, B, C]}`

如果 ask_credential_on_launchFalse,它表示忽略 POST /api/v2/job_templates/N/launch/ 中提供的自定义凭证。

在此模型下,ask_credential_on_launch 的唯一的目的是示意 API 客户端在启动时提示用户进行(可选)更改。

5.4. 后向兼容性

各种 API 客户端都依赖过时的机制进行凭证检索和分配,在新的 API 更改中,仍以与后向兼容的方式支持这些客户端。更新 JobTemplate.credentialJobTemplate.vault_credential 的请求仍像之前一样进行操作:

PATCH /api/v2/job_templates/N/ {'credential': X, 'vault_credential': Y}

在此模型下,当以此方式使用多个 vault 凭证更新作业模板时,新的底层列表将*仅*包含过时请求中指定的单个 Vault 凭证。

在过去,对 /api/v2/job_templates/N/GET 请求的响应中的 related_fields 中包括以下元数据:

{
    "related": {
        ...
        "credential": "/api/v2/credentials/1/",
        "vault_credential": "/api/v2/credentials/3/",
        "extra_credentials": "/api/v2/job_templates/5/extra_credentials/",
    }
}

summary_fields 中包括:

{
    "summary_fields": {
        "credential": {
            "description": "",
            "credential_type_id": 1,
            "id": 1,
            "kind": "ssh",
            "name": "Demo Credential"
        },
        "vault_credential": {
            "description": "",
            "credential_type_id": 3,
            "id": 3,
            "kind": "vault",
            "name": "some-vault"
        },
        "extra_credentials": [
            {
                "description": "",
                "credential_type_id": 5,
                "id": 2,
                "kind": "aws",
                "name": "some-aws"
            },
            {
                "description": "",
                "credential_type_id": 10,
                "id": 4,
                "kind": "gce",
                "name": "some-gce"
            }
        ],
    }
}

这些元数据将继续存在,并以向后兼容的方式运行。

/api/v2/job_templates/N/extra_credentials 端点已弃用,但仍将以相同的方式继续存在和运行。

/api/v2/job_templates/N/launch/ 端点还提供过时的、向后兼容的支持,以便在启动时通过 credentialvault_credentialextra_credentials 字段指定凭证:

POST /api/v2/job_templates/N/launch/ {'credential': A, 'vault_credential': B, 'extra_credentials': [C, D]}

5.5. 多 Vault 凭证

从 Ansible Tower 3.3 开始,可以为作业分配多个凭证,现在您可以在作业模板运行时指定多个 Vault 凭证来进行解密。此功能反映了对 Ansible 2.4 及之后的版本中的 multiple vault passwords for a playbook run 的支持。

现在,Vault 凭证有一个可选字段 vault_id,类似于 ansible-playbook--vault-id 参数。要运行使用多个 vault 密码的 playbook,请执行以下步骤:

  1. 在 Tower 中为每个 vault 密码创建一个 Vault 凭证;指定 Vault ID 作为凭证上的字段并输入密码(将会加密并存储)。

  2. 通过新凭据端点将多个 vault 凭证分配给作业模板:

POST /api/v2/job_templates/N/credentials/

{
    'associate': true,
    'id': X
}

或者,您可以在 Create Credential 页面的 Tower 用户界面中执行相同的分配:

_images/credentials-create-multivault-credential.png

在上例中,创建的凭证指定了其 Vault 标识符(“第一个”)和密码对要使用的 secret。当此凭证在作业模板中使用时,如下例所示,它只会解密与“第一个”Vault ID 关联的 secret:

_images/job-template-include-multi-vault-credential.png

如果您的 playbook 是采用传统方法设置的,所有 secret 不加区分放在一个大文件中,那么在设置 Vault 凭证时将 Vault Identifier 留空:

_images/credentials-create-novaultid-credential.png

5.5.1. 提示 Vault 凭证

标记为“启动时提示”的 Vault 凭证的密码,任何相关作业模板的启动端点都会通过 passwords_needed_to_start 密码进行必要的 Vault 密码通信:

GET /api/v2/job_templates/N/launch/
{
    'passwords_needed_to_start': [
        'vault_password.X',
        'vault_password.Y',
    ]
}

上例中的 XY 是关联的 Vault 凭证的主密钥。

POST /api/v2/job_templates/N/launch/
{
    'credential_passwords': {
        'vault_password.X': 'first-vault-password'
        'vault_password.Y': 'second-vault-password'
    }
}

5.5.2. 链接的凭证

您不需要将敏感凭证信息上传到 Tower 中,而是将凭证字段链接到外部系统,并使用它们运行您的 playbook。请参阅 Ansible Tower User GuideSecret Management System 部分。