Skip to content

Commit 4556399

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #26608 from tengqm/client-auth-config
Add reference for client-authentication v1beta1
2 parents 973caa3 + b28250b commit 4556399

File tree

3 files changed

+264
-1
lines changed

3 files changed

+264
-1
lines changed

‎content/en/docs/reference/_index.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,10 @@ operator to use or manage a cluster.
7676
* [kube-proxy configuration (v1alpha1)](/docs/reference/config-api/kube-proxy-config.v1alpha1/)
7777
* [`audit.k8s.io/v1` API](/docs/reference/config-api/apiserver-audit.v1/)
7878

79+
## Config APIs
80+
81+
* [Client authentication API (v1beta1)](/docs/reference/config-api/client-authentication.v1beta1/)
82+
7983
## Design Docs
8084

8185
An archive of the design docs for Kubernetes functionality. Good starting points are

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

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -955,7 +955,8 @@ When run from an interactive session, `stdin` is exposed directly to the plugin.
955955
[TTY check](https://godoc.org/golang.org/x/crypto/ssh/terminal#IsTerminal) to determine if it's
956956
appropriate to prompt a user interactively.
957957

958-
To use bearer token credentials, the plugin returns a token in the status of the `ExecCredential`.
958+
To use bearer token credentials, the plugin returns a token in the status of the
959+
[`ExecCredential`](/docs/reference/config-api/client-authentication.v1beta1/#client-authentication-k8s-io-v1beta1-ExecCredential)
959960

960961
```json
961962
{
@@ -1005,6 +1006,7 @@ RFC3339 timestamp. Presence or absence of an expiry has the following impact:
10051006
}
10061007
}
10071008
```
1009+
10081010
To enable the exec plugin to obtain cluster-specific information, set `provideClusterInfo` on the `user.exec`
10091011
field in the [kubeconfig](/docs/concepts/configuration/organize-cluster-access-kubeconfig/).
10101012
The plugin will then be supplied with an environment variable, `KUBERNETES_EXEC_INFO`.
@@ -1029,3 +1031,8 @@ The following `ExecCredential` manifest describes a cluster information sample.
10291031
}
10301032
}
10311033
```
1034+
1035+
## {{% heading "whatsnext" %}}
1036+
1037+
* Read the [client authentication reference (v1beta1)](/docs/reference/config-api/client-authentication.v1beta1/)
1038+

‎content/en/docs/reference/config-api/client-authentication.v1beta1.md

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
---
2+
title: Client Authentication (v1beta1)
3+
content_type: tool-reference
4+
package: client.authentication.k8s.io/v1beta1
5+
auto_generated: true
6+
---
7+
8+
9+
## Resource Types
10+
11+
12+
- [ExecCredential](#client-authentication-k8s-io-v1beta1-ExecCredential)
13+
14+
15+
16+
17+
## `ExecCredential` {#client-authentication-k8s-io-v1beta1-ExecCredential}
18+
19+
20+
21+
22+
23+
ExecCredential is used by exec-based plugins to communicate credentials to
24+
HTTP transports.
25+
26+
<table class="table">
27+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
28+
<tbody>
29+
30+
<tr><td><code>apiVersion</code><br/>string</td><td><code>client.authentication.k8s.io/v1beta1</code></td></tr>
31+
<tr><td><code>kind</code><br/>string</td><td><code>ExecCredential</code></td></tr>
32+
33+
34+
35+
36+
<tr><td><code>spec</code> <B>[Required]</B><br/>
37+
<a href="#client-authentication-k8s-io-v1beta1-ExecCredentialSpec"><code>ExecCredentialSpec</code></a>
38+
</td>
39+
<td>
40+
Spec holds information passed to the plugin by the transport.</td>
41+
</tr>
42+
43+
44+
<tr><td><code>status</code><br/>
45+
<a href="#client-authentication-k8s-io-v1beta1-ExecCredentialStatus"><code>ExecCredentialStatus</code></a>
46+
</td>
47+
<td>
48+
Status is filled in by the plugin and holds the credentials that the transport
49+
should use to contact the API.</td>
50+
</tr>
51+
52+
53+
</tbody>
54+
</table>
55+
56+
57+
58+
## `Cluster` {#client-authentication-k8s-io-v1beta1-Cluster}
59+
60+
61+
62+
63+
**Appears in:**
64+
65+
- [ExecCredentialSpec](#client-authentication-k8s-io-v1beta1-ExecCredentialSpec)
66+
67+
68+
Cluster contains information to allow an exec plugin to communicate
69+
with the kubernetes cluster being authenticated to.
70+
71+
To ensure that this struct contains everything someone would need to communicate
72+
with a kubernetes cluster (just like they would via a kubeconfig), the fields
73+
should shadow "k8s.io/client-go/tools/clientcmd/api/v1".Cluster, with the exception
74+
of CertificateAuthority, since CA data will always be passed to the plugin as bytes.
75+
76+
<table class="table">
77+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
78+
<tbody>
79+
80+
81+
82+
<tr><td><code>server</code> <B>[Required]</B><br/>
83+
<code>string</code>
84+
</td>
85+
<td>
86+
Server is the address of the kubernetes cluster (https://hostname:port).</td>
87+
</tr>
88+
89+
90+
<tr><td><code>tls-server-name</code><br/>
91+
<code>string</code>
92+
</td>
93+
<td>
94+
TLSServerName is passed to the server for SNI and is used in the client to
95+
check server certificates against. If ServerName is empty, the hostname
96+
used to contact the server is used.</td>
97+
</tr>
98+
99+
100+
<tr><td><code>insecure-skip-tls-verify</code><br/>
101+
<code>bool</code>
102+
</td>
103+
<td>
104+
InsecureSkipTLSVerify skips the validity check for the server's certificate.
105+
This will make your HTTPS connections insecure.</td>
106+
</tr>
107+
108+
109+
<tr><td><code>certificate-authority-data</code><br/>
110+
<code>[]byte</code>
111+
</td>
112+
<td>
113+
CAData contains PEM-encoded certificate authority certificates.
114+
If empty, system roots should be used.</td>
115+
</tr>
116+
117+
118+
<tr><td><code>proxy-url</code><br/>
119+
<code>string</code>
120+
</td>
121+
<td>
122+
ProxyURL is the URL to the proxy to be used for all requests to this
123+
cluster.</td>
124+
</tr>
125+
126+
127+
<tr><td><code>config</code><br/>
128+
<a href="https://godoc.org/k8s.io/apimachinery/pkg/runtime/#RawExtension"><code>k8s.io/apimachinery/pkg/runtime.RawExtension</code></a>
129+
</td>
130+
<td>
131+
Config holds additional config data that is specific to the exec
132+
plugin with regards to the cluster being authenticated to.
133+
134+
This data is sourced from the clientcmd Cluster object's
135+
extensions[client.authentication.k8s.io/exec] field:
136+
137+
clusters:
138+
- name: my-cluster
139+
cluster:
140+
...
141+
extensions:
142+
- name: client.authentication.k8s.io/exec # reserved extension name for per cluster exec config
143+
extension:
144+
audience: 06e3fbd18de8 # arbitrary config
145+
146+
In some environments, the user config may be exactly the same across many clusters
147+
(i.e. call this exec plugin) minus some details that are specific to each cluster
148+
such as the audience. This field allows the per cluster config to be directly
149+
specified with the cluster info. Using this field to store secret data is not
150+
recommended as one of the prime benefits of exec plugins is that no secrets need
151+
to be stored directly in the kubeconfig.</td>
152+
</tr>
153+
154+
155+
</tbody>
156+
</table>
157+
158+
159+
160+
## `ExecCredentialSpec` {#client-authentication-k8s-io-v1beta1-ExecCredentialSpec}
161+
162+
163+
164+
165+
**Appears in:**
166+
167+
- [ExecCredential](#client-authentication-k8s-io-v1beta1-ExecCredential)
168+
169+
170+
ExecCredentialSpec holds request and runtime specific information provided by
171+
the transport.
172+
173+
<table class="table">
174+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
175+
<tbody>
176+
177+
178+
179+
<tr><td><code>cluster</code><br/>
180+
<a href="#client-authentication-k8s-io-v1beta1-Cluster"><code>Cluster</code></a>
181+
</td>
182+
<td>
183+
Cluster contains information to allow an exec plugin to communicate with the
184+
kubernetes cluster being authenticated to. Note that Cluster is non-nil only
185+
when provideClusterInfo is set to true in the exec provider config (i.e.,
186+
ExecConfig.ProvideClusterInfo).</td>
187+
</tr>
188+
189+
190+
</tbody>
191+
</table>
192+
193+
194+
195+
## `ExecCredentialStatus` {#client-authentication-k8s-io-v1beta1-ExecCredentialStatus}
196+
197+
198+
199+
200+
**Appears in:**
201+
202+
- [ExecCredential](#client-authentication-k8s-io-v1beta1-ExecCredential)
203+
204+
205+
ExecCredentialStatus holds credentials for the transport to use.
206+
207+
Token and ClientKeyData are sensitive fields. This data should only be
208+
transmitted in-memory between client and exec plugin process. Exec plugin
209+
itself should at least be protected via file permissions.
210+
211+
<table class="table">
212+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
213+
<tbody>
214+
215+
216+
217+
<tr><td><code>expirationTimestamp</code><br/>
218+
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#time-v1-meta"><code>meta/v1.Time</code></a>
219+
</td>
220+
<td>
221+
ExpirationTimestamp indicates a time when the provided credentials expire.</td>
222+
</tr>
223+
224+
225+
<tr><td><code>token</code> <B>[Required]</B><br/>
226+
<code>string</code>
227+
</td>
228+
<td>
229+
Token is a bearer token used by the client for request authentication.</td>
230+
</tr>
231+
232+
233+
<tr><td><code>clientCertificateData</code> <B>[Required]</B><br/>
234+
<code>string</code>
235+
</td>
236+
<td>
237+
PEM-encoded client TLS certificates (including intermediates, if any).</td>
238+
</tr>
239+
240+
241+
<tr><td><code>clientKeyData</code> <B>[Required]</B><br/>
242+
<code>string</code>
243+
</td>
244+
<td>
245+
PEM-encoded private key for the above certificate.</td>
246+
</tr>
247+
248+
249+
</tbody>
250+
</table>
251+
252+

0 commit comments

Comments
 (0)