kopium

Kubernetes openapi unmangler.

Generates Rust data structs from Kubernetes customresourcedefinitions and their embedded openapi schemas.

[!NOTE] Compatible with almost * all catalogued CRDs. If a CRD does not work, please raise an issue!

Requires stable CustomResourceDefinition/v1 schemas (Kubernetes >=1.16) following the standard spec/status model.

Features

Instantly queryable: generated type optionally implements kube::CustomResource to provide api integration with kube
Rust doc comments: optionally extracted from description values in schema
Safe case conversion: generated types uses rust standard casing with occasional serde rename attributes
Usable locally and in CI: Can read crds by name in cluster via mycrd.group.io or from file via -f crd.yaml

Installation

Grab a prebuilt directly / via binstall, or install from crates.io:

cargo install kopium # from src
cargo binstall kopium # from release

Usage

If you have a crd installed in your cluster, pass a crd name accessible from your KUBECONFIG:

kopium prometheusrules.monitoring.coreos.com -A > prometheusrule.rs

Or pass a file/stdin via -f:

curl -sSL https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/main/example/prometheus-operator-crd/monitoring.coreos.com_prometheusrules.yaml \
    | kopium -Af - > prometheusrule.rs

Output

use kube::CustomResource;
use schemars::JsonSchema;
use serde::{Serialize, Deserialize};
use std::collections::BTreeMap;
use k8s_openapi::apimachinery::pkg::util::intstr::IntOrString;

/// Specification of desired alerting rule definitions for Prometheus.
#[derive(CustomResource, Serialize, Deserialize, Clone, Debug, JsonSchema)]
#[kube(group = "monitoring.coreos.com", version = "v1", kind = "PrometheusRule", plural = "prometheusrules")]
#[kube(namespaced)]
pub struct PrometheusRuleSpec {
    /// Content of Prometheus rule file
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub groups: Option<Vec<PrometheusRuleGroups>>,
}

/// RuleGroup is a list of sequentially evaluated recording and alerting rules.
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)]
pub struct PrometheusRuleGroups {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub interval: Option<String>,
    pub name: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub partial_response_strategy: Option<String>,
    pub rules: Vec<PrometheusRuleGroupsRules>,
}

/// Rule describes an alerting or recording rule
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)]
pub struct PrometheusRuleGroupsRules {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub alert: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub annotations: Option<BTreeMap<String, String>>,
    pub expr: IntOrString,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub r#for: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub labels: Option<BTreeMap<String, String>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub record: Option<String>,
}

Usage with kube

Add the generated file (e.g. output from above in prometheusrule.rs) to your library, and import (at least) the special root type:

use prometheusrule::PrometheusRule;
use kube::{Api, Client, ResourceExt};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::try_default().await?;
    let pr: Api<PrometheusRule> = Api::default_namespaced(client);
    for p in pr.list(&Default::default()).await? {
        println!("Found PrometheusRule {} in current namespace", p.name_any());
    }
    Ok(())
}

Note that you will need to depend on kube, along with k8s-openapi and schemars at semver compatible versions with the latest kube release (which can be seen in the last release cargo.toml for kube). E.g. with kube 1:

kube = { version = "2", features = ["derive"] }
schemars = { version = "1" }
k8s-openapi = { version = "0.26", features = ["latest", "schemars"] }

Autocomplete

Autocompletion for most shells available via kopium completions:

source <(kopium completions bash)

Testing

Unit tests and running kopium from a file do not require a cluster and can be run with:

cargo test --lib
cargo run --bin kopium -- -f mycrd.yaml -A
cargo test --test trycmd_tests

Full integration tests use your current cluster to try to read a CRD and a gen object (instance of the CRD type) and parse it into the generated type:

cargo run --bin kopium -- -f prometheusrules.monitoring.coreos.com > tests/gen.rs
echo "pub type CR = PrometheusRule;" >> tests/gen.rs
kubectl apply -f tests/pr.yaml # needs to contain a CR with name "gen"
cargo test --test runner -- --nocapture

test shortcuts available via just in the justfile and run pre-merge.

Existing Bindings

Certain binding libraries publish the kopium output up to crates.io for easier consumption, and this can avoid having to inline generated files in your repo (provided you do not need customization / patches to the output).

The main catalogue library is metio/kube-custom-resources-rs which selects crds via features (don't use all-features).

Specific group binding libraries:

Feel free to edit this file to add more.

License

Apache 2.0 licensed. See LICENSE for details.

kopium 0.22.5