Summary

Refactor Helm Chart to separate User Configuration from System Defaults (Database & Volumes)

Problem Statement

Currently, the RHDH Helm chart forces users to override extensive default configurations to make simple changes. This is most critical when configuring an external database or setting up dynamic plugin caching.

To disable the internal database password or add a volume, a customer must copy and paste our entire default extraEnvVars or extraVolumes list into their values.yaml.

This creates a significant "Day 2" operational risk. If the RHDH engineering team updates these default values in a future release, customers with overridden configurations will not receive these updates. Their instances may break or behave inconsistently because their static configuration is masking our new defaults.

Current Behavior

As documented in the External PostgreSQL Guide, a user must manually redefine extraEnvVars to remove POSTGRESQL_ADMIN_PASSWORD.

User's values.yaml (Current - Problematic):

upstream:  
  postgresql:  
    enabled: false

# User has to copy-paste all internal defaults just to remove one variable  
extraEnvVars:  
  - name: BACKEND_SECRET  
    valueFrom:  
      secretKeyRef:  
        key: backend-secret  
        name: '{{ include "janus-idp.backend-secret-name" . }}'  
  # ... user must maintain this list forever ...

Similarly, for Dynamic Plugins Cache, the user must redefine all extraVolumes.

User's values.yaml (Current - Problematic):

upstream:  
  backstage:  
    extraVolumes:  
      # --- MANDATORY DEFAULTS START (User is forced to copy-paste all of these) ---  
      # If we update these in the future, this user config will break.  
      - name: dynamic-plugins-root  
        persistentVolumeClaim:  
          claimName: dynamic-plugins-root  
      - name: dynamic-plugins  
        configMap:  
          defaultMode: 420  
          name: '{{ printf "%s-dynamic-plugins" .Release.Name }}'  
          optional: true  
      - name: dynamic-plugins-npmrc  
        secret:  
          defaultMode: 420  
          optional: true  
          secretName: '{{ printf "%s-dynamic-plugins-npmrc" .Release.Name }}'  
      - name: dynamic-plugins-registry-auth  
        secret:  
          defaultMode: 416  
          optional: true  
          secretName: '{{ printf "%s-dynamic-plugins-registry-auth" .Release.Name }}'  
      - name: npmcacache  
        emptyDir: {}  
      - name: temp  
        emptyDir: {}  
      # --- MANDATORY DEFAULTS END ---

      # --- USER CUSTOM CONFIGURATION ---  
      # This is the ONLY volume the user actually wanted to add.  
      - name: my-custom-cache  
        emptyDir: {}

Proposed Solution

We need to adopt an "Extend, Don't Replace" pattern. The Helm chart templates should handle the logic for defaults internally, so the user only provides what is specific to their environment.

1. Dedicated Database Flags

Instead of asking users to manipulate environment variables directly, we should provide a semantic flag (or use existing ones effectively).

Logic:
The deployment.yaml template should check if the internal database is enabled.

_ If Internal: The template automatically injects POSTGRESQL_ADMIN_PASSWORD.
_ If External: The template skips injecting that variable.

2. Additive Volumes

extraVolumes should default to an empty list []. The mandatory system volumes (required for RHDH to run) should be defined directly in the deployment.yaml template.

Logic:
The template should iterate over the internal system volumes AND the user-provided extraVolumes.

Desired User Experience

The user's configuration should look like this:

User's values.yaml (Target):

upstream:  
  postgresql:  
    enabled: false  
    # No need to touch extraEnvVars. The chart handles the password logic.

# Only add what is new. Do not repeat system defaults.  
extraVolumes:  
  - name: my-custom-cache  
    emptyDir: {}

Acceptance Criteria

1. Users can configure an external PostgreSQL database without redefining extraEnvVars.
2. Users can add new volumes via extraVolumes without redefining the default RHDH volumes.
3. Existing default values (like BACKEND_SECRET) are preserved automatically during upgrades, even if the user has custom configurations.

Architectural Root Cause: Subchart Dependency

The rhdh-chart currently utilizes the upstream Backstage chart as a direct Helm subchart dependency.

This wrapper architecture creates a limitation: Helm does not support deep merging of list arrays (like extraEnvVars) between a parent chart and a subchart.
We cannot simply "inject" our defaults into the subchart's list; if the user defines the list in values.yaml, it overrides the subchart's default list entirely.
Options:

1. Push for Upstream Changes: Collaborate with the upstream community to introduce more granular customization options in the upstream Helm chart.
2. The Nuclear Option: If the subchart dependency prevents us from delivering a reliable configuration experience, we must evaluate removing the dependency. This means forking or re-implementing the templates directly within rhdh-chart. This trades "upstream alignment" for "control and stability," drastically increasing our maintenance burden but solving the configuration drift problem permanently and improving the user experience.