Multi-Cluster: Adds v1alpha1 API Types and Docs

Makefile

@@ -307,13 +307,24 @@ live-docs:
 	docker build -t gaie/mkdocs hack/mkdocs/image
 	docker run --rm -it -p 3000:3000 -v ${PWD}:/docs gaie/mkdocs
 
-.PHONY: apix-ref-docs
-apix-ref-docs: crd-ref-docs
+.PHONY: api-ref-docs-all
+api-ref-docs-all: apix-v1a1-ref-docs apix-v1a2-ref-docs api-ref-docs
+
+.PHONY: apix-v1a1-ref-docs
+apix-v1a1-ref-docs: crd-ref-docs
+	${CRD_REF_DOCS} \
+		--source-path=${PWD}/apix/v1alpha1 \
+		--config=crd-ref-docs.yaml \
+		--renderer=markdown \
+		--output-path=${PWD}/site-src/reference/x-v1a1-spec.md
+
+.PHONY: apix-v1a2-ref-docs
+apix-v1a2-ref-docs: crd-ref-docs
 	${CRD_REF_DOCS} \
 		--source-path=${PWD}/apix/v1alpha2 \
 		--config=crd-ref-docs.yaml \
 		--renderer=markdown \
-		--output-path=${PWD}/site-src/reference/x-spec.md
+		--output-path=${PWD}/site-src/reference/x-v1a2-spec.md
 
 .PHONY: api-ref-docs
 api-ref-docs: crd-ref-docs

api/v1/inferencepool_types.go

@@ -202,8 +202,42 @@ type ParentStatus struct {
 	//
 	// +required
 	ParentRef ParentReference `json:"parentRef,omitzero"`
+
+	// ControllerName is a domain/path string that indicates the name of the controller that
+	// wrote this status. This corresponds with the GatewayClass controllerName field when the
+	// parentRef references a Gateway kind.
+	//
+	// Example: "example.net/gateway-controller".
+	//
+	// The format of this field is DOMAIN "/" PATH, where DOMAIN and PATH are valid Kubernetes names:
+	//
+	//  https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+	//
+	// Controllers MAY populate this field when writing status. When populating this field, controllers
+	// should ensure that entries to status populated with their ControllerName are cleaned up when they
+	// are no longer necessary.
+	//
+	// +optional
+	ControllerName ControllerName `json:"controllerName,omitempty"`
 }
 
+// ControllerName is the name of a controller that manages ParentStatus. It must be a domain prefixed
+// path.
+//
+// Valid values include:
+//
+// * "example.com/bar"
+//
+// Invalid values include:
+//
+// * "example.com" - must include path
+// * "foo.example.com" - must include path
+//
+// +kubebuilder:validation:MinLength=1
+// +kubebuilder:validation:MaxLength=253
+// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[A-Za-z0-9\/\-._~%!$&'()*+,;=:]+$`
+type ControllerName string
+
 // InferencePoolConditionType is a type of status condition for the InferencePool.
 type InferencePoolConditionType string
 
@@ -274,6 +308,38 @@ const (
 	InferencePoolReasonInvalidExtensionRef InferencePoolReason = "InvalidExtensionRef"
 )
 
+const (
+	// InferencePoolConditionExported is a type of condition that indicates whether the
+	// controller was able to export the InferencePool to the specified clusters.
+	//
+	// Possible reasons for this condition to be True are:
+	//
+	// * "Exported"
+	//
+	// Possible reasons for this condition to be False are:
+	//
+	// * "NotRequested"
+	// * "NotSupported"
+	//
+	// Controllers MAY raise this condition with other reasons, but should
+	// prefer to use the reasons listed above to improve interoperability.
+	InferencePoolConditionExported InferencePoolConditionType = "Exported"
+
+	// InferencePoolReasonExported is a reason used with the "Exported" condition when the
+	// condition is true.
+	InferencePoolReasonExported InferencePoolReason = "Exported"
+
+	// InferencePoolReasonNotRequested is a reason used with the "Exported" condition when the
+	// condition is false and no export was requested by the InferencePool. This indicates a
+	// deliberate non-action rather than an error.
+	InferencePoolReasonNotRequested InferencePoolReason = "NotRequested"
+
+	// InferencePoolReasonNotSupported is a reason used with the "Exported" condition when the
+	// condition is false and the export was requested but is not supported by the implementation.
+	// Controllers should include details in the condition message.
+	InferencePoolReasonNotSupported InferencePoolReason = "NotSupported"
+)
+
 // ParentReference identifies an API object. It is used to associate the InferencePool with a
 // parent resource, such as a Gateway.
 type ParentReference struct {

apix/v1alpha1/doc.go

@@ -0,0 +1,22 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+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 contains API Schema definitions for the
+// inference.networking.x-k8s.io API group.
+//
+// +kubebuilder:object:generate=true
+// +groupName=inference.networking.x-k8s.io
+package v1alpha1

apix/v1alpha1/inferencepoolimport_types.go

@@ -0,0 +1,143 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+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 (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	v1 "sigs.k8s.io/gateway-api-inference-extension/api/v1"
+)
+
+// InferencePoolImport is the Schema for the InferencePoolImports API.
+//
+// +kubebuilder:object:root=true
+// +kubebuilder:resource:shortName=infpimp
+// +kubebuilder:subresource:status
+// +kubebuilder:storageversion
+// +genclient
+type InferencePoolImport struct {
+	metav1.TypeMeta `json:",inline"`
+
+	// +optional
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	// Status defines the observed state of the InferencePoolImport.
+	//
+	// +optional
+	//nolint:kubeapilinter // status should not be a pointer.
+	Status InferencePoolImportStatus `json:"status,omitempty"`
+}
+
+// InferencePoolImportList contains a list of InferencePoolImports.
+//
+// +kubebuilder:object:root=true
+type InferencePoolImportList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []InferencePoolImport `json:"items"`
+}
+
+// InferencePoolImportStatus defines the observed state of the InferencePoolImport.
+type InferencePoolImportStatus struct {
+	// Controllers is a list of controllers that are responsible for managing the InferencePoolImport.
+	//
+	// +listType=map
+	// +listMapKey=name
+	// +kubebuilder:validation:MaxItems=8
+	// +kubebuilder:validation:Required
+	Controllers []ImportController `json:"controllers"`
+}
+
+// ImportController defines a controller that is responsible for managing the InferencePoolImport.
+type ImportController struct {
+	// Name is a domain/path string that indicates the name of the controller that manages the
+	// InferencePoolImport. Name corresponds to the GatewayClass controllerName field when the
+	// controller will manage parents of type "Gateway". Otherwise, the name is implementation-specific.
+	//
+	// Example: "example.net/import-controller".
+	//
+	// The format of this field is DOMAIN "/" PATH, where DOMAIN and PATH are valid Kubernetes
+	// names (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).
+	//
+	// A controller MUST populate this field when writing status and ensure that entries to status
+	// populated with their controller name are removed when they are no longer necessary.
+	//
+	// +required
+	Name ControllerName `json:"name"`
+
+	// ExportingClusters is a list of clusters that exported the InferencePool(s) that back the
+	// InferencePoolImport. Required when the controller is responsible for CRUD'ing the InferencePoolImport
+	// from the exported InferencePool(s).
+	//
+	// +optional
+	ExportingClusters []ExportingCluster `json:"exportingClusters,omitempty"`
+
+	// Parents is a list of parent resources, typically Gateways, that are associated with the
+	// InferencePoolImport, and the status of the InferencePoolImport with respect to each parent.
+	//
+	// Ancestor would be a more accurate name, but Parent is consistent with InferencePool terminology.
+	//
+	// Required when the controller manages the InferencePoolImport as an HTTPRoute backendRef. The controller
+	// must add an entry for each parent it manages and remove the parent entry when the controller no longer
+	// considers the InferencePoolImport to be associated with that parent.
+	//
+	// +optional
+	// +listType=atomic
+	Parents []v1.ParentStatus `json:"parents,omitempty"`
+
+	// Conditions track the state of the InferencePoolImport.
+	//
+	// Known condition types are:
+	//
+	//  * "Accepted"
+	//
+	// +optional
+	// +listType=map
+	// +listMapKey=type
+	// +kubebuilder:validation:MaxItems=8
+	Conditions []metav1.Condition `json:"conditions,omitempty"`
+}
+
+// ControllerName is the name of a controller that manages a resource. It must be a domain prefixed path.
+//
+// Valid values include:
+//
+//   - "example.com/bar"
+//
+// Invalid values include:
+//
+//   - "example.com" - must include path
+//   - "foo.example.com" - must include path
+//
+// +kubebuilder:validation:MinLength=1
+// +kubebuilder:validation:MaxLength=253
+// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[A-Za-z0-9\/\-._~%!$&'()*+,;=:]+$`
+type ControllerName string
+
+// ClusterName is the name of a cluster that exported the InferencePool.
+//
+// +kubebuilder:validation:MinLength=1
+// +kubebuilder:validation:MaxLength=253
+type ClusterName string
+
+// ExportingCluster defines a cluster that exported the InferencePool that backs this InferencePoolImport.
+type ExportingCluster struct {
+	// Name of the exporting cluster (must be unique within the list).
+	//
+	// +kubebuilder:validation:Required
+	Name ClusterName `json:"name"`
+}

apix/v1alpha1/shared_types.go

@@ -0,0 +1,24 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+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
+
+// ExportAnnotationKey is the annotation key used to export an InferencePool.
+var ExportAnnotationKey = "inference.networking.x-k8s.io/export"
+
+// ExportAnnotationVal is the annotation value used to export an InferencePool
+// to all clusters.
+var ExportAnnotationVal = "ClusterSet"