exec credential provider: v1 documentation

content/en/docs/reference/access-authn-authz/authentication.md

@@ -836,7 +836,7 @@ rules:
 
 ## client-go credential plugins
 
-{{< feature-state for_k8s_version="v1.11" state="beta" >}}
+{{< feature-state for_k8s_version="v1.22" state="stable" >}}
 
 `k8s.io/client-go` and tools using it such as `kubectl` and `kubelet` are able to execute an
 external command to receive user credentials.
@@ -867,6 +867,8 @@ To authenticate against the API:
 Credential plugins are configured through [kubectl config files](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)
 as part of the user fields.
 
+{{< tabs name="exec_plugin_kubeconfig_example_1" >}}
+{{% tab name="client.authentication.k8s.io/v1" %}}
 ```yaml
 apiVersion: v1
 kind: Config
@@ -882,7 +884,81 @@ users:
       # The API version returned by the plugin MUST match the version listed here.
       #
       # To integrate with tools that support multiple versions (such as client.authentication.k8s.io/v1alpha1),
-      # set an environment variable or pass an argument to the tool that indicates which version the exec plugin expects.
+      # set an environment variable, pass an argument to the tool that indicates which version the exec plugin expects,
+      # or read the version from the ExecCredential object in the KUBERNETES_EXEC_INFO environment variable.
+      apiVersion: "client.authentication.k8s.io/v1"
+
+      # Environment variables to set when executing the plugin. Optional.
+      env:
+      - name: "FOO"
+        value: "bar"
+
+      # Arguments to pass when executing the plugin. Optional.
+      args:
+      - "arg1"
+      - "arg2"
+
+      # Text shown to the user when the executable doesn't seem to be present. Optional.
+      installHint: |
+        example-client-go-exec-plugin is required to authenticate
+        to the current cluster.  It can be installed:
+
+        On macOS: brew install example-client-go-exec-plugin
+
+        On Ubuntu: apt-get install example-client-go-exec-plugin
+
+        On Fedora: dnf install example-client-go-exec-plugin
+
+        ...
+
+      # Whether or not to provide cluster information, which could potentially contain
+      # very large CA data, to this exec plugin as a part of the KUBERNETES_EXEC_INFO
+      # environment variable.
+      provideClusterInfo: true
+
+      # The contract between the exec plugin and the standard input I/O stream. If the
+      # contract cannot be satisfied, this plugin will not be run and an error will be
+      # returned. Valid values are "Never" (this exec plugin never uses standard input),
+      # "IfAvailable" (this exec plugin wants to use standard input if it is available),
+      # or "Always" (this exec plugin requires standard input to function). Required.
+      interactiveMode: Never
+clusters:
+- name: my-cluster
+  cluster:
+    server: "https://172.17.4.100:6443"
+    certificate-authority: "/etc/kubernetes/ca.pem"
+    extensions:
+    - name: client.authentication.k8s.io/exec # reserved extension name for per cluster exec config
+      extension:
+        arbitrary: config
+        this: can be provided via the KUBERNETES_EXEC_INFO environment variable upon setting provideClusterInfo
+        you: ["can", "put", "anything", "here"]
+contexts:
+- name: my-cluster
+  context:
+    cluster: my-cluster
+    user: my-user
+current-context: my-cluster
+```
+{{% /tab %}}
+{{% tab name="client.authentication.k8s.io/v1beta1" %}}
+```yaml
+apiVersion: v1
+kind: Config
+users:
+- name: my-user
+  user:
+    exec:
+      # Command to execute. Required.
+      command: "example-client-go-exec-plugin"
+
+      # API version to use when decoding the ExecCredentials resource. Required.
+      #
+      # The API version returned by the plugin MUST match the version listed here.
+      #
+      # To integrate with tools that support multiple versions (such as client.authentication.k8s.io/v1alpha1),
+      # set an environment variable, pass an argument to the tool that indicates which version the exec plugin expects,
+      # or read the version from the ExecCredential object in the KUBERNETES_EXEC_INFO environment variable.
       apiVersion: "client.authentication.k8s.io/v1beta1"
 
       # Environment variables to set when executing the plugin. Optional.
@@ -912,6 +988,14 @@ users:
       # very large CA data, to this exec plugin as a part of the KUBERNETES_EXEC_INFO
       # environment variable.
       provideClusterInfo: true
+
+      # The contract between the exec plugin and the standard input I/O stream. If the
+      # contract cannot be satisfied, this plugin will not be run and an error will be
+      # returned. Valid values are "Never" (this exec plugin never uses standard input),
+      # "IfAvailable" (this exec plugin wants to use standard input if it is available),
+      # or "Always" (this exec plugin requires standard input to function). Optional.
+      # Defaults to "IfAvailable".
+      interactiveMode: Never
 clusters:
 - name: my-cluster
   cluster:
@@ -930,6 +1014,8 @@ contexts:
     user: my-user
 current-context: my-cluster
 ```
+{{% /tab %}}
+{{< /tabs >}}
 
 Relative command paths are interpreted as relative to the directory of the config file. If
 KUBECONFIG is set to `/home/jane/kubeconfig` and the exec command is `./bin/example-client-go-exec-plugin`,
@@ -941,21 +1027,53 @@ the binary `/home/jane/bin/example-client-go-exec-plugin` is executed.
     exec:
       # Path relative to the directory of the kubeconfig
       command: "./bin/example-client-go-exec-plugin"
-      apiVersion: "client.authentication.k8s.io/v1beta1"
+      apiVersion: "client.authentication.k8s.io/v1"
+      interactiveMode: Never
 ```
 
 ### Input and output formats
 
 The executed command prints an `ExecCredential` object to `stdout`. `k8s.io/client-go`
 authenticates against the Kubernetes API using the returned credentials in the `status`.
-
-When run from an interactive session, `stdin` is exposed directly to the plugin. Plugins should use a
-[TTY check](https://godoc.org/golang.org/x/crypto/ssh/terminal#IsTerminal) to determine if it's
-appropriate to prompt a user interactively.
+The executed command is passed an `ExecCredential` object as input via the `KUBERNETES_EXEC_INFO`
+environment variable. This input contains helpful information like the expected API version
+of the returned `ExecCredential` object and whether or not the plugin can use `stdin` to interact
+with the user.
+
+When run from an interactive session (i.e., a terminal), `stdin` can be exposed directly
+to the plugin. Plugins should use the `spec.interactive` field of the input
+`ExecCredential` object from the `KUBERNETES_EXEC_INFO` environment variable in order to
+determine if `stdin` has been provided. A plugin's `stdin` requirements (i.e., whether
+`stdin` is optional, strictly required, or never used in order for the plugin
+to run successfully) is declared via the `user.exec.interactiveMode` field in the
+[kubeconfig](/docs/concepts/configuration/organize-cluster-access-kubeconfig/) (see table
+below for valid values). The `user.exec.interactiveMode` field is optional in `client.authentication.k8s.io/v1beta1`
+and required in `client.authentication.k8s.io/v1`.
+
+{{< table caption="interactiveMode values" >}}
+| `interactiveMode` Value | Meaning |
+| ----------------------- | ------- |
+| `Never` | This exec plugin never needs to use standard input, and therefore the exec plugin will be run regardless of whether standard input is available for user input. |
+| `IfAvailable` | This exec plugin would like to use standard input if it is available, but can still operate if standard input is not available. Therefore, the exec plugin will be run regardless of whether stdin is available for user input. If standard input is available for user input, then it will be provided to this exec plugin. |
+| `Always` | This exec plugin requires standard input in order to run, and therefore the exec plugin will only be run if standard input is available for user input. If standard input is not available for user input, then the exec plugin will not be run and an error will be returned by the exec plugin runner. |
+{{< /table >}}
 
 To use bearer token credentials, the plugin returns a token in the status of the
 [`ExecCredential`](/docs/reference/config-api/client-authentication.v1beta1/#client-authentication-k8s-io-v1beta1-ExecCredential)
 
+{{< tabs name="exec_plugin_ExecCredential_example_1" >}}
+{{% tab name="client.authentication.k8s.io/v1" %}}
+```json
+{
+  "apiVersion": "client.authentication.k8s.io/v1",
+  "kind": "ExecCredential",
+  "status": {
+    "token": "my-bearer-token"
+  }
+}
+```
+{{% /tab %}}
+{{% tab name="client.authentication.k8s.io/v1beta1" %}}
 ```json
 {
   "apiVersion": "client.authentication.k8s.io/v1beta1",
@@ -965,6 +1083,8 @@ To use bearer token credentials, the plugin returns a token in the status of the
   }
 }
 ```
+{{% /tab %}}
+{{< /tabs >}}
 
 Alternatively, a PEM-encoded client certificate and key can be returned to use TLS client auth.
 If the plugin returns a different certificate and key on a subsequent call, `k8s.io/client-go`
@@ -974,6 +1094,20 @@ If specified, `clientKeyData` and `clientCertificateData` must both must be pres
 
 `clientCertificateData` may contain additional intermediate certificates to send to the server.
 
+{{< tabs name="exec_plugin_ExecCredential_example_2" >}}
+{{% tab name="client.authentication.k8s.io/v1" %}}
+```json
+{
+  "apiVersion": "client.authentication.k8s.io/v1",
+  "kind": "ExecCredential",
+  "status": {
+    "clientCertificateData": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
+    "clientKeyData": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
+  }
+}
+```
+{{% /tab %}}
+{{% tab name="client.authentication.k8s.io/v1beta1" %}}
 ```json
 {
   "apiVersion": "client.authentication.k8s.io/v1beta1",
@@ -984,6 +1118,8 @@ If specified, `clientKeyData` and `clientCertificateData` must both must be pres
   }
 }
 ```
+{{% /tab %}}
+{{< /tabs >}}
 
 Optionally, the response can include the expiry of the credential formatted as a
 RFC3339 timestamp. Presence or absence of an expiry has the following impact:
@@ -994,6 +1130,20 @@ RFC3339 timestamp. Presence or absence of an expiry has the following impact:
 - 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.
 
+{{< tabs name="exec_plugin_ExecCredential_example_3" >}}
+{{% tab name="client.authentication.k8s.io/v1" %}}
+```json
+{
+  "apiVersion": "client.authentication.k8s.io/v1",
+  "kind": "ExecCredential",
+  "status": {
+    "token": "my-bearer-token",
+    "expirationTimestamp": "2018-03-05T17:30:20-08:00"
+  }
+}
+```
+{{% /tab %}}
+{{% tab name="client.authentication.k8s.io/v1beta1" %}}
 ```json
 {
   "apiVersion": "client.authentication.k8s.io/v1beta1",
@@ -1004,14 +1154,38 @@ RFC3339 timestamp. Presence or absence of an expiry has the following impact:
   }
 }
 ```
+{{% /tab %}}
+{{< /tabs >}}
 
 To enable the exec plugin to obtain cluster-specific information, set `provideClusterInfo` on the `user.exec`
 field in the [kubeconfig](/docs/concepts/configuration/organize-cluster-access-kubeconfig/).
-The plugin will then be supplied with an environment variable, `KUBERNETES_EXEC_INFO`.
+The plugin will then be supplied this cluster-specific information in the `KUBERNETES_EXEC_INFO` environment variable.
 Information from this environment variable can be used to perform cluster-specific
 credential acquisition logic.
 The following `ExecCredential` manifest describes a cluster information sample.
 
+{{< tabs name="exec_plugin_ExecCredential_example_4" >}}
+{{% tab name="client.authentication.k8s.io/v1" %}}
+```json
+{
+  "apiVersion": "client.authentication.k8s.io/v1",
+  "kind": "ExecCredential",
+  "spec": {
+    "cluster": {
+      "server": "https://172.17.4.100:6443",
+      "certificate-authority-data": "LS0t...",
+      "config": {
+        "arbitrary": "config",
+        "this": "can be provided via the KUBERNETES_EXEC_INFO environment variable upon setting provideClusterInfo",
+        "you": ["can", "put", "anything", "here"]
+      }
+    },
+    "interactive": true
+  }
+}
+```
+{{% /tab %}}
+{{% tab name="client.authentication.k8s.io/v1beta1" %}}
 ```json
 {
   "apiVersion": "client.authentication.k8s.io/v1beta1",
@@ -1025,12 +1199,14 @@ The following `ExecCredential` manifest describes a cluster information sample.
         "this": "can be provided via the KUBERNETES_EXEC_INFO environment variable upon setting provideClusterInfo",
         "you": ["can", "put", "anything", "here"]
       }
-    }
+    },
+    "interactive": true
   }
 }
 ```
+{{% /tab %}}
+{{< /tabs >}}
 
 ## {{% heading "whatsnext" %}}
 
 * Read the [client authentication reference (v1beta1)](/docs/reference/config-api/client-authentication.v1beta1/)
-