Skip to content

2. Repository Model

7k-inari is the client overlay and documentation repository in a hub-and-spoke architecture. It contains client-specific GitOps configuration, architecture documentation, and shared templates. The 7KGroup management plane (fleet hub) is configured separately in 7k-inari-fleet and is restricted to platform operators.

7k-inari delegates reusable platform definitions and CI/CD workflows to existing repositories.

2.1 External Repositories

Repository Role Contract
github.com/7kgroup/hiroba-catalog Golden catalog of XRDs and compositions Semantic-versioned releases consumed via ArgoCD targetRevision
github.com/7kgroup/workflows Reusable GitHub Actions workflows Tagged releases invoked by uses: references
github.com/7kgroup/7k-inari-fleet Management-plane GitOps configuration Restricted to 7KGroup platform operators

7k-inari must not duplicate Hiroba definitions, reusable workflow logic, or management-plane configuration. If a change is needed in any of those, the work happens in the upstream repository and is released before 7k-inari consumes it.

2.2 Directory Layout

7k-inari (this repository)

7k-inari/
├── docs/                          # All architecture, runbooks, and client docs
│   ├── architecture/
│   ├── runbooks/
│   └── clients/
├── crossplane/                    # Per-client Crossplane claims consumed by mgmt-plane ArgoCD
│   └── claims/
├── clients/                       # GitOps-native client overlays
│   ├── _templates/                # Shared baseline and reusable client components
│   │   ├── base/                  # Always-on platform components
│   │   ├── components/            # Reusable opt-in components (Kustomize Components)
│   │   │   └── keycloak/
│   │   └── applicationset/
│   │       └── client-platform.yaml
│   └── <client-id>/
│       ├── base/
│       │   ├── kustomization.yaml
│       │   ├── 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
├── scripts/                       # Client-facing scripts only
│   └── onboarding/
└── .github/
    └── workflows/                 # Calls workflows-library actions

7k-inari-fleet (management-plane repository)

7k-inari-fleet/
├── fleet/                         # Management-plane internal config
│   ├── bootstrap/                 # ArgoCD plumbing (root app, project, self app)
│   ├── components/                # GitOps components
│   │   ├── bootstrap/             # ArgoCD self-management Application
│   │   ├── infrastructure/        # CRDs, operators, shared infrastructure
│   │   │   ├── gateway-api-crds/
│   │   │   ├── istio/
│   │   │   ├── cert-manager/
│   │   │   ├── gateway/
│   │   │   ├── external-secrets/
│   │   │   └── crossplane/        # Client control-plane provisioning
│   │   │       ├── compositions/  # XRDs and Compositions applied to mgmt-plane Crossplane
│   │   │       └── providerconfigs/  # Per-client ProviderConfigs for mgmt-plane Crossplane
│   │   └── platform/              # Management-plane services
│   │       ├── vault/
│   │       ├── identity/keycloak/
│   │       ├── observability/
│   │       └── client-claims/     # ArgoCD Application referencing 7k-inari claims
│   └── management-cluster/        # Bare-metal K8s provisioning config
├── scripts/                       # Fleet operator scripts
└── .github/
    └── workflows/

2.3 Versioning Strategy

Layer Repository / Artifact Versioning Approach
Client overlays and templates 7k-inari Whole-repo semantic versioning (v2026.07.0, v2026.08.0)
Management-plane config 7k-inari-fleet Whole-repo semantic versioning, independent of 7k-inari
Golden XRDs / compositions hiroba-catalog Semantic-versioned releases consumed via ArgoCD targetRevision
Reusable CI/CD workflows workflows Tagged releases invoked by uses: references
Per-client environments Client overlay directories Promoted dev → staging → prod via Kustomize overlays and ArgoCD sync windows

Promotion Model

  1. Canary client: One non-paying or internal client receives baseline changes first in dev/staging.
  2. Environment tracking:
  3. dev overlays may track main or the latest release candidate tag.
  4. staging overlays track release candidate tags.
  5. prod overlays track stable tags only.
  6. Production gates: Use ArgoCD sync windows or manual sync for prod to prevent blast-radius updates.
  7. Baseline changes: A change to clients/_templates/base/ must pass the canary client before any other prod overlay is updated.

Practical Rule

A change to _templates/base/ must be validated by the canary client before it is promoted to other clients' production environments.

2.4 Change Flow

  1. A change to the platform baseline is made in hiroba-catalog and released.
  2. 7k-inari updates the pinned version in the relevant client overlay or template.
  3. Each client ArgoCD pulls the updated overlay from 7k-inari and applies changes in sync waves.
  4. Management-plane changes flow through 7k-inari-fleet independently and are reconciled by the management-plane ArgoCD.

The management-plane ArgoCD in 7k-inari-fleet does not push to client clusters. It only reconciles management-plane components.

2.5 Governance Rules

  • No raw secrets, kubeconfigs, or credentials in either repository.
  • 7k-inari contains manifests consumed by client-local ArgoCD: client overlays, shared templates, and opt-in components.
  • 7k-inari-fleet contains manifests consumed by management-plane ArgoCD: management-plane runtime config, including per-client Crossplane Claims, ProviderConfigs, and Compositions.
  • Reusable platform components that are not client-specific live upstream in hiroba-catalog or workflows.
  • All changes that affect architecture must update the corresponding ADR or overview doc.
  • Client-local ArgoCD pulls from 7k-inari; management-plane ArgoCD pulls from 7k-inari-fleet.

See ADR-007: Management Plane as Fleet Hub, ADR-008: Bare-Metal Management Plane, and ADR-010: Client-Local ArgoCD.