implement

Files (1)

• SKILL.md

SKILL.md (first lines)

# Infrastructure Implementation

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:implement [target] [--env=<env>] [--cloud=<cloud>] [--auto]`

## Desired Outcome

Code that can be applied to the named environment, in which every version is pinned, every
touched resource has a single identifiable owner, the image digest is continuous from build to
deploy, and no secret value appears in any artifact — accompanied by the verification commands
that were actually run and their results.

## Decision Criteria

| Situation | Do this |
|-----------|---------|
| No design exists | Run a short design pass first — at minimum the ownership split, target clouds and target environments. Do not start writing without them |
| The repository and the bundle disagree | **Follow the repository** and report the difference. The bundle is a snapshot of specific commits (@rules/okf-k8s-tf-bundle.md §4) |
| The write target is owned by something else | Stop. Never hand-edit a Terraform-managed resource, never touch an Argo CD-managed resource from CI [architecture/platform-architecture.md] |
| A version must be written | Look it up; never recall it, and never copy it from an example in this repository (@rules/dependency-versions.md) |
| The work hits hard ground (complex migration, state surgery, CRD upgrade) | Do not push through. Say so and suggest `/model opus` |

## Prerequisites

| File | Required/Recommended | Source |
|------|---------------------|--------|
| `knowledge/okf-k8s-tf/` | **Required** | Vendored bundle (@rules/okf-k8s-tf-bundle.md) |
| The agreed design document | **Required** | /infra:design, or the user |
| The target repository | **Required** | Read its real structure before writing |

When invoked from `/infra:start`, environment, cloud, target path, `$OKF` and the freshness list
arrive already settled. **Do not re-ask them.**

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 version, API
version, flag or chart value taken from a listed document is resolved from its registry or
official page rather than copied (@rules/dependency-versions.md), and the implementation notes
say the document awaits re-verification and why.

## Step 0 — Fix the environment before writing anything

The environment changes both where the code goes and who applies it.

| Environment | Where it is written | Applied by | Bundle |
|-------------|--------------------|------------|--------|
| local | Shared base + a local overlay, plus a startup script | The developer | **Out of scope** |
| test | `kubernetes/test` or the app's `k8s/` | A documented procedure or CI `kubectl apply` | Observed implementation |
| staging | `kubernetes/staging` (the app-of-apps entry `kustomization.yaml`) | Argo CD | Observed implementation |
| production | To be decided (follows staging) | Argo CD + approval | **No observed implementation** |

Production code is written as staging's configuration **plus** approval, protection and sync
windows — stating explicitly that the bundle has no precedent for it
(@rules/infra/environments.md §0, §4).

## Step 1 — Read the target repository

The bundle describes specific commits. Where the real repository differs, the repository wins;
report the difference rather than quietly converging on the bundle. Confirm the owner of every
write target before writing.

## Directory Convention

Following the observed implementation
[foundation/terraform.md, architecture/platform-architecture.md]:

```
terraform/
  global/
  environments/<cloud>/<env>/infra/         # network, cluster, database, IAM, storage
  environments/<cloud>/<env>/kubernetes/    # shared components (helm_release etc.)
  modules/{aws,azure,gcp,kubernetes}/
  charts/                                   # per-environment values for upstream charts
kubernetes/
  base/          # common to every environment; no environment branching
  local/         # overlay onto base. Out of the bundle's scope (replica 1, substituted dependencies)
  test/          # overlay onto base. Applied by procedure or CI kubectl apply
  staging/       # overlay onto base. The app-of-apps entry point
  production/    # overlay onto base. To be decided (follows staging)
```

`<env>` is `test` / `staging` / `production`. **Local never enters the terraform tree** (it builds
no L1); its manifest differences live in the Kustomize overlay.

The observed implementation has only `kubernetes/test` and `kubernetes/staging`; factoring out
`base/` and adding `local/` and `production/` is **this skill's convention**, not the bundle's.
Where the existing repository is arranged differently, follow it and report the difference.

## Terraform

Mandatory [foundation/terraform.md]:

- Pin Terraform and provider versions **exactly** in the root module
- Commit `.terraform.lock.hcl` per root configuration; for several OS/arch, pre-register hashes
  with `terraform providers lock -platform=...`
- Remote backend, encrypted, access-controlled, with locking and versioning/backup. State never
  goes in Git
- Modules are **high-level capabilities** (`network`, `database`, `kubernetes-cluster`). Keep the
  module tree shallow and prefer composing small modules
- `variables.tf` carries type, description and validation; `outputs.tf` carries description
- Prefer implicit dependencies through value references; use `depends_on` only where order cannot
  be expressed as a value
- Rename and refactor with `moved` blocks rather than relying on `terraform state mv`
- `sensitive = true` suppresses display; it does not remove the value from state. Keep secret
  values out of tfvars, plan artifacts, CI logs and `local-exec` arguments

For multi-cloud, align L1 module output names across the three clouds
(@rules/infra/multi-cloud.md §1).

Minimum verification after generating:

```bash
terraform fmt -check -recursive
terraform init -backend=false
terraform validate
terraform plan -detailed-exitcode   # only where credentials are available
```

From wfukatsu/nexus-architect, MIT.

More from wfukatsu/nexus-architect