Attribute Macro versioned

Source

#[versioned]

Expand description

This macro enables generating versioned structs and enums.

In this guide, code blocks usually come in pairs. The first code block describes how the macro is used. The second expandable block displays the generated piece of code for explanation purposes. It should be noted, that the exact code can diverge from what is being depicted in this guide. For example, #[automatically_derived] and #[allow(deprecated)] are removed in most examples to reduce visual clutter.

It is important to note that this macro must be placed before any other (derive) macros and attributes. Macros supplied before the versioned macro will be erased, because the original struct, enum or module (container) is erased, and new containers are generated. This ensures that the macros and attributes are applied to the generated versioned instances of the container.

§Declaring Versions

Before any of the fields or variants can be versioned, versions need to be declared at the container level. Each version currently supports two parameters: name and the deprecated flag. The name must be a valid (and supported) format.

Currently, only Kubernetes API versions are supported. The macro checks each declared version and reports any error encountered during parsing.

It should be noted that the defined struct always represents the latest version, eg: when defining three versions v1alpha1, v1beta1, and v1, the struct will describe the structure of the data in v1. This behaviour is especially noticeable in the changed() action which works “backwards” by describing how a field looked before the current (latest) version.

#[versioned(version(name = "v1alpha1"))]
struct Foo {
    bar: usize,
}

Generated code

The #[automatically_derived] attribute indicates that the following piece of code is automatically generated by a macro instead of being handwritten by a developer. This information is used by cargo and rustc.
For each declared version, a new module containing the container is generated. This enables you to reference the container by versions via v1alpha1::Foo.
This use statement gives the generated containers access to the imports at the top of the file. This is a convenience, because otherwise you would need to prefix used items with super::. Additionally, other macros can have trouble using items referred to with super::.

#[automatically_derived] // 1
mod v1alpha1 {           // 2
    use super::*;        // 3
    pub struct Foo {
        bar: usize,
    }
}

§Deprecation of a Version

The deprecated flag marks the version as deprecated. This currently adds the #[deprecated] attribute to the appropriate piece of code.

#[versioned(version(name = "v1alpha1", deprecated))]
struct Foo {
    bar: usize,
}

Generated code

The deprecated flag will generate a #[deprecated] attribute and the note is automatically generated.

#[automatically_derived]
#[deprecated = "Version v1alpha1 is deprecated"] // 1
mod v1alpha1 {
    use super::*;
    pub struct Foo {
        pub bar: usize,
    }
}

§Version Sorting

Additionally, it is ensured that each version is unique. Declaring the same version multiple times will result in an error. Furthermore, declaring the versions out-of-order is prohibited by default. It is possible to opt-out of this check by setting options(allow_unsorted).

It is not recommended to use this setting and instead use sorted versions across all versioned items.

#[versioned(
    version(name = "v1beta1"),
    version(name = "v1alpha1"),
    options(allow_unsorted)
)]
struct Foo {
    bar: usize,
}

§Versioning Items in a Module

Using the macro on structs and enums is explained in detail in the following sections. This section is dedicated to explain the usage of the macro when applied to a module.

Using the macro on a module has one clear use-case: Versioning multiple structs and enums at once in a single file. Applying the #[versioned] macro to individual containers will result in invalid Rust code which the compiler rejects. This behaviour can best be explained using the following example:

#[versioned(version(name = "v1alpha1"))]
struct Foo {}

#[versioned(version(name = "v1alpha1"))]
struct Bar {}

In this example, two different structs are versioned using the same version, v1alpha1. Each macro will now (independently) expand into versioned code. This will result in the module named v1alpha1 to be emitted twice, in the same file. This is invalid Rust code. You cannot define the same module more than once in the same file.

Expand Generated Invalid Code

mod v1alpha1 {
    struct Foo {}
}

mod v1alpha1 {
    struct Bar {}
}

This behaviour makes it impossible to version multiple containers in the same file. The only solution would be to put each container into its own file which in many cases is not needed or even undesired. To solve this issue, it is thus possible to apply the macro to a module.

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1")
)]
mod versioned {
    struct Foo {
        bar: usize,
    }

    struct Bar {
        baz: String,
    }
}

Expand Generated Code

All containers defined in the module will get versioned. That’s why every version module includes all containers.
Each version will expand to a version module, as expected.

mod v1alpha1 {
    use super::*;
    pub struct Foo { // 1
        bar: usize,
    }
    pub struct Bar { // 1
        baz: String,
    }
}

mod v1 {             // 2
    use super::*;
    pub struct Foo {
        bar: usize,
    }
    pub struct Bar {
        baz: String,
    }
}

It should be noted that versions are now defined at the module level and not at the struct / enum level. Item actions describes in the following section can be used as expected.

§Preserve Module

The previous examples completely replaced the versioned module with top-level version modules. This is the default behaviour. Preserving the module can however be enabled by setting the preserve_module flag.

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1"),
    options(preserve_module)
)]
mod versioned {
    struct Foo {
        bar: usize,
    }

    struct Bar {
        baz: String,
    }
}

§Re-emitting and merging Submodules

Modules defined in the versioned module will be re-emitted. This allows for composition of re-exports to compose easier to use imports for downstream consumers of versioned containers. The following rules apply:

Only modules named the same like defined versions will be re-emitted. Using modules with invalid names will return an error.
Only use statements defined in the module will be emitted. Declaring other items will return an error.

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1")
)]
mod versioned {
    mod v1alpha1 {
        pub use a::v1alpha1::*;
        pub use b::v1alpha1::*;
    }

    struct Foo {
        bar: usize,
    }
}

Expand Generated Code

mod v1alpha1 {
    use super::*;
    pub use a::v1alpha1::*;
    pub use b::v1alpha1::*;
    pub struct Foo {
        pub bar: usize,
    }
}

impl ::std::convert::From<v1alpha1::Foo> for v1::Foo {
    fn from(__sv_foo: v1alpha1::Foo) -> Self {
        Self {
            bar: __sv_foo.bar.into(),
        }
    }
}

mod v1 {
    use super::*;
    pub struct Foo {
        pub bar: usize,
    }
}

§Item Actions

This crate currently supports three different item actions. Items can be added, changed, and deprecated. The macro ensures that these actions adhere to the following set of rules:

Items cannot be added and deprecated in the same version.
Items cannot be added and changed in the same version.
Items cannot be changed and deprecated in the same version.
Items added in version a, renamed 0…n times in versions b₁, …, b_n and deprecated in version c must ensure a < b₁, …, b_n < c.
All item actions must use previously declared versions. Using versions not present at the container level will result in an error.

For items marked as deprecated, one additional rule applies:

Fields must start with the deprecated_ and variants with the Deprecated prefix. This is enforced because Kubernetes doesn’t allow removing fields in CRDs entirely. Instead, they should be marked as deprecated. By convention this is done with the deprecated prefix.

§Added Action

This action indicates that an item is added in a particular version. Available parameters are:

since to indicate since which version the item is present.
default to customize the default function used to populate the item in auto-generated From implementations.

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1beta1")
)]
pub struct Foo {
    #[versioned(added(since = "v1beta1"))]
    bar: usize,
    baz: bool,
}

Expand Generated Code

The field bar is not yet present in version v1alpha1 and is therefore not generated.
Now the field bar is present and uses Default::default() to populate the field during conversion. This function can be customized as shown later in this guide.

pub mod v1alpha1 {
    use super::*;
    pub struct Foo {                 // 1
        pub baz: bool,
    }
}

impl From<v1alpha1::Foo> for v1beta1::Foo {
    fn from(foo: v1alpha1::Foo) -> Self {
        Self {
            bar: Default::default(), // 2
            baz: foo.baz,
        }
    }
}

pub mod v1beta1 {
    use super::*;
    pub struct Foo {
        pub bar: usize,              // 2
        pub baz: bool,
    }
}

§Custom Default Function

To customize the default function used in the generated From implementation you can use the default parameter. It expects a path to a function without braces.

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1beta1")
)]
pub struct Foo {
    #[versioned(added(since = "v1beta1", default = "default_bar"))]
    bar: usize,
    baz: bool,
}

fn default_bar() -> usize {
    42
}

Expand Generated Code

Instead of Default::default(), the provided function default_bar() is used. It is of course fully type checked and needs to return the expected type (usize in this case).

// Snip

impl From<v1alpha1::Foo> for v1beta1::Foo {
    fn from(foo: v1alpha1::Foo) -> Self {
        Self {
            bar: default_bar(), // 1
            baz: foo.baz,
        }
    }
}

// Snip

§Changed Action

This action indicates that an item is changed in a particular version. It combines renames and type changes into a single action. You can choose to change the name, change the type or do both. Available parameters are:

since to indicate since which version the item is changed.
from_name to indicate from which previous name the field is renamed.
from_type to indicate from which previous type the field is changed.
upgrade_with to provide a custom upgrade function. This argument can only be used in combination with the from_type argument. The expected function signature is: fn (OLD_TYPE) -> NEW_TYPE. This function must not fail.
downgrade_with to provide a custom downgrade function. This argument can only be used in combination with the from_type argument. The expected function signature is: fn (NEW_TYPE) -> OLD_TYPE. This function must not fail.

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1beta1")
)]
pub struct Foo {
    #[versioned(changed(
        since = "v1beta1",
        from_name = "prev_bar",
        from_type = "u16",
        downgrade_with = usize_to_u16
    ))]
    bar: usize,
    baz: bool,
}

fn usize_to_u16(input: usize) -> u16 {
    input.try_into().unwrap()
}

Expand Generated Code

In version v1alpha1 the field is named prev_bar and uses a u16.
In the next version, v1beta1, the field is now named bar and uses usize instead of a u16. The From implementation transforms the type automatically via the .into() call.

pub mod v1alpha1 {
    use super::*;
    pub struct Foo {
        pub prev_bar: u16,            // 1
        pub baz: bool,
    }
}

impl From<v1alpha1::Foo> for v1beta1::Foo {
    fn from(foo: v1alpha1::Foo) -> Self {
        Self {
            bar: foo.prev_bar.into(), // 2
            baz: foo.baz,
        }
    }
}

pub mod v1beta1 {
    use super::*;
    pub struct Foo {
        pub bar: usize,               // 2
        pub baz: bool,
    }
}

§Deprecated Action

This action indicates that an item is deprecated in a particular version. Deprecated items are not removed.

#[versioned(version(name = "v1alpha1"), version(name = "v1beta1"))]
pub struct Foo {
    #[versioned(deprecated(since = "v1beta1"))]
    deprecated_bar: usize,
    baz: bool,
}

Expand Generated Code

In version v1alpha1 the field bar is not yet deprecated and thus uses the name without the deprecated_ prefix.
In version v1beta1 the field is deprecated and now includes the deprecated_ prefix. It also uses the #[deprecated] attribute to indicate to Clippy this part of Rust code is deprecated. Therefore, the From implementation includes #[allow(deprecated)] to allow the usage of deprecated items in automatically generated code.

pub mod v1alpha1 {
    use super::*;
    pub struct Foo {
        pub bar: usize,                     // 1
        pub baz: bool,
    }
}

#[allow(deprecated)]                        // 2
impl From<v1alpha1::Foo> for v1beta1::Foo {
    fn from(foo: v1alpha1::Foo) -> Self {
        Self {
            deprecated_bar: foo.bar,        // 2
            baz: foo.baz,
        }
    }
}

pub mod v1beta1 {
    use super::*;
    pub struct Foo {
        #[deprecated]                       // 2
        pub deprecated_bar: usize,
        pub baz: bool,
    }
}

§Auto-generated `From` Implementations

To enable smooth container version upgrades, the macro automatically generates From implementations. On a high level, code generated for two versions a and b, with a < b looks like this: impl From<a> for b. As you can see, only upgrading is currently supported. Downgrading from a higher version to a lower one is not supported at the moment.

This automatic generation can be skipped to enable a custom implementation for more complex conversions.

§Custom conversion function at field level

As stated in the changed() section, a custom conversion function can be provided using the downgrade_with and upgrade_with argument. A simple example looks like this:

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1beta1")
)]
pub struct Foo {
    #[versioned(changed(
        since = "v1beta1",
        from_type = "u8",
        downgrade_with = "u16_to_u8"
    ))]
    bar: u16,
}

fn u16_to_u8(input: u16) -> u8 {
    input.try_into().unwrap()
}

Expand Generated Code

pub mod v1alpha1 {
    use super::*;
    pub struct Foo {
        pub bar: u8,
    }
}

impl ::std::convert::From<v1alpha1::Foo> for v1beta1::Foo {
    fn from(__sv_foo: v1alpha1::Foo) -> Self {
        Self {
            bar: __sv_foo.bar.into(),
        }
    }
}

impl ::std::convert::From<v1beta1::Foo> for v1alpha1::Foo {
    fn from(__sv_foo: v1beta1::Foo) -> Self {
        Self {
            bar: u16_to_u8(__sv_foo.bar),
        }
    }
}

pub mod v1beta1 {
    use super::*;
    pub struct Foo {
        pub bar: u16,
    }
}

§Skipping at the Container Level

Disabling this behavior at the container level results in no From implementation for all versions.

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1beta1"),
    version(name = "v1"),
    options(skip(from))
)]
pub struct Foo {
    #[versioned(
        added(since = "v1beta1"),
        deprecated(since = "v1")
    )]
    deprecated_bar: usize,
    baz: bool,
}

§Skipping at the Version Level

Disabling this behavior at the version level results in no From implementation for that particular version. This can be read as “skip generation for converting this version to the next one”. In the example below no conversion between version v1beta1 and v1 is generated.

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1beta1", skip(from)),
    version(name = "v1")
)]
pub struct Foo {
    #[versioned(
        added(since = "v1beta1"),
        deprecated(since = "v1")
    )]
    deprecated_bar: usize,
    baz: bool,
}

§Kubernetes-specific Features

This macro also offers support for Kubernetes-specific versioning, especially for CustomResourceDefinitions (CRDs). These features are completely opt-in. You need to enable the k8s feature (which enables optional dependencies) and use the k8s() parameter in the macro.

You need to derive both [kube::CustomResource] and schemars::JsonSchema.

§Simple Versioning

use kube::CustomResource;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1beta1"),
    version(name = "v1"),
    k8s(group = "example.com")
)]
#[derive(Clone, Debug, Deserialize, Serialize, CustomResource, JsonSchema)]
pub struct FooSpec {
    #[versioned(
        added(since = "v1beta1"),
        changed(
            since = "v1",
            from_name = "prev_bar",
            from_type = "u16",
            downgrade_with = usize_to_u16
        )
    )]
    bar: usize,
    baz: bool,
}

fn usize_to_u16(input: usize) -> u16 {
    input.try_into().unwrap()
}

§Versioning Items in a Module

Versioning multiple CRD related structs via a module is supported and common rules from above apply here as well. It should however be noted, that specifying Kubernetes specific arguments is done on the container level instead of on the module level, which is detailed in the following example:

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1")
)]
mod versioned {
    #[versioned(k8s(group = "foo.example.org"))]
    #[derive(Clone, Debug, Deserialize, Serialize, CustomResource, JsonSchema)]
    struct FooSpec {
        bar: usize,
    }

    #[versioned(k8s(group = "bar.example.org"))]
    #[derive(Clone, Debug, Deserialize, Serialize, CustomResource, JsonSchema)]
    struct BarSpec {
        baz: String,
    }
}

Expand Generated Code

mod v1alpha1 {
    use super::*;
    #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema, CustomResource)]
    #[kube(
        group = "foo.example.org",
        version = "v1alpha1",
        kind = "Foo"
    )]
    pub struct FooSpec {
        pub bar: usize,
    }

    #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema, CustomResource)]
    #[kube(
        group = "bar.example.org",
        version = "v1alpha1",
        kind = "Bar"
    )]
    pub struct BarSpec {
        pub bar: usize,
    }
}

mod v1 {
    use super::*;
    #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema, CustomResource)]
    #[kube(
        group = "foo.example.org",
        version = "v1",
        kind = "Foo"
    )]
    pub struct FooSpec {
        pub bar: usize,
    }

    #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema, CustomResource)]
    #[kube(
        group = "bar.example.org",
        version = "v1",
        kind = "Bar"
    )]
    pub struct BarSpec {
        pub bar: usize,
    }
}

It is possible to include structs and enums which are not CRDs. They are instead versioned as expected (without adding the #[kube] derive macro and generating code to merge CRD versions).

§Arguments

Currently, the following Kubernetes (kube) specific arguments are supported

§`#[versioned(k8s(group = "..."))]`

Required. Set the group of the CRD, usually the domain of the company, like example.com.

§`#[versioned(k8s(kind = "..."))]`

Override the kind field of the CRD. This defaults to the struct name (without the Spec suffix). Overriding this value will also influence the names of other generated items, like the status struct (if used) or the version enum.

§`#[versioned(k8s(singular = "..."))]`

Set the singular name. Defaults to lowercased kind value.

§`#[versioned(k8s(plural = "..."))]`

Set the plural name. Defaults to inferring from singular.

§`#[versioned(k8s(namespaced))]`

Indicate that this is a namespaced scoped resource rather than a cluster scoped resource.

§`#[versioned(k8s(crates(...)))]`

Override the import path of specific crates. The following code block depicts supported overrides and their default values.

#[versioned(k8s(crates(
    kube_core = ::kube::core,
    kube_client = ::kube::client,
    k8s_openapi = ::k8s_openapi,
    schemars = ::schemars,
    serde = ::serde,
    serde_json = ::serde_json,
    versioned = ::stackable_versioned,
)))]
pub struct Foo {}

§`#[versioned(k8s(status = "..."))]`

Set the specified struct as the status subresource. If conversion tracking is enabled, this struct will be automatically merged into the generated tracking status struct.

§`#[versioned(k8s(shortname = "..."))]`

Set a shortname. This can be specified multiple times.

§`#[versioned(k8s(options(...)))]`

#[versioned(k8s(options(
    // Highly experimental conversion tracking. Opting into this feature will
    // introduce frequent breaking changes.
    experimental_conversion_tracking,

    // Enables instrumentation and log events via the tracing crate.
    enable_tracing,
)))]
pub struct Foo {}

§Merge CRDs

The generated merged_crd method is a wrapper around kube’s merge_crds function. It automatically calls the crd methods of the CRD in all of its versions and additionally provides a strongly typed selector for the stored API version.

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1beta1"),
    k8s(group = "example.com")
)]
#[derive(Clone, Debug, Deserialize, Serialize, CustomResource, JsonSchema)]
pub struct FooSpec {
    #[versioned(added(since = "v1beta1"))]
    bar: usize,
    baz: bool,
}

let merged_crd = Foo::merged_crd(FooVersion::V1Beta1).unwrap();
println!("{yaml}", yaml = serde_yaml::to_string(&merged_crd).unwrap());

§Convert CRDs

The conversion of CRDs is tightly integrated with ConversionReviews, the payload which a conversion webhook receives from the K8s apiserver. Naturally, the try_convert function takes in ConversionReview as a parameter and also returns a ConversionReview indicating success or failure.

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1beta1"),
    k8s(group = "example.com")
)]
#[derive(Clone, Debug, Deserialize, Serialize, CustomResource, JsonSchema)]
pub struct FooSpec {
    #[versioned(added(since = "v1beta1"))]
    bar: usize,
    baz: bool,
}

let conversion_review = Foo::try_convert(conversion_review);

§OpenTelemetry Semantic Conventions

If tracing is enabled, various traces and events are emitted. The fields of these signals follow the general rules of OpenTelemetry semantic conventions. There are currently no agreed-upon semantic conventions for CRD conversions. In the meantime these fields are used:

Field	Type (Example)	Description
`k8s.crd.conversion.converted_object_count`	usize (6)	The number of successfully converted objects sent back in a conversion review
`k8s.crd.conversion.desired_api_version`	String (v1alpha1)	The desired api version received via a conversion review
`k8s.crd.conversion.api_version`	String (v1beta1)	The current api version of an object received via a conversion review
`k8s.crd.conversion.steps`	usize (2)	The number of steps required to convert a single object from the current to the desired version
`k8s.crd.conversion.kind`	String (Foo)	The kind of the CRD

Attribute Macro versionedCopy item path

§Declaring Versions

§Deprecation of a Version

§Version Sorting

§Versioning Items in a Module

§Preserve Module

§Re-emitting and merging Submodules

§Item Actions

§Added Action

§Custom Default Function

§Changed Action

§Deprecated Action

§Auto-generated From Implementations

§Custom conversion function at field level

§Skipping at the Container Level

§Skipping at the Version Level

§Kubernetes-specific Features

§Simple Versioning

§Versioning Items in a Module

§Arguments

§#[versioned(k8s(group = "..."))]

§#[versioned(k8s(kind = "..."))]

§#[versioned(k8s(singular = "..."))]

§#[versioned(k8s(plural = "..."))]

§#[versioned(k8s(namespaced))]

§#[versioned(k8s(crates(...)))]

§#[versioned(k8s(status = "..."))]

§#[versioned(k8s(shortname = "..."))]

§#[versioned(k8s(options(...)))]

§Merge CRDs

§Convert CRDs

§OpenTelemetry Semantic Conventions

Attribute Macro versioned

§Auto-generated `From` Implementations

§`#[versioned(k8s(group = "..."))]`

§`#[versioned(k8s(kind = "..."))]`

§`#[versioned(k8s(singular = "..."))]`

§`#[versioned(k8s(plural = "..."))]`

§`#[versioned(k8s(namespaced))]`

§`#[versioned(k8s(crates(...)))]`

§`#[versioned(k8s(status = "..."))]`

§`#[versioned(k8s(shortname = "..."))]`

§`#[versioned(k8s(options(...)))]`