scalex-release-template

Best-practice template repository for a ScaleX Federation release: a values-driven app catalog where each app is pinned to a Karmada member cluster of your choice. Ships with one simple Python app (hello) targeting the edgex member — change one value to twinx and the app moves there; add a second app with its own targetCluster (e.g. datax) and it deploys independently.

How placement works

# chart/values.yaml
apps:
  hello:
    targetCluster: edgex   # ← change to "twinx" and the next sync moves hello

Each enabled app renders a Deployment, an optional Service, and one PropagationPolicy pinning it to targetCluster. The Service never sets a static IP — exposure goes through a Cilium LB-IPAM pool reference (service.lbPool, a fleet-fact placeholder rendered as a pool annotation/label). karmada.enabled: false exists only for local development against a plain cluster (renders workloads, no policies).

Repository layout

.
├── AGENTS.md                   # operating guide for coding agents (invariants)
├── .claude/skills/             # project skills (tracked)
├── chart/                      # THE deploy unit
│   ├── Chart.yaml
│   ├── values.yaml             # app catalog + repo defaults
│   ├── values.schema.json      # Federation platform contract (copy)
│   ├── templates/
│   │   ├── _helpers.tpl        # name/labels/image/appFullname helpers
│   │   ├── app/                # Deployment + Service, ranged over apps.*
│   │   └── policy/             # one PropagationPolicy per app (karmada gate)
│   └── tests/                  # helm-unittest: catalog + placement, both modes
├── services/hello/             # the shipped Python app (pyproject, src, tests)
├── scaffolds/                  # Go/Rust starting points for NEW apps
│   ├── go-service/             #   (not build targets - no images/ Dockerfile)
│   └── rust-service/
├── images/hello/Dockerfile     # build context = repo root (tower-ci contract)
├── examples/                   # release examples + opt-in GitHub Actions template
│   └── github-actions/ci.yaml  # inactive until copied to .github/workflows/
├── docs/
│   ├── architecture.md
│   └── adding-an-app.md        # ← guide: second app to datax
├── tekton/                     # tower-ci build contract notes
└── Justfile

Adding an app (short version — full guide: docs/adding-an-app.md)

1. Copy scaffolds/go-service (or rust-service, or model on services/hello) to services/<name>/.
2. Add images/<name>/Dockerfile (repo-root build context).
3. Add images.<name> and apps.<name> to chart/values.yaml — with its own targetCluster (e.g. datax).
4. just lint && just test, commit, promote via the Federation.

Verify

just lint            # helm lint --strict + ruff + scaffold linters
just test            # helm unittest + pytest + scaffold builds
just template        # render (hello -> edgex)
just template-twinx  # render the retarget demo (hello -> twinx)
just run-local       # run the hello app on :8080

Optional GitHub Actions template

examples/github-actions/ci.yaml is deliberately outside .github/workflows, so GitHub Actions does not run in this template repository. Copy it to .github/workflows/ci.yaml in a generated release repository to opt in.

Deployment path

Charts are never deployed from here directly. scalex-federation promotes this repo as a release pinned to an immutable commit SHA; Tower Argo CD applies it to the Karmada API, and each app's PropagationPolicy places it on its targetCluster member. Copy examples/release.yaml and examples/federation-values.yaml into the federation repo to register.