Skip to content

Commit 67ad182

Browse files
danehansdanehans
authored
Multi-Cluster: Adds v1alpha1 API Types and Docs (#1658)
* Multi-Cluster: Adds v1alpha1 API Types and Docs Signed-off-by: Daneyon Hansen <[email protected]> * Resolves initial review comments Signed-off-by: Daneyon Hansen <[email protected]> * Makes ControllerName optional Signed-off-by: Daneyon Hansen <[email protected]> --------- Signed-off-by: Daneyon Hansen <[email protected]>
1 parent 5a5f552 commit 67ad182

40 files changed

+2074
-10
lines changed

‎Makefile‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -307,13 +307,24 @@ live-docs:
307307
docker build -t gaie/mkdocs hack/mkdocs/image
308308
docker run --rm -it -p 3000:3000 -v ${PWD}:/docs gaie/mkdocs
309309

310-
.PHONY: apix-ref-docs
311-
apix-ref-docs: crd-ref-docs
310+
.PHONY: api-ref-docs-all
311+
api-ref-docs-all: apix-v1a1-ref-docs apix-v1a2-ref-docs api-ref-docs
312+
313+
.PHONY: apix-v1a1-ref-docs
314+
apix-v1a1-ref-docs: crd-ref-docs
315+
${CRD_REF_DOCS} \
316+
--source-path=${PWD}/apix/v1alpha1 \
317+
--config=crd-ref-docs.yaml \
318+
--renderer=markdown \
319+
--output-path=${PWD}/site-src/reference/x-v1a1-spec.md
320+
321+
.PHONY: apix-v1a2-ref-docs
322+
apix-v1a2-ref-docs: crd-ref-docs
312323
${CRD_REF_DOCS} \
313324
--source-path=${PWD}/apix/v1alpha2 \
314325
--config=crd-ref-docs.yaml \
315326
--renderer=markdown \
316-
--output-path=${PWD}/site-src/reference/x-spec.md
327+
--output-path=${PWD}/site-src/reference/x-v1a2-spec.md
317328

318329
.PHONY: api-ref-docs
319330
api-ref-docs: crd-ref-docs

‎api/v1/inferencepool_types.go‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -202,8 +202,42 @@ type ParentStatus struct {
202202
//
203203
// +required
204204
ParentRef ParentReference `json:"parentRef,omitzero"`
205+
206+
// ControllerName is a domain/path string that indicates the name of the controller that
207+
// wrote this status. This corresponds with the GatewayClass controllerName field when the
208+
// parentRef references a Gateway kind.
209+
//
210+
// Example: "example.net/gateway-controller".
211+
//
212+
// The format of this field is DOMAIN "/" PATH, where DOMAIN and PATH are valid Kubernetes names:
213+
//
214+
// https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
215+
//
216+
// Controllers MAY populate this field when writing status. When populating this field, controllers
217+
// should ensure that entries to status populated with their ControllerName are cleaned up when they
218+
// are no longer necessary.
219+
//
220+
// +optional
221+
ControllerName ControllerName `json:"controllerName,omitempty"`
205222
}
206223

224+
// ControllerName is the name of a controller that manages ParentStatus. It must be a domain prefixed
225+
// path.
226+
//
227+
// Valid values include:
228+
//
229+
// * "example.com/bar"
230+
//
231+
// Invalid values include:
232+
//
233+
// * "example.com" - must include path
234+
// * "foo.example.com" - must include path
235+
//
236+
// +kubebuilder:validation:MinLength=1
237+
// +kubebuilder:validation:MaxLength=253
238+
// +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\/\-._~%!$&'()*+,;=:]+$`
239+
type ControllerName string
240+
207241
// InferencePoolConditionType is a type of status condition for the InferencePool.
208242
type InferencePoolConditionType string
209243

@@ -274,6 +308,38 @@ const (
274308
InferencePoolReasonInvalidExtensionRef InferencePoolReason = "InvalidExtensionRef"
275309
)
276310

311+
const (
312+
// InferencePoolConditionExported is a type of condition that indicates whether the
313+
// controller was able to export the InferencePool to the specified clusters.
314+
//
315+
// Possible reasons for this condition to be True are:
316+
//
317+
// * "Exported"
318+
//
319+
// Possible reasons for this condition to be False are:
320+
//
321+
// * "NotRequested"
322+
// * "NotSupported"
323+
//
324+
// Controllers MAY raise this condition with other reasons, but should
325+
// prefer to use the reasons listed above to improve interoperability.
326+
InferencePoolConditionExported InferencePoolConditionType = "Exported"
327+
328+
// InferencePoolReasonExported is a reason used with the "Exported" condition when the
329+
// condition is true.
330+
InferencePoolReasonExported InferencePoolReason = "Exported"
331+
332+
// InferencePoolReasonNotRequested is a reason used with the "Exported" condition when the
333+
// condition is false and no export was requested by the InferencePool. This indicates a
334+
// deliberate non-action rather than an error.
335+
InferencePoolReasonNotRequested InferencePoolReason = "NotRequested"
336+
337+
// InferencePoolReasonNotSupported is a reason used with the "Exported" condition when the
338+
// condition is false and the export was requested but is not supported by the implementation.
339+
// Controllers should include details in the condition message.
340+
InferencePoolReasonNotSupported InferencePoolReason = "NotSupported"
341+
)
342+
277343
// ParentReference identifies an API object. It is used to associate the InferencePool with a
278344
// parent resource, such as a Gateway.
279345
type ParentReference struct {

‎apix/v1alpha1/doc.go‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
/*
2+
Copyright 2025 The Kubernetes Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
// Package v1alpha1 contains API Schema definitions for the
18+
// inference.networking.x-k8s.io API group.
19+
//
20+
// +kubebuilder:object:generate=true
21+
// +groupName=inference.networking.x-k8s.io
22+
package v1alpha1

‎apix/v1alpha1/inferencepoolimport_types.go‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
/*
2+
Copyright 2025 The Kubernetes Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package v1alpha1
18+
19+
import (
20+
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
21+
22+
v1 "sigs.k8s.io/gateway-api-inference-extension/api/v1"
23+
)
24+
25+
// InferencePoolImport is the Schema for the InferencePoolImports API.
26+
//
27+
// +kubebuilder:object:root=true
28+
// +kubebuilder:resource:shortName=infpimp
29+
// +kubebuilder:subresource:status
30+
// +kubebuilder:storageversion
31+
// +genclient
32+
type InferencePoolImport struct {
33+
metav1.TypeMeta `json:",inline"`
34+
35+
// +optional
36+
metav1.ObjectMeta `json:"metadata,omitempty"`
37+
38+
// Status defines the observed state of the InferencePoolImport.
39+
//
40+
// +optional
41+
//nolint:kubeapilinter // status should not be a pointer.
42+
Status InferencePoolImportStatus `json:"status,omitempty"`
43+
}
44+
45+
// InferencePoolImportList contains a list of InferencePoolImports.
46+
//
47+
// +kubebuilder:object:root=true
48+
type InferencePoolImportList struct {
49+
metav1.TypeMeta `json:",inline"`
50+
metav1.ListMeta `json:"metadata,omitempty"`
51+
Items []InferencePoolImport `json:"items"`
52+
}
53+
54+
// InferencePoolImportStatus defines the observed state of the InferencePoolImport.
55+
type InferencePoolImportStatus struct {
56+
// Controllers is a list of controllers that are responsible for managing the InferencePoolImport.
57+
//
58+
// +listType=map
59+
// +listMapKey=name
60+
// +kubebuilder:validation:MaxItems=8
61+
// +kubebuilder:validation:Required
62+
Controllers []ImportController `json:"controllers"`
63+
}
64+
65+
// ImportController defines a controller that is responsible for managing the InferencePoolImport.
66+
type ImportController struct {
67+
// Name is a domain/path string that indicates the name of the controller that manages the
68+
// InferencePoolImport. Name corresponds to the GatewayClass controllerName field when the
69+
// controller will manage parents of type "Gateway". Otherwise, the name is implementation-specific.
70+
//
71+
// Example: "example.net/import-controller".
72+
//
73+
// The format of this field is DOMAIN "/" PATH, where DOMAIN and PATH are valid Kubernetes
74+
// names (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).
75+
//
76+
// A controller MUST populate this field when writing status and ensure that entries to status
77+
// populated with their controller name are removed when they are no longer necessary.
78+
//
79+
// +required
80+
Name ControllerName `json:"name"`
81+
82+
// ExportingClusters is a list of clusters that exported the InferencePool(s) that back the
83+
// InferencePoolImport. Required when the controller is responsible for CRUD'ing the InferencePoolImport
84+
// from the exported InferencePool(s).
85+
//
86+
// +optional
87+
ExportingClusters []ExportingCluster `json:"exportingClusters,omitempty"`
88+
89+
// Parents is a list of parent resources, typically Gateways, that are associated with the
90+
// InferencePoolImport, and the status of the InferencePoolImport with respect to each parent.
91+
//
92+
// Ancestor would be a more accurate name, but Parent is consistent with InferencePool terminology.
93+
//
94+
// Required when the controller manages the InferencePoolImport as an HTTPRoute backendRef. The controller
95+
// must add an entry for each parent it manages and remove the parent entry when the controller no longer
96+
// considers the InferencePoolImport to be associated with that parent.
97+
//
98+
// +optional
99+
// +listType=atomic
100+
Parents []v1.ParentStatus `json:"parents,omitempty"`
101+
102+
// Conditions track the state of the InferencePoolImport.
103+
//
104+
// Known condition types are:
105+
//
106+
// * "Accepted"
107+
//
108+
// +optional
109+
// +listType=map
110+
// +listMapKey=type
111+
// +kubebuilder:validation:MaxItems=8
112+
Conditions []metav1.Condition `json:"conditions,omitempty"`
113+
}
114+
115+
// ControllerName is the name of a controller that manages a resource. It must be a domain prefixed path.
116+
//
117+
// Valid values include:
118+
//
119+
// - "example.com/bar"
120+
//
121+
// Invalid values include:
122+
//
123+
// - "example.com" - must include path
124+
// - "foo.example.com" - must include path
125+
//
126+
// +kubebuilder:validation:MinLength=1
127+
// +kubebuilder:validation:MaxLength=253
128+
// +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\/\-._~%!$&'()*+,;=:]+$`
129+
type ControllerName string
130+
131+
// ClusterName is the name of a cluster that exported the InferencePool.
132+
//
133+
// +kubebuilder:validation:MinLength=1
134+
// +kubebuilder:validation:MaxLength=253
135+
type ClusterName string
136+
137+
// ExportingCluster defines a cluster that exported the InferencePool that backs this InferencePoolImport.
138+
type ExportingCluster struct {
139+
// Name of the exporting cluster (must be unique within the list).
140+
//
141+
// +kubebuilder:validation:Required
142+
Name ClusterName `json:"name"`
143+
}

‎apix/v1alpha1/shared_types.go‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
/*
2+
Copyright 2025 The Kubernetes Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package v1alpha1
18+
19+
// ExportAnnotationKey is the annotation key used to export an InferencePool.
20+
var ExportAnnotationKey = "inference.networking.x-k8s.io/export"
21+
22+
// ExportAnnotationVal is the annotation value used to export an InferencePool
23+
// to all clusters.
24+
var ExportAnnotationVal = "ClusterSet"

0 commit comments

Comments
 (0)