From 85ffdb9802498e85d6bec420fc9d8acd5b301db6 Mon Sep 17 00:00:00 2001 From: Andrew Lytvynov Date: Wed, 30 May 2018 15:50:04 -0700 Subject: [PATCH 1/5] Update exec plugin docs with TLS credentials kubernetes/kubernetes#61803 implements TLS client credential support for 1.11. --- .../access-authn-authz/authentication.md | 26 ++++++++++++++----- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/content/en/docs/reference/access-authn-authz/authentication.md b/content/en/docs/reference/access-authn-authz/authentication.md index 81be4a8dfb69d..90a1a0eb78178 100644 --- a/content/en/docs/reference/access-authn-authz/authentication.md +++ b/content/en/docs/reference/access-authn-authz/authentication.md @@ -789,24 +789,34 @@ include metadata about the response. } ``` -The executed command is expected to print an `ExceCredential` to `stdout`. `k8s.io/client-go` -will then use the returned bearer token in the `status` when authenticating against the +The executed command is expected to print an `ExceCredential` to `stdout`. +`k8s.io/client-go` will then use the returned bearer token and/or client TLS +key and certificate from the `status` field when authenticating against the Kubernetes API. +- The returned status may contain `token`, `clientCertificateData` and + `clientKeyData`, or all three +- `clientCertificateData` and `clientKeyData` must be provided together +- `clientCertificateData` may contain additional intermediate certificates to + send to the server + ```json { "apiVersion": "client.authentication.k8s.io/v1alpha1", "kind": "ExecCredential", "status": { - "token": "my-bearer-token" + "token": "my-bearer-token", + "clientCertificateData": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", + "clientKeyData": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----" } } ``` -Optionally, this output can include the expiry of the token formatted as a RFC3339 timestamp. -If an expiry is omitted, the bearer token is cached until the server responds with a 401 HTTP -status code. Note that this caching is only for the duration of process and therefore the plugin -is triggered each time the tool using the plugin is invoked. +Optionally, this output can include the expiry of the token formatted as a +RFC3339 timestamp. If an expiry is omitted, the bearer token and TLS +credentials are cached until the server responds with a 401 HTTP status code. +Note that this caching is only for the duration of process and therefore the +plugin is triggered each time the tool using the plugin is invoked. ```json { @@ -814,6 +824,8 @@ is triggered each time the tool using the plugin is invoked. "kind": "ExecCredential", "status": { "token": "my-bearer-token", + "clientCertificateData": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", + "clientKeyData": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----", "expirationTimestamp": "2018-03-05T17:30:20-08:00" } } From bd80083fa2b2260c838cadd78b4ae432c9d05dd4 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Wed, 6 Jun 2018 14:27:24 -0700 Subject: [PATCH 2/5] Copyedit --- .../access-authn-authz/authentication.md | 28 ++++++++----------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/content/en/docs/reference/access-authn-authz/authentication.md b/content/en/docs/reference/access-authn-authz/authentication.md index 90a1a0eb78178..2063ce7baf293 100644 --- a/content/en/docs/reference/access-authn-authz/authentication.md +++ b/content/en/docs/reference/access-authn-authz/authentication.md @@ -766,10 +766,10 @@ KUBERNETES_EXEC_INFO='{ ``` When plugins are executed from an interactive session, `stdin` and `stderr` are directly -exposed to the plugin so it can prompt the user for input for interactive logins. +exposed to the plugin so the user can provide input for interactive logins. -When responding to a 401 HTTP status code (indicating invalid credentials), this object will -include metadata about the response. +When responding to a 401 HTTP status code, which indicates invalid credentials, this object +includes metadata about the response. ```json { @@ -789,16 +789,13 @@ include metadata about the response. } ``` -The executed command is expected to print an `ExceCredential` to `stdout`. -`k8s.io/client-go` will then use the returned bearer token and/or client TLS -key and certificate from the `status` field when authenticating against the -Kubernetes API. - -- The returned status may contain `token`, `clientCertificateData` and - `clientKeyData`, or all three -- `clientCertificateData` and `clientKeyData` must be provided together -- `clientCertificateData` may contain additional intermediate certificates to - send to the server +When the plugin prints `ExecCredential` to `stdout`, the `k8s.io/cient-go` library +looks for a bearer token or client TLS key and certificate (or all three) in the +`status` field and uses it to authenticate against the Kubernetes API. The library can +use a bearer token on its own (`token`), a client TLS key and certificate +(`clientKeyData` and `clientCertificateData`; both must be present), or a combination +of both methods. `clientCertificateData` may contain additional intermediate +certificates to send to the server. ```json { @@ -814,9 +811,8 @@ Kubernetes API. Optionally, this output can include the expiry of the token formatted as a RFC3339 timestamp. If an expiry is omitted, the bearer token and TLS -credentials are cached until the server responds with a 401 HTTP status code. -Note that this caching is only for the duration of process and therefore the -plugin is triggered each time the tool using the plugin is invoked. +credentials are cached until the server responds with a 401 HTTP status code +or until the process completes. ```json { From 907f964c5fc8d28620941ac8e07e3603f73145c2 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Wed, 6 Jun 2018 14:45:55 -0700 Subject: [PATCH 3/5] More copyedits for clarification --- .../reference/access-authn-authz/authentication.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/content/en/docs/reference/access-authn-authz/authentication.md b/content/en/docs/reference/access-authn-authz/authentication.md index 2063ce7baf293..b07db8b0720fc 100644 --- a/content/en/docs/reference/access-authn-authz/authentication.md +++ b/content/en/docs/reference/access-authn-authz/authentication.md @@ -809,10 +809,15 @@ certificates to send to the server. } ``` -Optionally, this output can include the expiry of the token formatted as a -RFC3339 timestamp. If an expiry is omitted, the bearer token and TLS -credentials are cached until the server responds with a 401 HTTP status code -or until the process completes. +Optionally, the response can include the expiry of the token formatted as a +RFC3339 timestamp. Presence or absense of an expiry has the following impact: + +- If an expiry is included, the bearer token and TLS credentials are cached until + the expiry time is reached, or if the server responds with a 401 HTTP status code, + or when the process exits. +- If an expiry is omitted, the bearer token and TLS credentials are cached until + the server responds with a 401 HTTP status code or until the process exits. + ```json { From 7f6c52558becdc329ae50aef02c8fca1544ae4c4 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Wed, 6 Jun 2018 15:56:44 -0700 Subject: [PATCH 4/5] Additional copyedit --- content/en/docs/reference/access-authn-authz/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/reference/access-authn-authz/authentication.md b/content/en/docs/reference/access-authn-authz/authentication.md index b07db8b0720fc..75bdd2cabc736 100644 --- a/content/en/docs/reference/access-authn-authz/authentication.md +++ b/content/en/docs/reference/access-authn-authz/authentication.md @@ -789,7 +789,7 @@ includes metadata about the response. } ``` -When the plugin prints `ExecCredential` to `stdout`, the `k8s.io/cient-go` library +After the plugin outputs an `ExecCredential` structure to `stdout`, the `k8s.io/cient-go` library looks for a bearer token or client TLS key and certificate (or all three) in the `status` field and uses it to authenticate against the Kubernetes API. The library can use a bearer token on its own (`token`), a client TLS key and certificate From 15a01acee1895942c53f06a769c957f7ee18883f Mon Sep 17 00:00:00 2001 From: Andrew Lytvynov Date: Mon, 11 Jun 2018 15:31:21 -0700 Subject: [PATCH 5/5] Change token->credential --- content/en/docs/reference/access-authn-authz/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/reference/access-authn-authz/authentication.md b/content/en/docs/reference/access-authn-authz/authentication.md index 75bdd2cabc736..c186cc8cf9594 100644 --- a/content/en/docs/reference/access-authn-authz/authentication.md +++ b/content/en/docs/reference/access-authn-authz/authentication.md @@ -809,7 +809,7 @@ certificates to send to the server. } ``` -Optionally, the response can include the expiry of the token formatted as a +Optionally, the response can include the expiry of the credential formatted as a RFC3339 timestamp. Presence or absense of an expiry has the following impact: - If an expiry is included, the bearer token and TLS credentials are cached until