[common]: Add externalRefs registry for reusable external dependencies

[rbcb-dev]

Summary

• Introduces externalRefs, a shared registry for external dependencies that can be referenced by ID from multiple parts of the chart
• Supports ConfigMap, Secret, PersistentVolumeClaim, and Service entries in the same registry
• Adds support for both creating a Service with spec.type: ExternalName from chart values and referencing an already existing Service
• Adds externalServiceRef so container env vars can resolve an external service through externalRefs
• Keeps externalRefs as an array so Flux/Kustomize nameReference rules stay simple

Why

Today, charts often need to refer to external resources from several different places, for example:

• a Secret used in envFrom
• a ConfigMap used in valueFrom
• a PersistentVolumeClaim mounted as a volume
• an external hostname that should be exposed through a Kubernetes Service with spec.type: ExternalName

Without a shared registry, the same resource names need to be repeated at each usage site. That makes values harder to read, increases the risk of drift when names change, and makes GitOps overlays more verbose.

This PR introduces externalRefs as a single place to declare those dependencies once and then reference them by ID from supported chart fields.

The same mechanism also supports external services through kind: Service, so the chart can either create a Service with spec.type: ExternalName or point at an already existing Service.

What is externalRefs

externalRefs is a top-level array in values.yaml.

Each entry:

• declares one external dependency
• assigns it a stable id
• describes its type via kind
• provides the resource name or service configuration needed to use it elsewhere in the chart

Supported kinds in this PR:

• ConfigMap
• Secret
• PersistentVolumeClaim
• Service

Other chart fields can then reference an externalRefs entry by id instead of repeating the raw resource name.

What changed

New capabilities

Feature	Description
externalRefs	New top-level registry for reusable external dependencies
kind: Service	Allows externalRefs entries to represent external services
mode: create / reference	Controls whether the chart creates a Service or references an existing one
externalServiceRef	New env field that resolves to a referenced Service name
fullnameOverride	Override the generated service name for created Services
annotations	Per-entry annotations for created Services

Integration points

externalRefs entries can now be used in:

• envFrom (ConfigMap/Secret)
• env[].valueFrom.secretKeyRef / configMapKeyRef
• env[].externalServiceRef (Service)
• volumes (ConfigMap/Secret/PVC)
• ingresses[].rules[].secretName (Secret)
• servicemonitor.basicAuth.existingSecret (Secret)
• imagePullSecrets (Secret)

Feature toggle

includes.externalRefs controls whether chart-managed Service resources declared through externalRefs are rendered.

Schema & validation

• Array-based schema with required: ["id", "kind"]
• Conditional validation: mode: create requires externalName + kind: Service; mode: reference requires name
• minLength: 1 on id, name, and externalName fields
• Unique id enforcement at template level
• Kind validation at every consumer site (e.g., envFrom rejects PVC/Service)

Backwards compatibility

• Consumer fields remain type-specific and validated at render time
• Service support is added without introducing a separate second registry for external services

Kustomize compatibility

The array format preserves simple Kustomize nameReference configuration:

nameReference:
  - kind: ConfigMap
    fieldSpecs:
      - path: spec/values/externalRefs/name
        kind: HelmRelease
        group: helm.toolkit.fluxcd.io
  - kind: Secret
    fieldSpecs:
      - path: spec/values/externalRefs/name
        kind: HelmRelease
        group: helm.toolkit.fluxcd.io
  - kind: PersistentVolumeClaim
    fieldSpecs:
      - path: spec/values/externalRefs/name
        kind: HelmRelease
        group: helm.toolkit.fluxcd.io

Example

externalRefs:
  - id: app-config
    kind: ConfigMap
    name: my-app-config

  - id: ext-database
    kind: Service
    mode: create
    externalName: db.external.example.com

  - id: partner-api
    kind: Service
    mode: reference
    name: partner-api-gateway

components:
  backend:
    controller:
      envFrom:
        - externalRef: app-config
      env:
        - name: DATABASE_HOST
          externalServiceRef: ext-database
        - name: PARTNER_API_HOST
          externalServiceRef: partner-api

includes:
  externalRefs: true

In this example:

• app-config declares a reusable external ConfigMap
• ext-database declares a Service that the chart should create with spec.type: ExternalName
• partner-api declares an already existing service that should only be referenced
• app-config, ext-database, and partner-api are then reused by ID from component configuration
• DATABASE_HOST and PARTNER_API_HOST resolve service names through externalServiceRef

Files changed

• charts/common/templates/helpers/_externalrefs.tpl (new)
• charts/common/templates/_externalname-service.yaml (new)
• charts/common/templates/_container.yaml
• charts/common/templates/_pod.yaml
• charts/common/templates/includes.yaml
• charts/common/values.yaml
• charts/common/values.schema.json
• charts/common/ci/values.test.yaml
• charts/common/README.md.gotmpl
• charts/common/README.md
• charts/common/Chart.yaml

Testing

• helm lint passes
• helm template verified: rendered Service resources use spec.type: ExternalName, env resolution works, and existing integration points (secretKeyRef, configMapKeyRef, envFrom, volumes, ingress TLS, ServiceMonitor, imagePullSecrets) continue to function