kube-rs

kube-rs 是一个类似于 client-go 的 Kubernetes 客户端，它提供了一个由 controller-runtime 启发的运行时抽象，以及由 kubebuilder 启发的 CRDs 衍生宏。作为 沙箱项目，由 CNCF 托管。

这些 crate 建立在 Kubernetes apimachinery 和 API 概念 之上，以实现通用抽象。这些抽象允许 Rust 对反射器、控制器和自定义资源接口进行重新解释，从而使您能够轻松编写应用程序。

安装

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

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

查看 功能 了解默认启用/可选功能。

升级

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

用法

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

• kube API 文档
• kube.rs

官方示例

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

对于真实世界的项目，请参阅 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中的宏来自动生成代码。

您需要在“spec”结构体上添加以下代码：`#[derive(CustomResource, JsonSchema)]` 和一些 `#[kube(attrs..)]`

#[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》的《watcher》。它作用于《watcher》公开的所有《Event`，以确保《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。