Skip to content

Commit 2856c88

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #33788 from tengqm/imagepolicy-api
Add imagepolicy.v1alpha1 API
2 parents 4a7ecb8 + c992c4c commit 2856c88

File tree

3 files changed

+183
-14
lines changed

3 files changed

+183
-14
lines changed

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ operator to use or manage a cluster.
7777
* [kube-apiserver configuration (v1alpha1)](/docs/reference/config-api/apiserver-config.v1alpha1/)
7878
* [kube-apiserver configuration (v1)](/docs/reference/config-api/apiserver-config.v1/)
7979
* [kube-apiserver encryption (v1)](/docs/reference/config-api/apiserver-encryption.v1/)
80+
* [kube-apiserver event rate limit (v1alpha1)](/docs/reference/config-api/apiserver-eventratelimit.v1/)
8081
* [kubelet configuration (v1alpha1)](/docs/reference/config-api/kubelet-config.v1alpha1/) and
8182
[kubelet configuration (v1beta1)](/docs/reference/config-api/kubelet-config.v1beta1/)
8283
* [kubelet credential providers (v1alpha1)](/docs/reference/config-api/kubelet-credentialprovider.v1alpha1/)
@@ -88,6 +89,7 @@ operator to use or manage a cluster.
8889
* [Client authentication API (v1beta1)](/docs/reference/config-api/client-authentication.v1beta1/) and
8990
[Client authentication API (v1)](/docs/reference/config-api/client-authentication.v1/)
9091
* [WebhookAdmission configuration (v1)](/docs/reference/config-api/apiserver-webhookadmission.v1/)
92+
* [ImagePolicy API (v1alpha1)](/docs/reference/config-api/imagepolicy.v1alpha1/)
9193

9294
## Config API for kubeadm
9395

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

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -356,19 +356,21 @@ users:
356356
For additional HTTP configuration, refer to the
357357
[kubeconfig](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) documentation.
358358

359-
#### Request Payloads
359+
#### Request payloads
360360

361361
When faced with an admission decision, the API Server POSTs a JSON serialized
362362
`imagepolicy.k8s.io/v1alpha1` `ImageReview` object describing the action.
363363
This object contains fields describing the containers being admitted, as well as
364364
any pod annotations that match `*.image-policy.k8s.io/*`.
365365

366-
Note that webhook API objects are subject to the same versioning compatibility rules
366+
{{ note }}
367+
The webhook API objects are subject to the same versioning compatibility rules
367368
as other Kubernetes API objects. Implementers should be aware of looser compatibility
368-
promises for alpha objects and check the "apiVersion" field of the request to
369+
promises for alpha objects and check the `apiVersion` field of the request to
369370
ensure correct deserialization.
370371
Additionally, the API Server must enable the `imagepolicy.k8s.io/v1alpha1` API extensions
371372
group (`--runtime-config=imagepolicy.k8s.io/v1alpha1=true`).
373+
{{ /note }}
372374

373375
An example request body:
374376

@@ -420,8 +422,8 @@ To disallow access, the service would return:
420422
}
421423
```
422424

423-
For further documentation refer to the `imagepolicy.v1alpha1` API objects and
424-
`plugin/pkg/admission/imagepolicy/admission.go`.
425+
For further documentation refer to the
426+
[`imagepolicy.v1alpha1` API](/docs/reference/config-api/imagepolicy.v1alpha1/).
425427

426428
#### Extending with Annotations
427429

@@ -432,9 +434,9 @@ accept different information.
432434

433435
Examples of information you might put here are:
434436

435-
* request to "break glass" to override a policy, in case of emergency.
436-
* a ticket number from a ticket system that documents the break-glass request
437-
* provide a hint to the policy server as to the imageID of the image being provided, to save it a lookup
437+
* request to "break glass" to override a policy, in case of emergency.
438+
* a ticket number from a ticket system that documents the break-glass request
439+
* provide a hint to the policy server as to the imageID of the image being provided, to save it a lookup
438440

439441
In any case, the annotations are provided by the user and are not validated by Kubernetes in any way.
440442

@@ -469,8 +471,7 @@ webhooks or validating admission controllers will permit the request to finish.
469471

470472
If you disable the MutatingAdmissionWebhook, you must also disable the
471473
`MutatingWebhookConfiguration` object in the `admissionregistration.k8s.io/v1`
472-
group/version via the `--runtime-config` flag (both are on by default in
473-
versions >= 1.9).
474+
group/version via the `--runtime-config` flag, both are on by default.
474475

475476
#### Use caution when authoring and installing mutating webhooks
476477

@@ -599,7 +600,7 @@ Starting from 1.11, this admission controller is disabled by default.
599600
This admission controller defaults and limits what node selectors may be used within a namespace
600601
by reading a namespace annotation and a global configuration.
601602

602-
#### Configuration File Format
603+
#### Configuration file format
603604

604605
`PodNodeSelector` uses a configuration file to set options for the behavior of the backend.
605606
Note that the configuration file format will move to a versioned file in a future release.
@@ -649,9 +650,7 @@ This admission controller has the following behavior:
649650
3. Evaluate the pod's node selector against the namespace node selector for conflicts. Conflicts
650651
result in rejection.
651652
4. Evaluate the pod's node selector against the namespace-specific allowed selector defined the
652-
plugin configuration file.
653-
654-
Conflicts result in rejection.
653+
plugin configuration file. Conflicts result in rejection.
655654

656655
{{< note >}}
657656
PodNodeSelector allows forcing pods to run on specifically labeled nodes. Also see the PodTolerationRestriction

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

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
title: Image Policy API (v1alpha1)
3+
content_type: tool-reference
4+
package: imagepolicy.k8s.io/v1alpha1
5+
auto_generated: true
6+
---
7+
8+
9+
## Resource Types
10+
11+
12+
- [ImageReview](#imagepolicy-k8s-io-v1alpha1-ImageReview)
13+
14+
15+
16+
## `ImageReview` {#imagepolicy-k8s-io-v1alpha1-ImageReview}
17+
18+
19+
20+
<p>ImageReview checks if the set of images in a pod are allowed.</p>
21+
22+
23+
<table class="table">
24+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
25+
<tbody>
26+
27+
<tr><td><code>apiVersion</code><br/>string</td><td><code>imagepolicy.k8s.io/v1alpha1</code></td></tr>
28+
<tr><td><code>kind</code><br/>string</td><td><code>ImageReview</code></td></tr>
29+
30+
31+
<tr><td><code>metadata</code><br/>
32+
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#objectmeta-v1-meta"><code>meta/v1.ObjectMeta</code></a>
33+
</td>
34+
<td>
35+
<p>Standard object's metadata.
36+
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata</p>
37+
Refer to the Kubernetes API documentation for the fields of the <code>metadata</code> field.</td>
38+
</tr>
39+
<tr><td><code>spec</code> <B>[Required]</B><br/>
40+
<a href="#imagepolicy-k8s-io-v1alpha1-ImageReviewSpec"><code>ImageReviewSpec</code></a>
41+
</td>
42+
<td>
43+
<p>Spec holds information about the pod being evaluated</p>
44+
</td>
45+
</tr>
46+
<tr><td><code>status</code><br/>
47+
<a href="#imagepolicy-k8s-io-v1alpha1-ImageReviewStatus"><code>ImageReviewStatus</code></a>
48+
</td>
49+
<td>
50+
<p>Status is filled in by the backend and indicates whether the pod should be allowed.</p>
51+
</td>
52+
</tr>
53+
</tbody>
54+
</table>
55+
56+
## `ImageReviewContainerSpec` {#imagepolicy-k8s-io-v1alpha1-ImageReviewContainerSpec}
57+
58+
59+
**Appears in:**
60+
61+
- [ImageReviewSpec](#imagepolicy-k8s-io-v1alpha1-ImageReviewSpec)
62+
63+
64+
<p>ImageReviewContainerSpec is a description of a container within the pod creation request.</p>
65+
66+
67+
<table class="table">
68+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
69+
<tbody>
70+
71+
72+
<tr><td><code>image</code><br/>
73+
<code>string</code>
74+
</td>
75+
<td>
76+
<p>This can be in the form image:tag or image@SHA:012345679abcdef.</p>
77+
</td>
78+
</tr>
79+
</tbody>
80+
</table>
81+
82+
## `ImageReviewSpec` {#imagepolicy-k8s-io-v1alpha1-ImageReviewSpec}
83+
84+
85+
**Appears in:**
86+
87+
- [ImageReview](#imagepolicy-k8s-io-v1alpha1-ImageReview)
88+
89+
90+
<p>ImageReviewSpec is a description of the pod creation request.</p>
91+
92+
93+
<table class="table">
94+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
95+
<tbody>
96+
97+
98+
<tr><td><code>containers</code><br/>
99+
<a href="#imagepolicy-k8s-io-v1alpha1-ImageReviewContainerSpec"><code>[]ImageReviewContainerSpec</code></a>
100+
</td>
101+
<td>
102+
<p>Containers is a list of a subset of the information in each container of the Pod being created.</p>
103+
</td>
104+
</tr>
105+
<tr><td><code>annotations</code><br/>
106+
<code>map[string]string</code>
107+
</td>
108+
<td>
109+
<p>Annotations is a list of key-value pairs extracted from the Pod's annotations.
110+
It only includes keys which match the pattern <code>*.image-policy.k8s.io/*</code>.
111+
It is up to each webhook backend to determine how to interpret these annotations, if at all.</p>
112+
</td>
113+
</tr>
114+
<tr><td><code>namespace</code><br/>
115+
<code>string</code>
116+
</td>
117+
<td>
118+
<p>Namespace is the namespace the pod is being created in.</p>
119+
</td>
120+
</tr>
121+
</tbody>
122+
</table>
123+
124+
## `ImageReviewStatus` {#imagepolicy-k8s-io-v1alpha1-ImageReviewStatus}
125+
126+
127+
**Appears in:**
128+
129+
- [ImageReview](#imagepolicy-k8s-io-v1alpha1-ImageReview)
130+
131+
132+
<p>ImageReviewStatus is the result of the review for the pod creation request.</p>
133+
134+
135+
<table class="table">
136+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
137+
<tbody>
138+
139+
140+
<tr><td><code>allowed</code> <B>[Required]</B><br/>
141+
<code>bool</code>
142+
</td>
143+
<td>
144+
<p>Allowed indicates that all images were allowed to be run.</p>
145+
</td>
146+
</tr>
147+
<tr><td><code>reason</code><br/>
148+
<code>string</code>
149+
</td>
150+
<td>
151+
<p>Reason should be empty unless Allowed is false in which case it
152+
may contain a short description of what is wrong. Kubernetes
153+
may truncate excessively long errors when displaying to the user.</p>
154+
</td>
155+
</tr>
156+
<tr><td><code>auditAnnotations</code><br/>
157+
<code>map[string]string</code>
158+
</td>
159+
<td>
160+
<p>AuditAnnotations will be added to the attributes object of the
161+
admission controller request using 'AddAnnotation'. The keys should
162+
be prefix-less (i.e., the admission controller will add an
163+
appropriate prefix).</p>
164+
</td>
165+
</tr>
166+
</tbody>
167+
</table>
168+

0 commit comments

Comments
 (0)