{"id":19750141,"url":"https://github.com/kube-rs/kopium","last_synced_at":"2026-04-06T00:11:24.950Z","repository":{"id":39796513,"uuid":"432426646","full_name":"kube-rs/kopium","owner":"kube-rs","description":"Kubernetes OPenapI UnMangler","archived":false,"fork":false,"pushed_at":"2024-05-20T21:50:34.000Z","size":564,"stargazers_count":99,"open_issues_count":19,"forks_count":19,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-05-21T00:14:43.456Z","etag":null,"topics":["crd","generator","openapi"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kube-rs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["clux"]}},"created_at":"2021-11-27T10:08:18.000Z","updated_at":"2024-05-27T23:12:21.252Z","dependencies_parsed_at":"2023-02-09T14:30:20.837Z","dependency_job_id":"0ece4c75-2089-4e89-b917-42cd16c62fd9","html_url":"https://github.com/kube-rs/kopium","commit_stats":{"total_commits":180,"total_committers":7,"mean_commits":"25.714285714285715","dds":0.1444444444444445,"last_synced_commit":"68a36662c3c9a4d718025d0456300c5c18ef0b5b"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kube-rs%2Fkopium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kube-rs%2Fkopium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kube-rs%2Fkopium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kube-rs%2Fkopium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kube-rs","download_url":"https://codeload.github.com/kube-rs/kopium/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247406085,"owners_count":20933803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crd","generator","openapi"],"created_at":"2024-11-12T02:30:47.086Z","updated_at":"2026-04-06T00:11:24.944Z","avatar_url":"https://github.com/kube-rs.png","language":"Rust","funding_links":["https://github.com/sponsors/clux"],"categories":[],"sub_categories":[],"readme":"# kopium\n\n[![CI](https://github.com/kube-rs/kopium/actions/workflows/release.yml/badge.svg)](https://github.com/kube-rs/kopium/actions/workflows/release.yml)\n[![Crates.io](https://img.shields.io/crates/v/kopium.svg)](https://crates.io/crates/kopium)\n[![dependency status](https://deps.rs/repo/github/kube-rs/kopium/status.svg)](https://deps.rs/repo/github/kube-rs/kopium)\n\n**K**ubernetes **op**enap**i** **u**n**m**angler.\n\nGenerates [Rust](https://www.rust-lang.org/) data structs from [Kubernetes `customresourcedefinitions`](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) and their embedded openapi schemas.\n\n\u003e [!NOTE]\n\u003e Compatible with [almost](https://github.com/search?q=repo%3Ametio%2Fkube-custom-resources-rs+path%3Aignore\u0026type=code\u0026p=2)[*](https://github.com/kube-rs/kopium/pull/370#issuecomment-3316697683) all [catalogued CRDs](https://github.com/metio/kube-custom-resources-rs). If a CRD does not work, please [raise an issue](https://github.com/kube-rs/kopium/issues)!\n\nRequires stable [CustomResourceDefinition/v1](https://kubernetes.io/blog/2019/09/18/kubernetes-1-16-release-announcement/#custom-resources-reach-general-availability) schemas (Kubernetes \u003e=1.16) following the standard [spec/status model](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#object-spec-and-status).\n\n## Features\n\n- **Instantly queryable**: generated type optionally implements [`kube::CustomResource`](https://docs.rs/kube/latest/kube/derive.CustomResource.html) to provide api integration with `kube`\n- **[Rust doc comments](https://doc.rust-lang.org/rust-by-example/meta/doc.html#doc-comments)**: optionally extracted from `description` values in schema\n- **Safe case [conversion](https://github.com/withoutboats/heck)**: generated types uses rust standard casing with occasional [serde rename attributes](https://serde.rs/field-attrs.html)\n- **Usable locally and in CI**: Can read crds by name in cluster via `mycrd.group.io` or from file via `-f crd.yaml`\n\n## Installation\n\nGrab a prebuilt [directly](https://github.com/kube-rs/kopium/releases) / via [binstall](https://github.com/cargo-bins/cargo-binstall), or install from [crates.io](https://crates.io/crates/kopium):\n\n```sh\ncargo install kopium # from src\ncargo binstall kopium # from release\n```\n\n## Usage\n\nIf you have a crd installed in your cluster, pass a crd name accessible from your `KUBECONFIG`:\n\n```sh\nkopium prometheusrules.monitoring.coreos.com -A \u003e prometheusrule.rs\n```\n\nOr pass a file/stdin via `-f`:\n\n```sh\ncurl -sSL https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/main/example/prometheus-operator-crd/monitoring.coreos.com_prometheusrules.yaml \\\n    | kopium -Af - \u003e prometheusrule.rs\n```\n\n\n## Output\n\n```rust\nuse kube::CustomResource;\nuse schemars::JsonSchema;\nuse serde::{Serialize, Deserialize};\nuse std::collections::BTreeMap;\nuse k8s_openapi::apimachinery::pkg::util::intstr::IntOrString;\n\n/// Specification of desired alerting rule definitions for Prometheus.\n#[derive(CustomResource, Serialize, Deserialize, Clone, Debug, JsonSchema)]\n#[kube(group = \"monitoring.coreos.com\", version = \"v1\", kind = \"PrometheusRule\", plural = \"prometheusrules\")]\n#[kube(namespaced)]\npub struct PrometheusRuleSpec {\n    /// Content of Prometheus rule file\n    #[serde(default, skip_serializing_if = \"Option::is_none\")]\n    pub groups: Option\u003cVec\u003cPrometheusRuleGroups\u003e\u003e,\n}\n\n/// RuleGroup is a list of sequentially evaluated recording and alerting rules.\n#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)]\npub struct PrometheusRuleGroups {\n    #[serde(default, skip_serializing_if = \"Option::is_none\")]\n    pub interval: Option\u003cString\u003e,\n    pub name: String,\n    #[serde(default, skip_serializing_if = \"Option::is_none\")]\n    pub partial_response_strategy: Option\u003cString\u003e,\n    pub rules: Vec\u003cPrometheusRuleGroupsRules\u003e,\n}\n\n/// Rule describes an alerting or recording rule\n#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)]\npub struct PrometheusRuleGroupsRules {\n    #[serde(default, skip_serializing_if = \"Option::is_none\")]\n    pub alert: Option\u003cString\u003e,\n    #[serde(default, skip_serializing_if = \"Option::is_none\")]\n    pub annotations: Option\u003cBTreeMap\u003cString, String\u003e\u003e,\n    pub expr: IntOrString,\n    #[serde(default, skip_serializing_if = \"Option::is_none\")]\n    pub r#for: Option\u003cString\u003e,\n    #[serde(default, skip_serializing_if = \"Option::is_none\")]\n    pub labels: Option\u003cBTreeMap\u003cString, String\u003e\u003e,\n    #[serde(default, skip_serializing_if = \"Option::is_none\")]\n    pub record: Option\u003cString\u003e,\n}\n```\n\n## Usage with kube\n\nAdd the generated file (e.g. output from above in `prometheusrule.rs`) to your library, and import (at least) the special root type:\n\n```rust\nuse prometheusrule::PrometheusRule;\nuse kube::{Api, Client, ResourceExt};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let client = Client::try_default().await?;\n    let pr: Api\u003cPrometheusRule\u003e = Api::default_namespaced(client);\n    for p in pr.list(\u0026Default::default()).await? {\n        println!(\"Found PrometheusRule {} in current namespace\", p.name_any());\n    }\n    Ok(())\n}\n```\n\nNote 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](https://docs.rs/crate/kube/latest/source/Cargo.toml)). E.g. with `kube` 1:\n\n```toml\nkube = { version = \"2\", features = [\"derive\"] }\nschemars = { version = \"1\" }\nk8s-openapi = { version = \"0.26\", features = [\"latest\", \"schemars\"] }\n```\n\n## Autocomplete\n\nAutocompletion for most shells available via `kopium completions`:\n\n```sh\nsource \u003c(kopium completions bash)\n```\n\n## Testing\n\nUnit tests and running `kopium` from a file do not require a cluster and can be run with:\n\n```sh\ncargo test --lib\ncargo run --bin kopium -- -f mycrd.yaml -A\ncargo test --test trycmd_tests\n```\n\nFull 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:\n\n```sh\ncargo run --bin kopium -- -f prometheusrules.monitoring.coreos.com \u003e tests/gen.rs\necho \"pub type CR = PrometheusRule;\" \u003e\u003e tests/gen.rs\nkubectl apply -f tests/pr.yaml # needs to contain a CR with name \"gen\"\ncargo test --test runner -- --nocapture\n```\n\ntest shortcuts available via `just` in the [`justfile`](./justfile) and run pre-merge.\n\n## Existing Bindings\n\nCertain 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).\n\nThe main catalogue library is [metio/kube-custom-resources-rs](https://github.com/metio/kube-custom-resources-rs) which selects crds via features ([don't use all-features](https://mastodon.online/@sebhoss/111356248593690997)).\n\nSpecific group binding libraries:\n- [gateway-api-rs](https://github.com/kube-rs/gateway-api-rs)\n- [istio-api-rs](https://github.com/BlankZhu/istio-api-rs)\n\nFeel free to [edit this file](https://github.com/kube-rs/kopium/edit/main/README.md) to add more.\n\n## License\n\nApache 2.0 licensed. See LICENSE for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkube-rs%2Fkopium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkube-rs%2Fkopium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkube-rs%2Fkopium/lists"}