Merge pull request #356 from clux/allow-avoiding-schemagen

make schema a default compile feature of kube-derive - for #355

Author: clux

.circleci/config.yml

@@ -102,6 +102,7 @@ jobs:
       - run: cargo test --lib --all -j4
       - run: cargo test --doc --all -j4
       - run: cargo test -j4 -p examples
+      - run: cd examples && cargo test --example crd_derive_no_schema --no-default-features --features=native-tls
       - run: cd kube && cargo test --lib --no-default-features --features=rustls-tls
       - save_cache:
           paths:

examples/Cargo.toml

@@ -9,15 +9,18 @@ publish = false
 edition = "2018"
 
 [features]
-default = ["native-tls"]
+default = ["native-tls", "schema", "kubederive"]
+kubederive = ["kube/derive"] # by default import kube-derive with its default features
+schema = ["kube-derive/schema"] # crd_derive_no_schema shows how to opt out
 native-tls = ["reqwest/native-tls", "kube/native-tls", "kube-runtime/native-tls"]
 rustls-tls = ["reqwest/rustls-tls", "kube/rustls-tls", "kube-runtime/rustls-tls"]
 
 [dev-dependencies]
 anyhow = "1.0.32"
 env_logger = "0.7.1"
 futures = "0.3.5"
-kube = { path = "../kube", version = "^0.44.0", default-features = false, features = ["derive"] }
+kube = { path = "../kube", version = "^0.44.0", default-features = false }
+kube-derive = { path = "../kube-derive", version = "^0.44.0", default-features = false } # only needed to opt out of schema
 kube-runtime = { path = "../kube-runtime", version = "^0.44.0", default-features = false }
 k8s-openapi = { version = "0.10.0", features = ["v1_19"], default-features = false }
 log = "0.4.11"
@@ -32,6 +35,7 @@ either = "1.6.0"
 # Some configuration tweaking require reqwest atm
 reqwest = { version = "0.10.8", default-features = false, features = ["json", "gzip", "stream"] }
 schemars = "0.8.0"
+static_assertions = "1.1.0"
 
 [[example]]
 name = "configmapgen_controller"
@@ -61,6 +65,10 @@ path = "crd_derive.rs"
 name = "crd_derive_schema"
 path = "crd_derive_schema.rs"
 
+[[example]] # run this without --no-default-features --features="native-tls"
+name = "crd_derive_no_schema"
+path = "crd_derive_no_schema.rs"
+
 [[example]]
 name = "crd_reflector"
 path = "crd_reflector.rs"

examples/README.md

@@ -23,6 +23,21 @@ cargo run --example dynamic_api
 NAMESPACE=dev cargo run --example log_stream -- kafka-manager-7d4f4bd8dc-f6c44
 ```
 
+## kube-derive focused examples
+How deriving `CustomResource` works in practice, and how it interacts with the [schemars](https://github.com/GREsau/schemars/) dependency.
+
+```sh
+cargo run --example crd_derive
+cargo run --example crd_derive_schema
+cargo run --example crd_derive_no_schema --no-default-features --features=native-tls
+```
+
+The last one opts out from the default `schema` feature from `kube-derive` (and thus the need for you to derive/impl `JsonSchema`).
+
+**However**: without the `schema` feature, it's left **up to you to fill in a valid openapi v3 schema**, as schemas are **required** for [v1::CustomResourceDefinitions](https://docs.rs/k8s-openapi/0.10.0/k8s_openapi/apiextensions_apiserver/pkg/apis/apiextensions/v1/struct.CustomResourceDefinition.html), and the generated crd will be rejected by the apiserver if it's missing. As the last example shows, you can do this directly without `schemars`.
+
+Note that these examples also contain tests for CI, and are invoked with the same parameters, but using `cargo test` rather than `cargo run`.
+
 ## kube-runtime focused examples
 
 ### watchers

examples/crd_derive.rs

@@ -133,10 +133,13 @@ fn verify_crd() {
 
 #[test]
 fn verify_resource() {
+    use static_assertions::{assert_impl_all, assert_impl_one};
     assert_eq!(Foo::KIND, "Foo");
     assert_eq!(Foo::GROUP, "clux.dev");
     assert_eq!(Foo::VERSION, "v1");
     assert_eq!(Foo::API_VERSION, "clux.dev/v1");
+    assert_impl_all!(Foo: k8s_openapi::Resource, k8s_openapi::Metadata, Default);
+    assert_impl_one!(MyFoo: JsonSchema);
 }
 
 #[test]

examples/crd_derive_no_schema.rs

@@ -0,0 +1,76 @@
+use k8s_openapi::apiextensions_apiserver::pkg::apis::apiextensions::v1::{
+    CustomResourceDefinition, CustomResourceValidation, JSONSchemaProps,
+};
+use kube_derive::CustomResource;
+use serde::{Deserialize, Serialize};
+
+/// CustomResource with manually implemented schema
+///
+/// NB: Everything here is gated on the example's `schema` feature not being set
+///
+/// Normally you would do this by deriving JsonSchema or manually implementing it / parts of it.
+/// But here, we simply drop in a valid schema from a string and avoid schemars from the dependency tree entirely.
+#[cfg(not(feature = "schema"))]
+#[derive(CustomResource, Serialize, Deserialize, Debug, Clone)]
+#[kube(group = "clux.dev", version = "v1", kind = "Bar", namespaced)]
+pub struct MyBar {
+    bars: u32,
+}
+
+const MANUAL_SCHEMA: &'static str = r#"
+type: object
+properties:
+  spec:
+    type: object
+    properties:
+      bars:
+        type: int
+    required:
+    - bars
+"#;
+
+#[cfg(not(feature = "schema"))]
+impl Bar {
+    fn crd_with_manual_schema() -> CustomResourceDefinition {
+        let schema: JSONSchemaProps = serde_yaml::from_str(MANUAL_SCHEMA).expect("invalid schema");
+
+        let mut crd = Self::crd();
+        crd.spec.versions.iter_mut().for_each(|v| {
+            v.schema = Some(CustomResourceValidation {
+                open_api_v3_schema: Some(schema.clone()),
+            })
+        });
+        crd
+    }
+}
+
+
+#[cfg(not(feature = "schema"))]
+fn main() {
+    let crd = Bar::crd_with_manual_schema();
+    println!("{}", serde_yaml::to_string(&crd).unwrap());
+}
+#[cfg(feature = "schema")]
+fn main() {
+    eprintln!("This example it disabled when using the schema feature");
+}
+
+// Verify CustomResource derivable still
+#[cfg(not(feature = "schema"))]
+#[test]
+fn verify_bar_is_a_custom_resource() {
+    use k8s_openapi::Resource;
+    use schemars::JsonSchema; // only for ensuring it's not implemented
+    use static_assertions::{assert_impl_all, assert_not_impl_any};
+
+    println!("Kind {}", Bar::KIND);
+    let bar = Bar::new("five", MyBar { bars: 5 });
+    println!("Spec: {:?}", bar.spec);
+    assert_impl_all!(Bar: k8s_openapi::Resource, k8s_openapi::Metadata);
+    assert_not_impl_any!(MyBar: JsonSchema); // but no schemars schema implemented
+
+    let crd = Bar::crd_with_manual_schema();
+    for v in crd.spec.versions {
+        assert!(v.schema.unwrap().open_api_v3_schema.is_some());
+    }
+}

kube-derive/Cargo.toml

@@ -18,6 +18,10 @@ serde_json = "1.0.53"
 [lib]
 proc-macro = true
 
+[features]
+default = ["schema"]
+schema = []
+
 [dev-dependencies]
 serde = { version = "1.0.111", features = ["derive"] }
 serde_yaml = "0.8.14"

kube-derive/src/custom_resource.rs

@@ -264,7 +264,7 @@ impl CustomDerive for CustomResource {
 
         // Schema generation is always enabled for v1 because it's mandatory.
         // TODO Enable schema generation for v1beta1 if the spec derives `JsonSchema`.
-        let schema_gen_enabled = apiextensions == "v1";
+        let schema_gen_enabled = apiextensions == "v1" && cfg!(feature = "schema");
         // We exclude fields `apiVersion`, `kind`, and `metadata` from our schema because
         // these are validated by the API server implicitly. Also, we can't generate the
         // schema for `metadata` (`ObjectMeta`) because it doesn't implement `JsonSchema`.
@@ -372,14 +372,29 @@ impl CustomDerive for CustomResource {
         let short_json = serde_json::to_string(&shortnames).unwrap();
         let crd_meta_name = format!("{}.{}", plural, group);
         let crd_meta = quote! { { "name": #crd_meta_name } };
-        let jsondata = if apiextensions == "v1" {
+
+        let schemagen = if schema_gen_enabled {
             quote! {
                 // Don't use definitions and don't include `$schema` because these are not allowed.
                 let gen = schemars::gen::SchemaSettings::openapi3().with(|s| {
                     s.inline_subschemas = true;
                     s.meta_schema = None;
                 }).into_generator();
                 let schema = gen.into_root_schema_for::<Self>();
+            }
+        } else {
+            // we could issue a compile time warning for this, but it would hit EVERY compile, which would be noisy
+            // eprintln!("warning: kube-derive configured with manual schema generation");
+            // users must manually set a valid schema in crd.spec.versions[*].schema - see examples: crd_derive_no_schema
+            quote! {
+                let schema: Option<k8s_openapi::apiextensions_apiserver::pkg::apis::apiextensions::v1::JSONSchemaProps> = None;
+            }
+        };
+
+        let jsondata = if apiextensions == "v1" {
+            quote! {
+                #schemagen
+
                 let jsondata = serde_json::json!({
                     "metadata": #crd_meta,
                     "spec": {