|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +Mirantis Launchpad is a CLI tool that installs, upgrades, and resets Mirantis Kubernetes Engine (MKE) and Mirantis Container Runtime (MCR) clusters on provisioned compute nodes. It is **stateless** between runs — all cluster state is discovered by querying hosts directly. |
| 8 | + |
| 9 | +## Agent Rules (from AI_AGENTS.md) |
| 10 | + |
| 11 | +- **NEVER** work on, push to, or merge into `main`. All work goes on feature branches. |
| 12 | +- **All commits MUST be signed** (`git commit -s`). |
| 13 | +- Use `GOTOOLCHAIN=auto` for all `go` commands (already set in Makefile via `export`). |
| 14 | +- Read `docs/guidance/project.md` before implementing features or bug fixes. |
| 15 | + |
| 16 | +## Commands |
| 17 | + |
| 18 | +```bash |
| 19 | +# Build |
| 20 | +make local # Build for current platform → dist/launchpad_GOOS_GOARCH |
| 21 | + |
| 22 | +# Lint & security |
| 23 | +make lint # golangci-lint run |
| 24 | +make security-scan # govulncheck ./... |
| 25 | + |
| 26 | +# Tests |
| 27 | +make unit-test # go test -v --tags 'testing' ./pkg/... |
| 28 | +make functional-test # go test -v ./test/functional/... -timeout 20m |
| 29 | +make integration-test # go test -v ./test/integration/... -timeout 20m |
| 30 | +make smoke-small # E2E small cluster (20m timeout) |
| 31 | +make smoke-full # E2E full matrix cluster (50m timeout) |
| 32 | + |
| 33 | +# Run a single test package |
| 34 | +go test -v --tags 'testing' ./pkg/config/... |
| 35 | + |
| 36 | +# Run a single test |
| 37 | +go test -v --tags 'testing' ./pkg/config/... -run TestFoo |
| 38 | +``` |
| 39 | + |
| 40 | +The build tag `testing` is required for unit tests in `pkg/`. |
| 41 | + |
| 42 | +## Architecture: Phase Manager Pattern |
| 43 | + |
| 44 | +All major operations (apply, reset, describe) are implemented as ordered sequences of **phases** executed by a `phase.Manager`. This is the central architectural pattern — new features should be implemented as new phases or additions to existing ones. |
| 45 | + |
| 46 | +``` |
| 47 | +cmd/apply.go |
| 48 | + └── product/mke/mke.go (Apply method) |
| 49 | + └── phase.Manager.Run() |
| 50 | + └── [Phase1, Phase2, ..., PhaseN] executed sequentially |
| 51 | +``` |
| 52 | + |
| 53 | +Each phase implements: |
| 54 | +- `Run() error` — required |
| 55 | +- `Title() string` — required |
| 56 | +- Optional: `Prepare(config)`, `ShouldRun()`, `CleanUp()`, `DisableCleanup()` |
| 57 | + |
| 58 | +**Key packages:** |
| 59 | + |
| 60 | +| Package | Role | |
| 61 | +|---|---| |
| 62 | +| `pkg/phase/` | Phase Manager orchestration | |
| 63 | +| `pkg/product/mke/` | MKE apply/reset/describe logic | |
| 64 | +| `pkg/product/mke/phase/` | 30+ phase implementations | |
| 65 | +| `pkg/product/mke/config/` | MKE-specific config structs | |
| 66 | +| `pkg/config/` | YAML config parsing, schema migrations (v1–v15) | |
| 67 | +| `pkg/configurer/` | OS/distro-specific host configuration | |
| 68 | +| `pkg/kubeclient/` | Kubernetes client operations | |
| 69 | +| `pkg/helm/` | Helm chart management | |
| 70 | +| `pkg/docker/` | Docker image handling and auth | |
| 71 | +| `pkg/analytics/` | Segment telemetry | |
| 72 | + |
| 73 | +## Configuration |
| 74 | + |
| 75 | +- Default config file: `launchpad.yaml` (override with `--config`) |
| 76 | +- Supports `--config -` to read from stdin |
| 77 | +- Environment variable substitution via `envsubst` |
| 78 | +- Schema migrations live in `pkg/config/migration/` — required for any config struct changes |
| 79 | +- Config migrations must be backward compatible; each migration version has unit tests |
| 80 | + |
| 81 | +## Host Management |
| 82 | + |
| 83 | +Hosts are managed via [k0sproject/rig](https://github.com/k0sproject/rig), which abstracts SSH (Linux) and WinRM (Windows) connections. Phases receive a configured host set and use rig for remote command execution, file upload/download, and shell quoting. |
| 84 | + |
| 85 | +## Testing Strategy |
| 86 | + |
| 87 | +| Type | Location | Notes | |
| 88 | +|---|---|---| |
| 89 | +| Unit | `pkg/**/*_test.go` | Requires `--tags 'testing'` build tag | |
| 90 | +| Functional | `test/functional/` | Component-level, may need network | |
| 91 | +| Integration | `test/integration/` | Requires real provisioned nodes | |
| 92 | +| Smoke | `test/smoke/` | Full E2E via Terraform (terratest) | |
| 93 | + |
| 94 | +## Linting |
| 95 | + |
| 96 | +`.golangci.yml` enables 30+ linters. Notable constraints: |
| 97 | +- `varnamelen`: max 10 chars (allowlist includes `i`, `h`, `ok`, `id`, etc.) |
| 98 | +- Package names may conflict with stdlib (log, version, user, constant) — these are excluded from the relevant linter |
| 99 | +- Generated files (`*.gen.go`) are excluded |
| 100 | + |
| 101 | +## Documentation |
| 102 | + |
| 103 | +Consult these before implementing non-trivial changes: |
| 104 | +- `docs/guidance/project.md` — core architectural principles |
| 105 | +- `docs/specifications/architecture.md` — Phase Manager and design decisions |
| 106 | +- `docs/development/workflow.md` — contribution and testing workflow |
| 107 | +- `docs/requirements/` — PRDs for planned features |
0 commit comments