RGDs can now generate cluster-scoped instance CRDs. Add scope: Cluster to your schema and kro produces a non-namespaced CRD. Namespaced child resources must explicitly declare metadata.namespace when the instance is cluster-scoped. The field defaults to Namespaced and is immutable after creation. Docs

includeWhen Can Reference Upstream Resources

includeWhen expressions are no longer limited to schema fields - they can now reference other resources in the graph. kro treats these references as real dependencies that participate in DAG construction and cycle detection. Docs.

Decorators - External Collections (KREP-008)

ExternalRef previously only supported name and namespace for scalar lookups. They now support full matchLabels and matchExpressions selectors, so a single externalRef can match multiple resources dynamically. Selector values accept CEL expressions. Docs

Reactive Watches on External References and Decorators (KREP-003)

kro now watches external references - both scalar and collections — and re-reconciles instances instantly when an external resource is created, updated, or deleted. (Docs)

omit() CEL Function ( ⚠️ feature-gated: CELOmitFunction)

A new CEL omit() function lets you conditionally remove fields from rendered templates. Use ${schema.spec.kmsKeyID != "" ? schema.spec.kmsKeyID : omit()} and the field is dropped entirely from the SSA payload - important for APIs that distinguish between field absence and an empty value. omit() is rejected on required metadata fields (name, namespace, apiVersion, kind). Alpha, default off. Docs

Instance Status Condition Events (⚠️ feature-gated: InstanceConditionEvents)

kro can now emit Kubernetes Events when instance status conditions transition between reconciliation cycles. Events show the transition as "False → True: ResourcesReady" and are typed Normal for transitions to True, Warning for everything else. Visible via kubectl describe on any instance. Alpha, default off. Docs

CEL Libraries Enrichment

The CEL environment gained nine new capabilities:

json: json.marshal() and json.unmarshal() for working with JSON payloads directly in expressions
maps: map.merge() to combine two maps with second-map-wins semantics
lists: lists.setAtIndex(), lists.insertAtIndex(), lists.removeAtIndex() for immutable list mutations; k8s Lists library for lists.concat() and friends
quantity: parse and manipulate Kubernetes Quantities ("500m", "2Gi") natively
bind: cel.bind(varName, init, body) to name intermediate values and reduce repetition
comprehensions: TwoVarComprehensions (transformMap, transformList) and sortBy for stable ordering by arbitrary expressions
random: random.seededInt(min, max, seed) for deterministic integer generation from resource UIDs

Graph Revisions (KREP-013)

RGD specs are now versioned. Each spec change creates an immutable GraphRevision snapshot (kubectl get gr) that is compiled and validated independently before instances can use it. If a new spec breaks compilation, instances block with a clear status instead of failing silently — you see exactly which revision failed and why via kubectl describe gr. kro retains the last 5 revisions per RGD (configurable), giving you an audit trail of every spec change. More importantly, Graph Revisions lay the foundation for progressive rollouts and revision pinning in future releases. Docs. Docs

✨ Features

feat: implement KREP-10 - support cluster-scoped instance CRDs by @antcybersec in #1152
feat: external ref watches and external ref collections by @jakobmoellerdev in #1079
feat: support CEL expressions in LabelSelectors for external collections by @jakobmoellerdev in #1079
feat: disable instance reconciliation when a kro.run/reconcile:"disabled" label is present by @NickKeller in #1062
feat(cel): add omit() for conditional field omission in templates by @michaelhtm in #1139
feat(events): Add events for instance status condition transition by @spattk in #1151
feat(#510): implement standard Kubernetes feature gates via component-base by @jakobmoellerdev in #1172
feat(helm): expose feature gates in chart values by @a-hilaly in #1187
feat(graph): gate omit() behind CELOmitFunction feature flag by @a-hilaly in #1185
feat(graph): reject omit() on required resource metadata fields by @michaelhtm in #1167
feat: allow includeWhen to reference other resources by @a-hilaly in #1104
feat(cel): add json.marshal and json.unmarshal CEL functions by @NicholasBlaskey in #1033
feat(cel): add map library with merge functionality by @a-hilaly in #1068
feat(cel): add index-mutation functions to the lists library by @pnz1990 in #1148
feat(cel): add k8s Lists library support by @NicholasBlaskey in #1178
feat(cel): add k8s Quantity library support by @NicholasBlaskey in #1177
feat(cel): add cel.bind() support to default environment and AST inspector by @pnz1990 in #1145
feat(cel): add support for TwoVarComprehensions in CEL environment by @jakobmoellerdev in #1136
feat(cel/ast): improve loop variable scoping and support sortBy comprehension by @jakobmoellerdev in #1136
feat(cel): add deterministic seeded integer generation function by @a-hilaly in #1108
feat(cel): add version support for the cel json library by @NicholasBlaskey in #1033
feat(compat): detect default value changes as non-breaking in schema comparison by @michaelhtm in #1098
feat(instance): block graph propagation on terminating managed resources by @a-hilaly in #1132
feat(helm): add topologySpreadConstraints in deployment by @QuentinBtd in #1137
feat: Add opt-in pprof profiling support via build tags by @a-hilaly in #922
feat: make instance requeue interval configurable by @a-hilaly in #1184
feat: expose leader election tuning flags in helm chart by @a-hilaly in #1205
feat: add metrics for pkg/runtime by @NicholasBlaskey in #1053
feat: Add RGD controller metrics by @NicholasBlaskey in #1063
feat: Add instance controller metrics by @NicholasBlaskey in #1056
feat(cel): add metrics for CEL cache hit/miss tracking by @a-hilaly in #1142
feat: Add client-go and reflector metrics registration by @a-hilaly in #1143
feat: Use expressive histogram buckets for controller reconciliation metrics by @a-hilaly in #1157
feat: Implementation of Graph Revisions (KREP-013) by @a-hilaly in #1085
feat: Watch owned GraphRevisions from the RGD controller by @a-hilaly in #1200
feat: watch graph revisions by spec.snapshot.name for orphan adoption by @a-hilaly in #1206
feat: Limit collection size to 1000 to protect cluster performance by @NicholasBlaskey in #1036
feat: limit collection dimension to 5 by @michaelhtm in #1045
feat: disable instance reconciliation with annotation instead of label by @michaelhtm in #1191
feat: KREP-15 label/annotation migration to internal.kro.run/ prefix by @michaelhtm in #1094

🐛 Bug Fixes

fix: flaky validate RGD status test by @michaelhtm in #1034
fix: flaky validate RGD status integration test by @Aman-Cool in #1041
fix(docs): Wrong schema apiVersion definition in RGD chaining by @gagahsyuja in #1050
fix: properly return error in simpleschema parsing when the marker does by @NickKeller in #1073
fix: remove the rgd labels from managed resources by @jakobmoellerdev in #1075
fix(applyset): preserve prune scope on UID conflicts and requeue retry by @a-hilaly in #1081
fix: pass up expressive error by @fabianburth in #1078
fix(runtime): schema-aware CEL value conversion by @jakobmoellerdev in #1080
fix: show root cause error by @fabianburth in #1160
fix(dynamic): skip parent instance events with unchanged generation by @jakobmoellerdev in #1173
fix(metadata): skip instance-namespace label for cluster-scoped instances by @a-hilaly in #1175
fix(docs): correct RGD conditions by @a-hilaly in #1181
fix(collections): register collection watch for all expanded resources by @a-hilaly in #1182
fix(cel): handle oneOf string|number schemas in UnstructuredToVal by @a-hilaly in #1179
fix: return a requeue error when waiting for readiness by @fabianburth in #1090
fix: do not count requeue signals as handler errors in dynamic_controller_handler_errors_total by @Avr8 in #1059
fix(cel): sort transformList result before comparison in TwoVar test by @a-hilaly in #1141
fix: add instance state in progress case by @fabianburth in #1090
fix(graph/resolver): expose schema resolver metrics on controller-runtime registry by @a-hilaly in #1113
fix: ResourceGraphDefinition delete predicate handling by @a-hilaly in #1097
fix(externalref): allow external collections to list across all namespaces by @a-hilaly in #1180
fix: tighten cluster-scoped instance namespace validation by @a-hilaly in #1152
fix: handle cluster-scoped instances in reconciliation and SSA patches by @a-hilaly in #1152
fix(instance): surface graph resolution failures in conditions and metrics by @a-hilaly in #1201
fix: get rid of cel build caches due to problems during stabilization by @jakobmoellerdev in #1195
fix: missing dynamic controller registration, and wire up missing metrics by @jakobmoellerdev in #1146

⚡ Performan

…(truncated)

v0.8.5

Feb 9, 2026Compare GitHub

Highlight

Fixed context building to properly distinguish between "not yet observed" (nil) and "observed but empty" ([]) collections. This was causing instances with empty forEach results to get stuck in IN_PROGRESS forever - dependents couldn't evaluate CEL expressions like size(entries) because empty collections were being excluded from context entirely.
CEL programs are now compiled once at build time and reused across reconciles. Previously we were re-parsing, re-compiling, and throwing away the program on every single evaluation. The new runtime now holds both the original string and the compiled program, so runtime skips straight to evaluation.
Schema lookups now handle additionalProperties, which is how Kubernetes represents map types like ConfigMap.data. Without this, the CEL type checker couldn't validate writes to map fields and silently missed type mismatches.

🚀 Features

Compile CEL programs at build time and reuse at runtime by @a-hilaly in https://github.com/kubernetes-sigs/kro/pull/1014
fix: validate status schema by @michaelhtm in https://github.com/kubernetes-sigs/kro/pull/1023
feat(validation): block kro-owned labels in resource templates by @spattk in https://github.com/kubernetes-sigs/kro/pull/1016

🐛 Bug fixes

fix(runtime): handle empty forEach collections and their dependents by @a-hilaly in https://github.com/kubernetes-sigs/kro/pull/1018
Fix empty arrays being converted to null instead of [] by @a-hilaly in https://github.com/kubernetes-sigs/kro/pull/1026
fix(graph): handle additionalProperties in schema lookups by @a-hilaly in https://github.com/kubernetes-sigs/kro/pull/1019
fix(dynamiccontroller): fix ctx race condition by @a-hilaly in https://github.com/kubernetes-sigs/kro/pull/1015
Handle CRD deletion so RGDs don't get stuck in Active by @Aman-Cool in https://github.com/kubernetes-sigs/kro/pull/1029
fix(rt/resolver): remove dead code and fix path handling asymmetry by @a-hilaly in https://github.com/kubernetes-sigs/kro/pull/1004

🔧 Refactoring

refactor(simpleschema): rework type system for easier extension by @a-hilaly in https://github.com/kubernetes-sigs/kro/pull/998

🧹 Chores

chore(ci): add -race for all unit tests by @jakobmoellerdev in https://github.com/kubernetes-sigs/kro/pull/1021
add gcal meeting link to readme by @olamilekan000 in https://github.com/kubernetes-sigs/kro/pull/1013

New Contributors

@olamilekan000 made their first contribution in https://github.com/kubernetes-sigs/kro/pull/1013
@spattk made their first contribution in https://github.com/kubernetes-sigs/kro/pull/1016
@Aman-Cool made their first contribution in https://github.com/kubernetes-sigs/kro/pull/1029

Full Changelog: https://github.com/kubernetes-sigs/kro/compare/v0.8.4...v0.8.5

v0.8.4

Jan 30, 2026Compare GitHub

Highlight

Removed the managed-by label from kro instances and fixed integration test coverage to actually measure pkg/ code.

🧹 Chores

chore: remove managed-by label from kro instances by @shabbskagalwala in https://github.com/kubernetes-sigs/kro/pull/997
fix(test): measure pkg/ coverage in integration tests by @a-hilaly in https://github.com/kubernetes-sigs/kro/pull/996

Full Changelog: https://github.com/kubernetes-sigs/kro/compare/v0.8.3...v0.8.4

v0.8.3

Jan 30, 2026Compare GitHub

Highlight

Fixed a bug where finalizer and label patches were reverting each other when applied as separate operations. Combined into a single patch.

🐛 Bug fixes

fix: unify finalizer and label patches, add cascading deletion integration test by @jakobmoellerdev in https://github.com/kubernetes-sigs/kro/pull/1000

Full Changelog: https://github.com/kubernetes-sigs/kro/compare/v0.8.2...v0.8.3

v0.8.2

Jan 30, 2026Compare GitHub

Highlight

Fixed child resource events triggering reconciliation on the wrong instance controller, and fixed release builds getting tagged with a dirty suffix.

🐛 bug fixes

fix: filter child events by parent instance GVK by @shabbskagalwala in https://github.com/kubernetes-sigs/kro/pull/986

🌱 Other

update kro cli go.mod to use kro v0.8.1 by @michaelhtm in https://github.com/kubernetes-sigs/kro/pull/992
Fix cmd/kro by updating Kro dependency to v0.8.1 by @chrisdoherty4 in https://github.com/kubernetes-sigs/kro/pull/994
fix: remove GIT_VERSION suffix by @michaelhtm in https://github.com/kubernetes-sigs/kro/pull/991

New Contributors

@chrisdoherty4 made their first contribution in https://github.com/kubernetes-sigs/kro/pull/994

Full Changelog: https://github.com/kubernetes-sigs/kro/compare/v0.8.1...v0.8.2

v0.8.1

Jan 28, 2026Compare GitHub

Highlight

Fixed a schema defaulting edge case where generated CRDs could produce invalid OpenAPI when parent fields had required children with defaults.

🐛 Bug fixes

fix(transform): update parent default logic for schemas with required fields by @jakobmoellerdev in https://github.com/kubernetes-sigs/kro/pull/983

Full Changelog: https://github.com/kubernetes-sigs/kro/compare/v0.8.0...v0.8.1

v0.8.0

Jan 28, 2026GitHub

🔆 Highlights

Collections Support (KREP-002)

RGDs now support Collections: define one template and kro expands it into many resources at runtime. Collections introduce a new forEach directive that lets a CEL expression drive the iteration, and the controller keeps each generated resource in sync as items are added, changed, or removed. This makes multi‑resource expansion practical without hand‑authoring repeated blocks. (Docs, #936, #679)

Recursive Custom Types in RGD Schema

RGD schemas now allow custom types to reference other custom types, so you can build reusable, nested data structures instead of duplicating field definitions. This improves schema hygiene for complex specs and statuses while keeping validation intact. (Docs, #950)

Breaking Schema Change Detection

kro now diffs RGD schemas before updating CRDs and blocks incompatible changes (like removing fields, changing types, or adding required properties) by default. This prevents accidental breaking updates to existing instances; use the kro.run/allow-breaking-changes: "true" annotation to intentionally override. (Docs, #352)

✨ Features

feat: add Collections support + runtime/controller rewrite by @a-hilaly in #936
feat: KREP-002 declarative resource collections support by @a-hilaly in #679
feat(simpleschema): add support for recursive custom types by @shivansh-gohem in #950
feat(crd): Detect and prevent breaking schema changes in RGDs by @a-hilaly in #352
feat: add early validation for apiVersion and kind to fail fast by @antcybersec in #980
feat: add controller warmup support for faster leader failover by @a-hilaly in #955
feat: add DurationType and TimestampType conversion to go native types by @shabbskagalwala in #960
feat: add bytes conversion to go native types by @shabbskagalwala in #951
feat: add support for labels and annotations in the generated CRDs by @cnvergence in #916

🐛 Bugfixes

fix(graph): reject cluster-scoped resources with namespace set by @a-hilaly in #976
fix(schema): preserve nested array/object paths in status schema by @a-hilaly in #972
fix(schema): use date-time format for timestamps by @a-hilaly in #973
fix(dag): preserve vertex order when dependencies are satisfied by @a-hilaly in #958
fix: Convert CEL type to Go type recursively by @cirias in #940
fix: Support []object and map[string]object types in RGD schema by @kunalvirwal in #939
fix: Prevent random.* from being classified as a resource in #919
fix(release): capture GIT_VERSION once to prevent -dirty suffix in LDFLAGS by @a-hilaly in #982
fix(cluster-mgmt): ensure access to workload cluster is granted before argocd secret create by @iamahgoub in #966
fix(graph): replace panic in CRD graph builder with proper error handling by @AnshulPatil2005 in #901

⚡ Performance

chore: cache compiled CEL programs by @bschaatsbergen in #943

📖 Documentation

docs: expand collections gotchas and cross-references by @a-hilaly in #971
docs(cel): explain multiline expressions and YAML chomping by @a-hilaly in #974
fix(website): version CRD with docs snapshots by @a-hilaly in #978
Docs: manifests download URL changed to match actual URL by @hatofmonkeys in #925
fix: Fixed Quickstart instance.yaml sample on document by @ricky9408 in #913
docs: correct apiVersion for Application example by @birapjr in #899
fix: url in kubectl commands for upgrade and delete by @Fsero in #938

🧪 Testing

test: improve unit test coverage for pkg/graph/variable by @shivansh-gohem in #949

🌱 Other

refactor(instance): align node state tracking by @a-hilaly in #970
chore: bump controller-runtime to v0.23.0 and k8s deps to v0.35.0 by @a-hilaly in #956
chore: dependency bumps (go1.25.6, golangci-lint, helm, ko, chainsaw, and more) by @jakobmoellerdev in #963
chore: bump kro in kro command by @tjamet in #952
cleanup: use variadic append for enum values by @PhantomInTheWire in #910
Improve CRD cleanup skip log clarity by @skools-here in #923
Update AWS cluster management example to use EKS capabilities by @iamahgoub in #946
chore: regenerate CRDs to reflect new schema.metadata field by @a-hilaly in #977

New Contributors

@AnshulPatil2005 made their first contribution in https://github.com/kubernetes-sigs/kro/pull/901
@birapjr made their first contribution in https://github.com/kubernetes-sigs/kro/pull/899
@PhantomInTheWire made their first contribution in https://github.com/kubernetes-sigs/kro/pull/910
@ricky9408 made their first contribution in https://github.com/kubernetes-sigs/kro/pull/913
@benzaidfoued made their first contribution in https://github.com/kubernetes-sigs/kro/pull/919
@skools-here made their first contribution in https://github.com/kubernetes-sigs/kro/pull/923
@hatofmonkeys made their first contribution in https://github.com/kubernetes-sigs/kro/pull/925
@Fsero made their first contribution in https://github.com/kubernetes-sigs/kro/pull/938
@kunalvirwal made their first contribution in https://github.com/kubernetes-sigs/kro/pull/939
@cirias made their first contribution in https://github.com/kubernetes-sigs/kro/pull/940
@shabbskagalwala made their first contribution in https://github.com/kubernetes-sigs/kro/pull/951
@shivansh-gohem made their first contribution in https://github.com/kubernetes-sigs/kro/pull/949
@cnvergence made their first contribution in https://github.com/kubernetes-sigs/kro/pull/916

Full Changelog: https://github.com/kubernetes-sigs/kro/compare/v0.7.1...v0.8.0

kro | Kube Resource Orchestrator

Go Report Card GitHub go.mod Go version GitHub License GitHub Repo stars

Kube Resource Orchestrator (kro) is a subproject of Kubernetes SIG Cloud Provider. This project aims to simplify the creation and management of complex custom resources for Kubernetes.

Kro helps you to define complex multi-resource constructs as reusable components in your applications and systems. It does this by providing a Kubernetes-native, vendor agnostic way to define groupings of Kubernetes resources.

Kro's fundamental custom resource is the ResourceGraphDefinition. A ResourceGraphDefinition defines collections of underlying Kubernetes resources. It can define any Kubernetes resources, either native or custom, and can specify the dependencies between them. This lets you define complex custom resources, and include default configurations for their use.

The kro controller will determine the dependencies between resources, establish the correct order of operations to create and configure them, and then dynamically create and manage all of the underlying resources for you.

Kro is Kubernetes native and integrates seamlessly with existing tools to preserve familiar processes and interfaces.

Documentation

Title	Description
Introduction	An introduction to kro
Installation	Install kro in your cluster
Getting started	Deploy your first ResourceGraphDefinition
Concepts	Learn more about kro concepts
Examples	Example resources
Contributions	How to get involved

FAQ

What is kro?
Kube Resource Orchestrator (kro) is a new operator for Kubernetes that simplifies the creation of complex Kubernetes resource configurations. kro lets you create and manage custom groups of Kubernetes resources by defining them as a ResourceGraphDefinition, the project's fundamental custom resource. ResourceGraphDefinition specifications define a set of resources and how they relate to each other functionally. Once defined, ResourceGraphDefinitions can be applied to a Kubernetes cluster where the kro controller is running. Once validated by kro, you can create instances of your ResourceGraphDefinition. kro translates your ResourceGraphDefinition instance and its parameters into specific Kubernetes resources and configurations which it then manages for you.
How does kro work?
kro is designed to use core Kubernetes primitives to make resource grouping, customization, and dependency management simpler. When a ResourceGraphDefinition is applied to the cluster, the kro controller verifies its specification, then dynamically creates a new CRD and registers it with the API server. kro then deploys a dedicated controller to respond to instance events on the CRD. This microcontroller is responsible for managing the lifecycle of resources defined in the ResourceGraphDefinition for each instance that is created.
How do I use kro?
To create your custom resource groupings, you create ResourceGraphDefinition specifications. These specify one or more Kubernetes resources, and can include specific configurations for each resource.
For example, you can define a WebApp ResourceGraphDefinition that defines a WebAppCRD CRD that is composed of a Deployment, pre-configured to deploy your web server backend, and a Service configured to run on a specific port. You can just as easily create a more complex WebAppWithDB ResourceGraphDefinition by combining the existing WebApp ResourceGraphDefinition with a Table custom resource to provision a cloud managed database instance for your web app to use.
Once you have defined a ResourceGraphDefinition, you can apply it to a Kubernetes cluster where the kro controller is running. kro will take care of the heavy lifting of creating CRDs and deploying dedicated controllers in order to manage instances of your new custom resource group.
To create an instance of your custom resource groupings, you create an instance of the CRD that your ResourceGraphDefinition specifies. In the WebApp ResourceGraphDefinition example, this would be an instance of the WebAppCRD CRD. kro will respond by dynamically creating, configuring, and managing the underlying Kubernetes resources for you.
Why did you build this project?
We want to help streamline and simplify building with Kubernetes. Building with Kubernetes means dealing with resources that need to operate and work together, and orchestrating this can get complex and difficult at scale. With this project, we're taking a step in reducing the complexity of resource dependency management and customization, paving the way for a simple and scalable way to create complex custom resources for Kubernetes.
What should I know about API changes?
kro's API is currently at v1alpha1. As kro evolves, we may introduce breaking changes to improve the API. We are committed to providing clear migration paths, deprecation notices, and comprehensive support to help users adapt to any breaking changes. Our goal is to ensure smooth transitions as the project continues to improve.

Community Participation

Development and discussion is coordinated in the Kubernetes Slack (invite link) channel #kro channel.

Please join our community meeting.

Every other Wednesday at 9AM PT (Pacific Time). Convert to local timezone
Add to Google Calendar
Agenda: Public doc
Join us: Zoom meeting
Community meeting recordings: YouTube channel

Code of conduct

Participation in the project community is governed by the Kubernetes Code of Conduct.

Security

See CONTRIBUTING and SECURITY for information.

License

Apache 2.0

View the full README on GitHub

Release history

v0.9.4

v0.9.3

v0.9.2

v0.9.1

v0.9.0

v0.8.5

v0.8.4

v0.8.3

v0.8.2

v0.8.1

v0.8.0

README

kro | Kube Resource Orchestrator

Documentation

FAQ

Community Participation

Code of conduct

Security

License