6. 複数の認証情報の割り当て¶

6.1. 背景¶

Ansible Tower 3.3 以前のバージョンでは、ジョブテンプレートには認証情報に関して特定の要件がありました。

• ジョブテンプレート (およびジョブ) は、マシン/SSH または Vault 認証情報 (またはいずれか) 1 つ だけ指定する必要がありました。

• 全ジョブテンプレート (およびジョブ) は、0 以上の "extra" 認証情報を指定できていました。

• Extra 認証情報は、環境変数経由で外部サービスへの認証に使用可能な "Cloud" および "Network" の認証情報を表していました (例: AWS_ACCESS_KEY_ID)。

このモデルは、ジョブテンプレートで認証情報を指定するために、さまざまなインターフェース要素が必要で、Playbook 事項で複数の Vault 認証情報を関連付ける機能にかけていました。また、ユースケースは、Ansible 2.4 以降の Ansible コアでサポートされていました。

また、このモデルは、要件を満たすためだけに「ダミー」のマシン/SSH 認証情報をジョブテンプレートにアタッチする必要があるなど、特定の Playbook 実行のワークフローに対する障害となっていました。

6.2. 重要な変更点¶

ジョブテンプレートには、認証情報の割り当て用にインターフェースが 1 つ用意されています。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 認証情報を割り当てることができます。

6.3. 起動時の考慮事項¶

Ansible Tower 3.3 以前では、ジョブテンプレートは ask_credential_on_launch の設定可能な属性がありました。起動時にこの値を使用して、起動時に、認証情報の中で不足している値はどれかを判断するために使用します。これは、マシン/SSH の認証情報を指定して認証情報の最小要件を満たす手段として主に使用されていました。

新しい統合型の認証情報リストモデルでは、この属性は存在しますが、認証情報は "必要なくなりました"。ask_credential_on_launch が True の場合は、起動時に認証情報一覧を指定して、ジョブテンプレートに定義している内容を上書きできるという意味です。以下に例を示します。

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

ask_credential_on_launch が False の場合には、POST /api/v2/job_templates/N/launch/ で指定のカスタムの認証情報は無視されます。

このモデルでは、ask_credential_on_launch は、起動時にユーザーに (任意で) 変更があるかどうかをプロンプトを表示して、API クライアントにシグナルを送るためだけのものです。

6.4. 後方互換性の考慮事項¶

さまざまな API クライアントは、すでに非推奨となっている認証情報の取得および割り当てのメカニズムに依存するので、API が新たに変更され、後方互換という形式でまだサポートされています。JobTemplate.credential と JobTemplate.vault_credential の更新要求は、以前と同じように動作します。

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

このモデルでは、複数の Vault 認証情報が指定されたジョブテンプレートがこの方法で更新されると、新たに基盤となるリストには、非推奨の要求で指定された Vault 認証情報 1 つ だけ が含まれます。

/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/ エンドポイントは、credential、vault_credential、extra_credentials フィールドを使用して、起動時に認証情報を指定できるように、非推奨化されている、後方互換性サポートも提供しています。

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

6.5. 複数の Vault 認証情報¶

Ansible Tower 3.3 以降で、複数の認証情報を 1 つのジョブに割り当てることができるようになり、複数の Vault 認証情報を指定して、ジョブテンプレートにの実行時に復号化できます。この機能は、Ansible 2.4 以降の「 multiple vault passwords for a playbook run 」のサポートをミラーリングしています。

Vault の認証情報には vault_id の任意のフィールドが追加されました。これは、ansible-playbook に対する --vault-id の引数と同じです。複数の Vault パスワードを使用する Playbook を実行するには以下を実行します。

1. Vault パスワードごとに Tower で Vault の認証情報を作成します。認証情報のフィールドとして Vault ID を指定して、パスワードを入力します (パスワードは暗号化され保存されます)。

2. 新しい認証情報のエンドポイントを使用してジョブテンプレートに複数の Vault 認証情報を割り当てます。

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

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

または、Tower のユーザーインターフェースの 認証情報の作成 画面で同じ割り当てを行うことができます。

上記の例では、作成した認証情報は、Vault Identifier (「最初」) とパスワードのペアが使用するシークレットを指定します。この認証情報が以下の例のように、ジョブテンプレートで使用される場合には、「最初の」Vault ID に関連付けられたシークレットのみを復号化します。

従来の方法で、1 つの大きいファイルに区別なく、すべてのシークレットを指定して Playbook を設定した場合には、Vault 認証情報の設定時には、Vault Identifier フィールドは空白のままにしてください。

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

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