ADR-003: Hiroba Framework for Infrastructure Abstraction

Status: Approved

Date: 2026-06-30

Decision

Use the existing Hiroba framework (CDK8s + Crossplane) as the primary infrastructure abstraction layer, distributed from a central catalog to all client control planes.

Rationale

• Already developed and tested internally
• CDK8s provides type-safe, versioned composition definitions
• Crossplane enables cloud-agnostic resource claims (AWS/GCP/Azure)
• Compositions map "platform profiles" (dev/staging/prod) to cloud-specific implementations

Catalog Structure

hiroba-catalog/
├── xrd/
│   ├── database.postgres.v1.yaml
│   ├── cache.redis.v1.yaml
│   ├── ingress.istio.v1.yaml
│   ├── storage.object.v1.yaml
│   └── cloudaccount.v1.yaml
├── compositions/
│   ├── aws/
│   ├── gcp/
│   ├── azure/
│   └── common/
└── profiles/
    ├── development.yaml
    ├── staging.yaml
    └── production.yaml

Distribution

• Golden catalog hosted in github.com/7kgroup/hiroba-catalog
• Versioned releases (e.g., v1.2.0)
• ArgoCD ApplicationSets sync pinned versions to each client cluster
• Clients consume XRDs; they cannot modify them

Related

• Client Overlays
• Repository Model