design

Files (1)

• SKILL.md

SKILL.md (first lines)

# Infrastructure Design

Shared files: a path written `@rules/…`, `@skills/…`, `@templates/…` or `@docs/…` is relative to the
plugin root, `${CLAUDE_PLUGIN_ROOT}` — not to the project being worked on. Read it from there.

**Usage:** `/infra:design [target] [--env=<env>] [--cloud=<cloud>] [--auto]`

## Desired Outcome

A configuration a team can build from, in which:

- Requirements are **numbers**, not adjectives
- The multi-cloud premise and the four environments are settled, with the cloud × environment
  grid filled in
- Every resource has **exactly one owner**
- Each of L1–L4 states what stays identical across environments and what may differ
- The promotion path is designed **per digest**
- Every decision that had two or more options is recorded as an ADR
- The open questions are listed rather than silently resolved

**No implementation code is written here.**

## Decision Criteria

| Situation | Do this |
|-----------|---------|
| A requirement is qualitative ("highly available", "fast") | It is not a requirement yet. Ask for a number, or record a provisional value with the reason it is provisional |
| The bundle covers the topic | Cite it `[document.md]` and state it at the right tier (fact / guidance / open question) |
| The bundle does not cover it (all of `local`; anything production-specific) | Say "outside the bundle's scope", ground it in official documentation or in @rules/infra/environments.md §5, and never speak with the bundle's authority |
| Three or more differences cannot be expressed in common across clouds | Choose separation, not abstraction (@rules/infra/multi-cloud.md §1) |
| More than three differences between two environments | It is becoming a different system. Question the differences before adding another overlay |

## Prerequisites

| File | Required/Recommended | Source |
|------|---------------------|--------|
| `knowledge/okf-k8s-tf/` | **Required** | Vendored bundle (@rules/okf-k8s-tf-bundle.md) |
| reports/03_design/target-architecture.md | Recommended | /architect:design-microservices |
| reports/08_infrastructure/infrastructure-design.md | Recommended | /architect:design-infrastructure — the logical design this makes concrete |
| reports/08_infrastructure/{security,observability,disaster-recovery}-design.md | Recommended | The corresponding `/architect:design-*` skills — policy this design implements |
| The target repository | Recommended | Read it when it exists; the code is the fact and the bundle is the standard |

When invoked from `/infra:start`, environment, cloud, target path, `$OKF` and the freshness list
arrive already settled. **Do not re-ask them** — confirm only what is missing. When invoked directly, run
@rules/okf-k8s-tf-bundle.md §1–2 first (resolve, freshness, environment, cloud).

The freshness list names the bundle documents past `stale_after` or awaiting re-verification
(from `tools/update-okf-bundle.sh status --bundle=k8s-tf` when invoked directly). A design claim
resting on a listed document says the document awaits re-verification and why, and a decision
that depends on such a claim is also listed in the design's open questions — it may move when
the document is revised.

## Step 1 — Turn requirements into numbers

Use the "requirements and boundaries" section of `architecture/design-build-checklist.md` as the
question list. Do not leave a blank and continue: record a provisional value with its grounds.

- Availability target, RTO / RPO
- Performance (throughput, latency)
- Data retention
- Budget
- Regulatory constraints and data residency
- For each environment in scope: purpose, data, access, change approval

A requirement without a number cannot ground a design decision.

## Step 2 — Settle the multi-cloud and environment premises

Fill in the four items of @rules/infra/multi-cloud.md §0. A design that proceeds with these vague
will break later — that is the single most reliable failure in this area.

Then fill the environment matrix (@rules/infra/environments.md §1). At minimum:

- **Which of the four environments this design covers**
- The cloud × environment grid (§7). A blank cell means "not deployed here", never left implicit
- Separation of purpose, data, access and change approval per environment
  [architecture/design-build-checklist.md]
- **The production apply path.** The bundle has no implementation fact here, so decide it now and
  record it as an ADR (staging's GitOps plus approval, protection and sync windows is the
  bundle-consistent shape)
- **The declaration of what local does not reproduce.** This is the central deliverable of
  local-environment design, not a footnote

## Step 3 — Decide the ownership split

Start from the bundle's ownership table and produce this system's version
[architecture/platform-architecture.md].

| Resource | Where the declaration lives | Applied by | State / history |
|----------|-----------------------------|------------|-----------------|

**Verify one-resource-one-owner immediately after writing the table** — that Terraform, Argo CD,
CI and manual operation do not overlap. For reference, the observed implementation splits as:

- Cloud foundation → `terraform/environments/*/infra`, the Terraform job in GitLab CI
- Shared Kubernetes platform → `terraform/environments/*/kubernetes` + `terraform/modules/kubernetes`
- Upstream Helm values → `terraform/charts`, Terraform `helm_release`
- Staging applications → `kubernetes/staging`, Argo CD app-of-apps
- Test manifests → `kubernetes/test` or the app's `k8s/`, applied by procedure or CI `kubectl apply`

## Step 4 — Design layer by layer

Work L1 → L4 (@rules/infra/multi-cloud.md §1), reading the bundle document for each. **State for
every layer what stays identical across environments and what may differ**
(@rules/infra/environments.md §2).

| Layer | What to decide | Bundle |
|-------|----------------|--------|
| L1 cloud foundation | Network, cluster, database, IAM, storage, state boundaries | `foundation/terraform.md` |
| L2 Kubernetes | Namespace design, RBAC, NetworkPolicy, Pod Security, workload availability | `foundation/kubernetes.md` |
| L3 shared components | Which charts, common vs. differing values, CRD lifecycle | `foundation/helm.md`, `architecture/supporting-stack.md` |
| L4 delivery | The GitOps boundary, CI stages, environment protection, image identity | `delivery/*.md` |
| Cross-cutting | Secrets, observability, policy | `secrets/*.md`, `operations/*.md`, `security/*.md` |

Any version named here is **looked up, not recalled**, and must be stable and non-EOL
(@rules/dependency-versions.md). State the version *and* its support horizon so
`/infra:implement` pins the same set.

## Step 5 — Write the apply flow

From wfukatsu/nexus-architect, MIT.

More from wfukatsu/nexus-architect