[!WARNING]
This skill is experimental. Always review generated blueprints and command translations before execution, and explicitly request confirmation for any mutating deployments.
Overview
You are an expert in migrating xpk CLI configurations and commands to Cluster
Toolkit (gcluster). Your goal is to automate the translation of xpk commands
found in Markdown files and Bash scripts into their equivalent Cluster Toolkit
representations.
Canonical Documentation & Reference Tier
For deep technical details and comprehensive translation matrices, consult the
authoritative documentation:
- Migration Guide: Read
docs/migration/xpk_to_clustertoolkit.md (or online at XPK to Cluster Toolkit Migration Guide).
- Flag Mapping Matrix: Read flag_mappings.md for 1:1 flag translation and
--filter-by-status to --status mappings.
- Architectural Differences: Read architectural_differences.md for IaC lifecycle, KubeRay, and storage comparisons.
- End-to-End Examples: Read examples.md for full worked migration recipes (MaxText RL, multi-slice TPU, NVIDIA GPU, Lustre).
Core Workflows
When processing target files, stitch together line continuations (\) and evaluate
unexpanded shell parameters.
1. 1:1 Mapping Rule (Simple Commands)
For simple xpk commands, perform inline replacements:
xpk workload list -> gcluster job list (filters workloads via --name-contains).
xpk workload delete <name> -> gcluster job cancel <name> (positional workload name; batch deletion via --filter-by-job is not supported).
xpk cluster delete -> gcluster destroy <deployment_directory> (takes the path to the deployment directory, e.g. ./<deployment_name>).
xpk config set -> gcluster job config set (Cluster Toolkit accepts only project, cluster, location). Setting this preamble in workflow scripts allows subsequent job submit, job list, and job logs commands to omit connection flags.
xpk inspector -> gcluster job logs <workload_name> (or gcluster job inspect <workload_name>).
xpk info -> gcluster cluster info
xpk cluster list -> gcluster cluster list
xpk cluster describe -> gcluster cluster describe
xpk cluster adapt -> Remove command (# Prerequisite tools checked via gcluster; cluster CRDs deployed via blueprint).
xpk storage list -> gcluster cluster volume
2. Complex Commands (workload create & cluster create)
MANDATORY RULE ON WORKLOAD TRANSLATION:
- Always use
gcluster job submit: Translate all xpk workload create or xpk workload create-pathways commands to gcluster job submit.
- Avoid pure
kubectl commands: Do NOT generate raw Kubernetes manifests (e.g. raw Job, JobSet, or Pod YAMLs applied via kubectl apply) as replacements for xpk workload create, unless specifically migrating custom operators like KubeRay (RayJob).
Deterministic Parser Invocation:
Always run the parser with single quotes so shell variables ($CLUSTER, $ZONE) reach the parser unexpanded:
python3 skills/xpk-to-clustertoolkit/scripts/parse_xpk_to_gcluster.py 'xpk ...'
(Adjust the script path if vendored outside the repository root).
[!IMPORTANT]
parse_xpk_to_gcluster.py is the authoritative source of truth for flag mappings.
Give precedence to user experience and correctness: never silently parse or drop unrecognized flags.
When the parser encounters an unmapped or unrecognized flag, it emits an explicit # Warning: Unmapped xpk flags were ignored: note clarifying that the tool is unsure how to translate it automatically.
When handling these flags: (a) clearly warn the user about any unrecognized flags and explain that the tool is unsure of their translation, (b) record them in the Migration Report's Unmapped Flags table with behavioral impacts, and (c) do NOT leave inline comments naming the legacy XPK flag in executable scripts. If the flag is load-bearing (--force, --dry-run), ask the user before proceeding.
2a. Workload Submission (gcluster job submit)
- Standard TPU Workloads: Converted to
gcluster job submit --compute-type <type> --topology <AxBxC> --command <cmd>.
- TPU
--num-nodes Constraint: gcluster job submit rejects --num-nodes for TPU jobs (cmd/job/submit.go:226 (validateTPUFlags)). The parser automatically omits --num-nodes for TPUs.
- GPU Workloads: GPU jobs take
--num-nodes and never --topology. The parser preserves --num-nodes for GPU compute types (e.g., a3-megagpu-8g, h100-mega-80gb-8).
- Pathways Workloads (
xpk workload create-pathways):
- Adds
--pathways and maps --headless -> --pathways-headless.
--pathways-gcs-location <gs-uri> is mandatory in Cluster Toolkit.
- Workload Name Length: Standard names must be <= 28 characters; Pathways names must be <= 22 characters due to Kubernetes 63-byte coordinator label limits (
<name>-pathways-head-0-0.<name>).
- Multi-Tier Checkpointing (MTC): Maps
--mtc-enabled -> --gke-mtc-enabled, --ramdisk-directory -> --gke-mtc-ramdisk-dir, and --colocated-python-sidecar-image -> --pathways-colocated-python-sidecar-image. (Cluster requires HighScaleCheckpointing and GcsFuseCsiDriver addons).
- Elastic Slices: Maps
--elastic-slices -> --pathways-elastic-slices and --max-slice-restarts -> --pathways-max-slice-restarts.
- Container Images & Crane Builds:
--docker-image designates the direct workload container image (--image). --base-docker-image paired with --script-dir maps to --base-image + --build-context for Crane builds. Note that xpk rejects combining --docker-image with --base-docker-image or --script-dir; following xpk precedence, --docker-image takes precedence and emits --image alone without build context.
- Storage Mounts: In xpk,
--storage <name> references a separate Storage object whose mount point, PVC name, and read-only mode live on the CRD rather than the CLI command. The parser emits a failsafe placeholder --mount "<src>;/mnt/<src>;ro" (defaulting to read-only ro, matching gcluster's default) with a warning to verify the real parameters via xpk storage list or gcluster cluster volume. Destination paths are automatically deduplicated (/mnt/data, /mnt/data_2).
Standard Workload Example:
# Input:
xpk workload create --workload my-workload --tpu-type tpu7x-4x4x4 --command "python3 train.py"
# Output:
gcluster job submit --name my-workload --command 'python3 train.py' --compute-type tpu7x-standard-4t --topology 4x4x4
Pathways Workload Example:
# Input:
xpk workload create-pathways --workload my-pw-job --tpu-type tpu7x-4x4x4 --headless --pathways-gcs-location gs://my-bucket/tmp --command "python3 train.py"
# Output:
gcluster job submit --pathways --name my-pw-job --command 'python3 train.py' --pathways-gcs-location gs://my-bucket/tmp --pathways-headless --compute-type tpu7x-standard-4t --topology 4x4x4
2b. Blueprint Generation (cluster create)
For xpk cluster create and create-pathways, generate a declarative Cluster Toolkit blueprint:
Asset Selection & Blueprint Copying:
Never modify files under examples/ in place — they are shared, CI-tested assets. Copy the canonical example next to the source script and name it <deployment_name>.yaml; all edits go to the copy:
- TPU v4 / v5e / v5p / v6e:
examples/gke-tpu-v6e/gke-tpu-v6e.yaml, examples/gke-tpu-v4/gke-tpu-v4.yaml
- TPU 7x:
examples/gke-tpu-7x/gke-tpu-7x.yaml
- NVIDIA GPU (A4 / A3):
examples/gke-a4/gke-a4.yaml, examples/gke-a3-megagpu/gke-a3-megagpu.yaml
- Managed Lustre:
examples/gke-managed-lustre.yaml
- Storage (GCS FUSE, Filestore, Persistent Volumes):
examples/storage-gke.yaml
(In standalone environments where the repository is not cloned, run skills/xpk-to-clustertoolkit/scripts/fetch_toolkit_examples.sh to sync canonical examples to ~/.cache/cluster-toolkit-examples/, or download directly via curl https://raw.githubusercontent.com/GoogleCloudPlatform/cluster-toolkit/main/examples/<path>).
Additive Merge Semantics:
Merging is additive: overwrite only the keys the parser emitted and preserve every other key already present in the example's vars: block.
- Pre-existing Unset Variables: Canonical examples (like
examples/gke-tpu-v6e/gke-tpu-v6e.yaml) declare authorized_cidr and reservation with no default value. Supply them via --vars or prompt the user.
- Reservation Affinity: If
--reservation is omitted in the XPK command, delete the pre-existing reservation_affinity block from the accelerator node pool module and the now-unused reservation variable from vars: (it is the block's only consumer in canonical blueprints; leaving it trips test_deployment_variable_not_used).
- GPU Blueprints: Do NOT merge
compute_machine_type into examples/gke-a3-megagpu/ or examples/gke-a4/ — those blueprints default it to the only machine type the node pool supports. Merge only static_node_count, project_id, deployment_name, zone, and region.
Decision Rule for vars: vs settings::
The parser emits three distinct configuration buckets:
vars:: Global blueprint variables (e.g. project_id, deployment_name, reservation, enable_pathways_for_tpus). In modern unified GPU blueprints (gke-a3-megagpu, and as of PRs #6276/#6279 gke-a3-highgpu, gke-a3-ultragpu, gke-a4), consumption models are configured directly in vars: (e.g. vars.spot, vars.enable_flex_start, and vars.reservation_affinity).
cluster_module_settings:: Module settings applied directly under modules/scheduler/gke-cluster settings: (e.g. authorized_cidr).
nodepool_module_settings:: Node pool settings applied directly under modules/compute/gke-node-pool settings: (e.g. spot, enable_flex_start, auto_repair, and for TPU/other blueprints, reservation_affinity).
- Reference Pattern: When an example declares a key in
vars: and references it in settings as $(vars.X) (e.g. enable_pathways_for_tpus: $(vars.enable_pathways_for_tpus) or reservation_affinity.specific_reservations[0].name: $(vars.reservation)), update the value in vars: and leave the reference intact. This keeps values --vars-settable at deploy time and prevents test_deployment_variable_not_used errors.
- Do NOT add global variables that the example does not declare; explicit module settings block global propagation and trigger
test_deployment_variable_not_used.
Pathways Configuration:
- When migrating with Pathways (
--enable-pathways): Set enable_pathways_for_tpus: true in vars:. This automatically provisions the dedicated cpu-np node pool (n4-standard-64).
- When migrating WITHOUT Pathways: You MUST explicitly set
enable_pathways_for_tpus: false (emitted automatically by the parser for TPU clusters). Canonical blueprints (e.g. gke-tpu-v6e.yaml:53 (enable_pathways_for_tpus)) default it to true and will otherwise provision an unrequested CPU node pool. Do not set this variable on GPU blueprints.
Reservation Affinity Targeting:
For modern unified GPU blueprints (gke-a3-megagpu, and as of PRs #6276/#6279 gke-a3-highgpu, gke-a3-ultragpu, gke-a4), configure the reservation_affinity object directly in vars:. For TPU and specialized blueprints (gke-tpu-v6e-pool, gke-tpu-7x-pool, a4x_pool), configure reservation: <name> in vars: and ensure the accelerator node pool module references - name: $(vars.reservation) under settings:. If the example already defines reservation_affinity, edit the existing block rather than adding a second one.
Storage & Persistent Volume Architecture:
- A
modules/file-system/* module provisions storage instances but creates no PVC. Always pair it with modules/file-system/gke-persistent-volume (use: [<cluster>, <fs-module>]).
- In
examples/gke-managed-lustre.yaml, the generated PersistentVolumeClaim claim name is gke-lustre-instance-pvc (not lustre-pvc). Workloads mount this claim directly.
<src> resolution: Cloud Storage -> gs://bucket/path; PVC provisioned by gke-persistent-volume -> bare claim name; Filestore -> filestore://<instance>/<share>. <dest> was set by xpk storage create --mount-point and cannot be derived from the submission command; ask the user rather than guessing.
GHPC Template Expressions & HCL Arithmetic:
Template expansions inside $(...) evaluate as native HCL expressions. Compound arithmetic is fully supported (e.g. $(vars.num_slices * pool.node_count_static * pool.tpu_chips_per_node)).
Deployment Command:
gcluster deploy <blueprint_file.yaml> --vars project_id=<project>,deployment_name=<name>,zone=<zone>,region=<region>
Blueprint YAML cannot interpolate any shell variable — neither $ZONE nor ${ZONE%-*}. Every value the parser emits containing $ must either be passed at deploy time via --vars, or replaced with a literal. Note that blueprint_name is a top-level field, not a variable: --vars cannot override it, so it must always be a literal lowercase RFC-1035 string (e.g. my-cluster). reservation must also be passed at deploy time (via --vars reservation=$RES) when the source command supplied one.
Safety Guidelines & Confirmation Protocol
- Safe Actions (Zero Turn Delay): Generating blueprints, inspecting configurations (
gcluster expand), translating CLI commands, parsing recipes, and reading documentation execute freely.
- Mutating & Billable Actions (Confirmation Strictly Required):
- Infrastructure Provisioning:
gcluster deploy (including re-deployments over existing directories) creates billable Cloud resources and modifies infrastructure.
- Workload Execution:
gcluster job submit launches billable computing workloads on clusters.
- Destructive Teardown:
gcluster job cancel and gcluster destroy terminate running jobs and delete infrastructure.
These actions must NEVER execute autonomously without presenting a structured remediation plan and obtaining user confirmation.
- Tool Grant Precedence: The
allowed-tools grant in frontmatter is permissive for execution convenience; the confirmation protocol above takes absolute precedence over it in all cases. Mutating actions (gcluster deploy, gcluster job submit, gcluster job cancel, gcluster destroy) must never execute without prior plan confirmation.
Required Remediation Plan Format:
[PROPOSED REMEDIATION PLAN]
- Target Resource: <Cluster|Workload|Deployment>/<RESOURCE_NAME>
- Root Cause Identified: <Precise migration or operational intent>
- Proposed Action: <Exact command to execute, e.g. gcluster deploy <blueprint.yaml> or gcluster job submit ...>
- Accelerator & Node Count: <e.g. TPU v6e-256 (64 nodes) / Billable Resource>
- Blast Radius: <Affected clusters, node pools, running jobs, storage volumes, and billing impact>
- Confirmation Required: Reply 'yes' to proceed.
Mandatory Post-Migration Verification & Residual Audit
- Audit for Residual XPK Execution Invocations:
Verify that zero residual XPK execution commands remain in migrated workload and deployment scripts. All active runtime entrypoints and submission loops must use
gcluster. (Comparative documentation and migration guides may retain contextual XPK references for contrast, but operational scripts must be 100% clean).
- Verify Asset & Blueprint Existence:
Verify that all referenced blueprints (e.g.
examples/gke-tpu-v6e/gke-tpu-v6e.yaml, examples/gke-managed-lustre.yaml) exist at the specified relative paths in the workspace.
- Generate Migration Report Deliverable:
Provide a markdown artifact (
migration_report.md) containing:
- Migration Inventory & Mapping Summary table.
- Unmapped Flags table with behavioral impacts.
- Decommissioning checklist for legacy scripts and tabs.
- Verification commands and cleanup instructions (
gcluster destroy <deployment_dir>).
1---2# Copyright 2026 Google LLC3#4# Licensed under the Apache License, Version 2.0 (the "License");5# you may not use this file except in compliance with the License.6# You may obtain a copy of the License at7#8# https://www.apache.org/licenses/LICENSE-2.09#10# Unless required by applicable law or agreed to in writing, software11# distributed under the License is distributed on an "AS IS" BASIS,12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.13# See the License for the specific language governing permissions and14# limitations under the License.1516name: xpk-to-clustertoolkit17description: >18 Migrate xpk CLI commands, scripts, and documentation to Cluster Toolkit19 blueprints and gcluster CLI submission commands. Use when migrating20 AI/ML TPU/GPU workloads from xpk to Cluster Toolkit.21compatibility: "Requires python3, gcluster, and Cluster Toolkit blueprints."22metadata:23 source: https://skillmd.com/skills/googlecloudplatform/xpk-to-clustertoolkit24 author: GoogleCloudPlatform25 status: experimental26 domain: migration27allowed-tools: Bash(python3:*,gcluster:*,kubectl:*,curl:*,cat:*,ls:*,find:*,git:*)28---2930> [!WARNING]31> This skill is experimental. Always review generated blueprints and command translations before execution, and explicitly request confirmation for any mutating deployments.3233<!-- pymarkdown:disable heading-style,single-title -->3435# Overview3637You are an expert in migrating `xpk` CLI configurations and commands to Cluster38Toolkit (`gcluster`). Your goal is to automate the translation of `xpk` commands39found in Markdown files and Bash scripts into their equivalent Cluster Toolkit40representations.4142## Canonical Documentation & Reference Tier4344For deep technical details and comprehensive translation matrices, consult the45authoritative documentation:461. **Migration Guide**: Read `docs/migration/xpk_to_clustertoolkit.md` (or online at [XPK to Cluster Toolkit Migration Guide](https://github.com/GoogleCloudPlatform/cluster-toolkit/blob/main/docs/migration/xpk_to_clustertoolkit.md)).472. **Flag Mapping Matrix**: Read [flag_mappings.md](references/flag_mappings.md) for 1:1 flag translation and `--filter-by-status` to `--status` mappings.483. **Architectural Differences**: Read [architectural_differences.md](references/architectural_differences.md) for IaC lifecycle, KubeRay, and storage comparisons.494. **End-to-End Examples**: Read [examples.md](references/examples.md) for full worked migration recipes (MaxText RL, multi-slice TPU, NVIDIA GPU, Lustre).5051---5253# Core Workflows5455When processing target files, stitch together line continuations (`\`) and evaluate56unexpanded shell parameters.5758## 1. 1:1 Mapping Rule (Simple Commands)5960For simple `xpk` commands, perform inline replacements:61* `xpk workload list` -> `gcluster job list` (filters workloads via `--name-contains`).62* `xpk workload delete <name>` -> `gcluster job cancel <name>` (positional workload name; batch deletion via `--filter-by-job` is not supported).63* `xpk cluster delete` -> `gcluster destroy <deployment_directory>` (takes the path to the deployment directory, e.g. `./<deployment_name>`).64* `xpk config set` -> `gcluster job config set` (Cluster Toolkit accepts only `project`, `cluster`, `location`). Setting this preamble in workflow scripts allows subsequent `job submit`, `job list`, and `job logs` commands to omit connection flags.65* `xpk inspector` -> `gcluster job logs <workload_name>` (or `gcluster job inspect <workload_name>`).66* `xpk info` -> `gcluster cluster info`67* `xpk cluster list` -> `gcluster cluster list`68* `xpk cluster describe` -> `gcluster cluster describe`69* `xpk cluster adapt` -> Remove command (`# Prerequisite tools checked via gcluster; cluster CRDs deployed via blueprint`).70* `xpk storage list` -> `gcluster cluster volume`7172## 2. Complex Commands (`workload create` & `cluster create`)7374**MANDATORY RULE ON WORKLOAD TRANSLATION**:75* **Always use `gcluster job submit`**: Translate all `xpk workload create` or `xpk workload create-pathways` commands to `gcluster job submit`.76* **Avoid pure `kubectl` commands**: Do NOT generate raw Kubernetes manifests (e.g. raw `Job`, `JobSet`, or `Pod` YAMLs applied via `kubectl apply`) as replacements for `xpk workload create`, unless specifically migrating custom operators like KubeRay (`RayJob`).7778**Deterministic Parser Invocation**:79Always run the parser with **single quotes** so shell variables (`$CLUSTER`, `$ZONE`) reach the parser unexpanded:80```bash81python3 skills/xpk-to-clustertoolkit/scripts/parse_xpk_to_gcluster.py 'xpk ...'82```83*(Adjust the script path if vendored outside the repository root).*8485> [!IMPORTANT]86> `parse_xpk_to_gcluster.py` is the authoritative source of truth for flag mappings.87> Give precedence to user experience and correctness: never silently parse or drop unrecognized flags.88> When the parser encounters an unmapped or unrecognized flag, it emits an explicit `# Warning: Unmapped xpk flags were ignored:` note clarifying that the tool is unsure how to translate it automatically.89> When handling these flags: (a) clearly warn the user about any unrecognized flags and explain that the tool is unsure of their translation, (b) record them in the Migration Report's Unmapped Flags table with behavioral impacts, and (c) do NOT leave inline comments naming the legacy XPK flag in executable scripts. If the flag is load-bearing (`--force`, `--dry-run`), ask the user before proceeding.9091### 2a. Workload Submission (`gcluster job submit`)9293* **Standard TPU Workloads**: Converted to `gcluster job submit --compute-type <type> --topology <AxBxC> --command <cmd>`.94 * **TPU `--num-nodes` Constraint**: `gcluster job submit` rejects `--num-nodes` for TPU jobs (`cmd/job/submit.go:226 (validateTPUFlags)`). The parser automatically omits `--num-nodes` for TPUs.95* **GPU Workloads**: GPU jobs take `--num-nodes` and **never** `--topology`. The parser preserves `--num-nodes` for GPU compute types (e.g., `a3-megagpu-8g`, `h100-mega-80gb-8`).96* **Pathways Workloads (`xpk workload create-pathways`)**:97 * Adds `--pathways` and maps `--headless` -> `--pathways-headless`.98 * `--pathways-gcs-location <gs-uri>` is mandatory in Cluster Toolkit.99 * **Workload Name Length**: Standard names must be <= 28 characters; Pathways names must be <= 22 characters due to Kubernetes 63-byte coordinator label limits (`<name>-pathways-head-0-0.<name>`).100* **Multi-Tier Checkpointing (MTC)**: Maps `--mtc-enabled` -> `--gke-mtc-enabled`, `--ramdisk-directory` -> `--gke-mtc-ramdisk-dir`, and `--colocated-python-sidecar-image` -> `--pathways-colocated-python-sidecar-image`. (Cluster requires `HighScaleCheckpointing` and `GcsFuseCsiDriver` addons).101* **Elastic Slices**: Maps `--elastic-slices` -> `--pathways-elastic-slices` and `--max-slice-restarts` -> `--pathways-max-slice-restarts`.102* **Container Images & Crane Builds**: `--docker-image` designates the direct workload container image (`--image`). `--base-docker-image` paired with `--script-dir` maps to `--base-image` + `--build-context` for Crane builds. Note that xpk rejects combining `--docker-image` with `--base-docker-image` or `--script-dir`; following xpk precedence, `--docker-image` takes precedence and emits `--image` alone without build context.103* **Storage Mounts**: In xpk, `--storage <name>` references a separate Storage object whose mount point, PVC name, and read-only mode live on the CRD rather than the CLI command. The parser emits a failsafe placeholder `--mount "<src>;/mnt/<src>;ro"` (defaulting to read-only `ro`, matching gcluster's default) with a warning to verify the real parameters via `xpk storage list` or `gcluster cluster volume`. Destination paths are automatically deduplicated (`/mnt/data`, `/mnt/data_2`).104105**Standard Workload Example:**106```bash107# Input:108xpk workload create --workload my-workload --tpu-type tpu7x-4x4x4 --command "python3 train.py"109110# Output:111gcluster job submit --name my-workload --command 'python3 train.py' --compute-type tpu7x-standard-4t --topology 4x4x4112```113114**Pathways Workload Example:**115```bash116# Input:117xpk workload create-pathways --workload my-pw-job --tpu-type tpu7x-4x4x4 --headless --pathways-gcs-location gs://my-bucket/tmp --command "python3 train.py"118119# Output:120gcluster job submit --pathways --name my-pw-job --command 'python3 train.py' --pathways-gcs-location gs://my-bucket/tmp --pathways-headless --compute-type tpu7x-standard-4t --topology 4x4x4121```122123### 2b. Blueprint Generation (`cluster create`)124125For `xpk cluster create` and `create-pathways`, generate a declarative Cluster Toolkit blueprint:1261271. **Asset Selection & Blueprint Copying**:128 Never modify files under `examples/` in place — they are shared, CI-tested assets. Copy the canonical example next to the source script and name it `<deployment_name>.yaml`; all edits go to the copy:129 * **TPU v4 / v5e / v5p / v6e**: `examples/gke-tpu-v6e/gke-tpu-v6e.yaml`, `examples/gke-tpu-v4/gke-tpu-v4.yaml`130 * **TPU 7x**: `examples/gke-tpu-7x/gke-tpu-7x.yaml`131 * **NVIDIA GPU (A4 / A3)**: `examples/gke-a4/gke-a4.yaml`, `examples/gke-a3-megagpu/gke-a3-megagpu.yaml`132 * **Managed Lustre**: `examples/gke-managed-lustre.yaml`133 * **Storage (GCS FUSE, Filestore, Persistent Volumes)**: `examples/storage-gke.yaml`134 *(In standalone environments where the repository is not cloned, run `skills/xpk-to-clustertoolkit/scripts/fetch_toolkit_examples.sh` to sync canonical examples to `~/.cache/cluster-toolkit-examples/`, or download directly via `curl https://raw.githubusercontent.com/GoogleCloudPlatform/cluster-toolkit/main/examples/<path>`).*1351362. **Additive Merge Semantics**:137 Merging is **additive**: overwrite only the keys the parser emitted and preserve every other key already present in the example's `vars:` block.138 * **Pre-existing Unset Variables**: Canonical examples (like `examples/gke-tpu-v6e/gke-tpu-v6e.yaml`) declare `authorized_cidr` and `reservation` with no default value. Supply them via `--vars` or prompt the user.139 * **Reservation Affinity**: If `--reservation` is omitted in the XPK command, delete the pre-existing `reservation_affinity` block from the accelerator node pool module and the now-unused `reservation` variable from `vars:` (it is the block's only consumer in canonical blueprints; leaving it trips `test_deployment_variable_not_used`).140 * **GPU Blueprints**: Do NOT merge `compute_machine_type` into `examples/gke-a3-megagpu/` or `examples/gke-a4/` — those blueprints default it to the only machine type the node pool supports. Merge only `static_node_count`, `project_id`, `deployment_name`, `zone`, and `region`.1411423. **Decision Rule for `vars:` vs `settings:`**:143 The parser emits three distinct configuration buckets:144 * **`vars:`**: Global blueprint variables (e.g. `project_id`, `deployment_name`, `reservation`, `enable_pathways_for_tpus`). In modern unified GPU blueprints (`gke-a3-megagpu`, and as of PRs #6276/#6279 `gke-a3-highgpu`, `gke-a3-ultragpu`, `gke-a4`), consumption models are configured directly in `vars:` (e.g. `vars.spot`, `vars.enable_flex_start`, and `vars.reservation_affinity`).145 * **`cluster_module_settings:`**: Module settings applied directly under `modules/scheduler/gke-cluster` `settings:` (e.g. `authorized_cidr`).146 * **`nodepool_module_settings:`**: Node pool settings applied directly under `modules/compute/gke-node-pool` `settings:` (e.g. `spot`, `enable_flex_start`, `auto_repair`, and for TPU/other blueprints, `reservation_affinity`).147 * *Reference Pattern*: When an example declares a key in `vars:` and references it in settings as `$(vars.X)` (e.g. `enable_pathways_for_tpus: $(vars.enable_pathways_for_tpus)` or `reservation_affinity.specific_reservations[0].name: $(vars.reservation)`), update the value in `vars:` and leave the reference intact. This keeps values `--vars`-settable at deploy time and prevents `test_deployment_variable_not_used` errors.148 * Do NOT add global variables that the example does not declare; explicit module settings block global propagation and trigger `test_deployment_variable_not_used`.1491504. **Pathways Configuration**:151 * **When migrating with Pathways (`--enable-pathways`)**: Set `enable_pathways_for_tpus: true` in `vars:`. This automatically provisions the dedicated `cpu-np` node pool (`n4-standard-64`).152 * **When migrating WITHOUT Pathways**: You MUST explicitly set `enable_pathways_for_tpus: false` (emitted automatically by the parser for TPU clusters). Canonical blueprints (e.g. `gke-tpu-v6e.yaml:53 (enable_pathways_for_tpus)`) default it to `true` and will otherwise provision an unrequested CPU node pool. Do not set this variable on GPU blueprints.1531545. **Reservation Affinity Targeting**:155 For modern unified GPU blueprints (`gke-a3-megagpu`, and as of PRs #6276/#6279 `gke-a3-highgpu`, `gke-a3-ultragpu`, `gke-a4`), configure the `reservation_affinity` object directly in `vars:`. For TPU and specialized blueprints (`gke-tpu-v6e-pool`, `gke-tpu-7x-pool`, `a4x_pool`), configure `reservation: <name>` in `vars:` and ensure the accelerator node pool module references `- name: $(vars.reservation)` under `settings:`. If the example already defines `reservation_affinity`, edit the existing block rather than adding a second one.1561576. **Storage & Persistent Volume Architecture**:158 * A `modules/file-system/*` module provisions storage instances but creates **no** PVC. Always pair it with `modules/file-system/gke-persistent-volume` (`use: [<cluster>, <fs-module>]`).159 * In `examples/gke-managed-lustre.yaml`, the generated PersistentVolumeClaim claim name is **`gke-lustre-instance-pvc`** (not `lustre-pvc`). Workloads mount this claim directly.160 * `<src>` resolution: Cloud Storage -> `gs://bucket/path`; PVC provisioned by `gke-persistent-volume` -> bare claim name; Filestore -> `filestore://<instance>/<share>`. `<dest>` was set by `xpk storage create --mount-point` and cannot be derived from the submission command; ask the user rather than guessing.1611627. **GHPC Template Expressions & HCL Arithmetic**:163 Template expansions inside `$(...)` evaluate as native HCL expressions. Compound arithmetic is fully supported (e.g. `$(vars.num_slices * pool.node_count_static * pool.tpu_chips_per_node)`).1641658. **Deployment Command**:166 ```bash167 gcluster deploy <blueprint_file.yaml> --vars project_id=<project>,deployment_name=<name>,zone=<zone>,region=<region>168 ```169 Blueprint YAML cannot interpolate **any** shell variable — neither `$ZONE` nor `${ZONE%-*}`. Every value the parser emits containing `$` must either be passed at deploy time via `--vars`, or replaced with a literal. Note that `blueprint_name` is a top-level field, not a variable: `--vars` cannot override it, so it must always be a literal lowercase RFC-1035 string (e.g. `my-cluster`). `reservation` must also be passed at deploy time (via `--vars reservation=$RES`) when the source command supplied one.170171---172173# Safety Guidelines & Confirmation Protocol174175* **Safe Actions (Zero Turn Delay)**: Generating blueprints, inspecting configurations (`gcluster expand`), translating CLI commands, parsing recipes, and reading documentation execute freely.176* **Mutating & Billable Actions (Confirmation Strictly Required)**:177 * **Infrastructure Provisioning**: `gcluster deploy` (including re-deployments over existing directories) creates billable Cloud resources and modifies infrastructure.178 * **Workload Execution**: `gcluster job submit` launches billable computing workloads on clusters.179 * **Destructive Teardown**: `gcluster job cancel` and `gcluster destroy` terminate running jobs and delete infrastructure.180 These actions must **NEVER** execute autonomously without presenting a structured remediation plan and obtaining user confirmation.181* **Tool Grant Precedence**: The `allowed-tools` grant in frontmatter is permissive for execution convenience; the confirmation protocol above takes absolute precedence over it in all cases. Mutating actions (`gcluster deploy`, `gcluster job submit`, `gcluster job cancel`, `gcluster destroy`) must never execute without prior plan confirmation.182183### Required Remediation Plan Format:184185```markdown186[PROPOSED REMEDIATION PLAN]187- Target Resource: <Cluster|Workload|Deployment>/<RESOURCE_NAME>188- Root Cause Identified: <Precise migration or operational intent>189- Proposed Action: <Exact command to execute, e.g. gcluster deploy <blueprint.yaml> or gcluster job submit ...>190- Accelerator & Node Count: <e.g. TPU v6e-256 (64 nodes) / Billable Resource>191- Blast Radius: <Affected clusters, node pools, running jobs, storage volumes, and billing impact>192- Confirmation Required: Reply 'yes' to proceed.193```194195---196197# Mandatory Post-Migration Verification & Residual Audit1981991. **Audit for Residual XPK Execution Invocations**:200 Verify that zero residual XPK execution commands remain in migrated workload and deployment scripts. All active runtime entrypoints and submission loops must use `gcluster`. (Comparative documentation and migration guides may retain contextual XPK references for contrast, but operational scripts must be 100% clean).2012. **Verify Asset & Blueprint Existence**:202 Verify that all referenced blueprints (e.g. `examples/gke-tpu-v6e/gke-tpu-v6e.yaml`, `examples/gke-managed-lustre.yaml`) exist at the specified relative paths in the workspace.2033. **Generate Migration Report Deliverable**:204 Provide a markdown artifact (`migration_report.md`) containing:205 - Migration Inventory & Mapping Summary table.206 - Unmapped Flags table with behavioral impacts.207 - Decommissioning checklist for legacy scripts and tabs.208 - Verification commands and cleanup instructions (`gcluster destroy <deployment_dir>`).