bootstrap-karmada

name

bootstrap-karmada

description

Safely extract, mirror, initialize, and verify a version-pinned Karmada control plane and optional Dashboard on an existing Kubernetes host cluster. Use when Codex needs to inventory every Karmada image before installation, copy multi-architecture images into a private registry, render manifests with private image references, run karmadactl init, configure offline or China-restricted deployments, or audit an existing Karmada bootstrap plan without exposing registry credentials or kubeconfig contents.

Bootstrap Karmada

Initialize Karmada only after extracting and mirroring the exact image set for a pinned release. Keep registry credentials, kubeconfig contents, certificates, and private keys outside the skill and generated plans.

Safety contract

• Require an exact stable Karmada tag such as v1.17.0; reject latest, branches, and floating tags.
• Clone or unpack the matching official release source, verify its Git tag/commit, then derive Kubernetes, etcd, Karmada, add-on, and Dashboard image references from that source.
• Run image extraction first. Present the complete source-to-destination mapping and wait for review before copying images.
• Preserve all architectures with skopeo copy --all. Read registry authentication only from the user's existing skopeo login state or a permission-restricted auth file. Never accept credentials in command arguments or write them to a plan.
• Verify every destination image before initializing Karmada. Do not fall back silently to an upstream registry.
• Run bootstrap_karmada.py without --apply first. It performs read-only cluster checks and prints a redacted plan. Add --apply only after explicit approval.
• Treat the host-cluster kubeconfig, generated Karmada kubeconfig, PKI, service-account tokens, and image-pull secrets as secrets. Never print, commit, upload, or copy their contents into chat.
• Stop when Karmada workloads already exist. Use an explicit upgrade or recovery workflow instead of re-running initialization.
• Do not initialize a production control plane with one replica and hostPath merely because they are defaults. Obtain the requested availability and storage design.
• Do not expose Dashboard with an unrestricted NodePort or --address 0.0.0.0. Prefer a local port-forward, authenticated ingress, or a controlled private load balancer.
• Never deinitialize Karmada, delete etcd data, unregister member clusters, or remove namespaces without a separate explicit request and reviewed plan.

Collect inputs

Obtain:

• exact Karmada version and official source checkout
• host-cluster kubeconfig path and context
• private registry namespace/project prefix, without a scheme, credentials, or image repository placeholder
• etcd storage mode, replica count, and storage class or host path
• API server replica count, advertise address, certificate IP/DNS, and NodePort requirements
• a local CRD archive from the same Karmada release
• optional pre-created image-pull secret name
• whether add-ons, OpenSearch, Dashboard, or member-cluster registration are in scope
• optional exact Dashboard version and official Dashboard source checkout

Keep deployment-specific values outside the skill directory.

Phase 1: extract images

Clone exact tags without replacing the user's repositories:

git clone --branch v1.17.0 --depth 1 \
  https://github.com/karmada-io/karmada.git \
  /absolute/path/to/karmada-v1.17.0

Extract the core control-plane images and generate a credential-free JSON plan:

python3 scripts/extract_images.py \
  --karmada-source /absolute/path/to/karmada-v1.17.0 \
  --karmada-version v1.17.0 \
  --target-prefix REGISTRY_HOST/NAMESPACE_OR_PROJECT \
  --output /absolute/path/to/karmada-images.json

Add --include-addons, --include-agent, or --include-opensearch only when those components will be deployed. For Dashboard, clone an exact dashboard tag and add:

--dashboard-source /absolute/path/to/dashboard-v0.4.0 \
--dashboard-version v0.4.0 \
--dashboard-kubectl-image registry.k8s.io/kubectl:v1.32.2

Supply the Dashboard kubectl job image explicitly because older tagged charts may reference a removed Bitnami image. Verify the replacement tag before accepting the plan; the generated alias lets the manifest rewriter replace the chart's historical reference without trying to mirror it.

Review every mapping. The destination layout is intentionally flat because karmadactl init --private-image-registry appends component basenames to the supplied prefix. Stop on destination collisions or mutable tags.

Phase 2: mirror and verify

Preview without registry requests or writes:

python3 scripts/mirror_images.py \
  --plan /absolute/path/to/karmada-images.json

Authenticate outside Codex output with skopeo login or a protected auth file, then copy after approval:

python3 scripts/mirror_images.py \
  --plan /absolute/path/to/karmada-images.json \
  --apply

Verify all destinations in a separate read-only pass:

python3 scripts/mirror_images.py \
  --plan /absolute/path/to/karmada-images.json \
  --verify-only

Do not proceed until every destination is readable from the environment that will initialize the cluster. For private pull authentication, pre-create the namespace and pull secret through a separate reviewed Kubernetes operation; pass only its name to the bootstrap script.

Phase 3: preview and initialize

Download the matching karmadactl release archive and checksum from GitHub Releases. Verify the checksum before extracting. Download crds.tar.gz from the same release and retain it as a local input.

Preview the initialization:

python3 scripts/bootstrap_karmada.py \
  --plan /absolute/path/to/karmada-images.json \
  --karmadactl /absolute/path/to/karmadactl \
  --kubectl /absolute/path/to/kubectl \
  --kubeconfig /absolute/path/to/host-cluster.config \
  --context HOST_CONTEXT \
  --crds /absolute/path/to/crds.tar.gz \
  --etcd-storage-mode PVC \
  --storage-class STORAGE_CLASS \
  --etcd-replicas 3 \
  --apiserver-replicas 3

Review the pinned versions, target context, node count, permissions, namespace state, registry prefix, storage mode, replicas, CRD source, and redacted karmadactl init command. Repeat the exact command with --apply only after approval.

For a disposable single-node test cluster, explicitly select one replica and hostPath; never infer this production-unsafe layout.

Optional Dashboard

Read references/dashboard.md when Dashboard is requested. Render the exact tagged Helm chart locally, pin all Dashboard image tags, then rewrite the rendered manifest from the reviewed image plan:

python3 scripts/rewrite_manifest_images.py \
  --plan /absolute/path/to/karmada-images.json \
  --input /absolute/path/to/dashboard-upstream.yaml \
  --output /absolute/path/to/dashboard-private.yaml \
  --require-group dashboard

Run kubectl diff before kubectl apply. Do not store the Karmada kubeconfig directly in version-controlled YAML.

Verify

After initialization, verify without displaying secret data:

kubectl --kubeconfig HOST_CONFIG --context HOST_CONTEXT \
  -n karmada-system get deployments,statefulsets,pods

karmadactl --kubeconfig /absolute/path/to/karmada.config version

Confirm that all workloads are ready and every running container image uses the reviewed private prefix. Report versions, readiness, storage mode, registry prefix, and kubeconfig file locations without reproducing file contents.

Read references/installation.md for release downloads, production/test topology choices, pull secrets, upgrade boundaries, and member-cluster handling. Read references/security-notes.md for workflow hardening and credential-handling requirements.

Failure handling

• If source checkout tag and requested version differ, stop and fetch the correct tag.
• If a source image or destination image is missing, stop before initialization; do not change tags or registries silently.
• If registry authentication fails, repair local login state. Never request a password in chat or add --dest-creds to a logged command.
• If cluster permissions are insufficient, use an approved administrative kubeconfig; do not broaden RBAC automatically.
• If the namespace already contains Karmada control-plane workloads, stop and classify the task as upgrade, repair, or adoption.
• If etcd PVCs remain pending, inspect storage class, topology, and capacity; do not switch to hostPath silently.
• If pods enter ImagePullBackOff, verify the rewritten image name, destination manifest, node network, and pull secret without printing the secret.
• If Dashboard manifests contain an image absent from the plan, regenerate the plan from the exact Dashboard tag rather than allowing an upstream pull.