Custom Overlay Example

UNOFFICIAL/EXPERIMENTAL

This is the custom overlay case in its simplest form.

Product Lane

ExternalDNS customer overlays sit across three product lanes:

1. Free/out-of-box catalog configs:
   reviewed ExternalDNS base shapes that are common enough to publish.

2. ConfigHub customization:
   customer, environment, region, target, gates, facts, and observation policy
   as derived variants over a reviewed base.

3. Managed or potentially paid complexity:
   private wrapper charts, private values, GitOps import, fleet variants, full
   stacks, production receipts, support SLAs, and old-version patch work.

The example below is a classification golden for that boundary. It is not a claim that every customer overlay is free catalog material, and it is not a live production import receipt.

Example

Component: ExternalDNS
Customer: Acme
Environment: production
Region: us-east
Target: prod-us-east
Domain: acme.example.com

Base Variant

The base variant is the reviewed ExternalDNS install shape.

ExternalDNS/managed-aws-acme

It is produced by cub installer.

It includes the choices that change rendered Kubernetes objects:

chart: external-dns/external-dns@1.21.1
provider: aws
sources:
  - service
  - ingress
registry: txt
txtPrefix: kubara-
domainFilters:
  - acme.example.com
txtOwnerId: acme-prod-us-east
serviceAccount:
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/external-dns-acme-prod
rbac:
  create: true

These values change controller args, ServiceAccount metadata, RBAC, or object behavior. They belong in the base because Kubernetes will receive different YAML.

Overlay Variant

The overlay variant is the customer production ConfigHub variant.

ExternalDNS/customer-acme-prod

It is created from:

ExternalDNS/managed-aws-acme

It applies customer production refinements after the reviewed base has been uploaded:

customer: acme
environment: prod
region: us-east
target: prod-us-east
observationFreshness: PT15M
targetFacts:
  requiredHostedZones:
    - name: acme.example.com
      provider: aws
      visibility: public
  requiredSecrets:
    - namespace: external-dns
      name: external-dns-aws
      keys:
        - credentials

It does not rerender Helm. It does not change the ExternalDNS Deployment, ServiceAccount, RBAC, or CRD shape. It can still bind target facts and fill approved existing fields when the Creator contract allows those changes and records checks and mutation receipts.

User UX

A future/polished Creator flow should present this as:

Create variant
From: ExternalDNS/managed-aws-acme
For: customer-acme-prod
Change: customer, environment, region, target, observation policy
Require: hosted zone acme.example.com, Secret external-dns/external-dns-aws
Review: same ExternalDNS install shape, approved customer production refinements
Status: ready when target facts are confirmed
Create

That is the whole user story.

When To Go Back To The Base

If Acme changes any of these, create or update a base variant:

provider
sources
registry
domainFilters
txtOwnerId
IAM role annotation
RBAC
CRDs
controller args or env

Those values affect rendered Kubernetes objects.

If Acme changes any of these, use a derived ConfigHub variant:

customer
environment
region
target
approval gates
observation freshness
required hosted zone
required external Secret reference
approved placeholder or TransformPaths fills

Those values refine the reviewed object set after upload without rerendering Helm.

Checked Example Files

The checked example data is here:

data/managed-overlay-goldens/external-dns-customer-acme-prod/

The main files are:

wrapper-chart/Chart.yaml
values/platform-values.yaml
values/customer-acme-prod-values.yaml
overlay-classification.yaml
preview.yaml
receipts/*.yaml