Merge pull request #63 from kube-rs/feature-doc

Document Features

docs/features.md

@@ -0,0 +1,50 @@
+# Features
+
+All public features are exposed through `kube` in [kube's Cargo.toml](https://github.com/kube-rs/kube/blob/main/kube/Cargo.toml).
+
+
+## Stable Features
+
+| Feature     | Enables                            | Default | Significant Inclusions       |
+| ----------- | ---------------------------------- | ------- | ---------------------------- |
+| config      | [Config]                           | yes     | [kube-client] partial        |
+| client      | [Client] + [Api]                   | yes     | [kube-client], [hyper], [tower] |
+| runtime     | [Controller] + [watcher]           | no      | [kube-runtime]               |
+| derive      | [CustomResource]                   | no      | [kube-derive], [syn], [quote]|
+| openssl-tls | tls via openssl                    | no      | [openssl], [hyper-openssl]   |
+| rustls-tls  | tls via rustls                     | [yes]   | [rustls], [hyper-rustls]     |
+| ws          | [Execute], [Attach], [Portforward] | no      | [tokio-tungstenite]          |
+| gzip        | gzip compressed transport          | no      | [tower-http] feature         |
+| jsonpatch   | [Patch] using jsonpatch            | no      | [json_patch]                 |
+| admission   | [admission] module                 | no      | [json_patch]                 |
+| socks5      | local cluster [socks5] proxying    | no      | [hyper-socks2]               |
+| oauth       | local cluster oauth for GCP        | no      | [tame-oauth]                 |
+| oidc        | local cluster [oidc] auth          | no      | none                         |
+
+!!! note "Client dependencies"
+
+    Most of these features depend on having the `client` feature (and thus the `config` feature) enabled as they would not be much use without them.
+
+!!! warning "--no-default-features"
+
+    If you turn off all default features (say, to change tls stacks), you also turn off the normal `client` default feature. Without default features you get a crate roughly equivalent to [kube-core].
+
+## Unstable Features
+
+- `unstable-runtime` for stream sharing and controller streams interface tracked in [#1080](https://github.com/kube-rs/kube/issues/1080)
+- `unstable-client` for client exts tracked in [#1032](https://github.com/kube-rs/kube/issues/1032)
+- `kubelet-debug` for kubelet debug api access - untracked
+
+---
+
+[yes]: https://github.com/kube-rs/kube/releases/tag/0.86.0
+[socks5]: https://kubernetes.io/docs/tasks/extend-kubernetes/socks5-proxy-access-api/
+[oidc]: https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens
+[admission]: https://docs.rs/kube/latest/kube/core/admission/index.html
+[Execute]: https://docs.rs/kube/latest/kube/api/trait.Execute.html
+[Attach]: https://docs.rs/kube/latest/kube/api/trait.Attach.html
+[Portforward]: https://docs.rs/kube/latest/kube/api/trait.Portforward.html
+
+
+--8<-- "includes/abbreviations.md"
+--8<-- "includes/links.md"

includes/links.md

@@ -12,6 +12,8 @@
 [applier]: https://docs.rs/kube/latest/kube/runtime/fn.applier.html
 [Api]: https://docs.rs/kube/latest/kube/struct.Api.html
 [Client]: https://docs.rs/kube/latest/kube/struct.Client.html
+[Config]: https://docs.rs/kube/latest/kube/struct.Config.html
+[Patch]: https://docs.rs/kube/latest/kube/api/enum.Patch.html
 [CustomResource]: https://docs.rs/kube/latest/kube/derive.CustomResource.html
 [CustomResourceExt]: https://docs.rs/kube/latest/kube/trait.CustomResourceExt.html
 [CustomResourceDefinition]: https://docs.rs/k8s-openapi/latest/k8s_openapi/apiextensions_apiserver/pkg/apis/apiextensions/v1/struct.CustomResourceDefinition.html
@@ -100,3 +102,17 @@
 [AdmissionResponse]: https://docs.rs/kube/latest/kube/core/admission/struct.AdmissionResponse.html
 [AdmissionRequest]: https://docs.rs/kube/latest/kube/core/admission/struct.AdmissionRequest.html
 [kube::core::admission]: https://docs.rs/kube/latest/kube/core/admission/index.html
+[json_patch]: https://docs.rs/json-patch/latest/json_patch/
+[kube-derive]: /crates/kube-derive/
+[kube-client]: /crates/kube-client/
+[kube-runtime]: /crates/kube-runtime/
+[kube-core]: /crates/kube-core/
+[openssl]: https://crates.io/crates/openssl
+[hyper-openssl]: https://crates.io/crates/hyper-openssl
+[rustls]: https://crates.io/crates/rustls
+[hyper-rustls]: https://crates.io/crates/hyper-rustls
+[tokio-tungstenite]: https://crates.io/crates/tokio-tungstenite
+[tame-oauth]: https://crates.io/crates/tame-oauth
+[hyper-socks2]: https://crates.io/crates/hyper-socks2
+[syn]: https://crates.io/crates/syn
+[quote]: https://crates.io/crates/quote

mkdocs.yml

@@ -61,6 +61,7 @@ nav:
   - adopters.md
   - guides.md
   - upgrading.md
+  - features.md
 
 - Controllers:
     Concepts: