Merge pull request #439 from clux/patch-docs

update patch documentation

Author: clux

Makefile

@@ -12,7 +12,8 @@ fmt:
 	cargo +nightly fmt
 
 doc:
-	cargo +nightly doc --lib
+	# 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:

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,19 @@ 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))
+/// - `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 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)
+///
+/// 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.
 ///

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.
+/// These strategies are configurable when deriving your [`CustomResource`](kube_derive::CustomResource#customizing-schemas).
+///
+/// # 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<T: Serialize> {
     /// [Server side apply](https://kubernetes.io/docs/reference/using-api/api-concepts/#server-side-apply)

kube/src/api/typed.rs

@@ -193,14 +193,9 @@ where
         self.client.request_status::<ObjectList<K>>(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<P: Serialize>(&self, name: &str, pp: &PatchParams, patch: &Patch<P>) -> Result<K> {
         let req = self.resource.patch(name, &pp, patch)?;
         self.client.request::<K>(req).await