Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

crd explicit instance name field support (#1799)

ming0ba97b1f16ef
diff --git a/kubernetes/operator/api/v1alpha1/openrag_types.go b/kubernetes/operator/api/v1alpha1/openrag_types.go
index c9c538c8a..6ec4495b2 100644
--- a/kubernetes/operator/api/v1alpha1/openrag_types.go
+++ b/kubernetes/operator/api/v1alpha1/openrag_types.go
@@ -674,16 +674,17 @@ type NetworkPolicySpec struct {
// OpenRAGSpec defines the desired state of an OpenRAG instance.
type OpenRAGSpec struct {
- // MultiInstance enables per-CR resource naming (openrag-<crName>-<role>) so that
- // multiple OpenRAG CRs can coexist in the same namespace. When false (default),
- // resources use the legacy static names (openrag-fe, openrag-be, openrag-lf),
- // which preserves backwards compatibility for existing deployments.
- // Changing this field after initial deployment will rename all managed resources,
- // which will break any external references (IngressRoutes, DNS, etc.).
- // +optional
- // +kubebuilder:default=false
- // +kubebuilder:validation:XValidation:rule="self == oldSelf",message="multiInstance is immutable after creation"
- MultiInstance bool `json:"multiInstance,omitempty"`
+ // InstanceName is a short unique identifier embedded in all resource names, enabling
+ // multiple OpenRAG CRs to coexist in the same namespace (e.g. "prod", "staging").
+ // Must start with a lowercase letter and contain only lowercase letters, digits, and
+ // hyphens, with a maximum of 8 characters. When empty (default), resources use legacy
+ // static names (openrag-fe, openrag-be, openrag-lf) for backwards compatibility.
+ // This field is immutable after creation.
+ // +optional
+ // +kubebuilder:validation:MaxLength=8
+ // +kubebuilder:validation:Pattern=`^[a-z][a-z0-9-]*$`
+ // +kubebuilder:validation:XValidation:rule="self == oldSelf",message="instanceName is immutable after creation"
+ InstanceName string `json:"instanceName,omitempty"`
// TargetNamespace is the namespace where all OpenRAG resources are created.
// Defaults to the namespace of the CR itself. Cannot be "default".
diff --git a/kubernetes/operator/config/crd/bases/openr.ag_openrags.yaml b/kubernetes/operator/config/crd/bases/openr.ag_openrags.yaml
index cbe02bfa7..9e8cadc8e 100644
--- a/kubernetes/operator/config/crd/bases/openr.ag_openrags.yaml
+++ b/kubernetes/operator/config/crd/bases/openr.ag_openrags.yaml
@@ -11609,6 +11609,20 @@ spec:
x-kubernetes-validations:
- message: imagePullSecret name cannot be empty
rule: self.all(x, x.name != '')
+ instanceName:
+ description: |-
+ InstanceName is a short unique identifier embedded in all resource names, enabling
+ multiple OpenRAG CRs to coexist in the same namespace (e.g. "prod", "staging").
+ Must start with a lowercase letter and contain only lowercase letters, digits, and
+ hyphens, with a maximum of 8 characters. When empty (default), resources use legacy
+ static names (openrag-fe, openrag-be, openrag-lf) for backwards compatibility.
+ This field is immutable after creation.
+ maxLength: 8
+ pattern: ^[a-z][a-z0-9-]*$
+ type: string
+ x-kubernetes-validations:
+ - message: instanceName is immutable after creation
+ rule: self == oldSelf
langflow:
description: Langflow configures the Langflow workflow engine.
properties:
@@ -13635,19 +13649,6 @@ spec:
provider:
type: string
type: object
- multiInstance:
- default: false
- description: |-
- MultiInstance enables per-CR resource naming (openrag-<crName>-<role>) so that
- multiple OpenRAG CRs can coexist in the same namespace. When false (default),
- resources use the legacy static names (openrag-fe, openrag-be, openrag-lf),
- which preserves backwards compatibility for existing deployments.
- Changing this field after initial deployment will rename all managed resources,
- which will break any external references (IngressRoutes, DNS, etc.).
- type: boolean
- x-kubernetes-validations:
- - message: multiInstance is immutable after creation
- rule: self == oldSelf
networkPolicy:
description: NetworkPolicy controls creation of a NetworkPolicy for
the Langflow pod.
diff --git a/kubernetes/operator/internal/controller/openrag_controller.go b/kubernetes/operator/internal/controller/openrag_controller.go
index c52404ba8..c7d56894d 100644
--- a/kubernetes/operator/internal/controller/openrag_controller.go
+++ b/kubernetes/operator/internal/controller/openrag_controller.go
@@ -98,10 +98,6 @@ func (r *OpenRAGReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ct
return ctrl.Result{}, r.handleDeletion(ctx, instance)
}
- if instance.Spec.MultiInstance && len(instance.Name) > 38 {
- return ctrl.Result{}, fmt.Errorf("CR name %q exceeds maximum length of 38 characters (%d) required for multiInstance mode", instance.Name, len(instance.Name))
- }
-
targetNS := targetNamespace(instance)
logger.Info("target namespace determined", "targetNS", targetNS, "crNamespace", instance.Namespace)
@@ -2250,27 +2246,26 @@ func targetNamespace(o *openragv1alpha1.OpenRAG) string {
return o.Namespace
}
-// instanceResourceName returns the resource name for a role, respecting MultiInstance.
-// When MultiInstance is false (default), legacy static names are used for backwards
-// compatibility. When true, the CR name is embedded to allow multiple CRs per namespace.
+// instanceResourceName returns the resource name for a role, respecting InstanceName.
+// When InstanceName is empty (default), legacy static names are used for backwards
+// compatibility. When set, the InstanceName is embedded to allow multiple CRs per namespace.
func instanceResourceName(o *openragv1alpha1.OpenRAG, role string) string {
- if o.Spec.MultiInstance {
- return resourceName(o.Name, role)
+ if o.Spec.InstanceName != "" {
+ return resourceName(o.Spec.InstanceName, role)
}
return legacyResourceName(role)
}
-// instanceSAName returns the ServiceAccount name for a role, respecting MultiInstance.
+// instanceSAName returns the ServiceAccount name for a role, respecting InstanceName.
func instanceSAName(o *openragv1alpha1.OpenRAG, role string) string {
- if o.Spec.MultiInstance {
- return saName(o.Name, role)
+ if o.Spec.InstanceName != "" {
+ return saName(o.Spec.InstanceName, role)
}
return legacySAName(role)
}
-// resourceName generates a per-CR resource name with the openrag- prefix for DNS-1035
-// compliance (required when crName is a UUID starting with a digit).
-// Max length with a 38-char crName: "openrag-"(8) + 38 + "-valkey-headless"(16) = 62 chars.
+// resourceName generates a per-CR resource name with the openrag- prefix.
+// Max length with an 8-char instanceName: "openrag-"(8) + 8 + "-valkey-headless"(16) = 32 chars.
func resourceName(crName, role string) string {
switch role {
case "ds":
diff --git a/kubernetes/operator/internal/controller/openrag_controller_test.go b/kubernetes/operator/internal/controller/openrag_controller_test.go
index 0652cbfe5..baee42f92 100644
--- a/kubernetes/operator/internal/controller/openrag_controller_test.go
+++ b/kubernetes/operator/internal/controller/openrag_controller_test.go
@@ -754,50 +754,25 @@ func TestReconcile_AllThreeComponentsSupportBothLevels(t *testing.T) {
// TestReconcile_UUIDNameDNS1035Compliance verifies that resource names are DNS-1035
// compliant even when the CR name is a UUID starting with a digit.
// The openrag- prefix ensures names always start with a letter.
-func TestReconcile_UUIDNameDNS1035Compliance(t *testing.T) {
+func TestReconcile_InstanceName_UsedInResourceNames(t *testing.T) {
s := newScheme(t)
- uuidName := "9a826efa-112d-4e2d-9f8d-ce103880ab41"
- cr := minimalCR(uuidName, "test-ns")
- cr.Spec.MultiInstance = true
+ cr := minimalCR("9a826efa-112d-4e2d-9f8d-ce103880ab41", "test-ns")
+ cr.Spec.InstanceName = "prod"
r, c := reconciler(s, cr)
reconcileOnce(t, r, cr)
dns1035Regex := `^[a-z]([-a-z0-9]*[a-z0-9])?$`
- feDeploy := &appsv1.Deployment{}
- feName := instanceResourceName(cr, "fe")
- require.NoError(t, c.Get(context.Background(),
- types.NamespacedName{Name: feName, Namespace: "test-ns"}, feDeploy))
- assert.Regexp(t, dns1035Regex, feName, "Frontend deployment name must be DNS-1035 compliant")
- assert.Regexp(t, dns1035Regex, feDeploy.Name, "Frontend deployment name must be DNS-1035 compliant")
-
- feSvc := &corev1.Service{}
- require.NoError(t, c.Get(context.Background(),
- types.NamespacedName{Name: feName, Namespace: "test-ns"}, feSvc))
- assert.Regexp(t, dns1035Regex, feSvc.Name, "Frontend service name must be DNS-1035 compliant")
-
- beDeploy := &appsv1.Deployment{}
- beName := instanceResourceName(cr, "be")
- require.NoError(t, c.Get(context.Background(),
- types.NamespacedName{Name: beName, Namespace: "test-ns"}, beDeploy))
- assert.Regexp(t, dns1035Regex, beName, "Backend deployment name must be DNS-1035 compliant")
+ for _, role := range []string{"fe", "be", "lf"} {
+ name := instanceResourceName(cr, role)
+ assert.Equal(t, "openrag-prod-"+role, name)
+ assert.Regexp(t, dns1035Regex, name, "resource name for role %s must be DNS-1035 compliant", role)
- lfDeploy := &appsv1.Deployment{}
- lfName := instanceResourceName(cr, "lf")
- require.NoError(t, c.Get(context.Background(),
- types.NamespacedName{Name: lfName, Namespace: "test-ns"}, lfDeploy))
- assert.Regexp(t, dns1035Regex, lfName, "Langflow deployment name must be DNS-1035 compliant")
-
- // Verify names follow the openrag-<crName>-<role> pattern
- assert.Equal(t, "openrag-"+uuidName+"-fe", feName)
- assert.Equal(t, "openrag-"+uuidName+"-be", beName)
- assert.Equal(t, "openrag-"+uuidName+"-lf", lfName)
-
- // CR name is tracked in labels
- assert.Equal(t, uuidName, feDeploy.Labels["app.kubernetes.io/instance"])
- assert.Equal(t, uuidName, beDeploy.Labels["app.kubernetes.io/instance"])
- assert.Equal(t, uuidName, lfDeploy.Labels["app.kubernetes.io/instance"])
+ d := &appsv1.Deployment{}
+ require.NoError(t, c.Get(context.Background(),
+ types.NamespacedName{Name: name, Namespace: "test-ns"}, d))
+ }
}
// ---------------------------------------------------------------------------