ResourceGraphDefinition

The ResourceGraphDefinition (RGD) is kro's core API for defining custom Kubernetes resources that orchestrate multiple underlying resources.

---

API Specification

API Version

kro.run/v1alpha1

Kind

ResourceGraphDefinition

Scope

Cluster

---

Fields Reference

Spec

Field	Type	Description
resources	[]object	Resources is the list of Kubernetes resources that will be created and managed for each instance. Resources can reference each other using CEL expressions, creating a dependency graph that determines creation order.
externalRef	object	ExternalRef references an existing resource in the cluster instead of creating one. This is useful for reading existing resources and using their values in other resources. Exactly one of template or externalRef must be provided.
idrequired	string	ID is a unique identifier for this resource within the ResourceGraphDefinition. It is used to reference this resource in CEL expressions from other resources. Example: "deployment", "service", "configmap".
includeWhen	[]string	IncludeWhen is a list of CEL expressions that determine whether this resource should be created. All expressions must evaluate to true for the resource to be included. If not specified, the resource is always included. Example: ["schema.spec.enableMonitoring == true"]
readyWhen	[]string	ReadyWhen is a list of CEL expressions that determine when this resource is considered ready. All expressions must evaluate to true for the resource to be ready. If not specified, the resource is considered ready when it exists. Example: ["self.status.phase == 'Running'", "self.status.readyReplicas > 0"]
template	object	Template is the Kubernetes resource manifest to create. It can contain CEL expressions (using ${...} syntax) that reference other resources. Exactly one of template or externalRef must be provided.
schemarequired	object	Schema defines the structure of instances created from this ResourceGraphDefinition. It specifies the API version, kind, and fields (spec/status) for the generated CRD. Use SimpleSchema syntax to define the instance schema concisely.
additionalPrinterColumns	[]object	AdditionalPrinterColumns defines additional printer columns that will be passed down to the created CRD. If set, no default printer columns will be added to the created CRD, and if default printer columns need to be retained, they need to be added explicitly.
apiVersionrequiredimmutable	string	APIVersion is the version identifier for the generated CRD. Must follow Kubernetes versioning conventions (v1, v1alpha1, v1beta1, etc.). This field is immutable after creation. Example: "v1alpha1", "v1", "v2beta1"
groupimmutable	string	Group is the API group for the generated CRD. Together with APIVersion and Kind, it forms the complete GVK (Group-Version-Kind) identifier. If omitted, defaults to "kro.run". This field is immutable after creation. Example: "mycompany.io", "databases.example.com"
kindrequiredimmutable	string	Kind is the name of the custom resource type that will be created. This becomes the kind field of the generated CRD and must be a valid Kubernetes kind name (PascalCase, starting with a capital letter). This field is immutable after creation. Example: "WebApplication", "Database", "MicroService"
spec	object	Spec defines the schema for the instance's spec section using SimpleSchema syntax. This becomes the OpenAPI schema for instances of the generated CRD. Use SimpleSchema's concise syntax to define fields, types, defaults, and validations. Example: {"replicas": "integer | default=1 | min=1 | max=10"}
status	object	Status defines the schema for the instance's status section using SimpleSchema syntax. Unlike spec, status fields use CEL expressions to project values from underlying resources. This allows you to surface important information from managed resources at the instance level. Example: {"connectionName": "${database.status.connectionName}", "endpoint": "${service.status.loadBalancer.ingress[0].hostname}"}
types	object	Types is a map of custom type definitions that can be referenced in the Spec. This allows you to define reusable complex types using SimpleSchema syntax. Reference custom types in Spec using the type name. Example: {"Server": {"host": "string", "port": "integer"}}

Status

Field	Type	Description
conditions	[]object	Conditions represent the latest available observations of the ResourceGraphDefinition's state. Common condition types include "Ready", "Validated", and "ReconcilerDeployed".
lastTransitionTime	string	Last time the condition transitioned from one status to another.
message	string	A human-readable message indicating details about the transition.
observedGeneration	integer	observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.
reason	string	The reason for the condition's last transition.
statusrequired	string	Status of the condition, one of True, False, Unknown.
typerequired	string	Type is the type of the Condition
resources	[]object	Resources provides detailed information about each resource in the graph, including their dependencies.
dependencies	[]object	Dependencies lists all resources that this resource depends on. A resource depends on another if it references it in a CEL expression. These dependencies determine the order of resource creation.
id	string	ID is the unique identifier of the resource as defined in the resources list.
state	string	State indicates whether the ResourceGraphDefinition is Active or Inactive. Active means the CRD has been created and the controller is running. Inactive means the ResourceGraphDefinition has been disabled or encountered an error.
topologicalOrder	[]string	TopologicalOrder is the ordered list of resource IDs based on their dependencies. Resources are created in this order to ensure dependencies are satisfied. Example: ["configmap", "deployment", "service"]