kube_core/

admission.rs

//! Contains types for implementing admission controllers.
//!
//! For more information on admission controllers, see:
//! <https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/>
//! <https://kubernetes.io/blog/2019/03/21/a-guide-to-kubernetes-admission-controllers/>
//! <https://github.com/kubernetes/api/blob/master/admission/v1/types.go>

use crate::{
    Status,
    dynamic::DynamicObject,
    gvk::{GroupVersionKind, GroupVersionResource},
    metadata::TypeMeta,
    resource::Resource,
};

use std::collections::HashMap;

use k8s_openapi::{api::authentication::v1::UserInfo, apimachinery::pkg::runtime::RawExtension};
use serde::{Deserialize, Serialize};
use thiserror::Error;

#[derive(Debug, Error)]
#[error("failed to serialize patch: {0}")]
/// Failed to serialize patch.
pub struct SerializePatchError(#[source] serde_json::Error);

#[derive(Debug, Error)]
#[error("failed to convert AdmissionReview into AdmissionRequest")]
/// Failed to convert `AdmissionReview` into `AdmissionRequest`.
pub struct ConvertAdmissionReviewError;

/// The `kind` field in [`TypeMeta`].
pub const META_KIND: &str = "AdmissionReview";
/// The `api_version` field in [`TypeMeta`] on the v1 version.
pub const META_API_VERSION_V1: &str = "admission.k8s.io/v1";

/// The top level struct used for Serializing and Deserializing AdmissionReview
/// requests and responses.
///
/// This is both the input type received by admission controllers, and the
/// output type admission controllers should return.
///
/// An admission controller should start by inspecting the [`AdmissionRequest`].
#[derive(Serialize, Deserialize, Clone, Debug)]
#[serde(rename_all = "camelCase")]
pub struct AdmissionReview<T: Resource> {
    /// Contains the API version and type of the request.
    #[serde(flatten)]
    pub types: TypeMeta,
    /// Describes the attributes for the admission request.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub request: Option<AdmissionRequest<T>>,
    /// Describes the attributes for the admission response.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub response: Option<AdmissionResponse>,
}

impl<T: Resource> TryInto<AdmissionRequest<T>> for AdmissionReview<T> {
    type Error = ConvertAdmissionReviewError;

    fn try_into(self) -> Result<AdmissionRequest<T>, Self::Error> {
        match self.request {
            Some(mut req) => {
                req.types = self.types;
                Ok(req)
            }
            None => Err(ConvertAdmissionReviewError),
        }
    }
}

/// An incoming [`AdmissionReview`] request.
///
/// In an admission controller scenario, this is extracted from an [`AdmissionReview`] via [`TryInto`]
///
/// ```no_run
/// use kube::core::{admission::{AdmissionRequest, AdmissionReview}, DynamicObject};
///
/// // The incoming AdmissionReview received by the controller.
/// let body: AdmissionReview<DynamicObject> = todo!();
/// let req: AdmissionRequest<_> = body.try_into().unwrap();
/// ```
///
/// Based on the contents of the request, an admission controller should construct an
/// [`AdmissionResponse`] using:
///
/// - [`AdmissionResponse::deny`] for illegal/rejected requests
/// - [`AdmissionResponse::invalid`] for malformed requests
/// - [`AdmissionResponse::from`] for the happy path
///
/// then wrap the chosen response in an [`AdmissionReview`] via [`AdmissionResponse::into_review`].
#[derive(Serialize, Deserialize, Clone, Debug)]
#[serde(rename_all = "camelCase")]
pub struct AdmissionRequest<T: Resource> {
    /// Copied from the containing [`AdmissionReview`] and used to specify a
    /// response type and version when constructing an [`AdmissionResponse`].
    #[serde(skip)]
    pub types: TypeMeta,
    /// An identifier for the individual request/response. It allows us to
    /// distinguish instances of requests which are otherwise identical (parallel
    /// requests, requests when earlier requests did not modify, etc). The UID is
    /// meant to track the round trip (request/response) between the KAS and the
    /// webhook, not the user request. It is suitable for correlating log entries
    /// between the webhook and apiserver, for either auditing or debugging.
    pub uid: String,
    /// The fully-qualified type of object being submitted (for example, v1.Pod
    /// or autoscaling.v1.Scale).
    pub kind: GroupVersionKind,
    /// The fully-qualified resource being requested (for example, v1.pods).
    pub resource: GroupVersionResource,
    /// The subresource being requested, if any (for example, "status" or
    /// "scale").
    #[serde(default)]
    pub sub_resource: Option<String>,
    /// The fully-qualified type of the original API request (for example, v1.Pod
    /// or autoscaling.v1.Scale). If this is specified and differs from the value
    /// in "kind", an equivalent match and conversion was performed.
    ///
    /// For example, if deployments can be modified via apps/v1 and apps/v1beta1,
    /// and a webhook registered a rule of `apiGroups:["apps"],
    /// apiVersions:["v1"], resources:["deployments"]` and
    /// `matchPolicy:Equivalent`, an API request to apps/v1beta1 deployments
    /// would be converted and sent to the webhook with `kind: {group:"apps",
    /// version:"v1", kind:"Deployment"}` (matching the rule the webhook
    /// registered for), and `requestKind: {group:"apps", version:"v1beta1",
    /// kind:"Deployment"}` (indicating the kind of the original API request).
    /// See documentation for the "matchPolicy" field in the webhook
    /// configuration type for more details.
    #[serde(default)]
    pub request_kind: Option<GroupVersionKind>,
    /// The fully-qualified resource of the original API request (for example,
    /// v1.pods). If this is specified and differs from the value in "resource",
    /// an equivalent match and conversion was performed.
    ///
    /// For example, if deployments can be modified via apps/v1 and apps/v1beta1,
    /// and a webhook registered a rule of `apiGroups:["apps"],
    /// apiVersions:["v1"], resources: ["deployments"]` and `matchPolicy:
    /// Equivalent`, an API request to apps/v1beta1 deployments would be
    /// converted and sent to the webhook with `resource: {group:"apps",
    /// version:"v1", resource:"deployments"}` (matching the resource the webhook
    /// registered for), and `requestResource: {group:"apps", version:"v1beta1",
    /// resource:"deployments"}` (indicating the resource of the original API
    /// request).
    ///
    /// See documentation for the "matchPolicy" field in the webhook
    /// configuration type.
    #[serde(default)]
    pub request_resource: Option<GroupVersionResource>,
    /// The name of the subresource of the original API request, if any (for
    /// example, "status" or "scale"). If this is specified and differs from the
    /// value in "subResource", an equivalent match and conversion was performed.
    /// See documentation for the "matchPolicy" field in the webhook
    /// configuration type.
    #[serde(default)]
    pub request_sub_resource: Option<String>,
    /// The name of the object as presented in the request. On a CREATE
    /// operation, the client may omit name and rely on the server to generate
    /// the name. If that is the case, this field will contain an empty string.
    #[serde(default)]
    pub name: String,
    /// The namespace associated with the request (if any).
    #[serde(default)]
    pub namespace: Option<String>,
    /// The operation being performed. This may be different than the operation
    /// requested. e.g. a patch can result in either a CREATE or UPDATE
    /// Operation.
    pub operation: Operation,
    /// Information about the requesting user.
    pub user_info: UserInfo,
    /// The object from the incoming request. It's `None` for [`DELETE`](Operation::Delete) operations.
    pub object: Option<T>,
    ///  The existing object. Only populated for DELETE and UPDATE requests.
    pub old_object: Option<T>,
    /// Specifies that modifications will definitely not be persisted for this
    /// request.
    #[serde(default)]
    pub dry_run: bool,
    /// The operation option structure of the operation being performed. e.g.
    /// `meta.k8s.io/v1.DeleteOptions` or `meta.k8s.io/v1.CreateOptions`. This
    /// may be different than the options the caller provided. e.g. for a patch
    /// request the performed [`Operation`] might be a [`CREATE`](Operation::Create), in
    /// which case the Options will a `meta.k8s.io/v1.CreateOptions` even though
    /// the caller provided `meta.k8s.io/v1.PatchOptions`.
    #[serde(default)]
    pub options: Option<RawExtension>,
}

/// The operation specified in an [`AdmissionRequest`].
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum Operation {
    /// An operation that creates a resource.
    Create,
    /// An operation that updates a resource.
    Update,
    /// An operation that deletes a resource.
    Delete,
    /// An operation that connects to a resource.
    Connect,
}

#[cfg(feature = "cel")]
#[cfg_attr(docsrs, doc(cfg(feature = "cel")))]
impl<T: Resource> AdmissionRequest<T> {
    /// Project this request into the [`kube_cel::AdmissionRequest`] used to
    /// bind the `request` variable for ValidatingAdmissionPolicy CEL evaluation.
    ///
    /// This is a lossy view: only the fields exposed to VAP's `request` variable
    /// are carried over (`operation`, `name`, `namespace`, `dryRun`, `kind`,
    /// `resource`, and `userInfo`'s `username`/`uid`/`groups`). Webhook-only fields
    /// such as `object`, `oldObject`, `requestKind`, `subResource`, and `options`
    /// are dropped. The carried `uid` is the *user* uid (`userInfo.uid`), matching
    /// the VAP `request.userInfo.uid` variable, not the request round-trip uid.
    pub fn to_cel_request(&self) -> kube_cel::AdmissionRequest {
        kube_cel::AdmissionRequest {
            operation: match self.operation {
                Operation::Create => "CREATE",
                Operation::Update => "UPDATE",
                Operation::Delete => "DELETE",
                Operation::Connect => "CONNECT",
            }
            .to_owned(),
            username: self.user_info.username.clone().unwrap_or_default(),
            uid: self.user_info.uid.clone().unwrap_or_default(),
            groups: self.user_info.groups.clone().unwrap_or_default(),
            name: self.name.clone(),
            namespace: self.namespace.clone().unwrap_or_default(),
            dry_run: self.dry_run,
            kind: kube_cel::GroupVersionKind {
                group: self.kind.group.clone(),
                version: self.kind.version.clone(),
                kind: self.kind.kind.clone(),
            },
            resource: kube_cel::GroupVersionResource {
                group: self.resource.group.clone(),
                version: self.resource.version.clone(),
                resource: self.resource.resource.clone(),
            },
        }
    }
}

/// An outgoing [`AdmissionReview`] response. Constructed from the corresponding
/// [`AdmissionRequest`].
/// ```no_run
/// use kube::core::{
///     admission::{AdmissionRequest, AdmissionResponse, AdmissionReview},
///     DynamicObject,
/// };
///
/// // The incoming AdmissionReview received by the controller.
/// let body: AdmissionReview<DynamicObject> = todo!();
/// let req: AdmissionRequest<_> = body.try_into().unwrap();
///
/// // A normal response with no side effects.
/// let _: AdmissionReview<_> = AdmissionResponse::from(&req).into_review();
///
/// // A response rejecting the admission webhook with a provided reason.
/// let _: AdmissionReview<_> = AdmissionResponse::from(&req)
///     .deny("Some rejection reason.")
///     .into_review();
///
/// use json_patch::{AddOperation, Patch, PatchOperation, jsonptr::PointerBuf};
///
/// // A response adding a label to the resource.
/// let _: AdmissionReview<_> = AdmissionResponse::from(&req)
///     .with_patch(Patch(vec![PatchOperation::Add(AddOperation {
///         path: PointerBuf::from_tokens(["metadata","labels","my-label"]),
///         value: serde_json::Value::String("my-value".to_owned()),
///     })]))
///     .unwrap()
///     .into_review();
///
/// ```
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct AdmissionResponse {
    /// Copied from the corresponding constructing [`AdmissionRequest`].
    #[serde(skip)]
    pub types: TypeMeta,
    /// Identifier for the individual request/response. This must be copied over
    /// from the corresponding AdmissionRequest.
    pub uid: String,
    /// Indicates whether or not the admission request was permitted.
    pub allowed: bool,
    /// Extra details into why an admission request was denied. This field IS NOT
    /// consulted in any way if "Allowed" is "true".
    #[serde(rename = "status")]
    pub result: Status,
    /// The patch body. Currently we only support "JSONPatch" which implements
    /// RFC 6902.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub patch: Option<Vec<u8>>,
    /// The type of Patch. Currently we only allow "JSONPatch".
    #[serde(skip_serializing_if = "Option::is_none")]
    patch_type: Option<PatchType>,
    /// An unstructured key value map set by remote admission controller (e.g.
    /// error=image-blacklisted). MutatingAdmissionWebhook and
    /// ValidatingAdmissionWebhook admission controller will prefix the keys with
    /// admission webhook name (e.g.
    /// imagepolicy.example.com/error=image-blacklisted). AuditAnnotations will
    /// be provided by the admission webhook to add additional context to the
    /// audit log for this request.
    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
    pub audit_annotations: HashMap<String, String>,
    /// A list of warning messages to return to the requesting API client.
    /// Warning messages describe a problem the client making the API request
    /// should correct or be aware of. Limit warnings to 120 characters if
    /// possible. Warnings over 256 characters and large numbers of warnings may
    /// be truncated.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub warnings: Option<Vec<String>>,
}

impl<T: Resource> From<&AdmissionRequest<T>> for AdmissionResponse {
    fn from(req: &AdmissionRequest<T>) -> Self {
        Self {
            types: req.types.clone(),
            uid: req.uid.clone(),
            allowed: true,
            result: Default::default(),
            patch: None,
            patch_type: None,
            audit_annotations: Default::default(),
            warnings: None,
        }
    }
}

impl AdmissionResponse {
    /// Constructs an invalid [`AdmissionResponse`]. It doesn't copy the uid from
    /// the corresponding [`AdmissionRequest`], so should only be used when the
    /// original request cannot be read.
    pub fn invalid<T: ToString>(reason: T) -> Self {
        Self {
            // Since we don't have a request to use for construction, just
            // default to "admission.k8s.io/v1beta1", since it is the most
            // supported and we won't be using any of the new fields.
            types: TypeMeta {
                kind: META_KIND.to_owned(),
                api_version: META_API_VERSION_V1.to_owned(),
            },
            uid: Default::default(),
            allowed: false,
            result: Status::failure(&reason.to_string(), "InvalidRequest"),
            patch: None,
            patch_type: None,
            audit_annotations: Default::default(),
            warnings: None,
        }
    }

    /// Deny the request with a reason. The reason will be sent to the original caller.
    #[must_use]
    pub fn deny<T: ToString>(mut self, reason: T) -> Self {
        self.allowed = false;
        self.result.message = reason.to_string();
        self
    }

    /// Add JSON patches to the response, modifying the object from the request.
    pub fn with_patch(mut self, patch: json_patch::Patch) -> Result<Self, SerializePatchError> {
        self.patch = Some(serde_json::to_vec(&patch).map_err(SerializePatchError)?);
        self.patch_type = Some(PatchType::JsonPatch);

        Ok(self)
    }

    /// Converts an [`AdmissionResponse`] into a generic [`AdmissionReview`] that
    /// can be used as a webhook response.
    pub fn into_review(self) -> AdmissionReview<DynamicObject> {
        AdmissionReview {
            types: self.types.clone(),
            request: None,
            response: Some(self),
        }
    }
}

/// The type of patch returned in an [`AdmissionResponse`].
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
pub enum PatchType {
    /// Specifies the patch body implements JSON Patch under RFC 6902.
    #[serde(rename = "JSONPatch")]
    JsonPatch,
}

#[cfg(test)]
mod test {
    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"}}}"#;

    use crate::{
        DynamicObject,
        admission::{AdmissionResponse, AdmissionReview, ConvertAdmissionReviewError},
    };

    #[test]
    fn v1_webhook_unmarshals() {
        serde_json::from_str::<AdmissionReview<DynamicObject>>(WEBHOOK_BODY).unwrap();
    }

    #[test]
    fn version_passes_through() -> Result<(), ConvertAdmissionReviewError> {
        let rev = serde_json::from_str::<AdmissionReview<DynamicObject>>(WEBHOOK_BODY).unwrap();
        let rev_typ = rev.types.clone();
        let res = AdmissionResponse::from(&rev.try_into()?).into_review();

        // Ensure TypeMeta was correctly deserialized.
        assert_ne!(&rev_typ.api_version, "");
        // The TypeMeta should be correctly passed through from the incoming
        // request.
        assert_eq!(&rev_typ, &res.types);
        Ok(())
    }

    #[cfg(feature = "cel")]
    #[test]
    fn to_cel_request_projects_fields() {
        use crate::admission::{AdmissionRequest, Operation};
        let rev = serde_json::from_str::<AdmissionReview<DynamicObject>>(WEBHOOK_BODY).unwrap();
        let mut req: AdmissionRequest<DynamicObject> = rev.try_into().unwrap();

        let cel = req.to_cel_request();
        assert_eq!(cel.operation, "CREATE");
        assert_eq!(cel.name, "echo-pod");
        assert_eq!(cel.namespace, "colin-coder");
        assert_eq!(cel.username, "colin@coder.com");
        assert_eq!(cel.groups, vec!["system:authenticated".to_string()]);
        assert_eq!(cel.kind.group, "");
        assert_eq!(cel.kind.version, "v1");
        assert_eq!(cel.kind.kind, "Pod");
        assert_eq!(cel.resource.resource, "pods");
        assert!(!cel.dry_run);

        // `uid` is the *user* uid (`userInfo.uid`), never the round-trip request uid.
        assert_ne!(req.uid, ""); // sanity: round-trip uid is populated in the payload
        assert_eq!(cel.uid, ""); // userInfo.uid is absent -> empty, NOT req.uid
        req.user_info.uid = Some("user-123".to_owned());
        assert_eq!(req.to_cel_request().uid, "user-123");

        // every Operation variant maps to its SCREAMING_SNAKE form
        for (op, expected) in [
            (Operation::Create, "CREATE"),
            (Operation::Update, "UPDATE"),
            (Operation::Delete, "DELETE"),
            (Operation::Connect, "CONNECT"),
        ] {
            req.operation = op;
            assert_eq!(req.to_cel_request().operation, expected);
        }

        // dry_run passes through
        req.dry_run = true;
        assert!(req.to_cel_request().dry_run);
    }
}