feat(stackable-versioned)!: Integrate with ConversionReviews

[sbernauer]

This PR adds utilities to convert a CRD from one version into a different version. This is tightly integrated with CRD conversions, which send ConversionReviews to registered webhooks and return that review to the K8s apiserver.

TLDR

• BREAKING: The #[versioned(k8s(skip(merged_crd)))] flag has been removed
• BREAKING: The version enum used in merged_crd is now suffixed with Version
• Add new try_convert function to convert objects received via a ConversionReview
• Add new enable_tracing option to #[versioned(k8s(options(...)))]

Detailed Overview

There are multiple different parts to make this whole process work. All of these parts are automatically generated by the macro and for the user it is a single function call: Foo::try_convert. The individual parts are explained below.

Note

The CRD spec currently does not contain any fields. During the development of the conversion mechanism, this is emitted to more easily focus on the newly generated code. It will eventually contain fields to fully test the implementation.

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1beta1"),
    version(name = "v1"),
    k8s(group = "foo.stackable.tech")
)]
#[derive(Clone, Debug, CustomResource, Deserialize, Serialize, JsonSchema)]
pub struct FooSpec {}

Updated Version Enum

The generated code tries to abstract away as much of the underlying code as possible. For this use-case, a top-level version enum exists. Before this PR, it only provided an easy way to produce a single, merged CRD based on all defined CRD versions via Foo::merged_crd(Foo::V1). The variants described the available versions and forced users to use well-defined versions instead of &str which can be anything (eg. an invalid version).

This PR changes the inner workings of this enum. Instead of only providing plain variants without any data, each variant now holds the appropriate version of the custom resource.

// Before
pub enum Foo {
    V1Alpha1,
    V1Beta1,
    V1,
}

// After
pub enum Foo {
    V1Alpha1(v1alpha1::Foo),
    V1Beta1(v1beta1::Foo),
    V1(v1::Foo),
}

This change enables us to directly deserialize an object of a custom resource into the enum. This then enables us to generate further (in addition to merged_crd) top-level abstractions on the enum.

With this change it is not possible to use Self to specify the stored apiversion via Foo::merged_crd(). Instead, a new enum for this purpose only is generated.

pub enum FooVersion {
    V1Alpha1,
    V1Beta1,
    V1,
}

impl ::std::fmt::Display for FooVersion {
    fn fmt(
        &self,
        f: &mut ::std::fmt::Formatter<'_>,
    ) -> ::std::result::Result<(), ::std::fmt::Error> {
        f.write_str(self.as_str())
    }
}

impl FooVersion {
    pub fn as_str(&self) -> &str {
        match self {
            V1Alpha1 => "v1alpha1",
            V1Beta1 => "v1beta1",
            V1 => "v1",
        }
    }
}

(De)serialization from/to JSON values

Most (if not all) conversion will be handled automatically by a CRD conversion webhook. Before the K8s apiserver either stores the custom resource in etcd or responds to clients, it will send a ConversionReview to the registered webhook. A list of to be converted objects is provided as a JSON object. This is also represented in Rust code, more specifically a serde_json::Value.

As such, the code needs to be able to turn the JSON object into a Rust representation (in the correct version). Once conversion is performed, the opposite operation needs to be performed: turning the Rust struct back into serialized JSON.

This PR introduces two new (private) methods to do this:

impl Foo {
    fn from_json_value(value: serde_json::Value) -> Result<Self, ()>
    fn into_json_value(self) -> Result<serde_json::Value, ()>
}

Conversion function

Currently, conversion of custom objects (defined by versioned CRDs) is achieved by receiving the ConversionReview via a webhook (which will be run alongside the operator in the future). This ConversionReview is then handed over to the try_convert function. Internally, this will construct strictly typed objects based on the current apiVersion. They are then converted to the desired apiVersion and added to the list of converted objects. If all objects were able to be converted, a successful ConversionReview is returned. Otherwise, a failure is indicated.

impl Foo {
    pub fn try_convert(review: ConversionReview) -> ConversionReview
}

...

Partial expanded code

#[automatically_derived]
pub enum Foo {
    V1Alpha1(v1alpha1::Foo),
    V1Beta1(v1beta1::Foo),
    V1(v1::Foo),
}
#[automatically_derived]
impl Foo {
    #[doc = r" Generates a merged CRD containing all versions and marking `stored_apiversion` as stored."]
    pub fn merged_crd(stored_apiversion:FooVersion) ->  ::std::result::Result< ::k8s_openapi::apiextensions_apiserver::pkg::apis::apiextensions::v1::CustomResourceDefinition, ::kube::core::crd::MergeError>{
        ::kube::core::crd::merge_crds(
            <[_]>::into_vec(
                #[rustc_box]
                alloc::boxed::Box::new([
                    (<v1alpha1::Foo as ::kube::core::CustomResourceExt>::crd()),
                    (<v1beta1::Foo as ::kube::core::CustomResourceExt>::crd()),
                    (<v1::Foo as ::kube::core::CustomResourceExt>::crd()),
                ]),
            ),
            stored_apiversion.as_str(),
        )
    }
    #[doc = "Tries to convert a list of objects of kind [`Foo`] to the desired API version"]
    #[doc = "specified in the [`ConversionReview`][cr]."]
    #[doc = ""]
    #[doc = "The returned [`ConversionReview`][cr] either indicates a success or a failure, which"]
    #[doc = "is handed back to the Kubernetes API server."]
    #[doc = ""]
    #[doc = "[cr]: ::kube::core::conversion::ConversionReview"]
    pub fn try_convert(
        review: ::kube::core::conversion::ConversionReview,
    ) -> ::kube::core::conversion::ConversionReview {
        let request = match ::kube::core::conversion::ConversionRequest::from_review(review) {
            ::std::result::Result::Ok(request) => request,
            ::std::result::Result::Err(err) => {
                return ::kube::core::conversion::ConversionResponse::invalid(
                    ::kube::client::Status {
                        status: Some(::kube::core::response::StatusSummary::Failure),
                        message: err.to_string(),
                        reason: err.to_string(),
                        details: None,
                        code: 400,
                    },
                )
                .into_review();
            }
        };
        let desired_api_version = request.desired_api_version.as_str();
        let response = match Self::convert_objects(request.objects, desired_api_version) {
            ::std::result::Result::Ok(converted_objects) => {
                ::kube::core::conversion::ConversionResponse {
                    result: ::kube::client::Status::success(),
                    types: request.types,
                    uid: request.uid,
                    converted_objects,
                }
            }
            ::std::result::Result::Err(err) => {
                let code = err.http_status_code();
                let message = err.join_errors();
                ::kube::core::conversion::ConversionResponse {
                    result: ::kube::client::Status {
                        status: Some(::kube::core::response::StatusSummary::Failure),
                        message: message.clone(),
                        reason: message,
                        details: None,
                        code,
                    },
                    types: request.types,
                    uid: request.uid,
                    converted_objects: alloc::vec::Vec::new(),
                }
            }
        };
        response.into_review()
    }
    fn convert_objects(
        objects: ::std::vec::Vec<::serde_json::Value>,
        desired_api_version: &str,
    ) -> ::std::result::Result<
        ::std::vec::Vec<::serde_json::Value>,
        ::stackable_versioned::ConvertObjectError,
    > {
        let mut converted_objects = ::std::vec::Vec::with_capacity(objects.len());
        for object in objects {
            let current_object = Self::from_json_value(object.clone())
                .map_err(|source| ::stackable_versioned::ConvertObjectError::Parse { source })?;
            match (current_object, desired_api_version) {
                (Self::V1Alpha1(__sv_foo), "v1beta1") => {
                    let converted: v1beta1::FooSpec = __sv_foo.spec.into();
                    let desired_object = Self::V1Beta1(v1beta1::Foo {
                        metadata: __sv_foo.metadata,
                        spec: converted,
                    });
                    let desired_object = desired_object.into_json_value().map_err(|source| {
                        ::stackable_versioned::ConvertObjectError::Serialize { source }
                    })?;
                    converted_objects.push(desired_object);
                }
                (Self::V1Alpha1(__sv_foo), "v1") => {
                    let converted: v1beta1::FooSpec = __sv_foo.spec.into();
                    let converted: v1::FooSpec = converted.into();
                    let desired_object = Self::V1(v1::Foo {
                        metadata: __sv_foo.metadata,
                        spec: converted,
                    });
                    let desired_object = desired_object.into_json_value().map_err(|source| {
                        ::stackable_versioned::ConvertObjectError::Serialize { source }
                    })?;
                    converted_objects.push(desired_object);
                }
                (Self::V1Beta1(__sv_foo), "v1alpha1") => {
                    let converted: v1alpha1::FooSpec = __sv_foo.spec.into();
                    let desired_object = Self::V1Alpha1(v1alpha1::Foo {
                        metadata: __sv_foo.metadata,
                        spec: converted,
                    });
                    let desired_object = desired_object.into_json_value().map_err(|source| {
                        ::stackable_versioned::ConvertObjectError::Serialize { source }
                    })?;
                    converted_objects.push(desired_object);
                }
                (Self::V1Beta1(__sv_foo), "v1") => {
                    let converted: v1::FooSpec = __sv_foo.spec.into();
                    let desired_object = Self::V1(v1::Foo {
                        metadata: __sv_foo.metadata,
                        spec: converted,
                    });
                    let desired_object = desired_object.into_json_value().map_err(|source| {
                        ::stackable_versioned::ConvertObjectError::Serialize { source }
                    })?;
                    converted_objects.push(desired_object);
                }
                (Self::V1(__sv_foo), "v1alpha1") => {
                    let converted: v1beta1::FooSpec = __sv_foo.spec.into();
                    let converted: v1alpha1::FooSpec = converted.into();
                    let desired_object = Self::V1Alpha1(v1alpha1::Foo {
                        metadata: __sv_foo.metadata,
                        spec: converted,
                    });
                    let desired_object = desired_object.into_json_value().map_err(|source| {
                        ::stackable_versioned::ConvertObjectError::Serialize { source }
                    })?;
                    converted_objects.push(desired_object);
                }
                (Self::V1(__sv_foo), "v1beta1") => {
                    let converted: v1beta1::FooSpec = __sv_foo.spec.into();
                    let desired_object = Self::V1Beta1(v1beta1::Foo {
                        metadata: __sv_foo.metadata,
                        spec: converted,
                    });
                    let desired_object = desired_object.into_json_value().map_err(|source| {
                        ::stackable_versioned::ConvertObjectError::Serialize { source }
                    })?;
                    converted_objects.push(desired_object);
                }
                _ => converted_objects.push(object),
            }
        }
        ::std::result::Result::Ok(converted_objects)
    }
    fn from_json_value(
        value: ::serde_json::Value,
    ) -> ::std::result::Result<Self, ::stackable_versioned::ParseObjectError> {
        let api_version = value
            .get("apiVersion")
            .ok_or_else(|| ::stackable_versioned::ParseObjectError::FieldNotPresent)?
            .as_str()
            .ok_or_else(|| ::stackable_versioned::ParseObjectError::FieldNotStr)?;
        let object = match api_version {
            "foo.stackable.tech/v1alpha1" | "v1alpha1" => {
                let object = ::serde_json::from_value(value).map_err(|source| {
                    ::stackable_versioned::ParseObjectError::Deserialize { source }
                })?;
                Self::V1Alpha1(object)
            }
            "foo.stackable.tech/v1beta1" | "v1beta1" => {
                let object = ::serde_json::from_value(value).map_err(|source| {
                    ::stackable_versioned::ParseObjectError::Deserialize { source }
                })?;
                Self::V1Beta1(object)
            }
            "foo.stackable.tech/v1" | "v1" => {
                let object = ::serde_json::from_value(value).map_err(|source| {
                    ::stackable_versioned::ParseObjectError::Deserialize { source }
                })?;
                Self::V1(object)
            }
            unknown_api_version => {
                return ::std::result::Result::Err(
                    ::stackable_versioned::ParseObjectError::UnknownApiVersion {
                        api_version: unknown_api_version.to_owned(),
                    },
                );
            }
        };
        ::std::result::Result::Ok(object)
    }
    fn into_json_value(self) -> ::std::result::Result<::serde_json::Value, ::serde_json::Error> {
        match self {
            Self::V1Alpha1(__sv_foo) => Ok(::serde_json::to_value(__sv_foo)?),
            Self::V1Beta1(__sv_foo) => Ok(::serde_json::to_value(__sv_foo)?),
            Self::V1(__sv_foo) => Ok(::serde_json::to_value(__sv_foo)?),
        }
    }
}
#[automatically_derived]
pub enum FooVersion {
    V1Alpha1,
    V1Beta1,
    V1,
}
#[automatically_derived]
impl ::std::fmt::Display for FooVersion {
    fn fmt(
        &self,
        f: &mut ::std::fmt::Formatter<'_>,
    ) -> ::std::result::Result<(), ::std::fmt::Error> {
        f.write_str(self.as_str())
    }
}
#[automatically_derived]
impl FooVersion {
    pub fn as_str(&self) -> &str {
        match self {
            V1Alpha1 => "v1alpha1",
            V1Beta1 => "v1beta1",
            V1 => "v1",
        }
    }
}

[NickLarsenNZ]

Left comments and suggestions

[NickLarsenNZ]

Note to self: check if this is the same in our other rust repos:

• operator-templating
• stackablectl
• docker-images (patchable)
• containerdebug
• actions (interu)
• trino-lb
• product-config (any reason this can't just be a crate inside operator-rs?)
• config-utils

There are more, but they are less used.

[NickLarsenNZ]

Nothing to action here, this was just me thinking. I will check it out later.

[NickLarsenNZ]

LGTM