Skip to content

Commit 03b5de4

Browse files
tengqmtengqm
authored
Kubelet config v1alpha1 (#30859)
* Add config API for kubelet v1alpha1 The CredentialProvider struct is defined in the v1alpha1 config API rather than v1beta1. The upstream generator is updated to include this version (kubernetes-sigs/reference-docs#268). This commit adds references to the API as well. * Wrap long lines in the page
1 parent efa89a4 commit 03b5de4

File tree

3 files changed

+312
-16
lines changed

3 files changed

+312
-16
lines changed

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@ by the API server in a RESTful way though they are essential for a user or an
7474
operator to use or manage a cluster.
7575

7676
* [kube-apiserver configuration (v1beta1)](/docs/reference/config-api/apiserver-config.v1beta1/)
77+
* [kubelet configuration (v1alpha1)](/docs/reference/config-api/kubelet-config.v1alpha1/)
7778
* [kubelet configuration (v1beta1)](/docs/reference/config-api/kubelet-config.v1beta1/)
7879
* [kube-scheduler configuration (v1beta2)](/docs/reference/config-api/kube-scheduler-config.v1beta2/)
7980
* [kube-scheduler configuration (v1beta3)](/docs/reference/config-api/kube-scheduler-config.v1beta3/)

‎content/en/docs/reference/config-api/kubelet-config.v1alpha1.md

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
---
2+
title: Kubelet Configuration (v1alpha1)
3+
content_type: tool-reference
4+
package: kubelet.config.k8s.io/v1alpha1
5+
auto_generated: true
6+
---
7+
8+
9+
## Resource Types
10+
11+
12+
- [CredentialProviderConfig](#kubelet-config-k8s-io-v1alpha1-CredentialProviderConfig)
13+
14+
15+
16+
## `FormatOptions` {#FormatOptions}
17+
18+
19+
20+
21+
**Appears in:**
22+
23+
- [LoggingConfiguration](#LoggingConfiguration)
24+
25+
26+
FormatOptions contains options for the different logging formats.
27+
28+
<table class="table">
29+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
30+
<tbody>
31+
32+
33+
34+
<tr><td><code>json</code> <B>[Required]</B><br/>
35+
<a href="#JSONOptions"><code>JSONOptions</code></a>
36+
</td>
37+
<td>
38+
[Experimental] JSON contains options for logging format "json".</td>
39+
</tr>
40+
41+
42+
</tbody>
43+
</table>
44+
45+
## `JSONOptions` {#JSONOptions}
46+
47+
48+
49+
50+
**Appears in:**
51+
52+
- [FormatOptions](#FormatOptions)
53+
54+
55+
JSONOptions contains options for logging format "json".
56+
57+
<table class="table">
58+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
59+
<tbody>
60+
61+
62+
63+
<tr><td><code>splitStream</code> <B>[Required]</B><br/>
64+
<code>bool</code>
65+
</td>
66+
<td>
67+
[Experimental] SplitStream redirects error messages to stderr while
68+
info messages go to stdout, with buffering. The default is to write
69+
both to stdout, without buffering.</td>
70+
</tr>
71+
72+
73+
<tr><td><code>infoBufferSize</code> <B>[Required]</B><br/>
74+
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#QuantityValue"><code>k8s.io/apimachinery/pkg/api/resource.QuantityValue</code></a>
75+
</td>
76+
<td>
77+
[Experimental] InfoBufferSize sets the size of the info stream when
78+
using split streams. The default is zero, which disables buffering.</td>
79+
</tr>
80+
81+
82+
</tbody>
83+
</table>
84+
85+
## `VModuleConfiguration` {#VModuleConfiguration}
86+
87+
(Alias of `[]k8s.io/component-base/config/v1alpha1.VModuleItem`)
88+
89+
90+
**Appears in:**
91+
92+
- [LoggingConfiguration](#LoggingConfiguration)
93+
94+
95+
VModuleConfiguration is a collection of individual file names or patterns
96+
and the corresponding verbosity threshold.
97+
98+
99+
100+
101+
102+
103+
## `CredentialProviderConfig` {#kubelet-config-k8s-io-v1alpha1-CredentialProviderConfig}
104+
105+
106+
107+
108+
109+
CredentialProviderConfig is the configuration containing information about
110+
each exec credential provider. Kubelet reads this configuration from disk and enables
111+
each provider as specified by the CredentialProvider type.
112+
113+
<table class="table">
114+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
115+
<tbody>
116+
117+
<tr><td><code>apiVersion</code><br/>string</td><td><code>kubelet.config.k8s.io/v1alpha1</code></td></tr>
118+
<tr><td><code>kind</code><br/>string</td><td><code>CredentialProviderConfig</code></td></tr>
119+
120+
121+
122+
123+
<tr><td><code>providers</code> <B>[Required]</B><br/>
124+
<a href="#kubelet-config-k8s-io-v1alpha1-CredentialProvider"><code>[]CredentialProvider</code></a>
125+
</td>
126+
<td>
127+
providers is a list of credential provider plugins that will be enabled by the kubelet.
128+
Multiple providers may match against a single image, in which case credentials
129+
from all providers will be returned to the kubelet. If multiple providers are called
130+
for a single image, the results are combined. If providers return overlapping
131+
auth keys, the value from the provider earlier in this list is used.</td>
132+
</tr>
133+
134+
135+
</tbody>
136+
</table>
137+
138+
139+
140+
## `CredentialProvider` {#kubelet-config-k8s-io-v1alpha1-CredentialProvider}
141+
142+
143+
144+
145+
**Appears in:**
146+
147+
- [CredentialProviderConfig](#kubelet-config-k8s-io-v1alpha1-CredentialProviderConfig)
148+
149+
150+
CredentialProvider represents an exec plugin to be invoked by the kubelet. The plugin is only
151+
invoked when an image being pulled matches the images handled by the plugin (see matchImages).
152+
153+
<table class="table">
154+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
155+
<tbody>
156+
157+
158+
159+
<tr><td><code>name</code> <B>[Required]</B><br/>
160+
<code>string</code>
161+
</td>
162+
<td>
163+
name is the required name of the credential provider. It must match the name of the
164+
provider executable as seen by the kubelet. The executable must be in the kubelet's
165+
bin directory (set by the --image-credential-provider-bin-dir flag).</td>
166+
</tr>
167+
168+
169+
<tr><td><code>matchImages</code> <B>[Required]</B><br/>
170+
<code>[]string</code>
171+
</td>
172+
<td>
173+
matchImages is a required list of strings used to match against images in order to
174+
determine if this provider should be invoked. If one of the strings matches the
175+
requested image from the kubelet, the plugin will be invoked and given a chance
176+
to provide credentials. Images are expected to contain the registry domain
177+
and URL path.
178+
179+
Each entry in matchImages is a pattern which can optionally contain a port and a path.
180+
Globs can be used in the domain, but not in the port or the path. Globs are supported
181+
as subdomains like '&lowast;.k8s.io' or 'k8s.&lowast;.io', and top-level-domains such as 'k8s.&lowast;'.
182+
Matching partial subdomains like 'app&lowast;.k8s.io' is also supported. Each glob can only match
183+
a single subdomain segment, so &lowast;.io does not match &lowast;.k8s.io.
184+
185+
A match exists between an image and a matchImage when all of the below are true:
186+
- Both contain the same number of domain parts and each part matches.
187+
- The URL path of an imageMatch must be a prefix of the target image URL path.
188+
- If the imageMatch contains a port, then the port must match in the image as well.
189+
190+
Example values of matchImages:
191+
- 123456789.dkr.ecr.us-east-1.amazonaws.com
192+
- &lowast;.azurecr.io
193+
- gcr.io
194+
- &lowast;.&lowast;.registry.io
195+
- registry.io:8080/path</td>
196+
</tr>
197+
198+
199+
<tr><td><code>defaultCacheDuration</code> <B>[Required]</B><br/>
200+
<a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
201+
</td>
202+
<td>
203+
defaultCacheDuration is the default duration the plugin will cache credentials in-memory
204+
if a cache duration is not provided in the plugin response. This field is required.</td>
205+
</tr>
206+
207+
208+
<tr><td><code>apiVersion</code> <B>[Required]</B><br/>
209+
<code>string</code>
210+
</td>
211+
<td>
212+
Required input version of the exec CredentialProviderRequest. The returned CredentialProviderResponse
213+
MUST use the same encoding version as the input. Current supported values are:
214+
- credentialprovider.kubelet.k8s.io/v1alpha1</td>
215+
</tr>
216+
217+
218+
<tr><td><code>args</code><br/>
219+
<code>[]string</code>
220+
</td>
221+
<td>
222+
Arguments to pass to the command when executing it.</td>
223+
</tr>
224+
225+
226+
<tr><td><code>env</code><br/>
227+
<a href="#kubelet-config-k8s-io-v1alpha1-ExecEnvVar"><code>[]ExecEnvVar</code></a>
228+
</td>
229+
<td>
230+
Env defines additional environment variables to expose to the process. These
231+
are unioned with the host's environment, as well as variables client-go uses
232+
to pass argument to the plugin.</td>
233+
</tr>
234+
235+
236+
</tbody>
237+
</table>
238+
239+
240+
241+
## `ExecEnvVar` {#kubelet-config-k8s-io-v1alpha1-ExecEnvVar}
242+
243+
244+
245+
246+
**Appears in:**
247+
248+
- [CredentialProvider](#kubelet-config-k8s-io-v1alpha1-CredentialProvider)
249+
250+
251+
ExecEnvVar is used for setting environment variables when executing an exec-based
252+
credential plugin.
253+
254+
<table class="table">
255+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
256+
<tbody>
257+
258+
259+
260+
<tr><td><code>name</code> <B>[Required]</B><br/>
261+
<code>string</code>
262+
</td>
263+
<td>
264+
<span class="text-muted">No description provided.</span>
265+
</td>
266+
</tr>
267+
268+
269+
<tr><td><code>value</code> <B>[Required]</B><br/>
270+
<code>string</code>
271+
</td>
272+
<td>
273+
<span class="text-muted">No description provided.</span>
274+
</td>
275+
</tr>
276+
277+
278+
</tbody>
279+
</table>
280+
281+

‎content/en/docs/tasks/kubelet-credential-provider/kubelet-credential-provider.md

Lines changed: 30 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ This guide demonstrates how to configure the kubelet's image credential provider
2828
## {{% heading "prerequisites" %}}
2929

3030
* The kubelet image credential provider is introduced in v1.20 as an alpha feature. As with other alpha features,
31-
a feature gate `KubeletCredentialProviders` must be enabled on only the kubelet for the feature to work.
31+
a feature gate `KubeletCredentialProviders` must be enabled on only the kubelet for the feature to work.
3232
* A working implementation of a credential provider exec plugin. You can build your own plugin or use one provided by cloud providers.
3333

3434
<!-- steps -->
@@ -41,17 +41,19 @@ every node in your cluster and stored in a known directory. The directory will b
4141
## Configuring the Kubelet
4242

4343
In order to use this feature, the kubelet expects two flags to be set:
44+
4445
* `--image-credential-provider-config` - the path to the credential provider plugin config file.
4546
* `--image-credential-provider-bin-dir` - the path to the directory where credential provider plugin binaries are located.
4647

4748
### Configure a kubelet credential provider
4849

4950
The configuration file passed into `--image-credential-provider-config` is read by the kubelet to determine which exec plugins
50-
should be invoked for which container images. Here's an example configuration file you may end up using if you are using the [ECR](https://aws.amazon.com/ecr/)-based plugin:
51+
should be invoked for which container images. Here's an example configuration file you may end up using if you are using the
52+
[ECR](https://aws.amazon.com/ecr/)-based plugin:
5153

5254
```yaml
53-
kind: CredentialProviderConfig
5455
apiVersion: kubelet.config.k8s.io/v1alpha1
56+
kind: CredentialProviderConfig
5557
# providers is a list of credential provider plugins that will be enabled by the kubelet.
5658
# Multiple providers may match against a single image, in which case credentials
5759
# from all providers will be returned to the kubelet. If multiple providers are called
@@ -86,11 +88,11 @@ providers:
8688
# - *.*.registry.io
8789
# - registry.io:8080/path
8890
matchImages:
89-
- "*.dkr.ecr.*.amazonaws.com"
90-
- "*.dkr.ecr.*.amazonaws.cn"
91-
- "*.dkr.ecr-fips.*.amazonaws.com"
92-
- "*.dkr.ecr.us-iso-east-1.c2s.ic.gov"
93-
- "*.dkr.ecr.us-isob-east-1.sc2s.sgov.gov"
91+
- "*.dkr.ecr.*.amazonaws.com"
92+
- "*.dkr.ecr.*.amazonaws.cn"
93+
- "*.dkr.ecr-fips.*.amazonaws.com"
94+
- "*.dkr.ecr.us-iso-east-1.c2s.ic.gov"
95+
- "*.dkr.ecr.us-isob-east-1.sc2s.sgov.gov"
9496
# defaultCacheDuration is the default duration the plugin will cache credentials in-memory
9597
# if a cache duration is not provided in the plugin response. This field is required.
9698
defaultCacheDuration: "12h"
@@ -101,23 +103,28 @@ providers:
101103
# Arguments to pass to the command when executing it.
102104
# +optional
103105
args:
104-
- get-credentials
106+
- get-credentials
105107
# Env defines additional environment variables to expose to the process. These
106108
# are unioned with the host's environment, as well as variables client-go uses
107109
# to pass argument to the plugin.
108110
# +optional
109111
env:
110-
- name: AWS_PROFILE
111-
value: example_profile
112+
- name: AWS_PROFILE
113+
value: example_profile
112114
```
113115
114116
The `providers` field is a list of enabled plugins used by the kubelet. Each entry has a few required fields:
115-
* `name`: the name of the plugin which MUST match the name of the executable binary that exists in the directory passed into `--image-credential-provider-bin-dir`.
116-
* `matchImages`: a list of strings used to match against images in order to determine if this provider should be invoked. More on this below.
117-
* `defaultCacheDuration`: the default duration the kubelet will cache credentials in-memory if a cache duration was not specified by the plugin.
118-
* `apiVersion`: the api version that the kubelet and the exec plugin will use when communicating.
119117

120-
Each credential provider can also be given optional args and environment variables as well. Consult the plugin implementors to determine what set of arguments and environment variables are required for a given plugin.
118+
* `name`: the name of the plugin which MUST match the name of the executable binary that exists
119+
in the directory passed into `--image-credential-provider-bin-dir`.
120+
* `matchImages`: a list of strings used to match against images in order to determine
121+
if this provider should be invoked. More on this below.
122+
* `defaultCacheDuration`: the default duration the kubelet will cache credentials in-memory
123+
if a cache duration was not specified by the plugin.
124+
* `apiVersion`: the API version that the kubelet and the exec plugin will use when communicating.
125+
126+
Each credential provider can also be given optional args and environment variables as well.
127+
Consult the plugin implementors to determine what set of arguments and environment variables are required for a given plugin.
121128

122129
#### Configure image matching
123130

@@ -134,8 +141,15 @@ A match exists between an image name and a `matchImage` entry when all of the be
134141
* If the imageMatch contains a port, then the port must match in the image as well.
135142

136143
Some example values of `matchImages` patterns are:
144+
137145
* `123456789.dkr.ecr.us-east-1.amazonaws.com`
138146
* `*.azurecr.io`
139147
* `gcr.io`
140148
* `*.*.registry.io`
141149
* `foo.registry.io:8080/path`
150+
151+
## {{% heading "whatsnext" %}}
152+
153+
* Read the details about `CredentialProviderConfig` in the
154+
[kubelet configuration API (v1alpha1) reference](/docs/reference/config-api/kubelet-config.v1alpha1/).
155+

0 commit comments

Comments
 (0)