Allow cluster-scoped instance CRDs via schema scope

README.md

@@ -27,6 +27,16 @@ Kro is Kubernetes native and integrates seamlessly with existing tools to preser
 | [Examples][kro-examples]               | Example resources               |
 | [Contributions](./CONTRIBUTING.md)       | How to get involved             |
 
+[kro-instance-scope]: https://kro.run/docs/concepts/resource-group-definitions
+
+### Instance scope (new)
+
+ResourceGraphDefinitions can now choose the scope of the generated instance CRD via `spec.schema.scope`:
+- `Namespaced` (default) — preserves current behavior.
+- `Cluster` — generates a cluster-scoped instance CRD when your graph needs to be cluster-level.
+
+The field is immutable after creation, matching Kubernetes CRD scope rules. See the concepts docs for details.
+
 [kro-overview]: https://kro.run/docs/overview
 [kro-installation]: https://kro.run/docs/getting-started/Installation
 [kro-getting-started]: https://kro.run/docs/getting-started/deploy-a-resource-graph-definition

api/v1alpha1/resourcegraphdefinition_types.go

@@ -69,6 +69,14 @@ type Schema struct {
 	// +kubebuilder:default="kro.run"
 	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="group is immutable"
 	Group string `json:"group,omitempty"`
+	// Scope determines whether the generated instance CRD is Namespaced or Cluster scoped.
+	// Default is Namespaced to preserve current behavior. This field is immutable.
+	//
+	// +kubebuilder:validation:Optional
+	// +kubebuilder:default="Namespaced"
+	// +kubebuilder:validation:Enum=Namespaced;Cluster
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="scope is immutable"
+	Scope ResourceScope `json:"scope,omitempty"`
 	// 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.
@@ -219,6 +227,14 @@ type Dependency struct {
 	ID string `json:"id,omitempty"`
 }
 
+// ResourceScope defines the scope of the generated instance CRD.
+type ResourceScope string
+
+const (
+	ScopeNamespaced ResourceScope = "Namespaced"
+	ScopeCluster    ResourceScope = "Cluster"
+)
+
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 // +kubebuilder:printcolumn:name="APIVERSION",type=string,priority=0,JSONPath=`.spec.schema.apiVersion`

pkg/controller/instance/controller_reconcile.go

@@ -516,10 +516,14 @@ func (igr *instanceGraphReconciler) setManaged(
 
 	igr.instanceLabeler.ApplyLabels(instancePatch)
 
-	updated, err := igr.client.Resource(igr.gvr).
-		Namespace(obj.GetNamespace()).
-		Apply(ctx, instancePatch.GetName(), instancePatch,
-			metav1.ApplyOptions{FieldManager: FieldManagerForLabeler, Force: true})
+	instanceClient := igr.client.Resource(igr.gvr)
+	var namespacedClient dynamic.ResourceInterface = instanceClient
+	if ns := obj.GetNamespace(); ns != "" {
+		namespacedClient = instanceClient.Namespace(ns)
+	}
+
+	updated, err := namespacedClient.Apply(ctx, instancePatch.GetName(), instancePatch,
+		metav1.ApplyOptions{FieldManager: FieldManagerForLabeler, Force: true})
 	if err != nil {
 		return nil, fmt.Errorf("failed to update managed state: %w", err)
 	}
@@ -552,10 +556,14 @@ func (igr *instanceGraphReconciler) setUnmanaged(
 		return nil, fmt.Errorf("failed to remove finalizer: %w", err)
 	}
 
-	updated, err := igr.client.Resource(igr.gvr).
-		Namespace(obj.GetNamespace()).
-		Apply(ctx, instancePatch.GetName(), instancePatch,
-			metav1.ApplyOptions{FieldManager: FieldManagerForLabeler, Force: true})
+	instanceClient := igr.client.Resource(igr.gvr)
+	var namespacedClient dynamic.ResourceInterface = instanceClient
+	if ns := obj.GetNamespace(); ns != "" {
+		namespacedClient = instanceClient.Namespace(ns)
+	}
+
+	updated, err := namespacedClient.Apply(ctx, instancePatch.GetName(), instancePatch,
+		metav1.ApplyOptions{FieldManager: FieldManagerForLabeler, Force: true})
 	if err != nil {
 		return nil, fmt.Errorf("failed to update unmanaged state: %w", err)
 	}

pkg/graph/builder.go

@@ -467,6 +467,11 @@ func (b *Builder) buildInstanceResource(
 	rgDefinition *v1alpha1.Schema,
 	resources map[string]*Resource,
 ) (*Resource, error) {
+	scope := extv1.NamespaceScoped
+	if rgDefinition.Scope == v1alpha1.ScopeCluster {
+		scope = extv1.ClusterScoped
+	}
+
 	// The instance resource is the resource users will create in their cluster,
 	// to request the creation of the resources defined in the resource graph definition.
 	//
@@ -491,7 +496,7 @@ func (b *Builder) buildInstanceResource(
 
 	// Synthesize the CRD for the instance resource.
 	overrideStatusFields := true
-	instanceCRD := crd.SynthesizeCRD(group, apiVersion, kind, *instanceSpecSchema, *instanceStatusSchema, overrideStatusFields, rgDefinition.AdditionalPrinterColumns)
+	instanceCRD := crd.SynthesizeCRD(group, apiVersion, kind, scope, *instanceSpecSchema, *instanceStatusSchema, overrideStatusFields, rgDefinition.AdditionalPrinterColumns)
 
 	instanceSchemaExt := instanceCRD.Spec.Versions[0].Schema.OpenAPIV3Schema
 	instanceSchema, err := schema.ConvertJSONSchemaPropsToSpecSchema(instanceSchemaExt)

pkg/graph/crd/crd.go

@@ -25,11 +25,11 @@ import (
 
 // SynthesizeCRD generates a CustomResourceDefinition for a given API version and kind
 // with the provided spec and status schemas~
-func SynthesizeCRD(group, apiVersion, kind string, spec, status extv1.JSONSchemaProps, statusFieldsOverride bool, additionalPrinterColumns []extv1.CustomResourceColumnDefinition) *extv1.CustomResourceDefinition {
-	return newCRD(group, apiVersion, kind, newCRDSchema(spec, status, statusFieldsOverride), additionalPrinterColumns)
+func SynthesizeCRD(group, apiVersion, kind string, scope extv1.ResourceScope, spec, status extv1.JSONSchemaProps, statusFieldsOverride bool, additionalPrinterColumns []extv1.CustomResourceColumnDefinition) *extv1.CustomResourceDefinition {
+	return newCRD(group, apiVersion, kind, scope, newCRDSchema(spec, status, statusFieldsOverride), additionalPrinterColumns)
 }
 
-func newCRD(group, apiVersion, kind string, schema *extv1.JSONSchemaProps, additionalPrinterColumns []extv1.CustomResourceColumnDefinition) *extv1.CustomResourceDefinition {
+func newCRD(group, apiVersion, kind string, scope extv1.ResourceScope, schema *extv1.JSONSchemaProps, additionalPrinterColumns []extv1.CustomResourceColumnDefinition) *extv1.CustomResourceDefinition {
 	pluralKind := flect.Pluralize(strings.ToLower(kind))
 	return &extv1.CustomResourceDefinition{
 		ObjectMeta: metav1.ObjectMeta{
@@ -44,7 +44,7 @@ func newCRD(group, apiVersion, kind string, schema *extv1.JSONSchemaProps, addit
 				Plural:   pluralKind,
 				Singular: strings.ToLower(kind),
 			},
-			Scope: extv1.NamespaceScoped,
+			Scope: scope,
 			Versions: []extv1.CustomResourceDefinitionVersion{
 				{
 					Name:    apiVersion,

pkg/graph/crd/crd_test.go

@@ -33,6 +33,7 @@ func TestSynthesizeCRD(t *testing.T) {
 		statusFieldsOverride bool
 		expectedName         string
 		expectedGroup        string
+		scope                extv1.ResourceScope
 	}{
 		{
 			name:                 "standard group and kind",
@@ -44,6 +45,7 @@ func TestSynthesizeCRD(t *testing.T) {
 			statusFieldsOverride: true,
 			expectedName:         "widgets.kro.com",
 			expectedGroup:        "kro.com",
+			scope:                extv1.NamespaceScoped,
 		},
 		{
 			name:                 "mixes case kind",
@@ -55,17 +57,19 @@ func TestSynthesizeCRD(t *testing.T) {
 			statusFieldsOverride: true,
 			expectedName:         "databases.kro.com",
 			expectedGroup:        "kro.com",
+			scope:                extv1.ClusterScoped,
 		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			crd := SynthesizeCRD(tt.group, tt.apiVersion, tt.kind, tt.spec, tt.status, tt.statusFieldsOverride, nil)
+			crd := SynthesizeCRD(tt.group, tt.apiVersion, tt.kind, tt.scope, tt.spec, tt.status, tt.statusFieldsOverride, nil)
 
 			assert.Equal(t, tt.expectedName, crd.Name)
 			assert.Equal(t, tt.expectedGroup, crd.Spec.Group)
 			assert.Equal(t, tt.kind, crd.Spec.Names.Kind)
 			assert.Equal(t, tt.kind+"List", crd.Spec.Names.ListKind)
+			assert.Equal(t, tt.scope, crd.Spec.Scope)
 
 			require.Len(t, crd.Spec.Versions, 1)
 			version := crd.Spec.Versions[0]
@@ -96,6 +100,7 @@ func TestNewCRD(t *testing.T) {
 		expectedPlural         string
 		expectedSingular       string
 		expectedPrinterColumns []extv1.CustomResourceColumnDefinition
+		scope                  extv1.ResourceScope
 	}{
 		{
 			name:                   "basic example",
@@ -107,6 +112,7 @@ func TestNewCRD(t *testing.T) {
 			expectedPlural:         "tests",
 			expectedSingular:       "test",
 			expectedPrinterColumns: defaultAdditionalPrinterColumns,
+			scope:                  extv1.NamespaceScoped,
 		},
 		{
 			name:                   "uppercase kind",
@@ -118,6 +124,7 @@ func TestNewCRD(t *testing.T) {
 			expectedPlural:         "configs",
 			expectedSingular:       "config",
 			expectedPrinterColumns: defaultAdditionalPrinterColumns,
+			scope:                  extv1.NamespaceScoped,
 		},
 		{
 			name:                   "mixed case kind",
@@ -129,6 +136,7 @@ func TestNewCRD(t *testing.T) {
 			expectedPlural:         "webhooks",
 			expectedSingular:       "webhook",
 			expectedPrinterColumns: defaultAdditionalPrinterColumns,
+			scope:                  extv1.NamespaceScoped,
 		},
 		{
 			name:                   "non nil empty printer columns",
@@ -141,6 +149,7 @@ func TestNewCRD(t *testing.T) {
 			expectedPlural:         "webhooks",
 			expectedSingular:       "webhook",
 			expectedPrinterColumns: defaultAdditionalPrinterColumns,
+			scope:                  extv1.NamespaceScoped,
 		},
 		{
 			name:       "custom printer columns",
@@ -175,13 +184,14 @@ func TestNewCRD(t *testing.T) {
 					JSONPath: ".spec.image",
 				},
 			},
+			scope: extv1.ClusterScoped,
 		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			schema := &extv1.JSONSchemaProps{Type: "object"}
-			crd := newCRD(tt.group, tt.apiVersion, tt.kind, schema, tt.printerColumns)
+			crd := newCRD(tt.group, tt.apiVersion, tt.kind, tt.scope, schema, tt.printerColumns)
 
 			assert.Equal(t, tt.expectedName, crd.Name)
 			assert.Equal(t, tt.group, crd.Spec.Group)
@@ -190,7 +200,7 @@ func TestNewCRD(t *testing.T) {
 			assert.Equal(t, tt.expectedPlural, crd.Spec.Names.Plural)
 			assert.Equal(t, tt.expectedSingular, crd.Spec.Names.Singular)
 
-			assert.Equal(t, extv1.NamespaceScoped, crd.Spec.Scope)
+			assert.Equal(t, tt.scope, crd.Spec.Scope)
 
 			require.Len(t, crd.Spec.Versions, 1)
 			assert.Equal(t, tt.apiVersion, crd.Spec.Versions[0].Name)