Skip to main content

ADR-001: Kustomize Components for Enterprise Pattern

Purpose: For platform engineers and contributors, explains the decision to adopt Kustomize Components for the community/enterprise service pattern in openCenter-gitops-base.

Status​

Proposed

Context​

The openCenter-gitops-base repository used parallel directory structures (community/ and enterprise/) for each service. This created 55 edition-specific files across 11 services with roughly 60% duplicate content. Version upgrades required touching 4–6 files per service, and copy-paste errors had already appeared (e.g., a Kyverno enterprise patch referencing MetalLB metadata).

Previous pattern for cert-manager:

cert-manager/
├── community/
│   ├── kustomization.yaml          # Base secretGenerator
│   └── source.yaml
└── enterprise/
    ├── kustomization.yaml          # Duplicates base secretGenerator + adds enterprise
    ├── patch-helmrelease-source.yaml
    └── helm-values/
        └── hardened-values-v1.18.2.yaml

The enterprise kustomization.yaml fully duplicated the community secretGenerator block, then added enterprise-specific secrets. Every service followed this pattern.

Decision​

Migrate to Kustomize Components (kind: Component) so enterprise becomes a composable add-on rather than a parallel directory tree.

New pattern for cert-manager:

cert-manager/
├── kustomization.yaml              # Base (community by default)
├── source.yaml                     # Community HelmRepository
├── namespace.yaml
├── helmrelease.yaml
├── helm-values/
│   └── values-v1.18.2.yaml
├── enterprise/
│   └── kustomization.yaml          # Thin wrapper: includes base + component
└── components/
    └── enterprise/
        ├── kustomization.yaml      # Component: patches source + adds enterprise values
        └── helm-values/
            └── hardened-values-v1.18.2.yaml

How It Works​

  1. The base kustomization at the service root produces a working community deployment.
  2. The enterprise component adds a global enterprise OCI source, patches the community HelmRepository to use it, and injects enterprise hardened values.
  3. A thin enterprise wrapper at enterprise/kustomization.yaml includes the base plus the component for backward compatibility.
  4. Customer overlays continue referencing existing paths (cert-manager/enterprise) with zero changes.

Component kustomization example:

apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component
resources:
  - ../../../global/enterprise/source.yaml
patches:
  - target:
      kind: HelmRepository
      name: jetstack
    patch: |
      $patch: delete
      apiVersion: source.toolkit.fluxcd.io/v1
      kind: HelmRepository
      metadata:
        name: jetstack
  - target:
      group: helm.toolkit.fluxcd.io
      version: v2
      kind: HelmRelease
      name: cert-manager
    patch: |
      - op: replace
        path: /spec/chart/spec/sourceRef
        value:
          kind: OCIRepository
          name: opencenter-cloud

Consequences​

Positive:

  • Eliminates ~60% content duplication across 11 services
  • Version upgrades touch 2 files instead of 6
  • New service onboarding requires fewer boilerplate files
  • Copy-paste errors are structurally prevented

Trade-offs:

  • Kustomize Components require FluxCD v2.1+ (already deployed on all clusters)
  • Team members need to understand the Component abstraction
  • Migration requires a coordinated rollout across existing customer overlays