Skip to content

feat(job): add Layer-1 orchestrator detector and decoupled TypeK8s CLI prerequisites - #6646

Draft
Neelabh94 wants to merge 6 commits into
GoogleCloudPlatform:developfrom
Neelabh94:feat/orchestrator-detector-prereqs
Draft

Neelabh94 wants to merge 6 commits into
GoogleCloudPlatform:developfrom
Neelabh94:feat/orchestrator-detector-prereqs

Conversation

@Neelabh94

@Neelabh94 Neelabh94 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Stacked PR (3 of 3 — Stacked on #6649):

Summary

Decouples gcluster job from hardcoded Google Cloud / GKE workstation prerequisites by introducing provider-registered Layer-1 orchestrator detection and orchestrator-scoped CLI prerequisites while preserving 100% GKE behavior parity.

  • Layer-1 Orchestrator Detector & Provider Registry (pkg/orchestrator/orchestrator.go, pkg/orchestrator/detector.go, pkg/orchestrator/k8s/kubeconfig.go, pkg/orchestrator/gke/kube_auth.go, pkg/orchestrator/gke/k8s_bridge.go):
    • Introduces ProviderSpec registration (Prerequisites, ResolveContext, Probe, Factory) plus k8s.ResolveContext, k8s.ClusterServerHostname (including schemeless host:port entries), and k8s.HasClientCertificateAuth so pkg/orchestrator and pkg/orchestrator/k8s remain provider-agnostic.
    • Evaluates 4-step precedence: GCLUSTER_ORCHESTRATOR (gke | k8s) override -> gke-gcloud-auth-plugin exec credential check (including Windows backslash and .exe paths) -> *.gke.goog API server endpoint check -> bounded 2s kubectl --context <ctx> version -o json --request-timeout=2s check on serverVersion.gitVersion containing -gke. (skipped when air-gapped or using X.509 client-certificate kubeconfigs such as kubeadm / kind) -> TypeK8s.
    • Isolates the temporary TypeK8s registration and context/hint helpers in pkg/orchestrator/gke/k8s_bridge.go, routes cmd/job through (&orchestrator.Detector{}).Detect and orchestrator.NewJobOrchestrator(), switches GKEOrchestrator.isGKE in pkg/orchestrator/gke/telemetry.go to use the detected mode, guards TypeK8s against 0-capacity Kueue ClusterQueue generation when a LocalQueue is absent, and replaces Google Cloud Console URLs with context-pinned gcluster job inspect --name / gcluster job logs / gcluster job cancel (--cluster / --gke-namespace) and kubectl --context hints in TypeK8s mode while keeping in-cluster SPS endpoint logs intact. (Note: migrating the pure-Kubernetes domain files cancel.go, kueue.go, infra_manager.go, manifest_generator.go, and scheduling.go into pkg/orchestrator/k8s behind a provider interface is intentionally staged into a dedicated follow-up PR so this PR stays review-sized.)
  • Decoupled TypeK8s CLI Prerequisites & Saved Context Isolation (pkg/orchestrator/prereqs.go, cmd/job/prereq.go, cmd/job/job.go):
    • BasicPrerequisites queries each provider's registered ProviderSpec.Prerequisites (TypeK8s declares [PrereqKubectl], skipping gcloud, gke-gcloud-auth-plugin, and Google Cloud ADC checks) without cross-mode PrereqState cache poisoning or unexpired GKE tool-cache loss, while preserving --cluster/--location/--project validation on TypeGKE.
    • Isolates saved ~/.gcluster/context.json GKE defaults when GCLUSTER_ORCHESTRATOR=k8s is set or when Detect resolves TypeK8s, clearing non-explicit location/projectID defaults while preserving saved job config resolution for TypeGKE.

Cloud-Docs: none

Testing

  • KUBECONFIG=/dev/null GOOGLE_API_USE_CLIENT_CERTIFICATE=false go test -race -count=1 ./pkg/shell/... ./pkg/orchestrator/... ./pkg/telemetry/... ./cmd/job/...
  • Covers TestResolveContext, TestClusterServerHostname, TestHasClientCertificateAuth, TestProviderRegistryAndFactory, TestRegisterProvider_PanicsOnInvalidSpec, TestDetector_ProviderDispatchAndFallback, TestDetector_EnvOverride, TestRegisteredTypes_IncludesGKEAndK8s, TestDetect_FourStepPrecedenceMatrix, TestDetect_HonorsDefaultEnvironmentAirGappedState, TestBasicPrerequisites, TestTypeK8s_ZeroGCloudAcrossLifecycle, TestTypeK8s_ConfigureKubectlUnseeded, TestTypeK8s_LogsAndConflictHintsOmitCloudConsole, TestTypeK8s_QueueGuardAndCompletionStatus, TestIsGKE_UsesDetectedPlatformMode, TestJobCmd_TypeK8sRequiresOnlyKubeconfigAndZeroGCloud, TestJobCmd_MissingContextAndRequiredGKEFlags, TestJobCmd_MissingClusterNotMaskedByActiveGKEContext, TestJobCmd_TypeK8sSubmitPrebuiltImageZeroFlags, TestJobCmd_SavedGKEConfigDoesNotBreakTypeK8sOrEnvOverride, TestEnsureBasicPrerequisitesFor_NoCrossModeCachePoisoning, and TestEnsureK8sOnlyBasicPrerequisites_MissingKubectl.

@Neelabh94 Neelabh94 added enhancement New feature or request go Pull requests that update Go code release-improvements Added to release notes under the "Improvements" heading. labels Nov 6, 2026
@Neelabh94 Neelabh94 self-assigned this Nov 6, 2026
@gemini-code-assist

Copy link
Copy Markdown
Contributor

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refactors the job orchestration layer to support generic Kubernetes clusters alongside GKE. By introducing a flexible provider-based detection mechanism and decoupling environment prerequisites, the CLI now adapts its behavior based on the detected cluster type. Additionally, it improves OCI registry interaction and packaging logic to support private or air-gapped environments while maintaining full parity for existing GKE workflows.

Highlights

  • Layer-1 Orchestrator Detection: Introduced a provider-registered orchestrator detector that dynamically switches between GKE and generic Kubernetes modes, removing hardcoded GKE prerequisites.
  • Decoupled Prerequisites & Air-Gap Guard: Optimized prerequisite checks to be orchestrator-aware, skipping Google Cloud-specific requirements in K8s mode and short-circuiting telemetry uploads in air-gapped environments.
  • WORKDIR-Aligned OCI Packaging: Enhanced Crane image building to respect base image WORKDIR settings and ensure reproducible tar headers, improving compatibility with diverse OCI registries.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces support for generic and air-gapped Kubernetes (k8s) clusters alongside GKE, allowing users to manage jobs and build container images on non-GCP environments. It implements automatic orchestrator detection, adds configuration options for air-gapped environments (GCLUSTER_AIR_GAPPED) and insecure registries (GCLUSTER_INSECURE_REGISTRY), and updates prerequisite checks to bypass Google Cloud dependencies when in Kubernetes mode. Additionally, the image builder is enhanced to support non-GAR OCI registries with proper working directory alignment and credential verification. Feedback on the changes suggests adding a defensive check in pkg/imagebuilder/crane_builder.go to ensure the retrieved image configuration is not nil before deep-copying it, preventing a potential nil pointer dereference.

Comment thread pkg/imagebuilder/crane_builder.go Outdated
Comment on lines +401 to +405
cf, err := newImg.ConfigFile()
if err != nil {
return "", fmt.Errorf("failed to pull base image %q: %w", baseImage, err)
return nil, fmt.Errorf("failed to inspect image config for WORKDIR update: %w", err)
}

newImg, err := appendLayers(baseImg, tarLayer)
cfg := cf.Config.DeepCopy()

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

In appendLayerAndWorkdir, newImg.ConfigFile() is called to retrieve the image configuration. While the error is checked, cf itself can theoretically be nil in some edge cases or custom image implementations. To prevent a potential nil pointer dereference when calling cf.Config.DeepCopy(), add a defensive check to ensure cf is not nil before accessing its fields.

cf, err := newImg.ConfigFile()
if err != nil {
	return nil, fmt.Errorf("failed to inspect image config for WORKDIR update: %w", err)
}
if cf == nil {
	return nil, fmt.Errorf("failed to inspect image config for WORKDIR update: config file is nil")
}
cfg := cf.Config.DeepCopy()

@Neelabh94
Neelabh94 force-pushed the feat/orchestrator-detector-prereqs branch from ffc169f to f1a5bb5 Compare November 6, 2026 10:58
@Neelabh94 Neelabh94 changed the title feat(job): add Layer-1 orchestrator detector, decoupled K8s prereqs, and local OCI Crane builds feat(job): add Layer-1 orchestrator detector and decoupled TypeK8s CLI prerequisites Nov 6, 2026
@Neelabh94
Neelabh94 force-pushed the feat/orchestrator-detector-prereqs branch 3 times, most recently from 1d8ea0d to 108ec87 Compare November 6, 2026 12:55
…lIn, and air-gap telemetry guard

- Add provider-agnostic kubeconfig loading, deterministic context resolution, cross-OS exec-plugin basename normalization, and --context pinning helpers in pkg/orchestrator/k8s.
- Refactor pkg/orchestrator/gke kube_auth, inspector, and namespace resolution onto pkg/orchestrator/k8s, move kube_auth type declarations into types.go, add empty-context-safe kubectlIn, and extend TestNoUnpinnedKubectlCalls across pkg/orchestrator/...
- Add non-probing GCLUSTER_AIR_GAPPED Environment state classification and skip Clearcut CLI telemetry uploads when air-gapped so disconnected runs exit immediately.
…onor current-context, and reuse ExtractRegion
…tighten doc comments, and defer ResolveContext
@Neelabh94
Neelabh94 force-pushed the feat/orchestrator-detector-prereqs branch 3 times, most recently from 6dda440 to cfd69aa Compare November 7, 2026 04:34
@Neelabh94
Neelabh94 force-pushed the feat/orchestrator-detector-prereqs branch from cfd69aa to 0b7e890 Compare November 7, 2026 05:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request go Pull requests that update Go code release-improvements Added to release notes under the "Improvements" heading.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant