Add Go SDK for GPUs

.coderabbit.yaml

@@ -16,3 +16,14 @@ reviews:
   profile: chill
   auto_review:
     enabled: true
+  path_filters:
+    - "!api/gen/**"                                         # Ignore generated protobuf bindings
+    - "!api/**/zz_generated.*"                              # Ignore generated deepcopy and conversion code
+    - "!client-go/client/**"                                # Ignore generated clientset
+    - "!client-go/listers/**"                               # Ignore generated listers
+    - "!client-go/informers/**"                             # Ignore generated informers
+    - "!code-generator/cmd/client-gen/args/gvtype.go"       # Ignore copied, unmodified upstream code
+    - "!code-generator/cmd/client-gen/args/gvpackages.go"   # Ignore copied, unmodified upstream code
+    - "!code-generator/cmd/client-gen/types/**"             # Ignore copied, unmodified upstream code
+    - "!code-generator/cmd/client-gen/generators/scheme/**" # Ignore copied, unmodified upstream code
+    - "!code-generator/cmd/client-gen/generators/util/**"   # Ignore copied, unmodified upstream code

.gitattributes

@@ -0,0 +1,21 @@
+# ==============================================================================
+# GIT ATTRIBUTES
+# ==============================================================================
+# Use 'linguist-generated=true' to hide generated code from GitHub PR diffs.
+# ==============================================================================
+
+# Hide Kubernetes generated helpers (DeepCopy, Defaults, Conversions, OpenAPI, etc)
+zz_generated.*.go linguist-generated=true
+
+# Hide generated Protobuf Go bindings
+*.pb.go linguist-generated=true
+
+# Hide generated client library
+client-go/client/** linguist-generated=true
+client-go/listers/** linguist-generated=true
+client-go/informers/** linguist-generated=true
+
+# Hide copied, unmodified upstream code
+code-generator/cmd/client-gen/types/** linguist-generated=true
+code-generator/cmd/client-gen/generators/scheme/** linguist-generated=true
+code-generator/cmd/client-gen/generators/util/** linguist-generated=true

.gitignore

@@ -15,6 +15,7 @@
 *.so
 *.dylib
 api/bin/*
+client-go/bin/*
 
 # Test binary, built with `go test -c`
 *.test

.versions.yaml

@@ -46,6 +46,8 @@ go_tools:
   setup_envtest: 'latest'
   goimports: 'v0.30.0'
   crane: 'v0.20.2'
+  goverter: 'v1.9.3'
+  kubernetes_code_gen: 'v0.34.1'
 
 # Protocol Buffers / gRPC
 protobuf:

Makefile

@@ -340,6 +340,7 @@ license-headers-lint: ## Check license headers in source files
 		-ignore '**/*.toml' \
 		-ignore '**/*lock.hcl' \
 		-ignore '**/*pb2*' \
+		-ignore '**/hack/**' \
 		.
 
 # Check go.mod files for proper replace directives

api/DEVELOPMENT.md

@@ -0,0 +1,25 @@
+# API Development
+
+## Workflow
+
+Follow these steps to add new resources or update existing fields:
+1. **Go Definitions**: Update `device/${VERSION}/${TYPE}_types.go`. Ensure you include the necessary marker comments (e.g., `// +k8s:deepcopy-gen`) required by the generators.
+2. **Proto Definitions**: Update `proto/device/${VERSION}/${TYPE}.proto`. Ensure Protobuf field numbers are never reused or changed once released.
+3. **Registration**: If adding a new **Kind**, register it in `device/${VERSION}/register.go` within the `addKnownTypes` function.
+4. **Conversion Logic**: Update the mapping interface in `device/${VERSION}/converter.go`. See [Goverter](https://github.com/jmattheis/goverter) documentation for additional details.
+5. **Generate**: Run `make code-gen`. This orchestrates `protoc`, `deepcopy-gen`, and `goverter` to refresh all artifacts.
+
+## Conventions
+
+- **Kubernetes Resource Model (KRM)**:
+  - Go type definitions must strictly follow the standard [Kubernetes Resource Model](https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md).
+  - **Separation of Concerns**: Use `Spec` for desired configuration and `Status` for observed state.
+
+## Housekeeping
+
+If your generated files are out of sync or contain stale data:
+
+```bash
+# Removes generated code (bindings, deepcopy, goverter)
+make clean
+```

api/Makefile

@@ -16,41 +16,16 @@
 # Configuration
 # ==============================================================================
 
-# Directories
-PROTO_DIR       := proto
-GEN_DIR         := gen/go
-
 # Shell setup
 SHELL = /usr/bin/env bash -o pipefail
 .SHELLFLAGS = -ec
 
-# Location to install dependencies to
-LOCALBIN ?= $(shell pwd)/bin
-$(LOCALBIN):
-	mkdir -p $(LOCALBIN)
-
-# Tool Binaries
-PROTOC_GEN_GO           ?= $(LOCALBIN)/protoc-gen-go
-PROTOC_GEN_GO_GRPC      ?= $(LOCALBIN)/protoc-gen-go-grpc
-
-# Tool Versions (load from ../.versions.yaml)
-# Requires yq to be installed: brew install yq (macOS) or see https://github.com/mikefarah/yq
-YQ := $(shell command -v yq 2> /dev/null)
-ifndef YQ
-$(error yq is required but not found. Install it with: brew install yq (macOS) or see https://github.com/mikefarah/yq)
-endif
-
-VERSIONS_FILE := ../.versions.yaml
-
-PROTOC_GEN_GO_VERSION           := $(shell $(YQ) '.protobuf.protoc_gen_go' $(VERSIONS_FILE))
-PROTOC_GEN_GO_GRPC_VERSION      := $(shell $(YQ) '.protobuf.protoc_gen_go_grpc' $(VERSIONS_FILE))
-
 # ==============================================================================
 # Targets
 # ==============================================================================
 
 .PHONY: all
-all: protos-generate build
+all: code-gen test build ## Run code generation, compile all code, and execute tests.
 
 ##@ General
 
@@ -60,66 +35,25 @@ help: ## Display this help.
 
 ##@ Development
 
-.PHONY: build
-build:
-	go build -v ./...
-
-.PHONY: protos-generate
-protos-generate: $(PROTOC_GEN_GO) $(PROTOC_GEN_GO_GRPC) protos-clean ## Generate Go code from Proto definitions.
-	@echo "Generating Proto code..."
-	@mkdir -p $(GEN_DIR)
-	cd proto && \
-	protoc \
-		-I . \
-		-I ../$(THIRD_PARTY_DIR) \
-		--plugin="protoc-gen-go=$(PROTOC_GEN_GO)" \
-		--plugin="protoc-gen-go-grpc=$(PROTOC_GEN_GO_GRPC)" \
-		--go_out=../$(GEN_DIR) \
-		--go_opt=paths=source_relative \
-		--go-grpc_out=../$(GEN_DIR) \
-		--go-grpc_opt=paths=source_relative \
-		device/v1alpha1/*.proto && \
-	protoc \
-		-I . \
-		-I ../$(THIRD_PARTY_DIR) \
-		--plugin="protoc-gen-go=$(PROTOC_GEN_GO)" \
-		--plugin="protoc-gen-go-grpc=$(PROTOC_GEN_GO_GRPC)" \
-		--go_out=../$(GEN_DIR) \
-		--go_opt=paths=source_relative \
-		--go-grpc_out=../$(GEN_DIR) \
-		--go-grpc_opt=paths=source_relative \
-		csp/v1alpha1/*.proto
-	@echo "Cleaning up dependencies..."
+.PHONY: code-gen
+code-gen: ## Run all code generation targets.
+	@echo "Generating code..."
+	./hack/update-codegen.sh
+	@echo "Synchronizing module dependencies..."
 	go mod tidy
-	@echo "Done."
-
-.PHONY: protos-clean
-protos-clean: ## Remove generated code.
-	@echo "Cleaning old generated Proto code..."
-	rm -rf $(GEN_DIR)
-	@echo "Done."
 
-##@ Build Dependencies
-
-$(PROTOC_GEN_GO):
-	$(call go-install-tool,$(PROTOC_GEN_GO),google.golang.org/protobuf/cmd/protoc-gen-go,$(PROTOC_GEN_GO_VERSION))
+.PHONY: build
+build: code-gen ## Compile all Go code after generation to verify type safety.
+	@echo "Compiling..."
+	go build -v ./...
 
-$(PROTOC_GEN_GO_GRPC):
-	$(call go-install-tool,$(PROTOC_GEN_GO_GRPC),google.golang.org/grpc/cmd/protoc-gen-go-grpc,$(PROTOC_GEN_GO_GRPC_VERSION))
+.PHONY: test
+test: code-gen ## Run unit tests and generate coverage after code generation.
+	@echo "Testing..."
+	go test -v $$(go list ./... | grep -v /gen/) -coverprofile cover.out
 
-# go-install-tool macro
-# $1 - target path with name of binary
-# $2 - package url which can be installed
-# $3 - specific version of package
-define go-install-tool
-@[ -f "$(1)-$(3)" ] || { \
-set -e; \
-mkdir -p $(LOCALBIN); \
-package=$(2)@$(3) ;\
-echo "Downloading $${package}" ;\
-rm -f $(1) || true ;\
-GOBIN=$(LOCALBIN) go install $${package} ;\
-mv $(1) $(1)-$(3) ;\
-} ;\
-ln -sf $(1)-$(3) $(1)
-endef
+.PHONY: clean
+clean: ## Remove all generated code.
+	@echo "Cleaning generated code..."
+	rm -rf gen/go
+	find . -name "zz_generated.*.go" -delete

api/README.md

@@ -0,0 +1,26 @@
+# API Definitions
+
+This module contains the canonical API definitions for the **NVIDIA Device API**. It serves as the single source of truth for resource schemas, gRPC wire formats, and Kubernetes-native Go types.
+
+## Structure
+
+* **`device/`**: Contains the **Kubernetes Resource Model (KRM)** definitions. These types implement the `runtime.Object` interface.
+* **`proto/`**: Contains the **Language-Agnostic Definitions**. Protobuf messages and gRPC service definitions that define the node-local communication contract.
+* **`gen/go/`**: Contains the **Bindings**. The output of the `protoc` compiler (`.pb.go` and `_grpc.pb.go`).
+
+## Code Generation
+
+This module relies on three distinct generation phases to maintain type safety:
+1. **Protobuf**: Compiles `.proto` files into Go structs.
+2. **DeepCopy**: Generates `zz_generated.deepcopy.go` to support Kubernetes object manipulation.
+3. **Conversion**: Generates `zz_generated.goverter.go` to map between Protobuf messages and KRM Go types (using Goverter).
+
+To run the full pipeline:
+
+```bash
+make code-gen
+```
+
+## Development
+
+Refer to [DEVELOPMENT.md](DEVELOPMENT.md) for instructions on adding new fields or resources to the API.

api/device/v1alpha1/converter.go

@@ -0,0 +1,136 @@
+// Copyright (c) 2025, NVIDIA CORPORATION.  All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package v1alpha1
+
+import (
+	pb "github.com/nvidia/nvsentinel/api/gen/go/device/v1alpha1"
+	"google.golang.org/protobuf/types/known/timestamppb"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// Converter is the interface used to generate type conversion methods between the
+// Kubernetes Resource Model structs and the Protobuf message structs.
+//
+// goverter:converter
+// goverter:output:file ./zz_generated.goverter.go
+// goverter:extend FromProtobufTypeMeta FromProtobufListTypeMeta FromProtobufTimestamp ToProtobufTimestamp
+// goverter:useZeroValueOnPointerInconsistency
+type Converter interface {
+	// FromProtobuf converts a protobuf Gpu message into a GPU object.
+	//
+	// goverter:map . TypeMeta | FromProtobufTypeMeta
+	// goverter:map Metadata ObjectMeta
+	FromProtobuf(source *pb.Gpu) GPU
+
+	// ToProtobuf converts a GPU object into a protobuf Gpu message.
+	//
+	// goverter:map ObjectMeta Metadata
+	// goverter:ignore state sizeCache unknownFields
+	ToProtobuf(source GPU) *pb.Gpu
+
+	// FromProtobufList converts a protobuf GpuList message into a GPUList object.
+	//
+	// goverter:map . TypeMeta | FromProtobufListTypeMeta
+	// goverter:map Metadata ListMeta
+	FromProtobufList(source *pb.GpuList) *GPUList
+
+	// ToProtobufList converts a GPUList object into a protobuf GpuList message.
+	//
+	// goverter:map ListMeta Metadata
+	// goverter:ignore state sizeCache unknownFields
+	ToProtobufList(source *GPUList) *pb.GpuList
+
+	// FromProtobufObjectMeta converts a protobuf ObjectMeta into a metav1.ObjectMeta object.
+	//
+	// goverter:ignoreMissing
+	FromProtobufObjectMeta(source *pb.ObjectMeta) metav1.ObjectMeta
+
+	// ToProtobufObjectMeta converts a metav1.ObjectMeta into a protobuf Object message.
+	//
+	// goverter:ignore state sizeCache unknownFields
+	ToProtobufObjectMeta(source metav1.ObjectMeta) *pb.ObjectMeta
+
+	// FromProtobufListMeta converts a protobuf ListMeta into a metav1.ListMeta object.
+	//
+	// goverter:ignore SelfLink Continue RemainingItemCount
+	FromProtobufListMeta(source *pb.ListMeta) metav1.ListMeta
+
+	// ToProtobufListMeta converts a metav1.ListMeta into a protobuf ListMeta message.
+	//
+	// goverter:ignore state sizeCache unknownFields
+	ToProtobufListMeta(source metav1.ListMeta) *pb.ListMeta
+
+	// FromProtobufSpec converts a protobuf GpuSpec message into a GPUSpec object.
+	//
+	// goverter:map Uuid UUID
+	FromProtobufSpec(source *pb.GpuSpec) GPUSpec
+
+	// ToProtobufSpec converts a GPUSpec object into a protobuf GpuSpec message.
+	//
+	// goverter:map UUID Uuid
+	// goverter:ignore state sizeCache unknownFields
+	ToProtobufSpec(source GPUSpec) *pb.GpuSpec
+
+	// FromProtobufStatus converts a protobuf GpuStatus message into a GPUStatus object.
+	FromProtobufStatus(source *pb.GpuStatus) GPUStatus
+
+	// ToProtobufStatus converts a GPUStatus object into a protobuf GpuStatus message.
+	//
+	// goverter:ignore state sizeCache unknownFields
+	ToProtobufStatus(source GPUStatus) *pb.GpuStatus
+
+	// FromProtobufCondition converts a protobuf Condition message into a metav1.Condition object.
+	//
+	// goverter:ignore ObservedGeneration
+	// Note: ObservedGeneration is specific to k8s and not found in the protobuf Condition message.
+	FromProtobufCondition(source *pb.Condition) metav1.Condition
+
+	// ToProtobufCondition converts a metav1.Condition object into a protobuf Condition message.
+	//
+	// goverter:ignore state sizeCache unknownFields
+	ToProtobufCondition(source metav1.Condition) *pb.Condition
+}
+
+// FromProtobufTypeMeta generates the standard TypeMeta for the root GPU resource.
+func FromProtobufTypeMeta(_ *pb.Gpu) metav1.TypeMeta {
+	return metav1.TypeMeta{
+		Kind:       "GPU",
+		APIVersion: SchemeGroupVersion.String(),
+	}
+}
+
+// FromProtobufListTypeMeta generates the standard TypeMeta for the GPUList resource.
+func FromProtobufListTypeMeta(_ *pb.GpuList) metav1.TypeMeta {
+	return metav1.TypeMeta{
+		Kind:       "GPUList",
+		APIVersion: SchemeGroupVersion.String(),
+	}
+}
+
+// FromProtobufTimestamp converts a protobuf Timestamp message to a metav1.Time.
+func FromProtobufTimestamp(source *timestamppb.Timestamp) metav1.Time {
+	if source == nil {
+		return metav1.Time{}
+	}
+	return metav1.NewTime(source.AsTime())
+}
+
+// ToProtobufTimestamp converts a metav1.Time to a protobuf Timestamp message.
+func ToProtobufTimestamp(source metav1.Time) *timestamppb.Timestamp {
+	if source.IsZero() {
+		return nil
+	}
+	return timestamppb.New(source.Time)
+}

api/device/v1alpha1/doc.go

@@ -0,0 +1,19 @@
+// Copyright (c) 2025, NVIDIA CORPORATION.  All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// +groupName=device.nvidia.com
+
+// Package v1alpha1 contains the API Schema definitions for the device.nvidia.com v1alpha1 API group.
+// This package includes types for GPU resources and conversions between Kubernetes and protobuf representations.
+package v1alpha1