Skip to content

Commit 3362aa9

Browse files
tengqmtengqm
committed
Add admission.k8s.io/v1 API and fix references to it
The `admission.k8s.io/v1` API group is not generated into the v2/v3 OpenAPI specification as part of Kubernetes API because it is not officially "served". However, the structs in the API group are used in other APIs that are user-facing. This PR addes the reference API and fixes references to it.
1 parent 5d78524 commit 3362aa9

File tree

3 files changed

+304
-4
lines changed

3 files changed

+304
-4
lines changed

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

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,10 @@ content_type: concept
99
no_list: true
1010
---
1111

12-
1312
<!-- overview -->
1413

1514
This section of the Kubernetes documentation contains references.
1615

17-
18-
1916
<!-- body -->
2017

2118
## API Reference
@@ -76,6 +73,7 @@ operator to use or manage a cluster.
7673

7774

7875
* [kubeconfig (v1)](/docs/reference/config-api/kubeconfig.v1/)
76+
* [kube-apiserver admission (v1)](/docs/reference/config-api/apiserver-admission.v1/)
7977
* [kube-apiserver configuration (v1alpha1)](/docs/reference/config-api/apiserver-config.v1alpha1/) and
8078
[kube-apiserver configuration (v1)](/docs/reference/config-api/apiserver-config.v1/)
8179
* [kube-apiserver encryption (v1)](/docs/reference/config-api/apiserver-encryption.v1/)

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -242,9 +242,10 @@ validations:
242242
`spec.validations[i].expression` represents the expression which will be evaluated by CEL.
243243
To learn more, see the [CEL language specification](https://github.com/google/cel-spec)
244244
CEL expressions have access to the contents of the Admission request/response, organized into CEL variables as well as some other useful variables:
245+
245246
- 'object' - The object from the incoming request. The value is null for DELETE requests.
246247
- 'oldObject' - The existing object. The value is null for CREATE requests.
247-
- 'request' - Attributes of the [admission request](/pkg/apis/admission/types.go#AdmissionRequest).
248+
- 'request' - Attributes of the [admission request](/docs/reference/config-api/apiserver-admission.v1/#admission-k8s-io-v1-AdmissionRequest).
248249
- 'params' - Parameter resource referred to by the policy binding being evaluated. The value is null if `ParamKind` is unset.
249250

250251
The `apiVersion`, `kind`, `metadata.name` and `metadata.generateName` are always accessible from the root of the

‎content/en/docs/reference/config-api/apiserver-admission.v1.md

Lines changed: 301 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,301 @@
1+
---
2+
title: kube-apiserver Admission (v1)
3+
content_type: tool-reference
4+
package: admission.k8s.io/v1
5+
auto_generated: true
6+
---
7+
8+
9+
## Resource Types
10+
11+
12+
- [AdmissionReview](#admission-k8s-io-v1-AdmissionReview)
13+
14+
15+
16+
## `AdmissionReview` {#admission-k8s-io-v1-AdmissionReview}
17+
18+
19+
20+
<p>AdmissionReview describes an admission review request/response.</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>admission.k8s.io/v1</code></td></tr>
28+
<tr><td><code>kind</code><br/>string</td><td><code>AdmissionReview</code></td></tr>
29+
30+
31+
<tr><td><code>request</code><br/>
32+
<a href="#admission-k8s-io-v1-AdmissionRequest"><code>AdmissionRequest</code></a>
33+
</td>
34+
<td>
35+
<p>Request describes the attributes for the admission request.</p>
36+
</td>
37+
</tr>
38+
<tr><td><code>response</code><br/>
39+
<a href="#admission-k8s-io-v1-AdmissionResponse"><code>AdmissionResponse</code></a>
40+
</td>
41+
<td>
42+
<p>Response describes the attributes for the admission response.</p>
43+
</td>
44+
</tr>
45+
</tbody>
46+
</table>
47+
48+
## `AdmissionRequest` {#admission-k8s-io-v1-AdmissionRequest}
49+
50+
51+
**Appears in:**
52+
53+
- [AdmissionReview](#admission-k8s-io-v1-AdmissionReview)
54+
55+
56+
<p>AdmissionRequest describes the admission.Attributes for the admission request.</p>
57+
58+
59+
<table class="table">
60+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
61+
<tbody>
62+
63+
64+
<tr><td><code>uid</code> <B>[Required]</B><br/>
65+
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/types#UID"><code>k8s.io/apimachinery/pkg/types.UID</code></a>
66+
</td>
67+
<td>
68+
<p>UID is an identifier for the individual request/response. It allows us to distinguish instances of requests which are
69+
otherwise identical (parallel requests, requests when earlier requests did not modify etc)
70+
The UID is meant to track the round trip (request/response) between the KAS and the WebHook, not the user request.
71+
It is suitable for correlating log entries between the webhook and apiserver, for either auditing or debugging.</p>
72+
</td>
73+
</tr>
74+
<tr><td><code>kind</code> <B>[Required]</B><br/>
75+
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#groupversionkind-v1-meta"><code>meta/v1.GroupVersionKind</code></a>
76+
</td>
77+
<td>
78+
<p>Kind is the fully-qualified type of object being submitted (for example, v1.Pod or autoscaling.v1.Scale)</p>
79+
</td>
80+
</tr>
81+
<tr><td><code>resource</code> <B>[Required]</B><br/>
82+
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#groupversionresource-v1-meta"><code>meta/v1.GroupVersionResource</code></a>
83+
</td>
84+
<td>
85+
<p>Resource is the fully-qualified resource being requested (for example, v1.pods)</p>
86+
</td>
87+
</tr>
88+
<tr><td><code>subResource</code><br/>
89+
<code>string</code>
90+
</td>
91+
<td>
92+
<p>SubResource is the subresource being requested, if any (for example, &quot;status&quot; or &quot;scale&quot;)</p>
93+
</td>
94+
</tr>
95+
<tr><td><code>requestKind</code><br/>
96+
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#groupversionkind-v1-meta"><code>meta/v1.GroupVersionKind</code></a>
97+
</td>
98+
<td>
99+
<p>RequestKind is the fully-qualified type of the original API request (for example, v1.Pod or autoscaling.v1.Scale).
100+
If this is specified and differs from the value in &quot;kind&quot;, an equivalent match and conversion was performed.</p>
101+
<p>For example, if deployments can be modified via apps/v1 and apps/v1beta1, and a webhook registered a rule of
102+
<code>apiGroups:[&quot;apps&quot;], apiVersions:[&quot;v1&quot;], resources: [&quot;deployments&quot;]</code> and <code>matchPolicy: Equivalent</code>,
103+
an API request to apps/v1beta1 deployments would be converted and sent to the webhook
104+
with <code>kind: {group:&quot;apps&quot;, version:&quot;v1&quot;, kind:&quot;Deployment&quot;}</code> (matching the rule the webhook registered for),
105+
and <code>requestKind: {group:&quot;apps&quot;, version:&quot;v1beta1&quot;, kind:&quot;Deployment&quot;}</code> (indicating the kind of the original API request).</p>
106+
<p>See documentation for the &quot;matchPolicy&quot; field in the webhook configuration type for more details.</p>
107+
</td>
108+
</tr>
109+
<tr><td><code>requestResource</code><br/>
110+
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#groupversionresource-v1-meta"><code>meta/v1.GroupVersionResource</code></a>
111+
</td>
112+
<td>
113+
<p>RequestResource is the fully-qualified resource of the original API request (for example, v1.pods).
114+
If this is specified and differs from the value in &quot;resource&quot;, an equivalent match and conversion was performed.</p>
115+
<p>For example, if deployments can be modified via apps/v1 and apps/v1beta1, and a webhook registered a rule of
116+
<code>apiGroups:[&quot;apps&quot;], apiVersions:[&quot;v1&quot;], resources: [&quot;deployments&quot;]</code> and <code>matchPolicy: Equivalent</code>,
117+
an API request to apps/v1beta1 deployments would be converted and sent to the webhook
118+
with <code>resource: {group:&quot;apps&quot;, version:&quot;v1&quot;, resource:&quot;deployments&quot;}</code> (matching the resource the webhook registered for),
119+
and <code>requestResource: {group:&quot;apps&quot;, version:&quot;v1beta1&quot;, resource:&quot;deployments&quot;}</code> (indicating the resource of the original API request).</p>
120+
<p>See documentation for the &quot;matchPolicy&quot; field in the webhook configuration type.</p>
121+
</td>
122+
</tr>
123+
<tr><td><code>requestSubResource</code><br/>
124+
<code>string</code>
125+
</td>
126+
<td>
127+
<p>RequestSubResource is the name of the subresource of the original API request, if any (for example, &quot;status&quot; or &quot;scale&quot;)
128+
If this is specified and differs from the value in &quot;subResource&quot;, an equivalent match and conversion was performed.
129+
See documentation for the &quot;matchPolicy&quot; field in the webhook configuration type.</p>
130+
</td>
131+
</tr>
132+
<tr><td><code>name</code><br/>
133+
<code>string</code>
134+
</td>
135+
<td>
136+
<p>Name is the name of the object as presented in the request. On a CREATE operation, the client may omit name and
137+
rely on the server to generate the name. If that is the case, this field will contain an empty string.</p>
138+
</td>
139+
</tr>
140+
<tr><td><code>namespace</code><br/>
141+
<code>string</code>
142+
</td>
143+
<td>
144+
<p>Namespace is the namespace associated with the request (if any).</p>
145+
</td>
146+
</tr>
147+
<tr><td><code>operation</code> <B>[Required]</B><br/>
148+
<a href="#admission-k8s-io-v1-Operation"><code>Operation</code></a>
149+
</td>
150+
<td>
151+
<p>Operation is the operation being performed. This may be different than the operation
152+
requested. e.g. a patch can result in either a CREATE or UPDATE Operation.</p>
153+
</td>
154+
</tr>
155+
<tr><td><code>userInfo</code> <B>[Required]</B><br/>
156+
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#userinfo-v1-authentication"><code>authentication/v1.UserInfo</code></a>
157+
</td>
158+
<td>
159+
<p>UserInfo is information about the requesting user</p>
160+
</td>
161+
</tr>
162+
<tr><td><code>object</code><br/>
163+
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime/#RawExtension"><code>k8s.io/apimachinery/pkg/runtime.RawExtension</code></a>
164+
</td>
165+
<td>
166+
<p>Object is the object from the incoming request.</p>
167+
</td>
168+
</tr>
169+
<tr><td><code>oldObject</code><br/>
170+
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime/#RawExtension"><code>k8s.io/apimachinery/pkg/runtime.RawExtension</code></a>
171+
</td>
172+
<td>
173+
<p>OldObject is the existing object. Only populated for DELETE and UPDATE requests.</p>
174+
</td>
175+
</tr>
176+
<tr><td><code>dryRun</code><br/>
177+
<code>bool</code>
178+
</td>
179+
<td>
180+
<p>DryRun indicates that modifications will definitely not be persisted for this request.
181+
Defaults to false.</p>
182+
</td>
183+
</tr>
184+
<tr><td><code>options</code><br/>
185+
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime/#RawExtension"><code>k8s.io/apimachinery/pkg/runtime.RawExtension</code></a>
186+
</td>
187+
<td>
188+
<p>Options is the operation option structure of the operation being performed.
189+
e.g. <code>meta.k8s.io/v1.DeleteOptions</code> or <code>meta.k8s.io/v1.CreateOptions</code>. This may be
190+
different than the options the caller provided. e.g. for a patch request the performed
191+
Operation might be a CREATE, in which case the Options will a
192+
<code>meta.k8s.io/v1.CreateOptions</code> even though the caller provided <code>meta.k8s.io/v1.PatchOptions</code>.</p>
193+
</td>
194+
</tr>
195+
</tbody>
196+
</table>
197+
198+
## `AdmissionResponse` {#admission-k8s-io-v1-AdmissionResponse}
199+
200+
201+
**Appears in:**
202+
203+
- [AdmissionReview](#admission-k8s-io-v1-AdmissionReview)
204+
205+
206+
<p>AdmissionResponse describes an admission response.</p>
207+
208+
209+
<table class="table">
210+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
211+
<tbody>
212+
213+
214+
<tr><td><code>uid</code> <B>[Required]</B><br/>
215+
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/types#UID"><code>k8s.io/apimachinery/pkg/types.UID</code></a>
216+
</td>
217+
<td>
218+
<p>UID is an identifier for the individual request/response.
219+
This must be copied over from the corresponding AdmissionRequest.</p>
220+
</td>
221+
</tr>
222+
<tr><td><code>allowed</code> <B>[Required]</B><br/>
223+
<code>bool</code>
224+
</td>
225+
<td>
226+
<p>Allowed indicates whether or not the admission request was permitted.</p>
227+
</td>
228+
</tr>
229+
<tr><td><code>status</code><br/>
230+
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#status-v1-meta"><code>meta/v1.Status</code></a>
231+
</td>
232+
<td>
233+
<p>Result contains extra details into why an admission request was denied.
234+
This field IS NOT consulted in any way if &quot;Allowed&quot; is &quot;true&quot;.</p>
235+
</td>
236+
</tr>
237+
<tr><td><code>patch</code><br/>
238+
<code>[]byte</code>
239+
</td>
240+
<td>
241+
<p>The patch body. Currently we only support &quot;JSONPatch&quot; which implements RFC 6902.</p>
242+
</td>
243+
</tr>
244+
<tr><td><code>patchType</code><br/>
245+
<a href="#admission-k8s-io-v1-PatchType"><code>PatchType</code></a>
246+
</td>
247+
<td>
248+
<p>The type of Patch. Currently we only allow &quot;JSONPatch&quot;.</p>
249+
</td>
250+
</tr>
251+
<tr><td><code>auditAnnotations</code><br/>
252+
<code>map[string]string</code>
253+
</td>
254+
<td>
255+
<p>AuditAnnotations is an unstructured key value map set by remote admission controller (e.g. error=image-blacklisted).
256+
MutatingAdmissionWebhook and ValidatingAdmissionWebhook admission controller will prefix the keys with
257+
admission webhook name (e.g. imagepolicy.example.com/error=image-blacklisted). AuditAnnotations will be provided by
258+
the admission webhook to add additional context to the audit log for this request.</p>
259+
</td>
260+
</tr>
261+
<tr><td><code>warnings</code><br/>
262+
<code>[]string</code>
263+
</td>
264+
<td>
265+
<p>warnings is a list of warning messages to return to the requesting API client.
266+
Warning messages describe a problem the client making the API request should correct or be aware of.
267+
Limit warnings to 120 characters if possible.
268+
Warnings over 256 characters and large numbers of warnings may be truncated.</p>
269+
</td>
270+
</tr>
271+
</tbody>
272+
</table>
273+
274+
## `Operation` {#admission-k8s-io-v1-Operation}
275+
276+
(Alias of `string`)
277+
278+
**Appears in:**
279+
280+
- [AdmissionRequest](#admission-k8s-io-v1-AdmissionRequest)
281+
282+
283+
<p>Operation is the type of resource operation being checked for admission control</p>
284+
285+
286+
287+
288+
## `PatchType` {#admission-k8s-io-v1-PatchType}
289+
290+
(Alias of `string`)
291+
292+
**Appears in:**
293+
294+
- [AdmissionResponse](#admission-k8s-io-v1-AdmissionResponse)
295+
296+
297+
<p>PatchType is the type of patch being used to represent the mutated object</p>
298+
299+
300+
301+

0 commit comments

Comments
 (0)