deskribe

Kubernetes resource descriptions in Rust, without starting kubectl.

Give deskribe an existing kube::Client and a resource. It reads the object, related resources, and events, then returns a text description. Applications can reuse their current connection and authentication setup.

Experimental. Supports 36 specialized resource kinds and a generic format for custom resources. The implementation is based on kubectl describers; upstream.json records the reviewed source baseline. Output is not guaranteed to match every kubectl version exactly.

Use it

The crate is not published yet. For local development:

[dependencies]
deskribe = { path = "../deskribe" }
kube = { version = "4.2", default-features = false, features = ["client", "rustls-tls", "aws-lc-rs"] }
k8s-openapi = { version = "0.28", features = ["latest"] }

Your application chooses the Kubernetes schema and TLS features. The example above uses the latest schema available in k8s-openapi 0.28 and rustls. Deskribe does not choose these features for you.

use deskribe::{gather, RenderOptions};
use kube::{api::{ApiResource, DynamicObject}, Client};

async fn describe(
    client: Client,
    resource: &ApiResource,
    selected: &DynamicObject,
) -> Result<String, String> {
    let description = gather(client, resource, selected).await?;
    description.render(&RenderOptions::default())
}

Pass the resource's discovered ApiResource and the selected object, including its name, namespace, and UID when known. Clone your existing client if you need to keep using it after the call.

API

• gather(client, resource, selected) fetches a fresh object and related data. The fresh GET uses the discovered API group, version, and plural. HPA v2 can fall back to v1; ServiceCIDR and IPAddress v1 can fall back to v1beta1. These fallbacks require the standard Kubernetes response for a missing endpoint. Other errors are returned without a version fallback. If the fallback fails, the original error is returned. It checks the selected UID when available, so an object recreated with the same name is not silently substituted. It follows paginated lists and overlaps independent requests.
• Description::render(&options) returns text without making network calls. Options control the current time and timezone. Defaults use the current time and the system timezone.
• fetch(client, resource, selected) gathers and renders with default options, returning (DynamicObject, String).

You can render the same snapshot more than once. Gather again to refresh its data. Dropping the gather future cancels the operation; requests already sent cannot be recalled.

Deskribe does not load kubeconfig, run subprocesses, create a runtime, print to stdout, or manage a UI. Those are the caller's responsibilities.

Errors and sensitive data

The client needs permission to read the object and the related resources used by its describer. Errors are returned as strings. Some optional reads are best-effort; for example, denied or unavailable ResourceSlice access does not fail a Node description.

If a Pod read fails but events are available, its description can show the error and those events. In that case, Description::object() returns the original selection rather than a fresh object.

Descriptions can contain secrets. Service-account Secret descriptions show data.token, as kubectl does. Other Secret values are shown as byte counts. Do not send descriptions to public logs or telemetry. Helm release notes belong to the calling application, not this library.

Development

cargo fmt --all -- --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked
python3 -m unittest discover -s scripts -p 'test_check_upstream.py' -v

Rust tests cover synthetic output snapshots, resource accounting, and the public fetch/render API. They do not need a cluster or Go. Sofka keeps separate TUI integration tests.

Code structure

• resource.rs selects the resource kind and event rules.
• fetch.rs gathers data through the API helpers in api.rs.
• description.rs stores the snapshot type and selects its renderer.
• Resource modules contain the related reads and text rendering for each group. Networking resources are in networking/; Jobs and CronJobs are in batch.rs.
• metadata.rs, events.rs, time.rs, format.rs, and json.rs contain shared functions.
• tests/corpus.rs checks and updates fixtures through the public gather and render API.

After reviewing an intentional output change, regenerate snapshots with:

DESKRIBE_UPDATE_FIXTURES=1 cargo test --locked --test corpus public_gather_and_render_match_regression_corpus

Review every changed snapshot. Regeneration alone does not prove correctness.

Upstream changes

The Upstream changes GitHub workflow runs weekly and can be started manually. It compares the source paths in upstream.json with the latest stable kubectl module tag, using the same tag for related Kubernetes repositories.

A source change marks the run as failed to request review. The run summary and upstream-report artifact contain the changed file list, commit IDs, and patches. Fetch errors are reported separately. The workflow does not run Go, edit Rust code, advance the baseline, or open pull requests.

See upstream maintenance for local commands and review steps. This checks source changes, not Rust output parity or every upstream dependency.

Publishing

A published GitHub Release triggers checks and a crates.io upload using trusted publishing. Use just release patch|minor|major from clean main after the one-time crates.io setup. This publishes only the crate, not binaries.

See release setup and commands, including the initial publish required before trusted publishing can be configured. just package verifies the crate without uploading it.

License

Apache-2.0. Adapted from Kubernetes and extracted from sofka. See LICENSE-APACHE and NOTICE.