From b3651ecf30bf288b3e50a0ee8a4d16da7bc1371e Mon Sep 17 00:00:00 2001 From: AlanCoding Date: Wed, 31 Jul 2019 08:58:39 -0400 Subject: [PATCH] Update docs to reflect field removals --- docs/multi_credential_assignment.md | 78 +++++++++++++---------------- docs/prompting.md | 28 ++++------- 2 files changed, 45 insertions(+), 61 deletions(-) diff --git a/docs/multi_credential_assignment.md b/docs/multi_credential_assignment.md index 3fbb487428..0b0732b679 100644 --- a/docs/multi_credential_assignment.md +++ b/docs/multi_credential_assignment.md @@ -83,62 +83,53 @@ ignored. Under this model, the only purpose for `ask_credential_on_launch` is to signal that API clients should prompt the user for (optional) changes at launch time. -Backwards Compatability Concerns +Backwards Compatibility Concerns -------------------------------- -A variety of API clients rely on now-deprecated mechanisms for Credential -retrieval and assignment, and those are still supported in a backwards -compatible way under this new API change. Requests to update -`JobTemplate.credential` and `JobTemplate.vault_credential` will still behave -as they did before: +Requests to update `JobTemplate.credential` and `JobTemplate.vault_credential` +will no longer work. Example request format: `PATCH /api/v2/job_templates/N/ {'credential': X, 'vault_credential': Y}` -If the job template (with pk=N) only has 1 vault credential, -that will be replaced with the new `Y` vault credential. +This request will have no effect because support for using these +fields has been removed. -If the job template has multiple vault credentials, and these do not include -`Y`, then the new list will _only_ contain the single vault credential `Y` -specified in the deprecated request. - -If the JobTemplate already has the `Y` vault credential associated with it, -then no change will take effect (the other vault credentials will not be -removed in this case). This is so that clients making deprecated requests -do not interfere with clients using the new `credentials` relation. +The relationship `extra_credentials` is deprecated but still supported for now. +Clients should favor the `credentials` relationship instead. `GET` requests to `/api/v2/job_templates/N/` and `/api/v2/jobs/N/` -have traditionally included a variety of metadata in the response via -`related_fields`: +will include this via `related_fields`: ``` { "related": { ... - "credential": "/api/v2/credentials/1/", - "vault_credential": "/api/v2/credentials/3/", + "credentials": "/api/v2/job_templates/5/credentials/", "extra_credentials": "/api/v2/job_templates/5/extra_credentials/", } } ``` -...and `summary_fields`: +...and `summary_fields`, which is not included in list views: ``` { "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" - }, + "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" + } + ], "extra_credentials": [ { "description": "", @@ -159,16 +150,15 @@ have traditionally included a variety of metadata in the response via } ``` -These metadata will continue to exist and function in a backwards-compatible way. +The only difference between `credentials` and `extra_credentials` is that the +latter is filtered to only show "cloud" type credentials, whereas the former +can be used to manage all types of related credentials. -The `/api/v2/job_templates/N/extra_credentials` endpoint has been deprecated, but -will also continue to exist and function in the same manner for multiple releases. - -The `/api/v2/job_templates/N/launch/` endpoint also provides -deprecated,backwards compatible support for specifying credentials at launch time -via the `credential`, `vault_credential`, and `extra_credentials` fields: - -`POST /api/v2/job_templates/N/launch/ {'credential': A, 'vault_credential': B, 'extra_credentials': [C, D]}` +The `/api/v2/job_templates/N/launch/` endpoint no longer provides +backwards compatible support for specifying credentials at launch time +via the `credential` or `vault_credential` fields. +The launch endpoint can still accept a list under the `extra_credentials` key, +but this is deprecated in favor `credentials`. Specifying Multiple Vault Credentials diff --git a/docs/prompting.md b/docs/prompting.md index a1612657b9..bbc0dc1b51 100644 --- a/docs/prompting.md +++ b/docs/prompting.md @@ -21,7 +21,7 @@ The standard pattern applies to fields - `diff_mode` - `verbosity` -##### Non-Standard Cases (Credentials Changing in Tower 3.3) +##### Non-Standard Cases - `ask_variables_on_launch` allows unrestricted use of - `extra_vars` @@ -30,9 +30,7 @@ The standard pattern applies to fields - Enabled survey allows restricted use of - `extra_vars`, only for variables in survey (with qualifiers) - `ask_credential_on_launch` allows use of - - `credential` - - `vault_credential` / `extra_credentials` / `credentials` - (version-dependent, see notes below) + - `credentials` - `ask_inventory_on_launch` allows use of - `inventory` @@ -42,16 +40,12 @@ spec to exist and `survey_enabled` to be true). On the other hand, if `ask_variables_on_launch` is true, users can provide any variables in extra_vars. -_(supported, but deprecated)_ Prompting enablement for several types of -credentials is controlled by a single -field. On launch, multiple types of credentials can be provided in their respective fields -inside of `credential`, `vault_credential`, and `extra_credentials`. Providing -credentials that require password input from the user on launch is -allowed, and the password must be provided along-side the credential, of course. - -If the job is being spawned using a saved launch configuration, -all credential types are managed by a many-to-many relationship -called `credentials` relative to the launch configuration object. +Prompting enablement for all types of credentials is controlled by `ask_credential_on_launch`. +Clients can manually provide a list of credentials of any type, but only 1 of _each_ type, in +`credentials` on a POST to the launch endpoint. +If the job is being spawned by a saved launch configuration (such as a schedule), +credentials are managed by the many-to-many relationship `credentials` relative +to the launch configuration object. The credentials in this relationship will either add to the job template's credential list, or replace a credential in the job template's list if it is the same type. @@ -69,9 +63,9 @@ actions in the API. - can accept certain fields, with no user configuration When launching manually, certain restrictions apply to the use of credentials - - if providing any of `credential`, `vault_credential`, and `extra_credentials` - this becomes the "legacy" method, and imposes additional restrictions on - relaunch, and is mutually exclusive with the use of `credentials` field + - if providing deprecated `extra_credentials` this becomes the "legacy" method, + and imposes additional restrictions on relaunch, + and is mutually exclusive with the use of `credentials` field - if providing `credentials`, existing credentials on the job template may only be removed if replaced by another credential of the same type this is so that relaunch will use the up-to-date credential on the template