dev-controller-and-translator

Implements or modifies Go operator reconciliation loops in internal/controller/, Slurm REST polling and event deduplication, JobSet translation, ClientMap and JWT token management, and Prometheus metric instruments. Use when changing how Slurm jobs are polled, translated into JobSets, unheld, preempted, or torn down in Go source code. Don't use for Slurm Lua submission plugins (use dev-slurm-lua), CRD schema or Helm template changes (use dev-api-and-codegen), deploying or upgrading the operator chart in a cluster (use infra-deploy-stack), or writing unit/E2E test suites (use test-unit-and-lint or test-e2e-cluster).

Jump to install Review files

Repository: GoogleCloudPlatform/k8s-bridge
Last source activity: November 3, 2026 at 10:55
Detected SKILL.md language: English
Stars: 17
Forks: 7

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install only the Agent Skill at https://github.com/GoogleCloudPlatform/k8s-bridge/tree/main/skills/dev-controller-and-translator.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/GoogleCloudPlatform/k8s-bridge --skill dev-controller-and-translator

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

SKILL.md

Source instructions · Read-only preview

name: dev-controller-and-translator
description: Implements or modifies Go operator reconciliation loops in internal/controller/, Slurm REST polling and event deduplication, JobSet translation, ClientMap and JWT token management, and Prometheus metric instruments. Use when changing how Slurm jobs are polled, translated into JobSets, unheld, preempted, or torn down in Go source code. Don't use for Slurm Lua submission plugins (use dev-slurm-lua), CRD schema or Helm template changes (use dev-api-and-codegen), deploying or upgrading the operator chart in a cluster (use infra-deploy-stack), or writing unit/E2E test suites (use test-unit-and-lint or test-e2e-cluster).

# Controller, Poller, and JobSet Translator Workflow (`dev-controller-and-translator`) ## 1. Preconditions & Inputs Before editing Go controller, translator, or metrics packages, inspect the target package in `cmd/` or `internal/`: - `cmd/main.go`: Manager entrypoint, CLI flags, event channels, and runnable registration. - `internal/clientmap/` & `internal/controller/slurmclientsync/`: `ClientMap` and `SlurmClientReconciler` (JWT minting/refresh). - `internal/controller/workloadmixing/`: `WorkloadMixingReconciler` (Slinky `Controller`/`RestApi` validation). - `internal/controller/slurmjob/`: `SlurmPoller` (`poller.go`), `SlurmJobReconciler` (`slurmjob_controller.go`), `JobSetTranslator` (`translator.go`), `JobTeardownReconciler` (`teardown_reconciler.go`), and cleanup utilities (`slurm_utils.go`). - `internal/metrics/metrics.go`: Prometheus metrics (paired with `README.md` `## Metrics & Monitoring`). --- ## 2. Guardrails - **Check nil, `Set`, and `Infinite` on Slurm OpenAPI `JobInfo` fields:** Follow the `*NoValStruct` field-checking pattern in `resolveReplicas` and `resolvePodResources` (`internal/controller/slurmjob/translator.go`). - **Preserve workqueue key deduplication (`slurm-job-<wmName>-<jobID>`):** Keep `SlurmPoller` `GenericEvent` keys and `JobSet` informer mapping (`Start`, `mapJobSetToRequest`, `parseRequestName` in `slurmjob_controller.go`) aligned on `slurm-job-<wmName>-<jobID>`. - **Keep `SlurmPoller` channel sends non-blocking:** Never block on admission or teardown channels in `poller.go` (record drops via `k8s_bridge_dropped_events_total`). - **Finalize `JobSet` before `r.Delete(ctx, js)`:** In `teardown_reconciler.go` and `slurmjob_controller.go`, run `finalizeJobSet` (`slurm_utils.go`) to delete Slurm nodes and remove `FinalizerJobSet` **before** calling `r.Delete(ctx, js)`. --- ## 3. Step-by-Step Procedure > **Component Selection:** Open and modify only the package(s) matching your task: 1. **Slurm REST Client Sync & `WorkloadMixing` Status (`internal/controller/slurmclientsync/`, `internal/controller/workloadmixing/`):** - In `slurmclient_controller.go`, keep `slurmclient` informer caching disabled (`DisableFor` live Slurm types) and refresh JWTs in `ClientMap` ahead of expiry. - In `workloadmixing_controller.go`, validate both the Slinky `Controller` CR and matching `RestApi` CR (`spec.controllerRef`) before setting `Available=True`. 2. **Polling, Admission, Reconciliation & Teardown (`internal/controller/slurmjob/`):** - In `poller.go`, poll once per unique Slinky `ControllerRef` per tick and skip finalized `JobSet`s. - In `slurmjob_controller.go` and `slurm_utils.go`, preserve explicit user/admin hold deferral (`isJobExplicitlyHeld` in `translator.go`), idempotent `JobSet` creation, `JobTranslationFailed` events, and deleting-`JobSet` finalization when the Slurm job, `WorkloadMixing`, or `Controller` is gone (`fetchState` / `releaseFinalizerForDeletingJobSet`). 3. **`JobSet` Translation (`internal/controller/slurmjob/translator.go`):** - Keep `Label*` and `FinalizerJobSet` constants in `translator.go` as the single source of truth (select `JobSet`s/pods by `LabelSlurmJobID` rather than lossy `LabelSlurmJobName`; see `slurmJobNameLabelValue`). - Preserve `podTemplate` merge and injection semantics in `resolvePodResources`, `mergeContainerResources`, `injectSlurmVolumes`, `appendSlurmdArgs`, `injectPreStopHook`, and `injectSlurmdProbes` in `translator.go`. 4. **Prometheus Metrics (`internal/metrics/metrics.go`):** - Register metrics with `metricNamespace` and low-cardinality `label*` constants in `init()`, update `Delete*Metrics` cleanup helpers, and sync `README.md` (`## Metrics & Monitoring`). --- ## 4. Verification 1. **Automated verification (default for agents):** Run code generation, formatting, static analysis, and the unit/`envtest` suite: ```bash make manifests generate fmt vet lint test ``` 2. **Host-to-cluster debug mode (only when requested for live cluster debugging):** Port-forward `svc/slurm-restapi:6820` and run `go run ./cmd/main.go --debug --metrics-bind-address=0` (`--debug` rewrites `slurmrestd` URLs in `SlurmClientReconciler` to `http://localhost:6820`). --- ## 5. Handoffs & Related Skills - **To write unit tests or `slurmclient` mocks for your changes:** Read [skills/test-unit-and-lint/SKILL.md](../test-unit-and-lint/SKILL.md). - **To deploy or upgrade the operator chart in a cluster:** Read [skills/infra-deploy-stack/SKILL.md](../infra-deploy-stack/SKILL.md). - **To run the full-stack Kind or GKE GPU E2E suite:** Read [skills/test-e2e-cluster/SKILL.md](../test-e2e-cluster/SKILL.md). - **If you modified CRD types or `+kubebuilder:rbac` markers:** Read [skills/dev-api-and-codegen/SKILL.md](../dev-api-and-codegen/SKILL.md).

View on GitHub

Back to search Back to installation

dev-api-and-codegen

Adds or modifies Kubernetes Custom Resource Definition (CRD) Go types in api/, Kubebuilder validation markers, RBAC annotations, Kustomize bases, and Helm chart templates, values, and CRD schemas; regenerates manifests, ClusterRoles, and DeepCopy methods via make manifests and make generate; and audits pre-PR repository parity across config/, helm/, VERSION, and docs/examples/ YAMLs. Use when changing WorkloadMixing API struct fields, updating CRD validation or RBAC permissions, editing Helm/Kustomize packaging templates, or verifying zero codegen and manifest drift before a pull request. Don't use for implementing Go controller reconciliation logic (use dev-controller-and-translator), Slurm Lua scripts (use dev-slurm-lua), or running unit/E2E test suites (use test-unit-and-lint or test-e2e-cluster).

2026-11-03

dev-slurm-lua

Implements, modifies, and tests the Slurm Lua plugins (hack/job_submit.lua and hack/cli_filter.lua) that validate CLI options, place jobs on bridged partitions into auto-hold, and protect k8s-bridge job constraints. Use when adding allowed Slurm CLI flags, changing job submission or modification interception rules in Lua, or testing plugin behavior with non-root users. Don't use for Go controller or JobSet translator changes (use dev-controller-and-translator) or cluster partition mapping configuration (use infra-configure-crs).

2026-11-03

infra-configure-crs

Configures, applies, and removes all workload-mixing Custom Resources (CRs) and Slurm partitions for CPU, GPU, priority, and GKE CCC workloads: Kueue CRs (ResourceFlavor, ClusterQueue, LocalQueue, WorkloadPriorityClass), GKE ComputeClass CRs, Slinky slurm Helm release (slurm-values.yaml and Lua plugins), WorkloadMixing CRs, non-root user verification, and job submission checks. Use when deploying, updating, or removing Slurm partitions, Kueue queues, priority classes, or typed/untyped GPU mappedResources. Don't use for creating cloud clusters or node pools (use infra-provision-cluster), installing and tearing down the base operators (use infra-deploy-stack), or diagnosing stuck workloads and cleaning up wedged state (use ops-diagnose-workload or ops-cleanup-state).

2026-11-03

View all from this repository

dev-controller-and-translator

Source facts

Install options

Install with an AI assistant

Review the source files

More from this repository

Install with an AI assistant

More from this repository