OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
feat: secret protection (#1569)
ming1bec64fae1a9
diff --git a/kubernetes/operator/api/v1alpha1/openrag_types.go b/kubernetes/operator/api/v1alpha1/openrag_types.goindex 13f636c99..fa2ab6362 100644--- a/kubernetes/operator/api/v1alpha1/openrag_types.go+++ b/kubernetes/operator/api/v1alpha1/openrag_types.go@@ -140,11 +140,16 @@ type BackendSpec struct {ComponentSpec `json:",inline"`// JWTSigningKeySecret references the Secret key that holds the JWT signing key.+ // If omitted, the operator auto-generates a stable key in the .env file.+ // WARNING: Do not change or delete after initial deployment - will break existing JWT tokens.+ // BEST PRACTICE: Create the referenced secret with immutable: true to prevent accidental modification.// +optionalJWTSigningKeySecret *corev1.SecretKeySelector `json:"jwtSigningKeySecret,omitempty"`// EncryptionKeySecret references the Secret key for OPENRAG_ENCRYPTION_KEY.- // If omitted the operator auto-generates a stable key.+ // If omitted, the operator auto-generates a stable key in the .env file.+ // WARNING: Do not change or delete after initial deployment - will make encrypted data unreadable.+ // BEST PRACTICE: Create the referenced secret with immutable: true to prevent accidental modification.// +optionalEncryptionKeySecret *corev1.SecretKeySelector `json:"encryptionKeySecret,omitempty"`@@ -170,8 +175,9 @@ type LangflowSpec struct {ComponentSpec `json:",inline"`// SecretKeySecret references the Secret key for LANGFLOW_SECRET_KEY,- // shared between backend and Langflow. If omitted the operator auto-generates- // a stable key stored in <cr-name>-openrag-gen-creds.+ // shared between backend and Langflow. If omitted, the operator auto-generates a stable key in the .env file.+ // WARNING: Do not change or delete after initial deployment - will break Langflow sessions and authentication.+ // BEST PRACTICE: Create the referenced secret with immutable: true to prevent accidental modification.// +optionalSecretKeySecret *corev1.SecretKeySelector `json:"secretKeySecret,omitempty"`diff --git a/kubernetes/operator/config/crd/bases/openr.ag_openrags.yaml b/kubernetes/operator/config/crd/bases/openr.ag_openrags.yamlindex 23015c281..d53d6a861 100644--- a/kubernetes/operator/config/crd/bases/openr.ag_openrags.yaml+++ b/kubernetes/operator/config/crd/bases/openr.ag_openrags.yaml@@ -1005,7 +1005,9 @@ spec:encryptionKeySecret:description: |-EncryptionKeySecret references the Secret key for OPENRAG_ENCRYPTION_KEY.- If omitted the operator auto-generates a stable key.+ If omitted, the operator auto-generates a stable key in the .env file.+ WARNING: Do not change or delete after initial deployment - will make encrypted data unreadable.+ BEST PRACTICE: Create the referenced secret with immutable: true to prevent accidental modification.properties:key:description: The key of the secret to select from. Must be@@ -1185,8 +1187,11 @@ spec:- message: imagePullSecret name cannot be emptyrule: self.all(x, x.name != '')jwtSigningKeySecret:- description: JWTSigningKeySecret references the Secret key that- holds the JWT signing key.+ description: |-+ JWTSigningKeySecret references the Secret key that holds the JWT signing key.+ If omitted, the operator auto-generates a stable key in the .env file.+ WARNING: Do not change or delete after initial deployment - will break existing JWT tokens.+ BEST PRACTICE: Create the referenced secret with immutable: true to prevent accidental modification.properties:key:description: The key of the secret to select from. Must be@@ -3966,8 +3971,9 @@ spec:secretKeySecret:description: |-SecretKeySecret references the Secret key for LANGFLOW_SECRET_KEY,- shared between backend and Langflow. If omitted the operator auto-generates- a stable key stored in <cr-name>-openrag-gen-creds.+ shared between backend and Langflow. If omitted, the operator auto-generates a stable key in the .env file.+ WARNING: Do not change or delete after initial deployment - will break Langflow sessions and authentication.+ BEST PRACTICE: Create the referenced secret with immutable: true to prevent accidental modification.properties:key:description: The key of the secret to select from. Must bediff --git a/kubernetes/operator/internal/controller/openrag_controller.go b/kubernetes/operator/internal/controller/openrag_controller.goindex 2f5b29fbd..fd16cfffd 100644--- a/kubernetes/operator/internal/controller/openrag_controller.go+++ b/kubernetes/operator/internal/controller/openrag_controller.go@@ -7,6 +7,7 @@ import ("encoding/json""fmt""strings"+ "time"appsv1 "k8s.io/api/apps/v1"corev1 "k8s.io/api/core/v1"@@ -25,8 +26,11 @@ import ()const (- finalizer = "openr.ag/namespace-cleanup"- specHashAnnotation = "openr.ag/spec-hash"+ finalizer = "openr.ag/namespace-cleanup"+ envSecretFinalizer = "openr.ag/env-secret-protection"+ userSecretFinalizer = "openr.ag/user-secret-protection"+ specHashAnnotation = "openr.ag/spec-hash"+ immutableAnnotation = "openr.ag/immutable")// OpenRAGReconciler reconciles an OpenRAG object.@@ -121,6 +125,63 @@ func (r *OpenRAGReconciler) handleDeletion(ctx context.Context, o *openragv1alph}targetNS := targetNamespace(o)++ // Remove finalizers from .env secrets so they can be deleted+ for _, envSecretName := range []string{resourceName("be-env"), resourceName("lf-env")} {+ envSecret := &corev1.Secret{}+ err := r.Get(ctx, client.ObjectKey{Name: envSecretName, Namespace: targetNS}, envSecret)+ if err == nil {+ if controllerutil.ContainsFinalizer(envSecret, envSecretFinalizer) {+ controllerutil.RemoveFinalizer(envSecret, envSecretFinalizer)+ if err := r.Update(ctx, envSecret); err != nil {+ return fmt.Errorf("failed to remove finalizer from env secret %s: %w", envSecretName, err)+ }+ }+ } else if !errors.IsNotFound(err) {+ return fmt.Errorf("failed to get env secret %s: %w", envSecretName, err)+ }+ }++ // Remove finalizers from user-provided secrets so they can be deleted+ userSecretRefs := collectProtectedSecrets(o)+ for _, secretRef := range userSecretRefs {+ userSecret := &corev1.Secret{}+ err := r.Get(ctx, client.ObjectKey{Name: secretRef.Name, Namespace: targetNS}, userSecret)+ if err == nil {+ if controllerutil.ContainsFinalizer(userSecret, userSecretFinalizer) {+ controllerutil.RemoveFinalizer(userSecret, userSecretFinalizer)+ if err := r.Update(ctx, userSecret); err != nil {+ return fmt.Errorf("failed to remove finalizer from user secret %s: %w", secretRef.Name, err)+ }+ }+ } else if !errors.IsNotFound(err) {+ return fmt.Errorf("failed to get user secret %s: %w", secretRef.Name, err)+ }+ }++ // Remove finalizers from auto-generated default secrets so they can be deleted+ // Use DNS-compliant names (lowercase, hyphens instead of underscores)+ defaultSecretNames := []string{+ o.Name + "-openrag-encryption-key-default",+ o.Name + "-jwt-private-key-default",+ o.Name + "-langflow-secret-key-default",+ }+ for _, secretName := range defaultSecretNames {+ defaultSecret := &corev1.Secret{}+ err := r.Get(ctx, client.ObjectKey{Name: secretName, Namespace: targetNS}, defaultSecret)+ if err == nil {+ if controllerutil.ContainsFinalizer(defaultSecret, userSecretFinalizer) {+ controllerutil.RemoveFinalizer(defaultSecret, userSecretFinalizer)+ if err := r.Update(ctx, defaultSecret); err != nil {+ return fmt.Errorf("failed to remove finalizer from default secret %s: %w", secretName, err)+ }+ }+ } else if !errors.IsNotFound(err) {+ return fmt.Errorf("failed to get default secret %s: %w", secretName, err)+ }+ }++ // Delete managed namespace if it existsns := &corev1.Namespace{}err := r.Get(ctx, client.ObjectKey{Name: targetNS}, ns)if err != nil && !errors.IsNotFound(err) {@@ -227,6 +288,10 @@ func (r *OpenRAGReconciler) reconcileEnvSecrets(ctx context.Context, o *openragvName: d.name,Namespace: targetNS,Labels: map[string]string{"app.kubernetes.io/managed-by": "openrag-operator"},+ Annotations: map[string]string{+ immutableAnnotation: "true",+ },+ Finalizers: []string{envSecretFinalizer},},StringData: map[string]string{".env": d.content},}@@ -1240,7 +1305,9 @@ func udpPort(p int32) networkingv1.NetworkPolicyPort {return networkingv1.NetworkPolicyPort{Port: &v, Protocol: &proto}}-// readSecretValue reads a secret value from a Kubernetes secret.+// readSecretValue reads a secret value from a Kubernetes secret without protection.+// Use this for non-critical secrets like external service credentials (OpenSearch, OAuth, etc.)+// that users may need to rotate or update.// Returns the value and nil error if found, empty string and error otherwise.func (r *OpenRAGReconciler) readSecretValue(ctx context.Context, namespace string, sel *corev1.SecretKeySelector) (string, error) {if sel == nil {@@ -1261,45 +1328,188 @@ func (r *OpenRAGReconciler) readSecretValue(ctx context.Context, namespace strinreturn string(value), nil}+// readSecretRequiredProtection reads a secret value from a Kubernetes secret with protection.+// Use this for critical security-sensitive secrets (JWT, encryption, and Langflow secret keys).+// It enforces that the secret must be immutable and adds a finalizer to prevent accidental deletion.+// Returns the value and nil error if found, error otherwise.+func (r *OpenRAGReconciler) readSecretRequiredProtection(ctx context.Context, namespace string, sel *corev1.SecretKeySelector) (string, error) {+ if sel == nil {+ return "", nil+ }++ secret := &corev1.Secret{}+ err := r.Get(ctx, client.ObjectKey{Namespace: namespace, Name: sel.Name}, secret)+ if err != nil {+ return "", err+ }++ // Validate that security-sensitive secrets are immutable+ if secret.Immutable == nil || !*secret.Immutable {+ return "", fmt.Errorf("secret %s/%s must be immutable (set immutable: true) to prevent accidental modification of critical security keys", namespace, sel.Name)+ }++ // Add finalizer to prevent deletion (immutable only prevents modification, not deletion)+ needsUpdate := false+ if !controllerutil.ContainsFinalizer(secret, userSecretFinalizer) {+ controllerutil.AddFinalizer(secret, userSecretFinalizer)+ needsUpdate = true+ }++ if needsUpdate {+ if err := r.Update(ctx, secret); err != nil {+ return "", fmt.Errorf("failed to add protection finalizer to secret %s/%s: %w", namespace, sel.Name, err)+ }+ }++ value, ok := secret.Data[sel.Key]+ if !ok {+ return "", fmt.Errorf("key %s not found in secret %s", sel.Key, sel.Name)+ }++ return string(value), nil+}++// collectProtectedSecrets gathers all user-provided secret references from the OpenRAG CR+func collectProtectedSecrets(o *openragv1alpha1.OpenRAG) []*corev1.SecretKeySelector {+ var refs []*corev1.SecretKeySelector++ // Backend secrets+ if o.Spec.Backend.JWTSigningKeySecret != nil {+ refs = append(refs, o.Spec.Backend.JWTSigningKeySecret)+ }+ if o.Spec.Backend.EncryptionKeySecret != nil {+ refs = append(refs, o.Spec.Backend.EncryptionKeySecret)+ }++ // Langflow secret+ if o.Spec.Langflow.SecretKeySecret != nil {+ refs = append(refs, o.Spec.Langflow.SecretKeySecret)+ }++ return refs+}+// getOrGenerateSecret retrieves a secret value following this priority:// 1. If userSecretRef is provided in CR, read from that secret-// 2. If value exists in existing .env secret, use that (for stability - never regenerate)-// 3. Generate a new secret using the appropriate generation function-// This consolidates all secrets into .env files without creating separate Kubernetes secrets.+// 2. If default secret exists (auto-generated), read from that+// 3. If value exists in existing .env secret, use that (for backward compatibility)+// 4. Generate a new secret and store it in a default Kubernetes secret+// Auto-generated secrets are stored as immutable Kubernetes secrets with -default suffix for better debuggability.func (r *OpenRAGReconciler) getOrGenerateSecret(ctx context.Context, o *openragv1alpha1.OpenRAG, targetNS string, userSecretRef *corev1.SecretKeySelector, envKeyName, envSecretName string, genFunc func() (string, error)) (string, error) {- // Priority 1: User-provided secret in CR+ // Read user-provided secret if specified+ var userProvidedValue stringif userSecretRef != nil {- value, err := r.readSecretValue(ctx, targetNS, userSecretRef)+ value, err := r.readSecretRequiredProtection(ctx, targetNS, userSecretRef)if err != nil {return "", fmt.Errorf("failed to read user-provided secret for %s: %w", envKeyName, err)}- if value != "" {- return value, nil+ userProvidedValue = value+ }++ // Construct default secret name (auto-generated by operator)+ // Convert envKeyName to DNS-compliant format (lowercase, hyphens instead of underscores)+ dnsCompliantName := strings.ToLower(strings.ReplaceAll(envKeyName, "_", "-"))+ defaultSecretName := o.Name + "-" + dnsCompliantName + "-default"++ // Check if default secret exists (auto-generated in previous reconcile)+ var defaultSecretValue string+ defaultSecret := &corev1.Secret{}+ err := r.Get(ctx, client.ObjectKey{Name: defaultSecretName, Namespace: targetNS}, defaultSecret)+ switch {+ case err == nil:+ // Default secret exists, read the value+ if val, ok := defaultSecret.Data["value"]; ok {+ defaultSecretValue = string(val)}+ case !errors.IsNotFound(err):+ return "", fmt.Errorf("failed to read default secret %s for %s: %w", defaultSecretName, envKeyName, err)}- // Priority 2: Check if key exists in the existing .env secret (for stability)+ // Check if key exists in the existing .env secret (for backward compatibility)+ var existingEnvValue stringexistingEnvSecret := &corev1.Secret{}- err := r.Get(ctx, client.ObjectKey{Name: envSecretName, Namespace: targetNS}, existingEnvSecret)+ err = r.Get(ctx, client.ObjectKey{Name: envSecretName, Namespace: targetNS}, existingEnvSecret)switch {case err == nil:- if value := parseEnvValue(string(existingEnvSecret.Data[".env"]), envKeyName); value != "" {- return value, nil // Never regenerate existing key- }+ existingEnvValue = parseEnvValue(string(existingEnvSecret.Data[".env"]), envKeyName)case !errors.IsNotFound(err):return "", fmt.Errorf("failed to read existing env secret %s for %s: %w", envSecretName, envKeyName, err)}- // Priority 3: Generate new secret using the provided generation function+ // If both user-provided secret and default/existing value exist, they MUST match+ // This prevents users from changing secret references or modifying secret values after initial deployment+ existingValue := defaultSecretValue+ if existingValue == "" {+ existingValue = existingEnvValue+ }+ if userProvidedValue != "" && existingValue != "" {+ if userProvidedValue != existingValue {+ return "", fmt.Errorf("security violation: %s value mismatch between user-provided secret and existing value (secret reference or value has been changed after initial deployment - this is not allowed for critical security keys)", envKeyName)+ }+ }++ // Priority 1: Use user-provided value if available+ if userProvidedValue != "" {+ return userProvidedValue, nil+ }++ // Priority 2: Use default secret value if available (auto-generated)+ if defaultSecretValue != "" {+ return defaultSecretValue, nil+ }++ // Priority 3: Use existing .env value if available (backward compatibility - never regenerate)+ if existingEnvValue != "" {+ return existingEnvValue, nil+ }++ // Priority 4: Generate new secret and store it in a default Kubernetes secretnewSecret, err := genFunc()if err != nil {return "", fmt.Errorf("failed to generate secret for %s: %w", envKeyName, err)}+ // Create immutable Kubernetes secret for the auto-generated value+ immutableTrue := true+ generatedTime := metav1.Now().Format(time.RFC3339)+ secret := &corev1.Secret{+ ObjectMeta: metav1.ObjectMeta{+ Name: defaultSecretName,+ Namespace: targetNS,+ Labels: map[string]string{+ "app.kubernetes.io/managed-by": "openrag-operator",+ "openr.ag/auto-generated": "true",+ "openr.ag/openrag-name": o.Name,+ },+ Annotations: map[string]string{+ "openr.ag/generated-at": generatedTime,+ "openr.ag/secret-key": envKeyName,+ "openr.ag/tenant-id": o.Spec.TenantID,+ immutableAnnotation: "true",+ },+ Finalizers: []string{userSecretFinalizer},+ },+ Immutable: &immutableTrue,+ Data: map[string][]byte{+ "value": []byte(newSecret),+ },+ }++ // Set owner reference or label+ if err := r.setOwnerOrLabel(o, secret, targetNS); err != nil {+ return "", err+ }++ // Create the secret+ if err := r.createOrUpdate(ctx, secret); err != nil {+ return "", fmt.Errorf("failed to create default secret %s for %s: %w", defaultSecretName, envKeyName, err)+ }+// Log the secret generation for auditing and debugginglogger := log.FromContext(ctx)- logger.Info("Generated new secret",+ logger.Info("Generated new secret and created default Kubernetes secret","secretKey", envKeyName,+ "defaultSecretName", defaultSecretName,"openragName", o.Name,"namespace", o.Namespace,"tenantId", o.Spec.TenantID,