{"id":13478466,"url":"https://github.com/kube-rs/kube","last_synced_at":"2025-05-13T15:04:14.334Z","repository":{"id":36999024,"uuid":"157133149","full_name":"kube-rs/kube","owner":"kube-rs","description":"Rust Kubernetes client and controller runtime","archived":false,"fork":false,"pushed_at":"2025-05-13T08:57:07.000Z","size":4528,"stargazers_count":3289,"open_issues_count":116,"forks_count":338,"subscribers_count":34,"default_branch":"main","last_synced_at":"2025-05-13T09:34:50.060Z","etag":null,"topics":["client","kubernetes","runtime","rust"],"latest_commit_sha":null,"homepage":"https://kube.rs","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kube-rs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["clux"]}},"created_at":"2018-11-11T23:53:47.000Z","updated_at":"2025-05-13T08:57:10.000Z","dependencies_parsed_at":"2023-01-17T13:01:28.857Z","dependency_job_id":"1eafc305-8965-469a-805e-fdfe065004b2","html_url":"https://github.com/kube-rs/kube","commit_stats":{"total_commits":1821,"total_committers":110,"mean_commits":"16.554545454545455","dds":0.442613948380011,"last_synced_commit":"e01187e13ba364ccecec452e023316a62fb13e04"},"previous_names":["kube-rs/kube-rs"],"tags_count":103,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kube-rs%2Fkube","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kube-rs%2Fkube/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kube-rs%2Fkube/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kube-rs%2Fkube/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kube-rs","download_url":"https://codeload.github.com/kube-rs/kube/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253968648,"owners_count":21992256,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","kubernetes","runtime","rust"],"created_at":"2024-07-31T16:01:57.448Z","updated_at":"2025-05-13T15:04:09.325Z","avatar_url":"https://github.com/kube-rs.png","language":"Rust","funding_links":["https://github.com/sponsors/clux"],"categories":["Rust","rust","kubernetes","\u003ca name=\"Rust\"\u003e\u003c/a\u003eRust","Major Projects that Use Aya"],"sub_categories":["Aya-related talks"],"readme":"# kube-rs\n\n[![Crates.io](https://img.shields.io/crates/v/kube.svg)](https://crates.io/crates/kube)\n[![Rust 1.81](https://img.shields.io/badge/MSRV-1.81-dea584.svg)](https://github.com/rust-lang/rust/releases/tag/1.81.0)\n[![Tested against Kubernetes v1.28 and above](https://img.shields.io/badge/MK8SV-v1.28-326ce5.svg)](https://kube.rs/kubernetes-version)\n[![Best Practices](https://bestpractices.coreinfrastructure.org/projects/5413/badge)](https://bestpractices.coreinfrastructure.org/projects/5413)\n[![Discord chat](https://img.shields.io/discord/500028886025895936.svg?logo=discord\u0026style=plastic)](https://discord.gg/tokio)\n\nA [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/).\n\nThese 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.\n\n## Installation\n\nSelect 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/):\n\n```toml\n[dependencies]\nkube = { version = \"0.99.0\", features = [\"runtime\", \"derive\"] }\nk8s-openapi = { version = \"0.24.0\", features = [\"latest\"] }\n```\n\nSee [features](https://kube.rs/features/) for a quick overview of default-enabled / opt-in functionality.\n\n## Upgrading\n\nSee [kube.rs/upgrading](https://kube.rs/upgrading/).\nNoteworthy changes are highlighted in [releases](https://github.com/kube-rs/kube/releases), and archived in the [changelog](https://kube.rs/changelog/).\n\n## Usage\n\nSee the **[examples directory](https://github.com/kube-rs/kube/blob/main/examples)** for how to use any of these crates.\n\n- **[kube API Docs](https://docs.rs/kube/)**\n- **[kube.rs](https://kube.rs)**\n\nOfficial examples:\n\n- [version-rs](https://github.com/kube-rs/version-rs): lightweight deployment `reflector` using axum\n- [controller-rs](https://github.com/kube-rs/controller-rs): `Controller` of a crd inside actix\n\nFor real world projects see [ADOPTERS](https://kube.rs/adopters/).\n\n## Api\n\nThe [`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):\n\n```rust\nuse k8s_openapi::api::core::v1::Pod;\nlet pods: Api\u003cPod\u003e = Api::default_namespaced(client);\n\nlet pod = pods.get(\"blog\").await?;\nprintln!(\"Got pod: {pod:?}\");\n\nlet patch = json!({\"spec\": {\n    \"activeDeadlineSeconds\": 5\n}});\nlet pp = PatchParams::apply(\"kube\");\nlet patched = pods.patch(\"blog\", \u0026pp, \u0026Patch::Apply(patch)).await?;\nassert_eq!(patched.spec.active_deadline_seconds, Some(5));\n\npods.delete(\"blog\", \u0026DeleteParams::default()).await?;\n```\n\nSee the examples ending in `_api` examples for more detail.\n\n## Custom Resource Definitions\n\nWorking with custom resources uses automatic code-generation via [proc_macros in kube-derive](https://docs.rs/kube/latest/kube/derive.CustomResource.html).\n\nYou need to add `#[derive(CustomResource, JsonSchema)]` and some `#[kube(attrs..)]` on a __spec__ struct:\n\n```rust\n#[derive(CustomResource, Debug, Serialize, Deserialize, Default, Clone, JsonSchema)]\n#[kube(group = \"kube.rs\", version = \"v1\", kind = \"Document\", namespaced)]\npub struct DocumentSpec {\n    title: String,\n    content: String,\n}\n```\n\nThen you can use the generated wrapper struct `Document` as a [`kube::Resource`](https://docs.rs/kube/*/kube/trait.Resource.html):\n\n```rust\nlet docs: Api\u003cDocument\u003e = Api::default_namespaced(client);\nlet d = Document::new(\"guide\", DocumentSpec::default());\nprintln!(\"doc: {:?}\", d);\nprintln!(\"crd: {:?}\", serde_yaml::to_string(\u0026Document::crd()));\n```\n\nThere 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.\n\n**NB:** `#[derive(CustomResource)]` requires the `derive` feature enabled on `kube`.\n\n## Runtime\n\nThe `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.\n\n### Watchers\n\nA 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.\n\n```rust\nlet api = Api::\u003cPod\u003e::default_namespaced(client);\nlet stream = watcher(api, Config::default()).default_backoff().applied_objects();\n```\n\nThis now gives a continual stream of events and you do not need to care about the watch having to restart, or connections dropping.\n\n```rust\nwhile let Some(event) = stream.try_next().await? {\n    println!(\"Applied: {}\", event.name_any());\n}\n```\n\n\nNote 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.\n\n## Reflectors\n\nA `reflector` is a `watcher` with `Store` on `K`. It acts on all the `Event\u003cK\u003e` exposed by `watcher` to ensure that the state in the `Store` is as accurate as possible.\n\n```rust\nlet nodes: Api\u003cNode\u003e = Api::all(client);\nlet lp = Config::default().labels(\"kubernetes.io/arch=amd64\");\nlet (reader, writer) = reflector::store();\nlet rf = reflector(writer, watcher(nodes, lp));\n```\n\nAt this point you can listen to the `reflector` as if it was a `watcher`, but you can also query the `reader` at any point.\n\n### Controllers\n\nA `Controller` is a `reflector` along with an arbitrary number of watchers that schedule events internally to send events through a reconciler:\n\n```rust\nController::new(root_kind_api, Config::default())\n    .owns(child_kind_api, Config::default())\n    .run(reconcile, error_policy, context)\n    .for_each(|res| async move {\n        match res {\n            Ok(o) =\u003e info!(\"reconciled {:?}\", o),\n            Err(e) =\u003e warn!(\"reconcile failed: {}\", Report::from(e)),\n        }\n    })\n    .await;\n```\n\nHere `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`.\n\nSee the [controller guide](https://kube.rs/controllers/intro/) for how to write these.\n\n## TLS\n\nUses [rustls](https://github.com/rustls/rustls) with `ring` provider (default) or `aws-lc-rs` provider (optional).\n\nTo switch [rustls providers](https://docs.rs/rustls/latest/rustls/crypto/struct.CryptoProvider.html), turn off `default-features` and enable the `aws-lc-rs` feature:\n\n```toml\nkube = { version = \"0.99.0\", default-features = false, features = [\"client\", \"rustls-tls\", \"aws-lc-rs\"] }\n```\n\nTo switch to `openssl`, turn off `default-features`, and enable the `openssl-tls` feature:\n\n```toml\nkube = { version = \"0.99.0\", default-features = false, features = [\"client\", \"openssl-tls\"] }\n```\n\nThis 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`.\n\n## musl-libc\n\nKube 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)).\n\n## License\n\nApache 2.0 licensed. See LICENSE for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkube-rs%2Fkube","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkube-rs%2Fkube","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkube-rs%2Fkube/lists"}