Merge pull request #1 from kai-scheduler/siormeir/reseed-from-main

feat: seed standalone API module from KAI-Scheduler main

Author: SiorMeir

CHANGELOG.md

@@ -5,44 +5,41 @@ All notable changes to api will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [v0.1.0] - 2026-04-13
+## [v0.1.0]
 
-Initial release of api as a standalone repository extracted from KAI-Scheduler.
+Initial release of the standalone `github.com/kai-scheduler/api` module, seeded from KAI-Scheduler `main`.
 
 ### Added
 
-- **API Types** with full git history preserved:
-  - Queue (v2) - Hierarchical queue resource
-  - PodGroup (v2alpha2) - Gang scheduling with subgroups
-  - BindRequest (v1alpha2) - Pod binding coordination
+- **API types** (client-backed CRD contracts):
+  - Queue (`scheduling.run.ai/v2`) — hierarchical queue resource
+  - PodGroup (`scheduling.run.ai/v2alpha2`) — gang scheduling with subgroups, plus validating webhook
+  - BindRequest, NumaPlacementRequest (`scheduling.run.ai/v1alpha2`) — pod binding coordination
+  - Topology (`kai.scheduler/v1alpha1`) — topology-aware scheduling input
 
-- **Generated Clients**:
-  - Clientset for all API versions
-  - Informers for watch/cache patterns
-  - Listers for indexed queries
+- **Generated clients** — single clientset, informer factory, and listers spanning both the
+  `scheduling.run.ai` and `kai.scheduler/v1alpha1` groups.
 
-- **CRD Manifests**:
-  - `config/crd/scheduling.run.ai_queues.yaml`
-  - `config/crd/scheduling.run.ai_podgroups.yaml`
-  - `config/crd/scheduling.run.ai_bindrequests.yaml`
+- **CRD manifests** (`config/crd/`):
+  - `scheduling.run.ai_queues.yaml`
+  - `scheduling.run.ai_podgroups.yaml`
+  - `scheduling.run.ai_bindrequests.yaml`
+  - `kai.scheduler_topologies.yaml`
 
 - **Utilities**:
-  - `utilities/resources/` - GPU sharing utilities:
-    - GPU fraction/memory extraction from pod annotations
-    - DRA (Dynamic Resource Allocation) support
-    - Resource list operations
-  - `utilities/podgroup/` - PodGroup business logic:
-    - `CalculatePreemptibility()` - Priority-based preemptibility
+  - `utilities/resources/` — GPU fraction/memory extraction, DRA support, resource list operations
+  - `utilities/podgroup/` — `CalculatePreemptibility()`
 
-- **Constants**:
-  - GPU annotation keys (GpuFraction, GpuMemory, etc.)
-  - Common labels and selectors
+- **Constants** — GPU annotation keys, labels, and priority constants.
+
+- **Code generation** — `make generate` (deepcopy), `make manifests` (CRDs), `make clients`
+  (clientset/informers/listers) reproduce all generated artifacts.
 
 ### Notes
 
-- Extracted from kai-scheduler v0.14.0 with full commit history (696+ commits)
-- Clean separation: Only client-facing API contracts included
-- Scheduler-specific utilities (framework handles, webhook wiring) remain in kai-scheduler
-- Dependencies: Kubernetes v0.35.3, controller-runtime v0.23.3
+- Seeded fresh from `main` (no git history preserved); Apache 2.0 / NVIDIA attribution retained via per-file headers.
+- Scheduler-internal code stays in kai-scheduler: `kai.scheduler/v1` config types (Config, SchedulingShard),
+  scheduler-framework glue (`k8s_utils`), and feature gates.
+- Dependencies: Kubernetes v0.35.4, controller-runtime v0.23.3, Go 1.26.3.
 
 [v0.1.0]: https://github.com/kai-scheduler/api/releases/tag/v0.1.0

CLAUDE.md

@@ -1,18 +1,25 @@
 # api Development Guide
 
-api is a standalone Go module providing Kubernetes API types, generated clients, and utilities for GPU-aware batch scheduling with KAI Scheduler.
+`github.com/kai-scheduler/api` is a standalone Go module providing Kubernetes API types, generated clients, and utilities for GPU-aware batch scheduling with KAI Scheduler.
 
 ## Repository Structure
 
 ```
 api/
-├── api/scheduling/          # API type definitions (Queue, PodGroup, BindRequest)
-├── client/                  # Generated clientset, informers, listers
-├── config/crd/              # CRD YAML manifests
-├── constants/               # Public API constants (GPU annotations, labels)
+├── scheduling/              # scheduling.run.ai types
+│   ├── v1alpha2/            # BindRequest, NumaPlacementRequest
+│   ├── v2/                  # Queue
+│   └── v2alpha2/            # PodGroup (+ validating webhook)
+├── kai/
+│   └── v1alpha1/            # Topology
+├── client/                  # Generated clientset, informers, listers (both groups)
+├── config/crd/              # Generated CRD YAML manifests
+├── constants/               # Public API constants (GPU annotations, labels, priorities)
 ├── utilities/               # Client-facing utilities
 │   ├── resources/           # GPU sharing, DRA extraction, resource helpers
 │   └── podgroup/            # PodGroup business logic (preemptibility)
+├── hack/                    # Codegen boilerplate + update-client.sh
+├── Makefile
 ├── go.mod
 ├── README.md
 ├── CHANGELOG.md
@@ -21,138 +28,61 @@ api/
 
 ## What Belongs in This Repository
 
-**Include (Client-Facing API Contracts):**
-- API type definitions (Queue, PodGroup, BindRequest)
+**Include (client-facing API contracts):**
+- CRD type definitions with a generated client — the `scheduling.run.ai` group and `kai.scheduler/v1alpha1` Topology
 - Generated Kubernetes clients (clientset, informers, listers)
-- CRD manifests (YAML definitions)
-- Constants that are part of the public API (annotations, labels)
-- Utilities for working with API types (GPU request inspection, DRA support)
-- Business logic directly referenced in API documentation (preemptibility calculation)
-
-**Exclude (Scheduler Implementation Details):**
-- Scheduler plugin implementations
-- Framework handles and infrastructure
-- Webhook wiring code (operator-specific)
-- Feature gates (runtime behavior, not API contracts)
-- Scheduler-specific internal utilities
+- CRD manifests (YAML)
+- Public-API constants (annotations, labels, priorities)
+- Utilities for working with API types (GPU request inspection, DRA support, preemptibility)
+- The PodGroup validating webhook (ships with its `v2alpha2` type)
 
-## Building and Testing
-
-### Build
-```bash
-go build ./...
-```
+**Exclude (stays in kai-scheduler):**
+- `kai.scheduler/v1` config types (Config, SchedulingShard) — operator-internal, controller-runtime only
+- Scheduler-framework glue (`k8s_utils`) — pulls `k8s.io/kubernetes`; imports feature gates (would cycle)
+- Feature gates and flags (runtime behavior, not API contract)
+- Scheduler plugins and infrastructure
 
-### Run Tests
-```bash
-go test ./...
-```
+## Building and Testing
 
-### Linting
-Use the same linter configuration as kai-scheduler:
 ```bash
-golangci-lint run
+make build   # go build ./...
+make test    # go test ./...
+make lint    # gofmt + go vet
 ```
 
 ## Code Generation
 
-Generated clients are created from API types using kubernetes code-generator tools.
-
-**When to regenerate:**
-- API types are modified (new fields, new versions)
-- After bumping Kubernetes dependencies
-
-**How to regenerate:**
 ```bash
-# TODO: Add code generation scripts when SDK CI/CD is set up
+make generate   # DeepCopy methods (controller-gen object)
+make manifests  # CRD manifests into config/crd/ (controller-gen crd)
+make clients    # clientset, informers, listers (k8s.io/code-generator)
 ```
 
-## Versioning
-
-This SDK follows [Semantic Versioning](https://semver.org/):
+Regenerate when API types change or after bumping Kubernetes dependencies. `make manifests` prepends the
+Kubernetes copyright header to `kai.scheduler_topologies.yaml` (derived from Kubernetes projects).
 
-- **MAJOR** (v1.x.x → v2.x.x): Breaking API changes
-  - Field removals
-  - Type changes
-  - Renamed resources
+## Versioning & Release
 
-- **MINOR** (v1.0.x → v1.1.x): Backward-compatible additions
-  - New API fields (with defaults)
-  - New utility functions
-  - New CRD versions (with conversion)
+Semantic Versioning; `v0.x` until the contract is declared stable.
 
-- **PATCH** (v1.0.0 → v1.0.1): Bug fixes and documentation
-  - Bug fixes in utilities
-  - Documentation improvements
-  - Non-breaking dependency updates
-
-## Release Process
-
-1. Update API types/utilities as needed
-2. Update `CHANGELOG.md` with changes
-3. Run tests: `go test ./...`
-4. Run build: `go build ./...`
-5. Commit changes
-6. Tag release: `git tag v0.x.y`
-7. Push tag: `git push origin v0.x.y`
+1. Update API types/utilities
+2. Regenerate (`make generate manifests clients`)
+3. Update `CHANGELOG.md`
+4. `make build && make test`
+5. Commit, tag `vX.Y.Z`, push the tag
 
 ## Local Development with kai-scheduler
 
-When making changes to both SDK and kai-scheduler simultaneously:
-
-1. **Make SDK changes first** in this repository
-2. **Test locally** using replace directive in kai-scheduler:
-   ```go
-   // kai-scheduler/go.mod
-   replace github.com/kai-scheduler/api => ../api
-   ```
-3. **Run kai-scheduler tests** with local SDK
-4. **Release SDK** when ready (tag version)
-5. **Update kai-scheduler** to use released SDK version:
-   ```bash
-   cd kai-scheduler
-   go get github.com/kai-scheduler/api@v0.x.y
-   # Remove replace directive
-   ```
-
-## Code Style
-
-Follow the same conventions as kai-scheduler:
-
-**Imports**: Three groups (stdlib, external, internal)
 ```go
-import (
-    "context"
-    "fmt"
-
-    v1 "k8s.io/api/core/v1"
-    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
-
-    "github.com/kai-scheduler/api/constants"
-)
+// kai-scheduler/go.mod (local only — not committed to release branches)
+replace github.com/kai-scheduler/api => ../api
 ```
 
-**Naming**:
-- Files: snake_case (`gpu_sharing.go`, `podgroup.go`)
-- Types: PascalCase (`Queue`, `PodGroup`)
-- Functions: PascalCase exported, camelCase unexported
-- Boolean functions: `Is`/`Has`/`Should` prefix
-
-**Comments**:
-- Apache 2.0 + NVIDIA copyright headers on all files
-- GoDoc-style for exported functions/types
-- Avoid obvious comments; explain "why" not "what"
+Make API changes here first, test against kai-scheduler via the `replace` directive, then release and bump
+kai-scheduler with `go get github.com/kai-scheduler/api@vX.Y.Z`.
 
-## Contributing
-
-Changes to API types should be made in this repository first, then consumed by kai-scheduler.
-
-For questions or contributions to the main scheduler, see [kai-scheduler repository](https://github.com/kai-scheduler/KAI-Scheduler).
-
-## Known Issues
-
-### Operator API in Generated Clients
-
-Generated clients currently include references to `kai/v1alpha1` (Topology CRD), which is operator-specific and should remain in kai-scheduler. This creates a dependency on the kai-scheduler module.
+## Code Style
 
-**Resolution**: Will be addressed when SDK client generation is set up independently. For now, the dependency exists but doesn't affect SDK users who only work with scheduling APIs.
+Follow kai-scheduler conventions: three import groups (stdlib, external, internal); snake_case files;
+PascalCase exported / camelCase unexported; `Is`/`Has`/`Should` boolean prefixes; Apache 2.0 + NVIDIA
+copyright headers on all files; GoDoc on exported symbols; explain "why" not "what".

Makefile

@@ -0,0 +1,51 @@
+# Copyright 2025 NVIDIA CORPORATION
+# SPDX-License-Identifier: Apache-2.0
+
+CONTROLLER_TOOLS_VERSION ?= v0.20.1
+
+LOCALBIN ?= $(shell pwd)/bin
+$(LOCALBIN):
+	mkdir -p $(LOCALBIN)
+
+CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
+
+# CRDs derived from Kubernetes projects that require the Kubernetes copyright header.
+K8S_COPYRIGHTED_MANIFEST_FILES := config/crd/kai.scheduler_topologies.yaml
+
+.PHONY: all
+all: generate manifests clients
+
+.PHONY: build
+build: ## Build all packages.
+	go build ./...
+
+.PHONY: test
+test: ## Run all tests.
+	go test ./...
+
+.PHONY: lint
+lint: ## Format and vet.
+	gofmt -l -w .
+	go vet ./...
+
+.PHONY: generate
+generate: controller-gen ## Generate DeepCopy method implementations.
+	$(CONTROLLER_GEN) object:headerFile="./hack/boilerplate.go.txt" paths="./scheduling/..." paths="./kai/..."
+
+.PHONY: manifests
+manifests: controller-gen ## Generate CustomResourceDefinition objects.
+	$(CONTROLLER_GEN) crd:allowDangerousTypes=true,generateEmbeddedObjectMeta=true,headerFile="./hack/boilerplate.yaml.txt" paths="./scheduling/..." paths="./kai/..." output:crd:artifacts:config=config/crd
+
+	# Prepend Kubernetes copyright to CRDs derived from Kubernetes projects.
+	@for f in $(K8S_COPYRIGHTED_MANIFEST_FILES); do \
+		cat ./hack/boilerplate.yaml.kb.txt $$f > $$f.tmp && mv $$f.tmp $$f; \
+	done
+
+.PHONY: clients
+clients: ## Generate clientset, listers, and informers.
+	hack/update-client.sh
+
+.PHONY: controller-gen
+controller-gen: $(CONTROLLER_GEN) ## Download controller-gen locally if necessary.
+$(CONTROLLER_GEN): $(LOCALBIN)
+	test -s $(LOCALBIN)/controller-gen || GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-tools/cmd/controller-gen@$(CONTROLLER_TOOLS_VERSION)