feat(imagefamily): implement GKE release channel awareness

[dm3ch]

What type of PR is this?

/kind feature
/kind api-change

What this PR does / why we need it:

Implements proposal/0002-release-channel-awareness: adds structured family/channel/version fields to ImageSelectorTerm, allowing image selection by GKE release channel or explicit version rather than only by the (now-deprecated) alias string.

New ImageSelectorTerm fields:

• family — image OS family (ContainerOptimizedOS, Ubuntu2404, Ubuntu2204)
• channel — GKE release channel (rapid, regular, stable, extended, or cluster to follow the cluster's enrolled channel)
• version — explicit version string or latest

How it works:

• When channel: is set, the provider calls GetServerConfig (Container API, 30-min cache) to resolve the highest K8s minor version shipped for that channel, then derives the corresponding GCE image via an exact GKE build filter (gke-{k8sKey}-gke{build}-*).
• channel: cluster reads the cluster's own enrolled channel from GetCluster.
• When version: is set, the milestone (125.19216.104.126) or date (v20260416) is used directly; invalid formats are rejected at admission.
• A build miss (no image for the channel's GKE version) surfaces as ImagesReady=False with reason ImageResolutionFailed rather than silently falling back.

Ubuntu 2204 support: isUsableUbuntu2204Image handles the 2204 naming convention (no -amd64- suffix on amd64 images); arm64 derivation inserts -arm64- before the -v{date} version suffix.

alias backward compatibility: The existing alias field continues to work unchanged. It is now soft-deprecated — new configurations should use family/channel/version.

Docs: New docs/image-selection.md (selection mode reference); docs/image-management.md rewritten to lead with the new paradigm (alias demoted to a Legacy section).

GC race fix (included in this PR): Increased the orphan garbage-collection grace period from 30 s to 3 min. GCE VMs appear in instances.list within seconds of the create call, but the lifecycle controller only writes providerID back to the NodeClaim after the zone operation completes (30–90 s). The previous 30 s grace was narrow enough to delete a legitimately-launching VM before its NodeClaim was updated, leaving the NodeClaim permanently stuck with Launched=True but no backing instance.

E2E fix (included in this PR): Dropped c4a from all four arm64 provisioning specs. c4a machines require hyperdisk-balanced but e2e NodeClasses use pd-balanced by default, so every c4a attempt fails with a GCP 400 before falling through to t2a. Removing c4a makes the arm64 specs reliable without narrowing what Karpenter itself supports.

Related proposal (if applicable):

proposals/0002-release-channel-awareness.md

Which issue(s) this PR fixes:

Fixes #330

Docs and examples

• docs/ and examples/ updated (or this PR does not affect user-facing behaviour, configuration, or APIs)
• MIGRATION.md updated (or this PR does not require any migration steps)

Special notes for your reviewer:

• alias CEL validation rules from the previous release are preserved unchanged for backward compatibility.
• GetServerConfig results are cached for 30 minutes to avoid hammering the GKE Container API on every reconcile.
• E2E suite test/suites/channel-image-selection/ validates channel-based, version-pinned, and version: latest selection end-to-end against a live GKE cluster.
• //nolint:staticcheck on term.Alias accesses in image.go: the Alias field carries a // Deprecated: doc comment so that IDEs and go vet surface the deprecation to users. That same annotation causes staticcheck (SA1019) to flag our own backward-compat handler; the suppression is intentional — we own both the deprecated field and the code that must keep reading it.
• GC grace period (30 s → 3 min): The previous 30 s grace was too short — a VM taking ~35 s to provision would pass the grace window before the lifecycle controller wrote the providerID back to the NodeClaim, causing the GC to delete it as an orphan. This was observed in e2e: the COS / amd64 / spot provisioning spec failed because the GC deleted the VM at 16:44:15 (35 s after creation) while the lifecycle controller completed at 16:44:15.842 (117 ms later). 3 min covers the full provisioning cycle at the cost of one extra GC cycle before a genuine orphan is collected.
• c4a dropped from arm64 e2e specs: c4a machines are incompatible with pd-balanced disk (they require hyperdisk-balanced). The provisioning tests now use only t2a-standard-{2,4} for arm64 — which is what actually works in asia-southeast1 with standard NodeClass config. This is a test-only change; Karpenter itself continues to surface c4a offerings.
• This PR was prepared with AI assistance (Claude Code). All changes have been reviewed and verified by the author.

Greptile Summary

This PR implements GKE release channel awareness for image selection, adding structured family/channel/version fields to ImageSelectorTerm as an alternative to the now-deprecated alias string. It also includes a GC grace-period fix (30 s → 3 min) to prevent premature orphan deletion of legitimately-launching VMs, and drops c4a from arm64 e2e specs to fix flaky test failures.

• Image selection redesign: resolveFamilyTerm routes through a new resolveVersion helper that calls GetServerConfig (30-min cache) when channel: is set and GetCluster for channel: cluster, then delegates to per-family ResolveImages implementations. A new resolveExactBuildCOSImage path uses an exact GKE-build filter and surfaces misses as imageResolutionError.
• Ubuntu 2204 support: isUsableUbuntu2204Image identifies amd64 images by excluding -arm64-, and deriveArm64Image inserts -arm64- before the -v{date} suffix for that series.
• GC grace period increase: gcGracePeriod raised to 3 minutes to cover the full VM provisioning cycle before the lifecycle controller writes providerID back to the NodeClaim.

Confidence Score: 5/5

Safe to merge; the new channel-based image resolution path is well-structured, imageResolutionError is correctly propagated in all new code paths, and the GC grace-period change is conservative and well-justified.

The core logic — channel resolution, version lookup, image filtering, and error classification — all look correct. Unit tests cover the key resolution scenarios, edge cases (UNSPECIFIED cluster channel, missing builds, semver ordering), and the Ubuntu 2204 naming conventions. The two findings are design-level observations rather than present defects.

pkg/providers/imagefamily/ubuntu.go — the ubuntuVersionRe replacement scope; pkg/apis/v1alpha1/gcenodeclass.go — mixed-family ImageSelectorTerms behaviour in ImageFamily().

Important Files Changed

Filename	Overview
pkg/providers/imagefamily/image.go	Core dispatch layer; adds resolveFamilyTerm and resolveVersion with correct imageResolutionError wrapping for channel/cluster lookup failures and empty-candidate GCP results.
pkg/providers/imagefamily/containeroptimizedos.go	Adds ParseGKEVersion and resolveExactBuildCOSImage for channel-based resolution; build-miss is correctly classified as imageResolutionError; arm64 derivation regex requires exactly 4 COS version groups.
pkg/providers/imagefamily/ubuntu.go	Adds Ubuntu 2204 support via release-parameterized struct; isUsableUbuntu2204Image correctly identifies amd64 images by excluding -arm64-; deriveArm64Image handles the 2204 naming convention correctly.
pkg/providers/gke/version.go	New file implementing ResolveVersionForChannel; correctly uses semver comparison (not lexicographic) and handles defaultVersion/validVersions fallback; well-tested.
pkg/providers/gke/gke.go	Adds GetClusterConfig and GetServerConfig with separate 30-min caches; both paths are straightforward GKE API wrappers.
pkg/apis/v1alpha1/gcenodeclass.go	Adds Family/Channel/Version fields to ImageSelectorTerm with comprehensive CEL validation; ImageFamily() extended to handle new family terms mapping Ubuntu2404/2204 to ImageFamilyUbuntu for downstream compatibility.
pkg/controllers/nodeclaim/garbagecollection/controller.go	GC grace period increased from 30 s to 3 min; well-documented rationale; isOrphaned logic is unchanged and correct.

Sequence Diagram

sequenceDiagram
    participant NC as NodeClass Reconciler
    participant IP as ImageProvider
    participant GKE as GKE Provider
    participant GCP as GCP Compute API

    NC->>IP: List(nodeClass)
    IP->>IP: hash(ImageSelectorTerms) → cache key
    alt cache hit
        IP-->>NC: cached Images
    else cache miss
        loop each ImageSelectorTerm
            alt term.Alias set
                IP->>IP: resolveAliasTerm(term)
            else term.ID set
                IP->>IP: resolveIDTerm(term)
            else term.Family set
                IP->>IP: resolveFamilyTerm(term)
                alt term.Version set
                    IP->>IP: "version = term.Version"
                else "term.Channel == cluster"
                    IP->>GKE: GetClusterConfig() [30m cache]
                    GKE-->>IP: cluster.ReleaseChannel.Channel
                    IP->>GKE: GetServerConfig() [30m cache]
                    GKE-->>IP: ServerConfig.Channels
                    IP->>IP: ResolveVersionForChannel
                    IP-->>IP: gkeVersion
                else term.Channel set
                    IP->>GKE: GetServerConfig() [30m cache]
                    GKE-->>IP: ServerConfig.Channels
                    IP->>IP: ResolveVersionForChannel
                    IP-->>IP: gkeVersion
                end
                IP->>IP: provider.ResolveImages(ctx, version)
                alt GKE version format
                    IP->>GCP: "Images.List(gke-k8sKey-gkebuild-*)"
                    GCP-->>IP: matching COS images
                    IP->>IP: pick best, build amd64/arm64/gpu URLs
                else latest or milestone pin
                    IP->>GCP: "Images.List(gke-k8sKey-*)"
                    GCP-->>IP: candidates
                    IP->>IP: pick latest, derive variants
                end
                IP->>GCP: Images.Get(each candidate)
                GCP-->>IP: exists or 404
                IP->>IP: imageResolutionError if all absent
            end
        end
        IP->>IP: cache.Set(key, result, 5m)
        IP-->>NC: Images
    end

Loading

_{Reviews (7): Last reviewed commit: "test(provisioning): drop c4a from arm64 ..." | Re-trigger Greptile}

[gitautomator]

Thanks to your contribution, the maintainers will review it as soon as they can!

[gitautomator]

The release note is either empty or incomplete, please consider: Adds GKE release channel awareness to GCENodeClass image selection, allowing users to specify image family, GKE release channel (e.g., rapid, regular, stable), or Kubernetes version (including 'latest') for automatic resolution of appropriate COS or Ubuntu images.

[dm3ch]

E2E Test Results

Cluster: `asia-southeast1-b` | Commit: `23e1edda` | Total duration: ~12m (provisioning), ~5m (drift/gpu/channel)

Suite	Spec	Result	Duration	Notes
Provisioning	COS / amd64 / on-demand	✅ pass	~3m
Provisioning	COS / amd64 / spot	✅ pass	2m 18s	Previously failing due to GC race — fixed by grace period 30s→3m
Provisioning	COS / arm64 / on-demand	✅ pass	~3m
Provisioning	COS / arm64 / spot	✅ pass	~3m
Provisioning	Ubuntu / amd64 / on-demand	✅ pass	~3m
Provisioning	Ubuntu / amd64 / spot	✅ pass	~3m
Provisioning	Ubuntu / arm64 / on-demand	✅ pass	3m 31s	Previously failing due to c4a + pd-balanced incompatibility — fixed by dropping c4a from arm64 specs
Provisioning	Ubuntu / arm64 / spot	✅ pass	~3m
Provisioning	Pinned COS version	✅ pass	~3m
Provisioning	Pinned Ubuntu version	✅ pass	~3m
Provisioning	NodeClass drift	✅ pass	~3m
Drift	should replace a node when GCENodeClass metadata changes	✅ pass	5m 17s
GPU	should provision a GPU node with correct taint, labels, and allocatable GPU resource	✅ pass	3m 8s
ChannelImageSelection	COS / channel: stable / amd64 / on-demand	✅ pass	~3m	Channel version verified against server config
ChannelImageSelection	Ubuntu2404 / version: latest / amd64 / on-demand	✅ pass	~3m	Ubuntu version verified in resolved image

Overall: ✅ all pass

[thameezb]

Great work