If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/kube-rs/kube shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 25+ active contributors
• Distributed ownership (top contributor 38% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live kube-rs/kube repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kube-rs/kube.

What it runs against: a local clone of kube-rs/kube — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in kube-rs/kube | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of kube-rs/kube. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kube-rs/kube.git
#   cd kube
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of kube-rs/kube and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kube-rs/kube(\\.git)?\\b" \\
  && ok "origin remote is kube-rs/kube" \\
  || miss "origin remote is not kube-rs/kube (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "kube-client/src/api/mod.rs" \\
  && ok "kube-client/src/api/mod.rs" \\
  || miss "missing critical file: kube-client/src/api/mod.rs"
test -f "kube-client/src/client" \\
  && ok "kube-client/src/client" \\
  || miss "missing critical file: kube-client/src/client"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "kube-client/Cargo.toml" \\
  && ok "kube-client/Cargo.toml" \\
  || miss "missing critical file: kube-client/Cargo.toml"
test -f "kube-client/src/api/core_methods.rs" \\
  && ok "kube-client/src/api/core_methods.rs" \\
  || miss "missing critical file: kube-client/src/api/core_methods.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/kube-rs/kube"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

kube-rs is a production-grade Rust client library and controller runtime for Kubernetes that mirrors client-go's design patterns. It provides type-safe API bindings via k8s-openapi, a reflector/controller abstraction for building operators, and a derive macro system for Custom Resource Definitions (CRDs) inspired by kubebuilder. The core enables Rust developers to build Kubernetes controllers, webhooks, and client applications without manual API scaffolding. See architecture tab.

Rust developers building Kubernetes operators, admission controllers, and client tools who need type-safe, async-first Kubernetes API interactions. Platform engineers extending Kubernetes with custom controllers. Contributors to the Kubernetes ecosystem who prefer Rust's memory safety over Go.

Production-ready and actively maintained. The project is a CNCF Sandbox Project, has comprehensive CI/CD across 11 GitHub workflows (.github/workflows/), enforces MSRV of 1.88 with Kubernetes 1.31+ support, and maintains detailed CHANGELOG.md and upgrading guides. Workspace tracks 5 core crates with synchronized versioning (3.1.0), indicating stability and coordinated releases.

Relatively low risk for a Kubernetes library due to CNCF backing and broad test coverage (CI, coverage, clippy, audit workflows). Main considerations: tight coupling to k8s-openapi versioning (0.27.0) and schemars (1.0.0)—Kubernetes API version mismatches can break compilation. The monorepo structure (5 interdependent crates) means a breaking change in kube-core affects all dependents. No single-maintainer risk visible, but audit workflow and deny.toml dependency controls are in place.

Active maintenance with Rust edition 2024 support and recent dependency updates (tokio 1.35, hyper 1.6.0, serde 1.0.221). Workflows actively run on every push (audit.yml, ci.yml, coverage.yml, features.yml). The repo tracks memory benchmarking (memory-bench.yml) and devcontainer testing, indicating focus on performance and developer experience. Release workflow suggests structured release cadence.

git clone https://github.com/kube-rs/kube
cd kube
rustup override set 1.88  # or newer (MSRV is 1.88)
cargo build
cargo test

For examples: cd examples && cargo run --example configmapgen_controller (requires active Kubernetes cluster). Use .devcontainer/ for isolated env: open in VS Code with Dev Containers extension.

Daily commands: Development: cargo build && cargo test runs full test suite. For controller examples: cd examples && cargo run --example configmapgen_controller (requires kubectl proxy or in-cluster config). E2E tests: cd e2e && cargo test --test boot against live cluster. Benchmarks: cargo bench --features bench (see memory-bench.yml for dhat profiling).

• kube-client/src/api/mod.rs — Core API trait definitions and builder patterns for all Kubernetes client operations; every contributor must understand the fluent API design.
• kube-client/src/client — HTTP client configuration, TLS handling, and request/response serialization; essential for understanding how kube-rs communicates with the Kubernetes API server.
• Cargo.toml — Workspace configuration defining all member crates (kube-client, kube-core, kube-derive, kube-runtime) and shared dependencies; critical for understanding the modular architecture.
• kube-client/Cargo.toml — Declares dependencies on tokio, hyper, serde, and determines feature flags that affect API surface; shapes what functionality is available.
• kube-client/src/api/core_methods.rs — Implementation of get, list, create, patch, delete, and watch operations; the bread-and-butter CRUD and streaming logic every user relies on.
• kube-client/src/api/subresource.rs — Handles Kubernetes subresources (status, scale, eviction, port-forward, exec); needed for advanced operations beyond standard CRUD.
• examples/pod_api.rs — Canonical example showing typical client usage patterns; reference implementation for new contributors.

Add a new API operation (e.g., custom endpoint)

1. Define the request/response types in your crate (or use existing K8s types from kube-core) (examples/pod_api.rs)
2. Extend the Api<K> trait with a new method in kube-client/src/api/mod.rs (kube-client/src/api/mod.rs)
3. Implement the method logic using request_url() and request_text() helpers in core_methods.rs (kube-client/src/api/core_methods.rs)
4. Add an example demonstrating the new operation (examples/custom_client.rs)

Customize client configuration (TLS, auth, timeouts)

1. Examine client initialization patterns in Client::try_default() or Client::new() in kube-client/src/client (kube-client/src/client)
2. Use ClientBuilder to set custom middleware, TLS, or auth strategy (examples/custom_client.rs)
3. Chain .tls_params(), .default_ns(), or .timeout() before .build() (examples/custom_client_tls.rs)

Implement a stream-based watcher (e.g., watch Pod changes)

1. Use Api::watch() or Api::list_metadata() with ListParams::default().watch_bookmark() to stream events (examples/pod_watcher.rs)
2. Handle WatchEvent enums (ADDED, MODIFIED, DELETED, BOOKMARK, ERROR) (examples/multi_watcher.rs)
3. Optionally integrate with kube-runtime for higher-level patterns (Reflector, Controller) (examples/pod_reflector.rs)

Execute a command inside a Pod (exec) or retrieve logs

1. Call Api::exec() with ExecCommand to open a bidirectional stream (examples/pod_exec.rs)
2. Use Api::log_stream() for log retrieval with optional tail/follow params (examples/log_stream.rs)
3. Handle the AsyncRead/AsyncWrite stream from remote_command.rs (kube-client/src/api/remote_command.rs)

• Tokio async runtime — Handles concurrent API requests and streaming (watch, exec, logs) without blocking; essential for controllers managing hundreds of objects.
• Hyper HTTP client — Low-level control over request/response handling, streaming, and connection pooling; enables port-forward and exec tunneling.
• Serde + k8s-openapi types — Automatic (de)serialization of Kubernetes API objects; keeps code maintainable as the API evolves.
• Rustls (optional) + OpenSSL — Secure TLS for API server communication; pluggable to support different certificate stores and FIPS compliance.
• Derive macros (darling, educe) — Reduces boilerplate in CRD definitions and reduces compile-time complexity through procedural macros.

• Separate kube-client, kube-core, kube-derive, and kube-runtime crates

  • Why: Allows users to pick only what they need (e.g., just the client without controller runtime).
  • Consequence: Increased maintenance complexity; version coordination across crates; duplicated code patterns (Api trait, error types).

• Fluent builder API (e.g., Api::namespaced().list(params)) instead of positional arguments

  • Why: More readable, discoverable, and extensible for optional parameters.
  • Consequence: More trait indirection; potential for longer compile times; API surface is larger.

• Async-only, no sync API

  • Why: Eliminates two codebases; Tokio is the de facto async runtime in Rust.
  • Consequence: Users must adopt async/await; harder integration into sync codebases.

• Use k8s-openapi types (code-generated from OpenAPI spec)

  • Why: Automatically tracks upstream Kubernetes API changes with little manual effort.
  • Consequence: Generated code can be verbose; harder to customize; dependency on external code generator.

• Does not provide authentication credentials; delegated to kubeconfig, in-cluster service accounts, or custom auth middleware.
• Does not implement Kubernetes resource scheduling, admission control, or cluster management logic.
• Not a full Kubernetes API mock or emulation; designed for real cluster communication.
• Does not abstract over multiple cloud providers; it is provider-agnostic.

Kubeconfig discovery: Client defaults to in-cluster config (via service account) if KUBECONFIG env var absent; local dev requires KUBECONFIG set or explicit Client builder config. Feature interactions: The runtime feature implicitly enables derive and client; disabling features can break examples. MSRV strictness: RUST_BACKTRACE and 1.88 (not 1.87) enforced in CI; upgrade Rust before running tests. Workspace dependency lock: All workspace crates use synchronized version (3.1.0 in Cargo.toml); releasing one requires releasing all five. Proc-macro compilation: kube-derive must compile before kube-core (see workspace member order); can cause mysterious failures if dirty build cache exists.

• Reflector pattern — Core abstraction in kube-runtime for maintaining an in-memory cache of Kubernetes resources via watch; essential for building efficient controllers that don't hammer the API server
• Reconciliation loop — The Controller<K> in kube-runtime repeatedly observes resource state and applies corrections; understanding this async loop is fundamental to writing operators
• Proc-macro code generation — kube-derive uses syn/quote to transform Rust structs into Kubernetes CRD OpenAPI schemas at compile time; critical for understanding how #[derive(CustomResource)] works
• Owner references and finalizers — Kubernetes garbage collection and cleanup patterns that controllers must implement via metadata fields; essential for resource lifecycle management in operators
• Watch API and streaming — HTTP long-lived connections to stream Kubernetes API events; kube-client wraps this in tokio-tungstenite for WebSocket and chunked encoding
• Admission webhooks (ValidatingWebhook / MutatingWebhook) — kube-rs provides server stubs for webhook frameworks (examples/admission_controller.rs); must validate/mutate requests before they persist to etcd
• RBAC and service account bindings — Controllers run as service accounts with specific permissions; understanding ClusterRole and ClusterRoleBinding is required for deploying operators safely

• kubernetes-sigs/controller-runtime — Go controller-runtime that kube-rs was architecturally inspired by; study this to understand reconciliation patterns
• Arnavion/k8s-openapi — Upstream API type bindings that kube-rs consumes; version compatibility is critical (locked at 0.27.0)
• kube-rs/version-rs — Official lightweight example using kube-rs with axum for a reflector-based deployment versioner
• kube-rs/controller-rs — Official full-featured controller example using kube-rs with actix; demonstrates CRD reconciliation patterns
• GREsau/schemars — Schema derivation library that powers kube-derive's CRD generation; understanding schema generation helps customize CRDs

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for custom TLS scenarios in kube-client

The repo has examples/custom_client_tls.rs demonstrating TLS usage, but there are no dedicated integration tests in the e2e/ directory validating TLS certificate verification, mTLS scenarios, and certificate rotation. This is critical for a Kubernetes client library where security is paramount. Currently, e2e/ only contains boot.rs and job.rs tests. Adding e2e/tls_client.rs would ensure TLS configurations work reliably across Rust versions and dependency updates.

• [ ] Create e2e/tls_client.rs with tests for: self-signed certificate validation, mTLS client-server authentication, and PEM certificate loading
• [ ] Add TLS test fixtures (certificates) to e2e/ directory following k8s test patterns
• [ ] Integrate new e2e test into e2e/Dockerfile and document in e2e/README.md
• [ ] Ensure test covers both hyper-rustls and hyper-openssl backends from Cargo.toml dependencies

Add feature-gated workflow for watcher backpressure and error handling scenarios

The examples/ directory includes errorbounded_configmap_watcher.rs, dynamic_watcher.rs, and event_watcher.rs, but .github/workflows/features.yml (which exists in the structure) may not comprehensively test all watcher + backpressure combinations. The kube-runtime crate likely has complex watcher semantics that need dedicated CI coverage. Adding a workflow step to test backpressure scenarios under different load conditions would catch regressions early.

• [ ] Extend .github/workflows/features.yml to include a dedicated 'watcher-scenarios' job that runs examples with timeout and memory constraints
• [ ] Add a new example examples/watcher_backpressure_test.rs that stresses the watcher with high-frequency updates and measures latency/memory
• [ ] Document watcher backpressure behavior in examples/README.md with performance characteristics
• [ ] Ensure coverage includes both backpressure handling and partial failure scenarios (using kube-runtime's error types)

Add missing documentation module for kube-derive macro capabilities with examples

The kube-derive crate (listed in Cargo.toml members) provides CRD derivation macros, but there are no dedicated doc examples showing all supported attributes. While examples/ has crd_derive*.rs files, the kube-derive crate itself likely lacks comprehensive internal documentation comments. This blocks users from discovering macro capabilities via rust-analyzer and generates poor IDE experience. Adding missing_docs = "deny" lint coverage to kube-derive would force documentation completion.

• [ ] Audit kube-derive/src/ for missing /// doc comments on public macros and attributes
• [ ] Add doc examples to each macro showing: basic #[derive(CustomResource)], schema generation, validation rules, and multi-version CRDs
• [ ] Create kube-derive/examples/ subdirectory with doc-test valid examples matching crd_derive*.rs patterns from examples/
• [ ] Update CONTRIBUTING.md to document macro development workflow and doc-test validation

• Add missing integration tests for webhook server (examples/admission_controller.rs) in e2e/ that validate ValidatingWebhookConfiguration and AdmissionReview round-trips; currently only covered in examples, not e2e test suite.
• Document the reflector pattern with a concrete walk-through example showing how watches, caching, and predicates interact in kube-runtime; add docs example to kube-runtime/src/reflector/mod.rs with code that tracks Pod ownership changes.
• Extend examples/Cargo.toml with new rustls-native-root-certs example showing certificate pinning for airgapped clusters (referenced in docs but no runnable example exists).

The kube-rs codebase demonstrates strong security posture with: (1) Explicit forbid on unsafe code at workspace level, (2) Active security audit workflow in CI/CD, (3) Dependabot-driven dependency updates, (4) Clear security policy and vulnerability reporting process, (5) CII Best Practices badge compliance. Main concerns are: (1) Critical edition typo ('2024' should be '2021') that could impact builds, (2) Dependency on cryptographic libraries requiring constant vigilance (mitigated by audit workflows), (3) One incomplete dependency specification. The project demonstrates security maturity with documented processes in SECURITY.md and established CI/CD security checks. Recommend fixing the edition typo immediately and completing the prettyplease dependency specification.

• Medium · Unsafe Code Forbidden Policy Not Enforced at All Levels — Cargo.toml workspace lints configuration. While the workspace forbids unsafe_code at the lint level, this only applies to members that inherit workspace lints. Proc-macro crates (kube-derive) and dependencies may contain unsafe code. Dependencies like 'openssl', 'hyper-rustls', and 'rustls' are cryptographic libraries that legitimately use unsafe code, but their version pinning and update frequency should be monitored. Fix: Ensure all workspace members explicitly inherit workspace lints. Regularly audit and update cryptographic dependencies. Use cargo-audit in CI/CD pipeline (noted in audit.yml workflow).
• Medium · TLS/Crypto Dependencies Require Active Maintenance — Cargo.toml - dependencies: rustls, hyper-rustls, openssl, hyper-openssl. The project uses rustls (0.23.16), hyper-rustls (0.27.1), hyper-openssl (0.10.2), and openssl (0.10.61). While versions appear recent, cryptographic libraries require constant vigilance for security updates. OpenSSL in particular has a history of CVEs. Fix: Maintain automated dependency updates via Dependabot (already configured in .github/dependabot.yml). Ensure audit.yml workflow runs regularly. Subscribe to security advisories for rustls and openssl projects.
• Medium · Missing Edition 2021 Compatibility Warning — Cargo.toml - workspace.package.edition. The workspace specifies edition = '2024' which does not exist (Rust editions are 2015, 2018, 2021). This appears to be a typo and should be '2021'. This could cause build failures or unexpected behavior. Fix: Change edition = '2024' to edition = '2021' to use the latest stable edition.
• Low · Incomplete Dependency in Workspace — Cargo.toml - workspace.dependencies.prettyplease. The prettyplease dependency is missing its version specification in the workspace dependencies list (shows 'prettyplease =' with no version). Fix: Complete the dependency specification with a version number, e.g., 'prettyplease = "0.2"'.
• Low · Docker Security Baseline — .devcontainer/Dockerfile. The Dockerfile in .devcontainer is present but not provided for analysis. Dev containers should follow security best practices including non-root users, minimal base images, and security scanning. Fix: Ensure Dockerfile uses minimal base images, runs processes as non-root user, and includes security scanning in the devcontainer workflow (already referenced in devcontainer.yml workflow).
• Low · MSRV Policy for Security Updates — Cargo.toml - rust-version, README.md. Minimum Supported Rust Version is 1.88.0. While this is recent, ensure that security patches for the Rust standard library and compiler are monitored and integrated into the CI pipeline. Fix: Keep MSRV updated and monitor Rust security advisories. Consider using 'cargo +nightly audit' for early warning of dependency issues.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.