[−]Derive Macro kube::CustomResource
#[derive(CustomResource)] { // Attributes available to this derive: #[kube] }
A custom derive for kubernetes custom resource definitions.
This will generate a root object containing your spec and metadata.
This root object will implement the k8s_openapi::Metadata
+ k8s_openapi::Resource
traits so it can be used with kube::Api
.
The generated type will also implement a ::crd
method to generate the crd
at the specified api version (or v1 if unspecified).
Example
use serde::{Serialize, Deserialize}; use kube_derive::CustomResource; #[derive(CustomResource, Clone, Debug, Deserialize, Serialize)] #[kube(group = "clux.dev", version = "v1", kind = "Foo", namespaced)] struct FooSpec { info: String, } fn main() { use k8s_openapi::Resource; println!("kind = {}", Foo::KIND); // impl k8s_openapi::Resource let f = Foo::new("foo-1", FooSpec { info: "informative info".into(), }); println!("foo: {:?}", f); // debug print on generated type println!("crd: {}", serde_yaml::to_string(&Foo::crd()).unwrap()); // crd yaml }
This example creates a struct Foo
containing metadata, the spec,
and optionally status. The generated type Foo
can be used with the kube
crate
as an Api<Foo>
object (FooSpec
can not be used with Api
).
let client = Client::try_default().await?; let foos: Api<Foo> = Api::namespaced(client.clone(), "default"); let crds: Api<CustomResourceDefinition> = Api::all(client.clone()); crds.patch("foos.clux.dev", &ssapply, serde_yaml::to_vec(&Foo::crd())?).await
This example posts the generated ::crd
to the CustomResourceDefinition
API.
After this has been accepted (few secs max), you can start using foos
as a normal
kube Api
object. See the crd_
prefixed examples
for details on this.
Required properties
#[kube(group = "mygroup.tld")]
Your cr api group. The part before the slash in the top level apiVersion
key.
#[kube(version = "v1")]
Your cr api version. The part after the slash in the top level apiVersion
key.
#[kube(kind = "Kind")]
Name of your kind and your generated root type.
Optional #[kube]
attributes
#[kube(apiextensions = "v1beta1")]
The version for CustomResourceDefinition
desired in the apiextensions.k8s.io
group.
Default is v1
(for clusters >= 1.17). If using kubernetes <= 1.16 pluase use v1beta1
.
NOTE: Support for v1
is still a bit limited. We have an open issue on the openapi
schema generation.
#[kube(namespaced)]
To specify that this is a namespaced resource rather than cluster level.
#[kube(status = "StatusStructName")]
Adds a status struct to the top level generated type and enables the status subresource in your crd.
#[kube(derive = "Trait")]
Adding #[kube(derive = "PartialEq")]
is required if you want your generated
top level type to be able to #[derive(PartialEq)]
#[kube(scale = r#"json"#)]
Allow customizing the scale struct for the scale subresource.
#[kube(printcoloum = r#"json"#)]
Allows adding straight json to printcolumns.
#[kube(shortname = "sn")]
Add a single shortname to the generated crd.
Example with all properties
use serde::{Serialize, Deserialize}; use kube_derive::CustomResource; #[derive(CustomResource, Serialize, Deserialize, Debug, PartialEq, Clone)] #[kube( group = "clux.dev", version = "v1", kind = "Foo", namespaced, status = "FooStatus", derive = "PartialEq", shortname = "f", scale = r#"{"specReplicasPath":".spec.replicas", "statusReplicasPath":".status.replicas"}"#, printcolumn = r#"{"name":"Spec", "type":"string", "description":"name of foo", "jsonPath":".spec.name"}"# )] struct FooSpec { data: String, replicas: i32 } #[derive(Serialize, Deserialize, Debug, PartialEq, Clone)] struct FooStatus { replicas: i32 }
Generated code
The example above will roughly generate:
#[derive(Serialize, Deserialize, Debug, PartialEq, Clone)] #[serde(rename_all = "camelCase")] pub struct Foo { api_version: String, kind: String, metadata: ObjectMeta, spec: FooSpec, status: Option<FooStatus>, } impl k8s_openapi::Resource for Foo {...} impl k8s_openapi::Metadata for Foo {...} impl Foo { pub fn new(name: &str, spec: FooSpec) -> Self { ... } pub fn crd() -> k8s_openapi::...::CustomResourceDefinition { ... } }
Debugging
Try cargo-expand
to see your own macro expansion.
Installation
Enable the derive
feature on the kube
crate:
kube = { version = "...", features = ["derive"] }