proposal: load local images into the local cluster

[atkrad]

Problem

Local kind (deployah cluster up) cannot pull private or freshly built images the way a laptop Docker daemon can. The usual kind workflow is: build or have myapp:dev on the host, then load it into the nodes so pods do not hit a remote registry.

Deployah already implements that in internal/localkube (LoadImage / LoadImageArchive + imageref.Open), but nothing in the CLI calls it. Developers fall back to kind load docker-image or push to a real registry. --sync-registry-auth only helps authenticated pulls, not host-daemon → node load.

Goals

• First-class CLI to load one or more image refs into the Deployah local cluster.
• Reuse existing Manager.LoadImage (daemon / .tar / remote → node archive load).
• Sensible defaults: current local cluster name, progress via existing step events.
• Document interaction with :latest / imagePullPolicy (loaded images must not be re-pulled away).
• Optional: load all image: refs from a deployah.yaml for an environment (dev convenience).
• Foundation for build proposals (proposal: optional Dockerfile / Buildx image build #26 / proposal: optional Cloud Native Buildpacks image build #27) registry.mode: kindLoad.

Non-goals

• Replacing remote registry auth sync (--sync-registry-auth); complementary.
• Running a full in-cluster / localhost registry as a required dependency in v1 (optional Phase 2; see below).
• Building images (see proposal: optional Dockerfile / Buildx image build #26 / proposal: optional Cloud Native Buildpacks image build #27); this issue is load only.
• Loading into non-localkube / remote clusters.

Proposed design

User experience (v1)

# Load from local Docker/Podman daemon (or tar / pullable ref)
deployah cluster load-image myapp:dev
deployah cluster load-image myapp:dev ghcr.io/acme/api:1.2.0 ./api.tar

# Optional: every component image in the spec for an environment
deployah cluster load-image --from-spec -e local

Aliases worth considering: deployah cluster load, deployah image load.

Behavior

1. Resolve local cluster (same naming as cluster up / status).
2. For each ref, call Manager.LoadImage (resolution order already: file → daemon → registry).
3. Stream progress with existing steps (resolving-image, loading-image).
4. On success, print that the tag is available to pods; remind about imagePullPolicy when tag is latest.
5. --from-spec: parse spec + env, collect unique components.*.image after substitution, load each.

Spec / platform (optional; can follow)

No schema required for the CLI. Later (with #26 / #27):

# deployah.platform.yaml
environments:
  local:
    registry:
      mode: kindLoad   # deploy/build path auto-loads instead of push

v1 can stop at the explicit load-image command; auto-load on deploy can land with build work.

Phase 2 (optional follow-up): local registry container

Some teams want localhost:5000/app:tag and docker push instead of kind load:

• Start a registry sidecar/container when cluster up --registry (or always).
• Wire containerd/kind mirrors or document localhost:5000 + insecure config.
• Heavier than load-image; not required if daemon load covers the main pain.

Track Phase 2 here or split later if scope grows.

Failure modes

• No local cluster → error pointing at deployah cluster up.
• Image not in daemon and not pullable → joined daemon+registry error from imageref.
• Partial multi-image load → fail fast with list of completed (preferred).
• Pod still ErrImagePull with :latest + Always → document IfNotPresent / digests / non-latest tags.

Alternatives considered

1. Document kind load docker-image only. Breaks one-binary / no-kind-CLI story; Deployah already embeds the load path.
2. Only --sync-registry-auth + push to a remote registry. Works for CI-like flows; slow for tight local loops.
3. Always run a local registry. More moving parts; good Phase 2, not the smallest fix.
4. Auto-load on every deploy without a command. Convenient but surprising/slow; better after explicit load ships.

Compatibility and migration

• Additive CLI under deployah cluster.
• No change to remote deploys.
• Related: proposal: optional Dockerfile / Buildx image build #26 / proposal: optional Cloud Native Buildpacks image build #27 (kindLoad), localkube LoadImage APIs, skills catalog (proposal: Agent Skills catalog and deployah skills install #28).

Test plan

• Unit/integration: CLI calls LoadImage with expected cluster name and refs
• Manual: docker build -t myapp:dev . → deployah cluster load-image myapp:dev → deploy with image: myapp:dev succeeds without registry
• Manual: load from .tar
• Docs: local cluster section; imagePullPolicy / tag guidance
• --from-spec smoke with multi-component project

Checklist

• I searched existing issues and discussions
• This includes enough design detail for implementation (not only a wish)

[atkrad]

Cross-link: Kind-based e2e harness is tracked in #37 (follow-ups #38–#41).

Once that lands, prefer adding live load-image → deploy smoke on that suite instead of one-off manual Kind checks. #41 may also reuse LoadImage (via this CLI) to pin/preload the e2e workload image and cut registry flakes.