kube_core/admission.rs
1//! Contains types for implementing admission controllers.
2//!
3//! For more information on admission controllers, see:
4//! <https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/>
5//! <https://kubernetes.io/blog/2019/03/21/a-guide-to-kubernetes-admission-controllers/>
6//! <https://github.com/kubernetes/api/blob/master/admission/v1/types.go>
7
8use crate::{
9 dynamic::DynamicObject,
10 gvk::{GroupVersionKind, GroupVersionResource},
11 metadata::TypeMeta,
12 resource::Resource,
13 Status,
14};
15
16use std::collections::HashMap;
17
18use k8s_openapi::{api::authentication::v1::UserInfo, apimachinery::pkg::runtime::RawExtension};
19use serde::{Deserialize, Serialize};
20use thiserror::Error;
21
22#[derive(Debug, Error)]
23#[error("failed to serialize patch")]
24/// Failed to serialize patch.
25pub struct SerializePatchError(#[source] serde_json::Error);
26
27#[derive(Debug, Error)]
28#[error("failed to convert AdmissionReview into AdmissionRequest")]
29/// Failed to convert `AdmissionReview` into `AdmissionRequest`.
30pub struct ConvertAdmissionReviewError;
31
32/// The `kind` field in [`TypeMeta`].
33pub const META_KIND: &str = "AdmissionReview";
34/// The `api_version` field in [`TypeMeta`] on the v1 version.
35pub const META_API_VERSION_V1: &str = "admission.k8s.io/v1";
36/// The `api_version` field in [`TypeMeta`] on the v1beta1 version.
37pub const META_API_VERSION_V1BETA1: &str = "admission.k8s.io/v1beta1";
38
39/// The top level struct used for Serializing and Deserializing AdmissionReview
40/// requests and responses.
41///
42/// This is both the input type received by admission controllers, and the
43/// output type admission controllers should return.
44///
45/// An admission controller should start by inspecting the [`AdmissionRequest`].
46#[derive(Serialize, Deserialize, Clone, Debug)]
47#[serde(rename_all = "camelCase")]
48pub struct AdmissionReview<T: Resource> {
49 /// Contains the API version and type of the request.
50 #[serde(flatten)]
51 pub types: TypeMeta,
52 /// Describes the attributes for the admission request.
53 #[serde(skip_serializing_if = "Option::is_none")]
54 pub request: Option<AdmissionRequest<T>>,
55 /// Describes the attributes for the admission response.
56 #[serde(skip_serializing_if = "Option::is_none")]
57 #[serde(default)]
58 pub response: Option<AdmissionResponse>,
59}
60
61impl<T: Resource> TryInto<AdmissionRequest<T>> for AdmissionReview<T> {
62 type Error = ConvertAdmissionReviewError;
63
64 fn try_into(self) -> Result<AdmissionRequest<T>, Self::Error> {
65 match self.request {
66 Some(mut req) => {
67 req.types = self.types;
68 Ok(req)
69 }
70 None => Err(ConvertAdmissionReviewError),
71 }
72 }
73}
74
75/// An incoming [`AdmissionReview`] request.
76///
77/// In an admission controller scenario, this is extracted from an [`AdmissionReview`] via [`TryInto`]
78///
79/// ```no_run
80/// use kube::core::{admission::{AdmissionRequest, AdmissionReview}, DynamicObject};
81///
82/// // The incoming AdmissionReview received by the controller.
83/// let body: AdmissionReview<DynamicObject> = todo!();
84/// let req: AdmissionRequest<_> = body.try_into().unwrap();
85/// ```
86///
87/// Based on the contents of the request, an admission controller should construct an
88/// [`AdmissionResponse`] using:
89///
90/// - [`AdmissionResponse::deny`] for illegal/rejected requests
91/// - [`AdmissionResponse::invalid`] for malformed requests
92/// - [`AdmissionResponse::from`] for the happy path
93///
94/// then wrap the chosen response in an [`AdmissionReview`] via [`AdmissionResponse::into_review`].
95#[derive(Serialize, Deserialize, Clone, Debug)]
96#[serde(rename_all = "camelCase")]
97pub struct AdmissionRequest<T: Resource> {
98 /// Copied from the containing [`AdmissionReview`] and used to specify a
99 /// response type and version when constructing an [`AdmissionResponse`].
100 #[serde(skip)]
101 pub types: TypeMeta,
102 /// An identifier for the individual request/response. It allows us to
103 /// distinguish instances of requests which are otherwise identical (parallel
104 /// requests, requests when earlier requests did not modify, etc). The UID is
105 /// meant to track the round trip (request/response) between the KAS and the
106 /// webhook, not the user request. It is suitable for correlating log entries
107 /// between the webhook and apiserver, for either auditing or debugging.
108 pub uid: String,
109 /// The fully-qualified type of object being submitted (for example, v1.Pod
110 /// or autoscaling.v1.Scale).
111 pub kind: GroupVersionKind,
112 /// The fully-qualified resource being requested (for example, v1.pods).
113 pub resource: GroupVersionResource,
114 /// The subresource being requested, if any (for example, "status" or
115 /// "scale").
116 #[serde(default)]
117 pub sub_resource: Option<String>,
118 /// The fully-qualified type of the original API request (for example, v1.Pod
119 /// or autoscaling.v1.Scale). If this is specified and differs from the value
120 /// in "kind", an equivalent match and conversion was performed.
121 ///
122 /// For example, if deployments can be modified via apps/v1 and apps/v1beta1,
123 /// and a webhook registered a rule of `apiGroups:["apps"],
124 /// apiVersions:["v1"], resources:["deployments"]` and
125 /// `matchPolicy:Equivalent`, an API request to apps/v1beta1 deployments
126 /// would be converted and sent to the webhook with `kind: {group:"apps",
127 /// version:"v1", kind:"Deployment"}` (matching the rule the webhook
128 /// registered for), and `requestKind: {group:"apps", version:"v1beta1",
129 /// kind:"Deployment"}` (indicating the kind of the original API request).
130 /// See documentation for the "matchPolicy" field in the webhook
131 /// configuration type for more details.
132 #[serde(default)]
133 pub request_kind: Option<GroupVersionKind>,
134 /// The fully-qualified resource of the original API request (for example,
135 /// v1.pods). If this is specified and differs from the value in "resource",
136 /// an equivalent match and conversion was performed.
137 ///
138 /// For example, if deployments can be modified via apps/v1 and apps/v1beta1,
139 /// and a webhook registered a rule of `apiGroups:["apps"],
140 /// apiVersions:["v1"], resources: ["deployments"]` and `matchPolicy:
141 /// Equivalent`, an API request to apps/v1beta1 deployments would be
142 /// converted and sent to the webhook with `resource: {group:"apps",
143 /// version:"v1", resource:"deployments"}` (matching the resource the webhook
144 /// registered for), and `requestResource: {group:"apps", version:"v1beta1",
145 /// resource:"deployments"}` (indicating the resource of the original API
146 /// request).
147 ///
148 /// See documentation for the "matchPolicy" field in the webhook
149 /// configuration type.
150 #[serde(default)]
151 pub request_resource: Option<GroupVersionResource>,
152 /// The name of the subresource of the original API request, if any (for
153 /// example, "status" or "scale"). If this is specified and differs from the
154 /// value in "subResource", an equivalent match and conversion was performed.
155 /// See documentation for the "matchPolicy" field in the webhook
156 /// configuration type.
157 #[serde(default)]
158 pub request_sub_resource: Option<String>,
159 /// The name of the object as presented in the request. On a CREATE
160 /// operation, the client may omit name and rely on the server to generate
161 /// the name. If that is the case, this field will contain an empty string.
162 #[serde(default)]
163 pub name: String,
164 /// The namespace associated with the request (if any).
165 #[serde(default)]
166 pub namespace: Option<String>,
167 /// The operation being performed. This may be different than the operation
168 /// requested. e.g. a patch can result in either a CREATE or UPDATE
169 /// Operation.
170 pub operation: Operation,
171 /// Information about the requesting user.
172 pub user_info: UserInfo,
173 /// The object from the incoming request. It's `None` for [`DELETE`](Operation::Delete) operations.
174 pub object: Option<T>,
175 /// The existing object. Only populated for DELETE and UPDATE requests.
176 pub old_object: Option<T>,
177 /// Specifies that modifications will definitely not be persisted for this
178 /// request.
179 #[serde(default)]
180 pub dry_run: bool,
181 /// The operation option structure of the operation being performed. e.g.
182 /// `meta.k8s.io/v1.DeleteOptions` or `meta.k8s.io/v1.CreateOptions`. This
183 /// may be different than the options the caller provided. e.g. for a patch
184 /// request the performed [`Operation`] might be a [`CREATE`](Operation::Create), in
185 /// which case the Options will a `meta.k8s.io/v1.CreateOptions` even though
186 /// the caller provided `meta.k8s.io/v1.PatchOptions`.
187 #[serde(default)]
188 pub options: Option<RawExtension>,
189}
190
191/// The operation specified in an [`AdmissionRequest`].
192#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
193#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
194pub enum Operation {
195 /// An operation that creates a resource.
196 Create,
197 /// An operation that updates a resource.
198 Update,
199 /// An operation that deletes a resource.
200 Delete,
201 /// An operation that connects to a resource.
202 Connect,
203}
204
205/// An outgoing [`AdmissionReview`] response. Constructed from the corresponding
206/// [`AdmissionRequest`].
207/// ```no_run
208/// use kube::core::{
209/// admission::{AdmissionRequest, AdmissionResponse, AdmissionReview},
210/// DynamicObject,
211/// };
212///
213/// // The incoming AdmissionReview received by the controller.
214/// let body: AdmissionReview<DynamicObject> = todo!();
215/// let req: AdmissionRequest<_> = body.try_into().unwrap();
216///
217/// // A normal response with no side effects.
218/// let _: AdmissionReview<_> = AdmissionResponse::from(&req).into_review();
219///
220/// // A response rejecting the admission webhook with a provided reason.
221/// let _: AdmissionReview<_> = AdmissionResponse::from(&req)
222/// .deny("Some rejection reason.")
223/// .into_review();
224///
225/// use json_patch::{AddOperation, Patch, PatchOperation, jsonptr::PointerBuf};
226///
227/// // A response adding a label to the resource.
228/// let _: AdmissionReview<_> = AdmissionResponse::from(&req)
229/// .with_patch(Patch(vec![PatchOperation::Add(AddOperation {
230/// path: PointerBuf::from_tokens(["metadata","labels","my-label"]),
231/// value: serde_json::Value::String("my-value".to_owned()),
232/// })]))
233/// .unwrap()
234/// .into_review();
235///
236/// ```
237#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
238#[serde(rename_all = "camelCase")]
239#[non_exhaustive]
240pub struct AdmissionResponse {
241 /// Copied from the corresponding consructing [`AdmissionRequest`].
242 #[serde(skip)]
243 pub types: TypeMeta,
244 /// Identifier for the individual request/response. This must be copied over
245 /// from the corresponding AdmissionRequest.
246 pub uid: String,
247 /// Indicates whether or not the admission request was permitted.
248 pub allowed: bool,
249 /// Extra details into why an admission request was denied. This field IS NOT
250 /// consulted in any way if "Allowed" is "true".
251 #[serde(rename = "status")]
252 pub result: Status,
253 /// The patch body. Currently we only support "JSONPatch" which implements
254 /// RFC 6902.
255 #[serde(skip_serializing_if = "Option::is_none")]
256 pub patch: Option<Vec<u8>>,
257 /// The type of Patch. Currently we only allow "JSONPatch".
258 #[serde(skip_serializing_if = "Option::is_none")]
259 patch_type: Option<PatchType>,
260 /// An unstructured key value map set by remote admission controller (e.g.
261 /// error=image-blacklisted). MutatingAdmissionWebhook and
262 /// ValidatingAdmissionWebhook admission controller will prefix the keys with
263 /// admission webhook name (e.g.
264 /// imagepolicy.example.com/error=image-blacklisted). AuditAnnotations will
265 /// be provided by the admission webhook to add additional context to the
266 /// audit log for this request.
267 #[serde(default, skip_serializing_if = "HashMap::is_empty")]
268 pub audit_annotations: HashMap<String, String>,
269 /// A list of warning messages to return to the requesting API client.
270 /// Warning messages describe a problem the client making the API request
271 /// should correct or be aware of. Limit warnings to 120 characters if
272 /// possible. Warnings over 256 characters and large numbers of warnings may
273 /// be truncated.
274 #[serde(skip_serializing_if = "Option::is_none")]
275 pub warnings: Option<Vec<String>>,
276}
277
278impl<T: Resource> From<&AdmissionRequest<T>> for AdmissionResponse {
279 fn from(req: &AdmissionRequest<T>) -> Self {
280 Self {
281 types: req.types.clone(),
282 uid: req.uid.clone(),
283 allowed: true,
284 result: Default::default(),
285 patch: None,
286 patch_type: None,
287 audit_annotations: Default::default(),
288 warnings: None,
289 }
290 }
291}
292
293impl AdmissionResponse {
294 /// Constructs an invalid [`AdmissionResponse`]. It doesn't copy the uid from
295 /// the corresponding [`AdmissionRequest`], so should only be used when the
296 /// original request cannot be read.
297 pub fn invalid<T: ToString>(reason: T) -> Self {
298 Self {
299 // Since we don't have a request to use for construction, just
300 // default to "admission.k8s.io/v1beta1", since it is the most
301 // supported and we won't be using any of the new fields.
302 types: TypeMeta {
303 kind: META_KIND.to_owned(),
304 api_version: META_API_VERSION_V1BETA1.to_owned(),
305 },
306 uid: Default::default(),
307 allowed: false,
308 result: Status::failure(&reason.to_string(), "InvalidRequest"),
309 patch: None,
310 patch_type: None,
311 audit_annotations: Default::default(),
312 warnings: None,
313 }
314 }
315
316 /// Deny the request with a reason. The reason will be sent to the original caller.
317 #[must_use]
318 pub fn deny<T: ToString>(mut self, reason: T) -> Self {
319 self.allowed = false;
320 self.result.message = reason.to_string();
321 self
322 }
323
324 /// Add JSON patches to the response, modifying the object from the request.
325 pub fn with_patch(mut self, patch: json_patch::Patch) -> Result<Self, SerializePatchError> {
326 self.patch = Some(serde_json::to_vec(&patch).map_err(SerializePatchError)?);
327 self.patch_type = Some(PatchType::JsonPatch);
328
329 Ok(self)
330 }
331
332 /// Converts an [`AdmissionResponse`] into a generic [`AdmissionReview`] that
333 /// can be used as a webhook response.
334 pub fn into_review(self) -> AdmissionReview<DynamicObject> {
335 AdmissionReview {
336 types: self.types.clone(),
337 request: None,
338 response: Some(self),
339 }
340 }
341}
342
343/// The type of patch returned in an [`AdmissionResponse`].
344#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
345pub enum PatchType {
346 /// Specifies the patch body implements JSON Patch under RFC 6902.
347 #[serde(rename = "JSONPatch")]
348 JsonPatch,
349}
350
351#[cfg(test)]
352mod test {
353 const WEBHOOK_BODY: &str = r#"{"kind":"AdmissionReview","apiVersion":"admission.k8s.io/v1","request":{"uid":"0c9a8d74-9cb7-44dd-b98e-09fd62def2f4","kind":{"group":"","version":"v1","kind":"Pod"},"resource":{"group":"","version":"v1","resource":"pods"},"requestKind":{"group":"","version":"v1","kind":"Pod"},"requestResource":{"group":"","version":"v1","resource":"pods"},"name":"echo-pod","namespace":"colin-coder","operation":"CREATE","userInfo":{"username":"colin@coder.com","groups":["system:authenticated"],"extra":{"iam.gke.io/user-assertion":["REDACTED"],"user-assertion.cloud.google.com":["REDACTED"]}},"object":{"kind":"Pod","apiVersion":"v1","metadata":{"name":"echo-pod","namespace":"colin-coder","creationTimestamp":null,"labels":{"app":"echo-server"},"annotations":{"kubectl.kubernetes.io/last-applied-configuration":"{\"apiVersion\":\"v1\",\"kind\":\"Pod\",\"metadata\":{\"annotations\":{},\"labels\":{\"app\":\"echo-server\"},\"name\":\"echo-pod\",\"namespace\":\"colin-coder\"},\"spec\":{\"containers\":[{\"image\":\"jmalloc/echo-server\",\"name\":\"echo-server\",\"ports\":[{\"containerPort\":8080,\"name\":\"http-port\"}]}]}}\n"},"managedFields":[{"manager":"kubectl","operation":"Update","apiVersion":"v1","time":"2021-03-29T23:02:16Z","fieldsType":"FieldsV1","fieldsV1":{"f:metadata":{"f:annotations":{".":{},"f:kubectl.kubernetes.io/last-applied-configuration":{}},"f:labels":{".":{},"f:app":{}}},"f:spec":{"f:containers":{"k:{\"name\":\"echo-server\"}":{".":{},"f:image":{},"f:imagePullPolicy":{},"f:name":{},"f:ports":{".":{},"k:{\"containerPort\":8080,\"protocol\":\"TCP\"}":{".":{},"f:containerPort":{},"f:name":{},"f:protocol":{}}},"f:resources":{},"f:terminationMessagePath":{},"f:terminationMessagePolicy":{}}},"f:dnsPolicy":{},"f:enableServiceLinks":{},"f:restartPolicy":{},"f:schedulerName":{},"f:securityContext":{},"f:terminationGracePeriodSeconds":{}}}}]},"spec":{"volumes":[{"name":"default-token-rxbqq","secret":{"secretName":"default-token-rxbqq"}}],"containers":[{"name":"echo-server","image":"jmalloc/echo-server","ports":[{"name":"http-port","containerPort":8080,"protocol":"TCP"}],"resources":{},"volumeMounts":[{"name":"default-token-rxbqq","readOnly":true,"mountPath":"/var/run/secrets/kubernetes.io/serviceaccount"}],"terminationMessagePath":"/dev/termination-log","terminationMessagePolicy":"File","imagePullPolicy":"Always"}],"restartPolicy":"Always","terminationGracePeriodSeconds":30,"dnsPolicy":"ClusterFirst","serviceAccountName":"default","serviceAccount":"default","securityContext":{},"schedulerName":"default-scheduler","tolerations":[{"key":"node.kubernetes.io/not-ready","operator":"Exists","effect":"NoExecute","tolerationSeconds":300},{"key":"node.kubernetes.io/unreachable","operator":"Exists","effect":"NoExecute","tolerationSeconds":300}],"priority":0,"enableServiceLinks":true},"status":{}},"oldObject":null,"dryRun":false,"options":{"kind":"CreateOptions","apiVersion":"meta.k8s.io/v1"}}}"#;
354
355 use crate::{
356 admission::{AdmissionResponse, AdmissionReview, ConvertAdmissionReviewError},
357 DynamicObject,
358 };
359
360 #[test]
361 fn v1_webhook_unmarshals() {
362 serde_json::from_str::<AdmissionReview<DynamicObject>>(WEBHOOK_BODY).unwrap();
363 }
364
365 #[test]
366 fn version_passes_through() -> Result<(), ConvertAdmissionReviewError> {
367 let rev = serde_json::from_str::<AdmissionReview<DynamicObject>>(WEBHOOK_BODY).unwrap();
368 let rev_typ = rev.types.clone();
369 let res = AdmissionResponse::from(&rev.try_into()?).into_review();
370
371 // Ensure TypeMeta was correctly deserialized.
372 assert_ne!(&rev_typ.api_version, "");
373 // The TypeMeta should be correctly passed through from the incoming
374 // request.
375 assert_eq!(&rev_typ, &res.types);
376 Ok(())
377 }
378}