base on Rust Kubernetes client and controller runtime # kube-rs [](https://crates.io/crates/kube) [](https://github.com/rust-lang/rust/releases/tag/1.77.2) [](https://kube.rs/kubernetes-version) [](https://bestpractices.coreinfrastructure.org/projects/5413) [](https://discord.gg/tokio) A [Rust](https://rust-lang.org/) client for [Kubernetes](http://kubernetes.io) in the style of a more generic [client-go](https://github.com/kubernetes/client-go), a runtime abstraction inspired by [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime), and a derive macro for [CRDs](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/) inspired by [kubebuilder](https://book.kubebuilder.io/reference/generating-crd.html). Hosted by [CNCF](https://cncf.io/) as a [Sandbox Project](https://www.cncf.io/sandbox-projects/). These crates build upon Kubernetes [apimachinery](https://github.com/kubernetes/apimachinery/blob/master/pkg/apis/meta/v1/types.go) + [api concepts](https://kubernetes.io/docs/reference/using-api/api-concepts/) to enable generic abstractions. These abstractions allow Rust reinterpretations of reflectors, controllers, and custom resource interfaces, so that you can write applications easily. ## Installation Select a version of `kube` along with the generated [k8s-openapi](https://github.com/Arnavion/k8s-openapi) structs at your chosen [Kubernetes version](https://kube.rs/kubernetes-version/): ```toml [dependencies] kube = { version = "0.97.0", features = ["runtime", "derive"] } k8s-openapi = { version = "0.23.0", features = ["latest"] } ``` See [features](https://kube.rs/features/) for a quick overview of default-enabled / opt-in functionality. ## Upgrading See [kube.rs/upgrading](https://kube.rs/upgrading/). Noteworthy changes are highlighted in [releases](https://github.com/kube-rs/kube/releases), and archived in the [changelog](https://kube.rs/changelog/). ## Usage See the **[examples directory](https://github.com/kube-rs/kube/blob/main/examples)** for how to use any of these crates. - **[kube API Docs](https://docs.rs/kube/)** - **[kube.rs](https://kube.rs)** Official examples: - [version-rs](https://github.com/kube-rs/version-rs): lightweight deployment `reflector` using axum - [controller-rs](https://github.com/kube-rs/controller-rs): `Controller` of a crd inside actix For real world projects see [ADOPTERS](https://kube.rs/adopters/). ## Api The [`Api`](https://docs.rs/kube/latest/kube/struct.Api.html) is what interacts with Kubernetes resources, and is generic over [`Resource`](https://docs.rs/kube/latest/kube/trait.Resource.html): ```rust use k8s_openapi::api::core::v1::Pod; let pods: Api<Pod> = Api::default_namespaced(client); let pod = pods.get("blog").await?; println!("Got pod: {pod:?}"); let patch = json!({"spec": { "activeDeadlineSeconds": 5 }}); let pp = PatchParams::apply("kube"); let patched = pods.patch("blog", &pp, &Patch::Apply(patch)).await?; assert_eq!(patched.spec.active_deadline_seconds, Some(5)); pods.delete("blog", &DeleteParams::default()).await?; ``` See the examples ending in `_api` examples for more detail. ## Custom Resource Definitions Working with custom resources uses automatic code-generation via [proc_macros in kube-derive](https://docs.rs/kube/latest/kube/derive.CustomResource.html). You need to add `#[derive(CustomResource, JsonSchema)]` and some `#[kube(attrs..)]` on a __spec__ struct: ```rust #[derive(CustomResource, Debug, Serialize, Deserialize, Default, Clone, JsonSchema)] #[kube(group = "kube.rs", version = "v1", kind = "Document", namespaced)] pub struct DocumentSpec { title: String, content: String, } ``` Then you can use the generated wrapper struct `Document` as a [`kube::Resource`](https://docs.rs/kube/*/kube/trait.Resource.html): ```rust let docs: Api<Document> = Api::default_namespaced(client); let d = Document::new("guide", DocumentSpec::default()); println!("doc: {:?}", d); println!("crd: {:?}", serde_yaml::to_string(&Document::crd())); ``` There are a ton of kubebuilder-like instructions that you can annotate with here. See the [documentation](https://docs.rs/kube/latest/kube/derive.CustomResource.html) or the `crd_` prefixed [examples](https://github.com/kube-rs/kube/blob/main/examples) for more. **NB:** `#[derive(CustomResource)]` requires the `derive` feature enabled on `kube`. ## Runtime The `runtime` module exports the `kube_runtime` crate and contains higher level abstractions on top of the `Api` and `Resource` types so that you don't have to do all the `watch`/`resourceVersion`/storage book-keeping yourself. ### Watchers A streaming interface (similar to informers) that presents [`watcher::Event`](https://docs.rs/kube/latest/kube/runtime/watcher/enum.Event.html)s and does automatic relists under the hood. ```rust let api = Api::<Pod>::default_namespaced(client); let stream = watcher(api, Config::default()).default_backoff().applied_objects(); ``` This now gives a continual stream of events and you do not need to care about the watch having to restart, or connections dropping. ```rust while let Some(event) = stream.try_next().await? { println!("Applied: {}", event.name_any()); } ``` Note the base items from a `watcher` stream are an abstraction above the native `WatchEvent` to allow for store buffering. If you are following along to "see what changed", you can use utilities from [`WatchStreamExt`](https://docs.rs/kube/latest/kube/runtime/trait.WatchStreamExt.html), such as `applied_objects` to get a more conventional stream. ## Reflectors A `reflector` is a `watcher` with `Store` on `K`. It acts on all the `Event<K>` exposed by `watcher` to ensure that the state in the `Store` is as accurate as possible. ```rust let nodes: Api<Node> = Api::all(client); let lp = Config::default().labels("kubernetes.io/arch=amd64"); let (reader, writer) = reflector::store(); let rf = reflector(writer, watcher(nodes, lp)); ``` At this point you can listen to the `reflector` as if it was a `watcher`, but you can also query the `reader` at any point. ### Controllers A `Controller` is a `reflector` along with an arbitrary number of watchers that schedule events internally to send events through a reconciler: ```rust Controller::new(root_kind_api, Config::default()) .owns(child_kind_api, Config::default()) .run(reconcile, error_policy, context) .for_each(|res| async move { match res { Ok(o) => info!("reconciled {:?}", o), Err(e) => warn!("reconcile failed: {}", Report::from(e)), } }) .await; ``` Here `reconcile` and `error_policy` refer to functions you define. The first will be called when the root or child elements change, and the second when the `reconciler` returns an `Err`. See the [controller guide](https://kube.rs/controllers/intro/) for how to write these. ## TLS By default [rustls](https://github.com/rustls/rustls) is used for TLS, but `openssl` is supported. To switch, turn off `default-features`, and enable the `openssl-tls` feature: ```toml [dependencies] kube = { version = "0.97.0", default-features = false, features = ["client", "openssl-tls"] } k8s-openapi = { version = "0.23.0", features = ["latest"] } ``` This will pull in `openssl` and `hyper-openssl`. If `default-features` is left enabled, you will pull in two TLS stacks, and the default will remain as `rustls`. ## musl-libc Kube will work with [distroless](https://github.com/kube-rs/controller-rs/blob/main/Dockerfile), [scratch](https://github.com/constellation-rs/constellation/blob/27dc89d0d0e34896fd37d638692e7dfe60a904fc/Dockerfile), and `alpine` (it's also possible to use alpine as a builder [with some caveats](https://github.com/kube-rs/kube/issues/331#issuecomment-715962188)). ## License Apache 2.0 licensed. See LICENSE for details. ", Assign "at most 3 tags" to the expected json: {"id":"12072","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"