4. Client Overlays

Each client has a GitOps-native overlay in this repository. The overlay describes how the shared platform baseline is configured and deployed to that client's control plane.

The client control plane runs its own ArgoCD instance. That ArgoCD pulls the overlay directly from github.com/7kgroup/7k-inari and applies it to the local cluster. The management plane does not push deployments to clients.

4.1 Directory Structure

clients/
├── _templates/                    # Shared baseline consumed by every client
│   ├── base/                      # Always-on platform components
│   │   ├── kustomization.yaml
│   │   ├── dex-connectors.yaml
│   │   ├── alloy-config.yaml
│   │   ├── namespaces.yaml
│   │   └── providerconfigs/
│   ├── components/                # Opt-in packaged components (e.g., Keycloak)
│   │   └── keycloak/
│   │       ├── kustomization.yaml
│   │       ├── keycloak-claim.yaml
│   │       └── dex-connector.yaml
│   └── applicationset/
│       └── client-platform.yaml   # Template for client-local ArgoCD Application
└── <client-id>/
    ├── base/
    │   ├── kustomization.yaml     # Composes _templates/base/ + client patches
    │   ├── dex-connectors.yaml
    │   ├── alloy-config.yaml
    │   └── providerconfigs/
    ├── overlays/
    │   └── <env>/
    │       ├── kustomization.yaml
    │       └── patches/
    └── extras/                    # Client-specific edge-case manifests
        └── <extra-name>/
            ├── kustomization.yaml
            └── argocd-application.yaml

4.2 Overlay Principles

• GitOps-native: every change to a client environment is a Git commit.
• Client-local ArgoCD: each client cluster pulls and applies its own overlay.
• Reusable base: the _templates/base/ directory contains the common starting point.
• Opt-in components: the _templates/components/ directory contains packaged, reusable stacks that a client can enable via a Kustomize components: line.
• Edge-case extras: the clients/<client-id>/extras/ directory holds one-off client-specific manifests or ArgoCD Applications that are not reusable enough to become components.
• Per-client, per-environment overrides: each client overlay patches only what differs from the base.
• Pinned versions: Hiroba catalog versions are pinned explicitly per client and environment.

4.3 Opt-In Components

Opt-in components live in _templates/components/<name>/ and use Kustomize Component semantics. A client enables a component by referencing it from an overlay:

# clients/client-a/overlays/prod/kustomization.yaml
components:
  - ../../../_templates/components/keycloak

Components should:

• Be packaged, versioned, and reusable across clients.
• Consume Hiroba catalog resources where applicable.
• Include any required platform integrations (e.g., a Dex connector for Keycloak).
• Avoid client-specific values; those are patched in the overlay.

Example component: keycloak — deploys a client-local Keycloak instance via a Hiroba claim and adds a supplementary Dex OIDC connector.

4.4 Edge-Case Extras

Extras are client-specific manifests that do not fit the reusable component model. They live in clients/<client-id>/extras/<name>/ and are typically referenced as ArgoCD Applications or raw Kustomize resources.

Use extras when:

• A one-off third-party chart or manifest is required.
• The change is too client-specific to generalize into _templates/components/.
• A temporary workaround or migration resource is needed.

Extras should still follow GitOps conventions and should not store secrets in Git.

4.5 Client ArgoCD Bootstrap

During cluster provisioning, the client ArgoCD instance is installed and configured to:

1. Authenticate to github.com/7kgroup/7k-inari using a per-client Git credential.
2. Create an Application pointing to clients/<client-id>/overlays/<env>/.
3. Sync the baseline, components, extras, and overlay in waves.

The client ArgoCD is owned and managed by 7KGroup. Clients receive read-only access to inspect it.

4.6 Configuration Owned by an Overlay

File	Purpose
kustomization.yaml	Declares resources, components, extras, and patches for the client environment
dex-connectors.yaml	Dex connector configuration for the client's IdP
alloy-config.yaml	Alloy scrape/push configuration, including management-plane endpoints
providerconfigs/	Crossplane ProviderConfigs for the client's cloud accounts
patches/	Environment-specific Kustomize patches
extras/	Client-specific manifests and ArgoCD Applications outside the reusable baseline

4.7 Promotion Flow

_template/base/  →  clients/<client-id>/base/  →  overlays/dev/  →  overlays/staging/  →  overlays/prod/

Changes are validated in dev, promoted to staging, and finally to prod. Client-local ArgoCD instances pick up changes automatically from Git. Sync windows and manual approvals may gate production deployments.

4.6 Client Naming and Identifiers

Each client receives a stable, DNS-safe identifier (client-id) used for:

• Directory names
• ArgoCD application names
• X-Scope-OrgID values in observability
• Cost allocation tags
• Kubernetes labels (client, managed-by)

4.7 Restrictions

• Overlays cannot modify Hiroba XRDs. They only consume them via claims.
• Components should be reusable across clients; client-specific values are patched in the overlay.
• Extras are intentionally client-scoped and are not promoted to _templates/components/ unless a second client needs them.
• Cloud credentials are never stored in overlays. ProviderConfigs reference secrets injected by External Secrets Operator.
• No bespoke application code lives in this repository.

---

See ADR-001: Physical Cluster Per Client, ADR-003: Hiroba Framework, and ADR-010: Client-Local ArgoCD.