From aee3d38494a75ed9e977ee48b4c3deb4f5a39320 Mon Sep 17 00:00:00 2001 From: clux Date: Sat, 27 Feb 2021 13:14:01 +0000 Subject: [PATCH 1/3] update patch documentation - closes #142 --- Makefile | 2 +- kube/src/api/params.rs | 38 +++++++++++++++++++++++++++++++++++--- kube/src/api/typed.rs | 15 ++++----------- 3 files changed, 40 insertions(+), 15 deletions(-) diff --git a/Makefile b/Makefile index a3308edbd..9ceeec800 100644 --- a/Makefile +++ b/Makefile @@ -12,7 +12,7 @@ fmt: cargo +nightly fmt doc: - cargo +nightly doc --lib + cargo +nightly doc --lib --features=derive,ws,oauth,jsonpatch xdg-open target/doc/kube/index.html test: diff --git a/kube/src/api/params.rs b/kube/src/api/params.rs index 628c2f7d9..0470092bb 100644 --- a/kube/src/api/params.rs +++ b/kube/src/api/params.rs @@ -144,9 +144,41 @@ impl PostParams { /// Describes changes that should be applied to a resource /// -/// For all strategies except `Json`, patch can be represented with arbitrary -/// serializable value, such as `serde_json::Value`. You may also want to use -/// a `k8s-openapi` definition for the resource for the better type safety. +/// Takes arbitrary serializable data for all strategies except `Json`. +/// +/// We recommend using ([server-side](https://kubernetes.io/blog/2020/04/01/kubernetes-1.18-feature-server-side-apply-beta-2)) `Apply` patches on new kubernetes releases. +/// +/// See [kubernetes patch docs](https://kubernetes.io/docs/tasks/run-application/update-api-object-kubectl-patch/#use-a-json-merge-patch-to-update-a-deployment) for the older patch types. +/// +/// Note that patches have different effects on different fields depending on their [merge-strategies](https://kubernetes.io/docs/reference/using-api/server-side-apply/#merge-strategy). +/// These strategies are configurable when deriving your [`CustomResource`](kube_derive::CustomResource). +/// +/// # Creating a patch via serde_json +/// ``` +/// use kube::api::Patch; +/// let patch = serde_json::json!({ +/// "apiVersion": "v1", +/// "kind": "Pod", +/// "metadata": { +/// "name": "blog" +/// }, +/// "spec": { +/// "activeDeadlineSeconds": 5 +/// } +/// }); +/// let patch = Patch::Apply(&patch); +/// ``` +/// # Creating a patch from a type +/// ``` +/// use kube::api::Patch; +/// use k8s_openapi::api::rbac::v1::Role; +/// use k8s_openapi::apimachinery::pkg::apis::meta::v1::ObjectMeta; +/// let r = Role { +/// metadata: ObjectMeta { name: Some("user".into()), ..ObjectMeta::default() }, +/// rules: Some(vec![]) +/// }; +/// let patch = Patch::Apply(&r); +/// ``` #[non_exhaustive] pub enum Patch { /// [Server side apply](https://kubernetes.io/docs/reference/using-api/api-concepts/#server-side-apply) diff --git a/kube/src/api/typed.rs b/kube/src/api/typed.rs index 89160fb5a..a22f3e8cb 100644 --- a/kube/src/api/typed.rs +++ b/kube/src/api/typed.rs @@ -193,14 +193,9 @@ where self.client.request_status::>(req).await } - /// Patch a resource a subset of its properties + /// Patch a subset of a resource's properties /// - /// Note that actual `patch` value depends on what `PatchStrategy` is used. - /// It is configured in `PatchParams` and defauls to strategic merge - /// patch. - /// - /// See [kubernetes json patch types](https://kubernetes.io/docs/tasks/run-application/update-api-object-kubectl-patch/#use-a-json-merge-patch-to-update-a-deployment) - /// for more information about their distinction. + /// Takes a [`Patch`] along with [`PatchParams`] for the call. /// /// ```no_run /// use kube::{api::{Api, PatchParams, Patch, Meta}, Client}; @@ -225,10 +220,8 @@ where /// Ok(()) /// } /// ``` - /// [`Merge`]: super::PatchStrategy::Merge - /// [`JSON`]: super::PatchStrategy::JSON - /// [`Strategic`]: super::PatchStrategy::Strategic - /// [`Apply`]: super::PatchStrategy::Apply + /// [`Patch`]: super::Patch + /// [`PatchParams`]: super::PatchParams pub async fn patch(&self, name: &str, pp: &PatchParams, patch: &Patch

) -> Result { let req = self.resource.patch(name, &pp, patch)?; self.client.request::(req).await From bf30b9de0e0918f0aae1ee5ffb619a7f4303f27f Mon Sep 17 00:00:00 2001 From: clux Date: Sat, 27 Feb 2021 13:41:08 +0000 Subject: [PATCH 2/3] summarize schema customization in kube-derive docs --- kube-derive/src/lib.rs | 14 +++++++++++++- kube/src/api/params.rs | 4 ++-- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/kube-derive/src/lib.rs b/kube-derive/src/lib.rs index 95f687a3a..292a1c043 100644 --- a/kube-derive/src/lib.rs +++ b/kube-derive/src/lib.rs @@ -70,7 +70,7 @@ mod custom_resource; /// /// ### `#[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`. +/// Default is `v1` (for clusters >= 1.17). If using kubernetes <= 1.16 please use `v1beta1`. /// /// **NOTE**: Support for `v1` requires deriving the openapi v3 `JsonSchema` via the `schemars` dependency. /// @@ -150,6 +150,18 @@ mod custom_resource; /// } /// ``` /// +/// ## Customizing Schemas +/// Should you need to customize the schemas, you can use: +/// - [Serde/Schemars Attributes](https://graham.cool/schemars/examples/3-schemars_attrs/) (no need to duplicate serde renames) +/// - [`#[schemars(schema_with = "func")]`](https://graham.cool/schemars/examples/7-custom_serialization/) (e.g. like in the [`crd_derive` example](https://github.com/clux/kube-rs/blob/master/examples/crd_derive.rs)) +/// +/// In general, you will need to override parts of the schemas (for fields in question) when you are: +/// - **using 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 +/// - **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/clux/kube-rs/blob/master/examples/crd_derive_schema.rs)) +/// - **customizing [certain kubebuilder like validation rules](https://github.com/clux/kube-rs/issues/129#issuecomment-749463718)** (tail the issue for state of affairs) +/// +/// If you have to override a lot, [you can opt-out of schema-generation entirely](https://github.com/clux/kube-rs/issues/355#issuecomment-751253657) +/// /// ## Debugging /// Try `cargo-expand` to see your own macro expansion. /// diff --git a/kube/src/api/params.rs b/kube/src/api/params.rs index 0470092bb..fab9a87dc 100644 --- a/kube/src/api/params.rs +++ b/kube/src/api/params.rs @@ -150,8 +150,8 @@ impl PostParams { /// /// See [kubernetes patch docs](https://kubernetes.io/docs/tasks/run-application/update-api-object-kubectl-patch/#use-a-json-merge-patch-to-update-a-deployment) for the older patch types. /// -/// Note that patches have different effects on different fields depending on their [merge-strategies](https://kubernetes.io/docs/reference/using-api/server-side-apply/#merge-strategy). -/// These strategies are configurable when deriving your [`CustomResource`](kube_derive::CustomResource). +/// Note that patches have different effects on different fields depending on their merge strategies. +/// These strategies are configurable when deriving your [`CustomResource`](kube_derive::CustomResource#customizing-schemas). /// /// # Creating a patch via serde_json /// ``` From 7591adce49328a851983410b753db14eb4527bc4 Mon Sep 17 00:00:00 2001 From: clux Date: Sat, 27 Feb 2021 22:10:50 +0000 Subject: [PATCH 3/3] feedback --- Makefile | 3 ++- kube-derive/src/lib.rs | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 9ceeec800..024a1066d 100644 --- a/Makefile +++ b/Makefile @@ -12,7 +12,8 @@ fmt: cargo +nightly fmt doc: - cargo +nightly doc --lib --features=derive,ws,oauth,jsonpatch + # TODO: replace with RUSTDOCFLAGS="--cfg docsrs" once it works + cargo +nightly doc --lib --workspace --features=derive,ws,oauth,jsonpatch xdg-open target/doc/kube/index.html test: diff --git a/kube-derive/src/lib.rs b/kube-derive/src/lib.rs index 292a1c043..015e4ff33 100644 --- a/kube-derive/src/lib.rs +++ b/kube-derive/src/lib.rs @@ -154,9 +154,10 @@ mod custom_resource; /// Should you need to customize the schemas, you can use: /// - [Serde/Schemars Attributes](https://graham.cool/schemars/examples/3-schemars_attrs/) (no need to duplicate serde renames) /// - [`#[schemars(schema_with = "func")]`](https://graham.cool/schemars/examples/7-custom_serialization/) (e.g. like in the [`crd_derive` example](https://github.com/clux/kube-rs/blob/master/examples/crd_derive.rs)) +/// - `impl JsonSchema` on a type / newtype around external type. See [#129](https://github.com/clux/kube-rs/issues/129#issuecomment-750852916) /// /// In general, you will need to override parts of the schemas (for fields in question) when you are: -/// - **using 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 +/// - **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 /// - **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/clux/kube-rs/blob/master/examples/crd_derive_schema.rs)) /// - **customizing [certain kubebuilder like validation rules](https://github.com/clux/kube-rs/issues/129#issuecomment-749463718)** (tail the issue for state of affairs) ///