kube-rs

A Rust 客户端，类似于 Kubernetes 的 client-go，受 controller-runtime 启发的运行时抽象，以及受 CRDs 启发的 kubebuilder 的 derive 宏。作为 CNCF 的 沙箱项目 进行托管

这些 Crates 基于 Kubernetes apimachinery + API 概念 来启用通用抽象。这些抽象允许 Rust 重新解释 reflectors、controllers 和自定义资源接口，这样您就可以轻松编写应用程序。

安装

选择 kube 的版本以及生成的 k8s-openapi 结构体，在您选择的 Kubernetes 版本 下

[dependencies]
kube = { version = "0.93.1", features = ["runtime", "derive"] }
k8s-openapi = { version = "0.22.0", features = ["latest"] }

查看 功能 了解默认启用/可选功能快速概述。

升级

查看 kube.rs/upgrading。重要的更改在 发布 中突出显示，并在 变更日志 中存档。

用法

查看 示例目录 了解如何使用这些 Crates。

• kube API 文档
• kube.rs

官方示例

• version-rs：使用 axum 的轻量级部署 reflector
• controller-rs：在 actix 中 Controller 的 crd

对于实际项目，请参阅 ADOPTERS。

API

Api是与Kubernetes资源交互的对象，它泛型地处理Resource

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?;

查看以_api结尾的示例以获取更多详细信息。

自定义资源定义

使用自定义资源涉及通过kube-derive中的proc_macros进行自动代码生成。

您需要在#[derive(CustomResource, JsonSchema)]和某些#[kube(attrs..)]上添加到spec结构体中

#[derive(CustomResource, Debug, Serialize, Deserialize, Default, Clone, JsonSchema)]
#[kube(group = "kube.rs", version = "v1", kind = "Document", namespaced)]
pub struct DocumentSpec {
    title: String,
    content: String,
}

然后您可以使用生成的包装结构体Document作为kube::Resource

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()));

您可以在其中添加大量类似于kubebuilder的指令。有关更多信息，请参阅文档或以crd_为前缀的示例。

注意：#[derive(CustomResource)]需要在kube上启用derive功能。

运行时

runtime模块导出kube_runtime包，并在Api和Resource类型之上提供高级抽象，以便您不必自己进行所有watch/resourceVersion/存储簿记。

观察者

一个流式接口（类似于informers），它呈现watcher::Event并在底层自动重新列出。

let api = Api::<Pod>::default_namespaced(client);
let stream = watcher(api, Config::default()).applied_objects();

现在这将提供一个持续的事件流，您无需担心观察是否需要重新启动或连接丢失。

while let Some(event) = stream.try_next().await? {
    println!("Applied: {}", event.name_any());
}

请注意，来自watcher流的基项是对原生WatchEvent的抽象，以便进行存储缓冲。如果您想“查看发生了什么变化”，可以使用WatchStreamExt等实用工具，例如applied_objects以获取更传统的流。

反射器

reflector是一个带有Store的K的watcher。它作用于由watcher暴露的所有Event<K>，以确保Store中的状态尽可能准确。

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));

此时，您可以像对待watcher一样监听reflector，但您也可以在任何时候查询reader。

控制器

Controller是一个带有任意数量观察者的reflector，它内部调度事件以通过协调器发送事件

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;

这里 reconcile 和 error_policy 指的是你定义的函数。第一个将在根或子元素更改时调用，第二个在 reconciler 返回一个 Err 时调用。

有关如何编写这些内容的说明，请参阅 控制器指南。

TLS

默认情况下使用 rustls 进行 TLS，但也支持 openssl。要切换，请关闭 default-features 并启用 openssl-tls 功能

[dependencies]
kube = { version = "0.93.1", default-features = false, features = ["client", "openssl-tls"] }
k8s-openapi = { version = "0.22.0", features = ["latest"] }

这将引入 openssl 和 hyper-openssl。如果保留启用 default-features，则将引入两个 TLS 堆栈，并且默认值将保持为 rustls。

musl-libc

Kube 可以与 distroless、scratch 和 alpine（也可以使用 alpine 作为构建器，但有一些限制 [链接]）一起工作。

许可证

Apache 2.0 许可。有关详细信息，请参阅 LICENSE。