[aryangorwade]

Description

This is a PR splitting /api into a standalone module, this would serve to fix GPU Operator versioning issues (Go supports v0.x.y and v1.x.y).

This architectural split involves:

• Moving dependencies external to api/ into /api to avoid circular imports
• Splitting API into its standalone module with its own go.mod and go.sum; root go.mod references this module now

CI checks introduced:

• PR check ensuring shared module dependencies stay in sync
• Post-release (after tagging) check ensuring compiled binary versions match tags
• PR check ensuring version bump PRs do not reference preexisting API tags (checks for "operator", "version", "bump" in PR title)

Changes to CI pipeline:

• Modified .nvidia-ci.yaml and .common-ci.yaml to ensure that tagging a release commit with operator and api tags does not cause a separate release process to trigger for the api tag in addition to the operator tag

Dependabot changes:

• Modified dependabot.yaml using group-by: dependency-name and a cross-directory pattern to update each shared dependency between both modules in one PR (one PR per dependency; for both modules). Note that groups such as k8s.io/* can be created, resulting in one cross-directory PR for all deps under k8s.io/*.

Checklist

• No secrets, sensitive information, or unrelated changes
• Lint checks passing (make lint)
• Generated assets in-sync (make validate-generated-assets)
• Go mod artifacts in-sync (make validate-modules)

Testing

Tested building & deploying the operator on a cluster with some test workloads. Tested Makefile commands.

[aryangorwade]

Should this be changed to a psuedo-verison v0.0.0-00010101000000-000000000000 that is not updated in any version-bump PRs? If changes were made to /api after say release 26.03.3, but those changes are not part of any current release; this could incorrectly point to a stale older API version.

A problem is that this would result in a built image's embedded binary reporting a psuedo-version and failing CVE scans. That is what currently happens with the gpu-operator and most of our Go products anyways

[rajathagasthya]

A problem is that this would result in a built image's embedded binary reporting a psuedo-version and failing CVE scans.

I'm not sure setting a version for github.com/NVIDIA/gpu-operator/api has any effect on the version embedded for the gpu-operator binary. I think a pseudo-version will be embedded for the main binary regardless of what version a dependency is declared as.

[aryangorwade]

Makes sense. #428 would only apply to the main binary which is the gpu operator.

[kvalliyurnatt]

@aryangorwade what is the plan for actually merging this PR ? what version would we set here ?

[rajathagasthya]

This should be v0.0.0-00010101000000-000000000000.

[kvalliyurnatt]

could it also be the version of the next potential release ?

[aryangorwade]

It could but that would tie back to this issue above:

If changes were made to /api after say release 26.03.3, but those changes are not part of any current release; this could incorrectly point to a stale older API version.

Say yesterday we released v26.03.3 of api and operator. But then today we merged changes to /api on main. The code would now incorrectly point to a stale api version of v26.03.3 until the next release. To avoid problems like this, it is better to just leave it as the zero version, v0.0.0-00010101000000-000000000000.

This change has not been made yet; the code still says github.com/NVIDIA/gpu-operator/api v0.2603.3.

[kvalliyurnatt]

This makes sense, thanks for clarifying

[coderabbitai]

📝 Walkthrough

Walkthrough

The repository now contains a separate api Go module with public driver constants and public image-package usage. Root consumers and tests reference the API package. Make targets cover API generation, builds, tests, vendoring, dependency synchronization, and API release validation. New scripts and GitHub Actions validate unpublished and published API versions. CI skips API-version tags for selected pipelines. Dependabot monitors both modules.

Priority: ➖ Normal

Merge Risk: 🟡 Moderate · up to 0acdb

A release PR can bypass API-tag collision validation by using a different title, risking an invalid release. The lint suppression can also hide new deprecated API usage. Resolve these checks before merge.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

Note

Quiet mode is enabled, so only the most important comments were posted inline. Other review comments are grouped below.

🟡 Other comments (1)

.golangci.yml-30-30 (1)

30-30: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Limit the SA1019 exclusion to the known compatibility sites.

This rule has no path restriction. Both lint commands scan root and API packages with this configuration, so any matching .ConfigMapName or .Name diagnostic outside the compatibility sites will be silently excluded. Restore a path restriction or narrow the exclusion to the affected legacy types so CI reports reintroduced deprecated uses.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: QUIET

Plan: Enterprise

Run ID: c6cb07c3-751f-40f4-a465-f56bb1f4e5ad

📥 Commits

Reviewing files that changed from the base of the PR and between 5799cfa and 0acdb89.

⛔ Files ignored due to path filters (23)

• api/go.sum is excluded by !**/*.sum
• vendor/github.com/NVIDIA/gpu-operator/api/image/image.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/nvidia/v1/clusterpolicy_types.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/nvidia/v1/groupversion_info.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/nvidia/v1/zz_generated.deepcopy.go is excluded by !vendor/**, !**/zz_generated.*.go
• vendor/github.com/NVIDIA/gpu-operator/api/nvidia/v1alpha1/gpucluster_types.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/nvidia/v1alpha1/groupversion_info.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/nvidia/v1alpha1/nvidiadriver_types.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/nvidia/v1alpha1/zz_generated.deepcopy.go is excluded by !vendor/**, !**/zz_generated.*.go
• vendor/github.com/NVIDIA/gpu-operator/api/versioned/clientset.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/versioned/scheme/doc.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/versioned/scheme/register.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/versioned/typed/nvidia/v1/clusterpolicy.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/versioned/typed/nvidia/v1/doc.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/versioned/typed/nvidia/v1/generated_expansion.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/versioned/typed/nvidia/v1/nvidia_client.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/versioned/typed/nvidia/v1alpha1/doc.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/versioned/typed/nvidia/v1alpha1/generated_expansion.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/versioned/typed/nvidia/v1alpha1/gpucluster.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/versioned/typed/nvidia/v1alpha1/nvidia_client.go is excluded by !vendor/**
• vendor/github.com/NVIDIA/gpu-operator/api/versioned/typed/nvidia/v1alpha1/nvidiadriver.go is excluded by !vendor/**
• vendor/k8s.io/client-go/discovery/fake/discovery.go is excluded by !vendor/**
• vendor/modules.txt is excluded by !vendor/**

📒 Files selected for processing (36)

• .common-ci.yml
• .github/dependabot.yml
• .github/workflows/api-post-tag-validation.yaml
• .github/workflows/api-release-checks.yaml
• .golangci.yml
• .nvidia-ci.yml
• Makefile
• api/go.mod
• api/image/image.go
• api/image/imagepath_validation_test.go
• api/nvidia/v1alpha1/nvidiadriver_types.go
• controllers/clusterpolicy_controller.go
• controllers/clusterpolicy_controller_test.go
• controllers/nodelabeling_controller.go
• controllers/nodelabeling_controller_test.go
• controllers/object_controls_test.go
• controllers/upgrade_controller.go
• controllers/upgrade_controller_test.go
• docker/Dockerfile.devel
• go.mod
• hack/validate-api-version-unpublished.sh
• hack/validate-published-api-module.sh
• hack/validate-shared-dependencies.sh
• internal/consts/consts.go
• internal/nvidiadriver/nvidiadriver.go
• internal/nvidiadriver/nvidiadriver_errors_test.go
• internal/nvidiadriver/nvidiadriver_test.go
• internal/state/configurable_state.go
• internal/state/dra_driver.go
• internal/state/driver.go
• internal/state/driver_manifest_test.go
• internal/state/driver_test.go
• internal/state/nodepool.go
• internal/state/nodepool_test.go
• internal/validator/validator_test.go
• tools/generate-third-party-notices.sh

💤 Files with no reviewable changes (1)

• internal/consts/consts.go

Included review availability: Your plan provides up to 12 included reviews per hour; 11 remain after this review.

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🔎 Supported by static analysis

🏁 Script executed:

sed -n '1,120p' .github/workflows/api-release-checks.yaml
rg -n --glob '!vendor/**' 'validate-api-version-unpublished|API Release Checks|operator.*version.*bump|OPERATOR_VERSION|api/v' .github Makefile hack versions.mk . 2>/dev/null | head -240

Repository: NVIDIA/gpu-operator

Length of output: 10771

---

🏁 Script executed:

#!/bin/bash
set -e
printf '%s\n' '--- validator ---'
sed -n '1,220p' hack/validate-api-version-unpublished.sh
printf '%s\n' '--- make/version definitions ---'
sed -n '220,265p' Makefile
sed -n '1,180p' versions.mk
printf '%s\n' '--- release/version references ---'
rg -n -i --glob '!vendor/**' --glob '!third_party/**' '(version bump|bump.*version|release.*version|operator.*version|api.*tag|unpublished|pull request.*title|title.*operator)' .github README.md CONTRIBUTING.md AGENTS.md PROJECT Makefile hack versions.mk 2>/dev/null | head -300
printf '%s\n' '--- release workflow/template filenames ---'
git ls-files '.github' | rg -i '(release|pull|pr|version|api)'

Repository: NVIDIA/gpu-operator

Length of output: 15870

---

🤖 get_repo_knowledge executed:

get_repo_knowledge NVIDIA/gpu-operator /tmp/coderabbit-repo-knowledge/nvidia-gpu-operator-eed98df4/conventions

Length of output: 4401

---

🏁 Script executed:

#!/bin/bash
set -e
printf '%s\n' '--- pull request template ---'
sed -n '1,220p' .github/PULL_REQUEST_TEMPLATE.md
printf '%s\n' '--- contributing release guidance ---'
sed -n '45,75p' CONTRIBUTING.md
printf '%s\n' '--- API post-tag validation workflow ---'
sed -n '1,110p' .github/workflows/api-post-tag-validation.yaml
printf '%s\n' '--- release workflow triggers and version inputs ---'
sed -n '1,75p' .github/workflows/release.yaml
sed -n '1,55p' .github/workflows/release-rc-assets.yaml

Repository: NVIDIA/gpu-operator

Length of output: 8575

---

Run the API-tag check for version changes.

If a PR changes the API module version but its title does not contain all three required substrings, GitHub skips api-version-unpublished. The validator then does not check whether api/<version> already exists, so a title such as Release v25.3.0 can bypass this release check. The PR template does not require the current title format.

Gate the job on changed API version metadata, or use a required release signal that cannot be omitted by changing the title.

[kvalliyurnatt]

I think with replace github.com/NVIDIA/gpu-operator/api => ./api plus the checked-in vendor/, root packages compile against vendor/github.com/NVIDIA/gpu-operator/api/..., not ./api. From the PR head, go list -f '{{.Dir}}' github.com/NVIDIA/gpu-operator/api/nvidia/v1 resolves to the vendor path.

I think we should have generate, generate-clientset and manifests depend on update-vendor, or add vendor to the diff here, so regenerating API code always leaves vendor/ consistent. maybe we can add a short not in AGENTS.md / CONTRIBUTING.md that api/ changes need make update-vendor.

[aryangorwade]

• generate: can change /api; makes sense to run update-vendor at the end of this command
• generate-clientset: same as above. Both of these read directly from /api and can change it
• manifests: reads from /vendored and /api. The first step of this command should be update-vendor.

This could run go mod vendor up to three times and cause possible race conditions. The solution is to add a validate-vendor command that generates /vendor into a temporary directory and diffs against /api (unique tmp directories per invocation). This command will substitute update-vendor in the commands described above.

Some others that need this validation are:

• cmd-*: prerequisite check
• goimports: postprocess check
• build-image: prerequisite check on the host
• run: prerequisite check
• lint: prerequisite check
• build: postprocess check (would affect unit-test and coverage)
• validate-modules: rewrite to use validate-vendor

Ideally only one command should run go mod vendor. I think this should be validate-generated-assets since it already writes to /api. What do you think?

[kvalliyurnatt]

yeah I think validate-generated-assets makes sense to me.

[kvalliyurnatt]

do we also need to check if the api version maps to an operator version, basically validate the mapping here as well ? like we do inhack/validate-published-api-module.sh , so that we catch the issue before an image is published ?

[aryangorwade]

This is the PR/pre-tag check, so the commit does not have operator version or api version tags at this point. Should it compare the operator version in versions.mk to the API version derived from root go.mod?

[kvalliyurnatt]

Yeah that is what I was thinking, do you see any issues with that ?

[aryangorwade]

That should be a good addition to this check. I will add it

[aryangorwade]

@kvalliyurnatt Adding github.com/NVIDIA/gpu-operator/api v0.0.0-00010101000000-000000000000 in root go.mod breaks this proposed check.

It also breaks the existing comparison (checking if root go.mod version tag exists upstream). We will have to change it to read version from versions.mk. Similar parts of of hack/validate-published-api-module.sh will also have to be reworked because of this.

[kvalliyurnatt]

ooh I see, I missed that. I guess we can leave this as is then