{"id":13499475,"url":"https://github.com/kube-rs/controller-rs","last_synced_at":"2025-05-16T10:08:03.082Z","repository":{"id":39887828,"uuid":"183964538","full_name":"kube-rs/controller-rs","owner":"kube-rs","description":"A kubernetes reference controller with actix-web","archived":false,"fork":false,"pushed_at":"2025-05-13T09:54:51.000Z","size":677,"stargazers_count":309,"open_issues_count":11,"forks_count":33,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-13T10:41:31.218Z","etag":null,"topics":["actix","controller","example","kubernetes"],"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":null,"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,"zenodo":null}},"created_at":"2019-04-28T22:17:48.000Z","updated_at":"2025-05-13T09:54:33.000Z","dependencies_parsed_at":"2023-02-14T14:10:37.947Z","dependency_job_id":"316fec65-0e8f-49cb-82c2-13ee9e0214eb","html_url":"https://github.com/kube-rs/controller-rs","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kube-rs%2Fcontroller-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kube-rs%2Fcontroller-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kube-rs%2Fcontroller-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kube-rs%2Fcontroller-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kube-rs","download_url":"https://codeload.github.com/kube-rs/controller-rs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254509477,"owners_count":22082891,"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":["actix","controller","example","kubernetes"],"created_at":"2024-07-31T22:00:33.467Z","updated_at":"2025-05-16T10:07:58.067Z","avatar_url":"https://github.com/kube-rs.png","language":"Rust","readme":"## controller-rs\n[![ci](https://github.com/kube-rs/controller-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/kube-rs/controller-rs/actions/workflows/ci.yml)\n\nA rust kubernetes reference controller for a [`Document` resource](https://github.com/kube-rs/controller-rs/blob/main/yaml/crd.yaml) using [kube](https://github.com/kube-rs/kube/), with observability instrumentation.\n\nThe `Controller` object reconciles `Document` instances when changes to it are detected, writes to its `.status` object, creates associated events, and uses finalizers for guaranteed delete handling.\n\n## Installation\n\n### CRD\nApply the CRD from [cached file](yaml/crd.yaml), or pipe it from `crdgen` to pickup schema changes:\n\n```sh\ncargo run --bin crdgen | kubectl apply -f -\n```\n\n### Controller\n\nInstall the controller via `helm` by setting your preferred settings. For defaults:\n\n```sh\nhelm template charts/doc-controller | kubectl apply -f -\nkubectl wait --for=condition=available deploy/doc-controller --timeout=30s\nkubectl port-forward service/doc-controller 8080:80\n```\n\nThe helm chart sets up the [container](https://github.com/kube-rs/controller-rs/pkgs/container/controller) built from this repository.\n\n### Opentelemetry\n\nBuild and run with `telemetry` feature, or configure it via `helm`:\n\n```sh\nhelm template charts/doc-controller --set tracing.enabled=true | kubectl apply -f -\n```\n\nThis requires an opentelemetry collector in your cluster. [Tempo](https://github.com/grafana/helm-charts/tree/main/charts/tempo) / [opentelemetry-operator](https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-operator) / [grafana agent](https://github.com/grafana/helm-charts/tree/main/charts/agent-operator) should all work out of the box. If your collector does not support grpc otlp you need to change the exporter in [`telemetry.rs`](./src/telemetry.rs).\n\nNote that the [images are pushed either with or without the telemetry feature](https://hub.docker.com/r/clux/controller/tags/) depending on whether the tag includes `otel`.\n\n### Metrics\n\nMetrics is available on `/metrics` and a `ServiceMonitor` is configurable from the chart:\n\n```sh\nhelm template charts/doc-controller --set serviceMonitor.enabled=true | kubectl apply -f -\n```\n\n## Running\n\n### Locally\n\n```sh\ncargo run\n```\n\nor, with optional telemetry:\n\n```sh\nOPENTELEMETRY_ENDPOINT_URL=https://0.0.0.0:4317 RUST_LOG=info,kube=trace,controller=debug cargo run --features=telemetry\n```\n\n### In-cluster\nFor prebuilt, edit the [chart values](./charts/doc-controller/values.yaml) or [snapshotted yaml](./yaml/deployment.yaml) and apply as you see fit (like above).\n\nTo develop by building/reloading the deployment in k3d quickly, you can use [`tilt up`](https://tilt.dev/).\n\n## Usage\nIn either of the run scenarios, your app is listening on port `8080`, and it will observe `Document` events.\n\nTry some of:\n\n```sh\nkubectl apply -f yaml/instance-lorem.yaml\nkubectl delete doc lorem\nkubectl edit doc lorem # change hidden\n```\n\nThe reconciler will run and write the status object on every change. You should see results in the logs of the pod, or on the `.status` object outputs of `kubectl get doc -oyaml`.\n\n### Webapp output\nThe sample web server exposes some example metrics and debug information you can inspect with `curl`.\n\n```sh\n$ kubectl apply -f yaml/instance-lorem.yaml\n$ curl 0.0.0.0:8080/metrics\n# HELP doc_controller_reconcile_duration_seconds The duration of reconcile to complete in seconds\n# TYPE doc_controller_reconcile_duration_seconds histogram\ndoc_controller_reconcile_duration_seconds_bucket{le=\"0.01\"} 1\ndoc_controller_reconcile_duration_seconds_bucket{le=\"0.1\"} 1\ndoc_controller_reconcile_duration_seconds_bucket{le=\"0.25\"} 1\ndoc_controller_reconcile_duration_seconds_bucket{le=\"0.5\"} 1\ndoc_controller_reconcile_duration_seconds_bucket{le=\"1\"} 1\ndoc_controller_reconcile_duration_seconds_bucket{le=\"5\"} 1\ndoc_controller_reconcile_duration_seconds_bucket{le=\"15\"} 1\ndoc_controller_reconcile_duration_seconds_bucket{le=\"60\"} 1\ndoc_controller_reconcile_duration_seconds_bucket{le=\"+Inf\"} 1\ndoc_controller_reconcile_duration_seconds_sum 0.013\ndoc_controller_reconcile_duration_seconds_count 1\n# HELP doc_controller_reconciliation_errors_total reconciliation errors\n# TYPE doc_controller_reconciliation_errors_total counter\ndoc_controller_reconciliation_errors_total 0\n# HELP doc_controller_reconciliations_total reconciliations\n# TYPE doc_controller_reconciliations_total counter\ndoc_controller_reconciliations_total 1\n$ curl 0.0.0.0:8080/\n{\"last_event\":\"2019-07-17T22:31:37.591320068Z\"}\n```\n\nThe metrics will be scraped by prometheus if you setup a`ServiceMonitor` for it.\n\n### Events\nThe example `reconciler` only checks the `.spec.hidden` bool. If it does, it updates the `.status` object to reflect whether or not the instance `is_hidden`. It also sends a Kubernetes event associated with the controller. It is visible at the bottom of `kubectl describe doc samuel`.\n\nTo extend this controller for a real-world setting. Consider looking at the [kube.rs controller guide](https://kube.rs/controllers/intro/).\n","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkube-rs%2Fcontroller-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkube-rs%2Fcontroller-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkube-rs%2Fcontroller-rs/lists"}