kube_derive/lib.rs
1//! A crate for kube's derive macros.
2#![recursion_limit = "1024"]
3extern crate proc_macro;
4#[macro_use] extern crate quote;
5
6mod cel_schema;
7mod custom_resource;
8mod resource;
9
10/// A custom derive for kubernetes custom resource definitions.
11///
12/// This will generate a **root object** containing your spec and metadata.
13/// This root object will implement the [`kube::Resource`] trait
14/// so it can be used with [`kube::Api`].
15///
16/// The generated type will also implement kube's [`kube::CustomResourceExt`] trait to generate the crd
17/// and generate [`kube::core::ApiResource`] information for use with the dynamic api.
18///
19/// # Example
20///
21/// ```rust
22/// use serde::{Serialize, Deserialize};
23/// use kube::core::{Resource, CustomResourceExt};
24/// use kube_derive::CustomResource;
25/// use schemars::JsonSchema;
26///
27/// #[derive(CustomResource, Clone, Debug, Deserialize, Serialize, JsonSchema)]
28/// #[kube(group = "clux.dev", version = "v1", kind = "Foo", namespaced)]
29/// struct FooSpec {
30/// info: String,
31/// }
32///
33/// println!("kind = {}", Foo::kind(&())); // impl kube::Resource
34/// let f = Foo::new("foo-1", FooSpec {
35/// info: "informative info".into(),
36/// });
37/// println!("foo: {:?}", f); // debug print on root type
38/// println!("crd: {}", serde_yaml::to_string(&Foo::crd()).unwrap()); // crd yaml
39/// ```
40///
41/// This example generates a `struct Foo` containing metadata, the spec,
42/// and optionally status. The **root** struct `Foo` can be used with the [`kube`] crate
43/// as an `Api<Foo>` object (`FooSpec` can not be used with [`Api`][`kube::Api`]).
44///
45/// ```no_run
46/// # use k8s_openapi::apiextensions_apiserver::pkg::apis::apiextensions::v1::CustomResourceDefinition;
47/// # use kube_derive::CustomResource;
48/// # use kube::{api::{Api, Patch, PatchParams}, Client, CustomResourceExt};
49/// # use serde::{Deserialize, Serialize};
50/// # async fn wrapper() -> Result<(), Box<dyn std::error::Error>> {
51/// # #[derive(CustomResource, Clone, Debug, Deserialize, Serialize, schemars::JsonSchema)]
52/// # #[kube(group = "clux.dev", version = "v1", kind = "Foo", namespaced)]
53/// # struct FooSpec {}
54/// # let client: Client = todo!();
55/// let foos: Api<Foo> = Api::default_namespaced(client.clone());
56/// let crds: Api<CustomResourceDefinition> = Api::all(client.clone());
57/// crds.patch("foos.clux.dev", &PatchParams::apply("myapp"), &Patch::Apply(Foo::crd())).await;
58/// # Ok(())
59/// # }
60/// ```
61///
62/// This example posts the generated `::crd` to the `CustomResourceDefinition` API.
63/// After this has been accepted (few secs max), you can start using `foos` as a normal
64/// kube `Api` object. See the `crd_` prefixed [examples](https://github.com/kube-rs/kube/blob/main/examples/)
65/// for details on this.
66///
67/// # Required properties
68///
69/// ## `#[kube(group = "mygroup.tld")]`
70/// Your cr api group. The part before the slash in the top level `apiVersion` key.
71///
72/// ## `#[kube(version = "v1")]`
73/// Your cr api version. The part after the slash in the top level `apiVersion` key.
74///
75/// ## `#[kube(kind = "Kind")]`
76/// Name of your kind, and implied default for your generated root type.
77///
78/// # Optional `#[kube]` attributes
79///
80/// ## `#[kube(singular = "nonstandard-singular")]`
81/// To specify the singular name. Defaults to lowercased `.kind` value.
82///
83/// ## `#[kube(plural = "nonstandard-plural")]`
84/// To specify the plural name. Defaults to inferring from singular.
85///
86/// ## `#[kube(namespaced)]`
87/// To specify that this is a namespaced resource rather than cluster level.
88///
89/// ## `#[kube(root = "StructName")]`
90/// Customize the name of the generated root struct (defaults to `.kind` value).
91///
92/// ## `#[kube(crates(kube_core = "::kube::core"))]`
93/// Customize the crate name the generated code will reach into (defaults to `::kube::core`).
94/// Should be one of `kube::core`, `kube_client::core` or `kube_core`.
95///
96/// ## `#[kube(crates(k8s_openapi = "::k8s_openapi"))]`
97/// Customize the crate name the generated code will use for [`k8s_openapi`](https://docs.rs/k8s-openapi/) (defaults to `::k8s_openapi`).
98///
99/// ## `#[kube(crates(schemars = "::schemars"))]`
100/// Customize the crate name the generated code will use for [`schemars`](https://docs.rs/schemars/) (defaults to `::schemars`).
101///
102/// ## `#[kube(crates(serde = "::serde"))]`
103/// Customize the crate name the generated code will use for [`serde`](https://docs.rs/serde/) (defaults to `::serde`).
104///
105/// ## `#[kube(crates(serde_json = "::serde_json"))]`
106/// Customize the crate name the generated code will use for [`serde_json`](https://docs.rs/serde_json/) (defaults to `::serde_json`).
107///
108/// ## `#[kube(status = "StatusStructName")]`
109/// Adds a status struct to the top level generated type and enables the status
110/// subresource in your crd.
111///
112/// ## `#[kube(derive = "Trait")]`
113/// Adding `#[kube(derive = "PartialEq")]` is required if you want your generated
114/// top level type to be able to `#[derive(PartialEq)]`
115///
116/// ## `#[kube(schema = "mode")]`
117/// Defines whether the `JsonSchema` of the top level generated type should be used when generating a `CustomResourceDefinition`.
118///
119/// Legal values:
120/// - `"derived"`: A `JsonSchema` implementation is automatically derived
121/// - `"manual"`: `JsonSchema` is not derived, but used when creating the `CustomResourceDefinition` object
122/// - `"disabled"`: No `JsonSchema` is used
123///
124/// This can be used to provide a completely custom schema, or to interact with third-party custom resources
125/// where you are not responsible for installing the `CustomResourceDefinition`.
126///
127/// Defaults to `"derived"`.
128///
129/// NOTE: `CustomResourceDefinition`s require a schema. If `schema = "disabled"` then
130/// `Self::crd()` will not be installable into the cluster as-is.
131///
132/// ## `#[kube(scale = r#"json"#)]`
133/// Allow customizing the scale struct for the [scale subresource](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#subresources).
134///
135/// ## `#[kube(printcolumn = r#"json"#)]`
136/// Allows adding straight json to [printcolumns](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#additional-printer-columns).
137///
138/// ## `#[kube(shortname = "sn")]`
139/// Add a single shortname to the generated crd.
140///
141/// ## `#[kube(category = "apps")]`
142/// Add a single category to `crd.spec.names.categories`.
143///
144/// ## `#[kube(selectable = "fieldSelectorPath")]`
145/// Adds a Kubernetes >=1.30 `selectableFields` property ([KEP-4358](https://github.com/kubernetes/enhancements/blob/master/keps/sig-api-machinery/4358-custom-resource-field-selectors/README.md)) to the schema.
146/// Unlocks `kubectl get kind --field-selector fieldSelectorPath`.
147///
148/// ## `#[kube(doc = "description")]`
149/// Sets the description of the schema in the generated CRD. If not specified
150/// `Auto-generated derived type for {customResourceName} via CustomResource` will be used instead.
151///
152/// ## `#[kube(annotation("ANNOTATION_KEY", "ANNOTATION_VALUE"))]`
153/// Add a single annotation to the generated CRD.
154///
155/// ## `#[kube(label("LABEL_KEY", "LABEL_VALUE"))]`
156/// Add a single label to the generated CRD.
157///
158/// ## `#[kube(storage = true)]`
159/// Sets the `storage` property to `true` or `false`.
160///
161/// ## `#[kube(served = true)]`
162/// Sets the `served` property to `true` or `false`.
163///
164/// ## `#[kube(rule = Rule::new("self == oldSelf").message("field is immutable"))]`
165/// Inject a top level CEL validation rule for the top level generated struct.
166/// This attribute is for resources deriving [`CELSchema`] instead of [`schemars::JsonSchema`].
167///
168/// ## Example with all properties
169///
170/// ```rust
171/// use serde::{Serialize, Deserialize};
172/// use kube_derive::CustomResource;
173/// use schemars::JsonSchema;
174///
175/// #[derive(CustomResource, Serialize, Deserialize, Debug, PartialEq, Clone, JsonSchema)]
176/// #[kube(
177/// group = "clux.dev",
178/// version = "v1",
179/// kind = "Foo",
180/// root = "FooCrd",
181/// namespaced,
182/// doc = "Custom resource representing a Foo",
183/// status = "FooStatus",
184/// derive = "PartialEq",
185/// singular = "foot",
186/// plural = "feetz",
187/// shortname = "f",
188/// scale = r#"{"specReplicasPath":".spec.replicas", "statusReplicasPath":".status.replicas"}"#,
189/// printcolumn = r#"{"name":"Spec", "type":"string", "description":"name of foo", "jsonPath":".spec.name"}"#,
190/// selectable = "spec.replicasCount"
191/// )]
192/// #[serde(rename_all = "camelCase")]
193/// struct FooSpec {
194/// #[schemars(length(min = 3))]
195/// data: String,
196/// replicas_count: i32
197/// }
198///
199/// #[derive(Serialize, Deserialize, Debug, PartialEq, Clone, JsonSchema)]
200/// struct FooStatus {
201/// replicas: i32
202/// }
203/// ```
204///
205/// # Enums
206///
207/// Kubernetes requires that the generated [schema is "structural"](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema).
208/// This means that the structure of the schema must not depend on the particular values. For enums this imposes a few limitations:
209///
210/// - Only [externally tagged enums](https://serde.rs/enum-representations.html#externally-tagged) are supported
211/// - Unit variants may not be mixed with struct or tuple variants (`enum Foo { Bar, Baz {}, Qux() }` is invalid, for example)
212///
213/// If these restrictions are not followed then `YourCrd::crd()` may panic, or the Kubernetes API may reject the CRD definition.
214///
215/// # Generated code
216///
217/// The example above will **roughly** generate:
218/// ```compile_fail
219/// #[derive(Serialize, Deserialize, Debug, PartialEq, Clone, JsonSchema)]
220/// #[serde(rename_all = "camelCase")]
221/// pub struct FooCrd {
222/// api_version: String,
223/// kind: String,
224/// metadata: ObjectMeta,
225/// spec: FooSpec,
226/// status: Option<FooStatus>,
227/// }
228/// impl kube::Resource for FooCrd { .. }
229///
230/// impl FooCrd {
231/// pub fn new(name: &str, spec: FooSpec) -> Self { .. }
232/// pub fn crd() -> CustomResourceDefinition { .. }
233/// }
234/// ```
235///
236/// # Customizing Schemas
237/// Should you need to customize the schemas, you can use:
238/// - [Serde/Schemars Attributes](https://graham.cool/schemars/examples/3-schemars_attrs/) (no need to duplicate serde renames)
239/// - [`#[schemars(schema_with = "func")]`](https://graham.cool/schemars/examples/7-custom_serialization/) (e.g. like in the [`crd_derive` example](https://github.com/kube-rs/kube/blob/main/examples/crd_derive.rs))
240/// - `impl JsonSchema` on a type / newtype around external type. See [#129](https://github.com/kube-rs/kube/issues/129#issuecomment-750852916)
241/// - [`#[garde(...)]` field attributes for client-side validation](https://github.com/jprochazk/garde) (see [`crd_api` example](https://github.com/kube-rs/kube/blob/main/examples/crd_api.rs))
242///
243/// You might need to override parts of the schemas (for fields in question) when you are:
244/// - **using complex enums**: enums do not currently generate [structural schemas](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema), so kubernetes won't support them by default
245/// - **customizing [merge-strategies](https://kubernetes.io/docs/reference/using-api/server-side-apply/#merge-strategy)** (e.g. like in the [`crd_derive_schema` example](https://github.com/kube-rs/kube/blob/main/examples/crd_derive_schema.rs))
246///
247/// See [kubernetes openapi validation](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation) for the format of the OpenAPI v3 schemas.
248///
249/// If you have to override a lot, [you can opt-out of schema-generation entirely](#kubeschema--mode)
250///
251/// # Advanced Features
252///
253/// - **embedding k8s-openapi types** can be done by enabling the `schemars` feature of `k8s-openapi` from [`0.13.0`](https://github.com/Arnavion/k8s-openapi/blob/master/CHANGELOG.md#v0130-2021-08-09)
254/// - **adding validation** via [validator crate](https://github.com/Keats/validator) is supported from `schemars` >= [`0.8.5`](https://github.com/GREsau/schemars/blob/master/CHANGELOG.md#085---2021-09-20)
255/// - **generating rust code from schemas** can be done via [kopium](https://github.com/kube-rs/kopium) and is supported on stable crds (> 1.16 kubernetes)
256///
257/// ## Schema Validation
258/// There are two main ways of doing validation; **server-side** (embedding validation attributes into the schema for the apiserver to respect), and **client-side** (provides `validate()` methods in your code).
259///
260/// Client side validation of structs can be achieved by hooking up `#[garde]` attributes in your struct and is a replacement of the now unmaintained [`validator`](https://github.com/Keats/validator/issues/201) crate.
261/// Server-side validation require mutation of your generated schema, and can in the basic cases be achieved through the use of `schemars`'s [validation attributes](https://graham.cool/schemars/deriving/attributes/#supported-validator-attributes).
262/// For complete control, [parts of the schema can be overridden](https://github.com/kube-rs/kube/blob/e01187e13ba364ccecec452e023316a62fb13e04/examples/crd_derive.rs#L37-L38) to support more advanced [Kubernetes specific validation rules](https://kubernetes.io/blog/2022/09/23/crd-validation-rules-beta/).
263///
264/// When using `garde` directly, you must add it to your dependencies (with the `derive` feature).
265///
266/// ### Validation Caveats
267/// Make sure your validation rules are static and handled by `schemars`:
268/// - validations from `#[garde(custom(my_func))]` will not show up in the schema.
269/// - similarly; [nested / must_match / credit_card were unhandled by schemars at time of writing](https://github.com/GREsau/schemars/pull/78)
270/// - encoding validations specified through garde (i.e. #[garde(ascii)]), are currently not supported by schemars
271/// - to validate required attributes client-side, garde requires a custom validation function (`#[garde(custom(my_required_check))]`)
272/// - when using garde, fields that should not be validated need to be explictly skipped through the `#[garde(skip)]` attr
273///
274/// For sanity, you should review the generated schema before sending it to kubernetes.
275///
276/// ## Versioning
277/// Note that any changes to your struct / validation rules / serialization attributes will require you to re-apply the
278/// generated schema to kubernetes, so that the apiserver can validate against the right version of your structs.
279///
280/// **Backwards compatibility** between schema versions is **recommended** unless you are in a controlled environment
281/// where you can migrate manually. I.e. if you add new properties behind options, and simply mark old fields as deprecated,
282/// then you can safely roll schema out changes **without bumping** the version.
283///
284/// If you need **multiple versions**, then you need:
285///
286/// - one **module** for **each version** of your types (e.g. `v1::MyCrd` and `v2::MyCrd`)
287/// - use the [`merge_crds`](https://docs.rs/kube/latest/kube/core/crd/fn.merge_crds.html) fn to combine crds
288/// - roll out new schemas utilizing conversion webhooks / manual conversions / or allow kubectl to do its best
289///
290/// See the [crd_derive_multi](https://github.com/kube-rs/kube/blob/main/examples/crd_derive_multi.rs) example to see
291/// how this upgrade flow works without special logic.
292///
293/// The **upgrade flow** with **breaking changes** involves:
294///
295/// 1. upgrade version marked as `storage` (from v1 to v2)
296/// 2. read instances from the older `Api<v1::MyCrd>`
297/// 3. perform conversion in memory and write them to the new `Api<v2::MyCrd>`.
298/// 4. remove support for old version
299///
300/// If you need to maintain support for the old version for some time, then you have to repeat or continuously
301/// run steps 2 and 3. I.e. you probably need a **conversion webhook**.
302///
303/// **NB**: kube does currently [not implement conversion webhooks yet](https://github.com/kube-rs/kube/issues/865).
304///
305/// ## Debugging
306/// Try `cargo-expand` to see your own macro expansion.
307///
308/// # Installation
309/// Enable the `derive` feature on the `kube` crate:
310///
311/// ```toml
312/// kube = { version = "...", features = ["derive"] }
313/// ```
314///
315/// ## Runtime dependencies
316/// Due to [rust-lang/rust#54363](https://github.com/rust-lang/rust/issues/54363), we cannot be resilient against crate renames within our generated code.
317/// It's therefore **required** that you have the following crates in scope, not renamed:
318///
319/// - `serde_json`
320/// - `k8s_openapi`
321/// - `schemars` (by default, unless `schema` feature disabled)
322///
323/// You are ultimately responsible for maintaining the versions and feature flags of these libraries.
324///
325/// [`kube`]: https://docs.rs/kube
326/// [`kube::Api`]: https://docs.rs/kube/*/kube/struct.Api.html
327/// [`kube::Resource`]: https://docs.rs/kube/*/kube/trait.Resource.html
328/// [`kube::core::ApiResource`]: https://docs.rs/kube/*/kube/core/struct.ApiResource.html
329/// [`kube::CustomResourceExt`]: https://docs.rs/kube/*/kube/trait.CustomResourceExt.html
330#[proc_macro_derive(CustomResource, attributes(kube))]
331pub fn derive_custom_resource(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
332 custom_resource::derive(proc_macro2::TokenStream::from(input)).into()
333}
334
335/// Generates a JsonSchema implementation a set of CEL validation rules applied on the CRD.
336///
337/// ```rust
338/// use kube::CELSchema;
339/// use kube::CustomResource;
340/// use serde::Deserialize;
341/// use serde::Serialize;
342/// use kube::core::crd::CustomResourceExt;
343///
344/// #[derive(CustomResource, CELSchema, Serialize, Deserialize, Clone, Debug)]
345/// #[kube(
346/// group = "kube.rs",
347/// version = "v1",
348/// kind = "Struct",
349/// rule = Rule::new("self.matadata.name == 'singleton'"),
350/// )]
351/// #[cel_validate(rule = Rule::new("self == oldSelf"))]
352/// struct MyStruct {
353/// #[serde(default = "default")]
354/// #[cel_validate(rule = Rule::new("self != ''").message("failure message"))]
355/// field: String,
356/// }
357///
358/// fn default() -> String {
359/// "value".into()
360/// }
361///
362/// assert!(serde_json::to_string(&Struct::crd()).unwrap().contains("x-kubernetes-validations"));
363/// assert!(serde_json::to_string(&Struct::crd()).unwrap().contains(r#""rule":"self == oldSelf""#));
364/// assert!(serde_json::to_string(&Struct::crd()).unwrap().contains(r#""rule":"self != ''""#));
365/// assert!(serde_json::to_string(&Struct::crd()).unwrap().contains(r#""message":"failure message""#));
366/// assert!(serde_json::to_string(&Struct::crd()).unwrap().contains(r#""default":"value""#));
367/// assert!(serde_json::to_string(&Struct::crd()).unwrap().contains(r#""rule":"self.matadata.name == 'singleton'""#));
368/// ```
369#[proc_macro_derive(CELSchema, attributes(cel_validate, schemars))]
370pub fn derive_schema_validation(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
371 cel_schema::derive_validated_schema(input.into()).into()
372}
373
374/// A custom derive for inheriting Resource impl for the type.
375///
376/// This will generate a [`kube::Resource`] trait implementation,
377/// inheriting from a specified resource trait implementation.
378///
379/// This allows strict typing to some typical resources like `Secret` or `ConfigMap`,
380/// in cases when implementing CRD is not desirable or it does not fit the use-case.
381///
382/// Once derived, the type can be used with [`kube::Api`].
383///
384/// # Example
385///
386/// ```rust,no_run
387/// use kube::api::ObjectMeta;
388/// use k8s_openapi::api::core::v1::ConfigMap;
389/// use kube_derive::Resource;
390/// use kube::Client;
391/// use kube::Api;
392/// use serde::Deserialize;
393///
394/// #[derive(Resource, Clone, Debug, Deserialize)]
395/// #[resource(inherit = "ConfigMap")]
396/// struct FooMap {
397/// metadata: ObjectMeta,
398/// data: Option<FooMapSpec>,
399/// }
400///
401/// #[derive(Clone, Debug, Deserialize)]
402/// struct FooMapSpec {
403/// field: String,
404/// }
405///
406/// let client: Client = todo!();
407/// let api: Api<FooMap> = Api::default_namespaced(client);
408/// let config_map = api.get("with-field");
409/// ```
410///
411/// The example above will generate:
412/// ```
413/// // impl kube::Resource for FooMap { .. }
414/// ```
415/// [`kube`]: https://docs.rs/kube
416/// [`kube::Api`]: https://docs.rs/kube/*/kube/struct.Api.html
417/// [`kube::Resource`]: https://docs.rs/kube/*/kube/trait.Resource.html
418/// [`kube::core::ApiResource`]: https://docs.rs/kube/*/kube/core/struct.ApiResource.html
419/// [`kube::CustomResourceExt`]: https://docs.rs/kube/*/kube/trait.CustomResourceExt.html
420#[proc_macro_derive(Resource, attributes(resource))]
421pub fn derive_resource(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
422 resource::derive(proc_macro2::TokenStream::from(input)).into()
423}