Clean up RuntimeClass Topology documentation

pkg/apis/node/types.go

@@ -17,8 +17,8 @@ limitations under the License.
 package node
 
 import (
-	v1 "k8s.io/kubernetes/pkg/apis/core"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/kubernetes/pkg/apis/core"
 )
 
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
@@ -47,24 +47,32 @@ type RuntimeClass struct {
 	// immutable.
 	Handler string
 
-	// Topology specifies the scheduling constrains that are necessary to assign
+	// Topology describes the set of nodes in the cluster that support this
-	// pods to the right node
+	// RuntimeClass. The rules are applied applied to pods running with this
+	// RuntimeClass and semantically merged with other scheduling constraints on
+	// the pod.
+	// If topology is nil, this RuntimeClass is assumed to be supported by all
+	// nodes.
 	// +optional
 	Topology *Topology
 }
 
-// Topology specifies the structure of scheduling constrains for the runtime class
+// Topology specifies the scheduling constraints for nodes supporting a
+// RuntimeClass.
 type Topology struct {
-	// nodeSelector selects the set of nodes that support this RuntimeClass.
+	// NodeSelector selects the set of nodes that support this RuntimeClass.
 	// Pods using this RuntimeClass can only be scheduled to a node matched by
-	// this selector. The nodeSelector is intersected (AND) with a pod's other
+	// this selector. The NodeSelector is intersected (AND) with a pod's other
-	// node affinity or node selector requirements.
+	// NodeAffinity or NodeSelector requirements.
+	// A nil NodeSelector selects all nodes.
 	// +optional
-	NodeSelector *v1.NodeSelector
+	NodeSelector *core.NodeSelector
 
-	// tolerations adds tolerations to pods running with this RuntimeClass.
+	// Tolerations are appended (excluding duplicates) to pods running with this
+	// RuntimeClass during admission, effectively unioning the set of nodes
+	// tolerated by the pod and the RuntimeClass.
 	// +optional
-	Tolerations []v1.Toleration
+	Tolerations []core.Toleration
 }
 
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

pkg/apis/node/v1alpha1/BUILD

@@ -40,7 +40,9 @@ go_test(
     srcs = ["conversion_test.go"],
     embed = [":go_default_library"],
     deps = [
+        "//pkg/apis/core:go_default_library",
         "//pkg/apis/node:go_default_library",
+        "//staging/src/k8s.io/api/core/v1:go_default_library",
         "//staging/src/k8s.io/api/node/v1alpha1:go_default_library",
         "//staging/src/k8s.io/apimachinery/pkg/apis/meta/v1:go_default_library",
         "//vendor/github.com/stretchr/testify/assert:go_default_library",

pkg/apis/node/v1alpha1/conversion_test.go

@@ -21,8 +21,10 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	corev1 "k8s.io/api/core/v1"
 	v1alpha1 "k8s.io/api/node/v1alpha1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	core "k8s.io/kubernetes/pkg/apis/core"
 	node "k8s.io/kubernetes/pkg/apis/node"
 )
 
@@ -31,24 +33,91 @@ func TestRuntimeClassConversion(t *testing.T) {
 		name    = "puppy"
 		handler = "heidi"
 	)
-	internalRC := node.RuntimeClass{
+	tests := map[string]struct {
+		internal *node.RuntimeClass
+		external *v1alpha1.RuntimeClass
+	}{
+		"fully-specified": {
+			internal: &node.RuntimeClass{
 				ObjectMeta: metav1.ObjectMeta{Name: name},
 				Handler:    handler,
-	}
+				Topology: &node.Topology{
-	v1alpha1RC := v1alpha1.RuntimeClass{
+					NodeSelector: &core.NodeSelector{
+						NodeSelectorTerms: []core.NodeSelectorTerm{{
+							MatchExpressions: []core.NodeSelectorRequirement{{
+								Key:      "extra-soft",
+								Operator: core.NodeSelectorOpExists,
+							}},
+						}},
+					},
+					Tolerations: []core.Toleration{{
+						Key:      "stinky",
+						Operator: core.TolerationOpExists,
+						Effect:   core.TaintEffectNoSchedule,
+					}},
+				},
+			},
+			external: &v1alpha1.RuntimeClass{
+				ObjectMeta: metav1.ObjectMeta{Name: name},
+				Spec: v1alpha1.RuntimeClassSpec{
+					RuntimeHandler: handler,
+					Topology: &v1alpha1.Topology{
+						NodeSelector: &corev1.NodeSelector{
+							NodeSelectorTerms: []corev1.NodeSelectorTerm{{
+								MatchExpressions: []corev1.NodeSelectorRequirement{{
+									Key:      "extra-soft",
+									Operator: corev1.NodeSelectorOpExists,
+								}},
+							}},
+						},
+						Tolerations: []corev1.Toleration{{
+							Key:      "stinky",
+							Operator: corev1.TolerationOpExists,
+							Effect:   corev1.TaintEffectNoSchedule,
+						}},
+					},
+				},
+			},
+		},
+		"empty-topology": {
+			internal: &node.RuntimeClass{
+				ObjectMeta: metav1.ObjectMeta{Name: name},
+				Handler:    handler,
+				Topology:   &node.Topology{},
+			},
+			external: &v1alpha1.RuntimeClass{
+				ObjectMeta: metav1.ObjectMeta{Name: name},
+				Spec: v1alpha1.RuntimeClassSpec{
+					RuntimeHandler: handler,
+					Topology:       &v1alpha1.Topology{},
+				},
+			},
+		},
+		"empty": {
+			internal: &node.RuntimeClass{
+				ObjectMeta: metav1.ObjectMeta{Name: name},
+				Handler:    handler,
+			},
+			external: &v1alpha1.RuntimeClass{
 				ObjectMeta: metav1.ObjectMeta{Name: name},
 				Spec: v1alpha1.RuntimeClassSpec{
 					RuntimeHandler: handler,
 				},
+			},
+		},
 	}
 
-	convertedInternal := node.RuntimeClass{}
+	for name, test := range tests {
+		t.Run(name, func(t *testing.T) {
+			convertedInternal := &node.RuntimeClass{}
 			require.NoError(t,
-		Convert_v1alpha1_RuntimeClass_To_node_RuntimeClass(&v1alpha1RC, &convertedInternal, nil))
+				Convert_v1alpha1_RuntimeClass_To_node_RuntimeClass(test.external, convertedInternal, nil))
-	assert.Equal(t, internalRC, convertedInternal)
+			assert.Equal(t, test.internal, convertedInternal, "external -> internal")
 
-	convertedV1alpha1 := v1alpha1.RuntimeClass{}
+			convertedV1alpha1 := &v1alpha1.RuntimeClass{}
 			require.NoError(t,
-		Convert_node_RuntimeClass_To_v1alpha1_RuntimeClass(&internalRC, &convertedV1alpha1, nil))
+				Convert_node_RuntimeClass_To_v1alpha1_RuntimeClass(test.internal, convertedV1alpha1, nil))
-	assert.Equal(t, v1alpha1RC, convertedV1alpha1)
+			assert.Equal(t, test.external, convertedV1alpha1, "internal -> external")
+		})
+	}
 }

pkg/apis/node/v1beta1/BUILD

@@ -3,7 +3,6 @@ load("@io_bazel_rules_go//go:def.bzl", "go_library")
 go_library(
     name = "go_default_library",
     srcs = [
-        "conversion.go",
         "doc.go",
         "register.go",
         "zz_generated.conversion.go",

pkg/apis/node/v1beta1/conversion.go

@@ -1,25 +0,0 @@
-/*
-Copyright 2019 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 v1beta1
-
-import (
-	"k8s.io/apimachinery/pkg/runtime"
-)
-
-func addConversionFuncs(s *runtime.Scheme) error {
-	return s.AddConversionFuncs()
-}

pkg/apis/node/v1beta1/register.go

@@ -37,10 +37,3 @@ var (
 	// AddToScheme node API registration
 	AddToScheme = localSchemeBuilder.AddToScheme
 )
-
-func init() {
-	// We only register manually written functions here. The registration of the
-	// generated functions takes place in the generated files. The separation
-	// makes the code compile even when the generated files are missing.
-	localSchemeBuilder.Register(addConversionFuncs)
-}

staging/src/k8s.io/api/node/v1alpha1/doc.go

@@ -15,6 +15,7 @@ limitations under the License.
 */
 
 // +k8s:deepcopy-gen=package
+// +k8s:protobuf-gen=package
 // +k8s:openapi-gen=true
 
 // +groupName=node.k8s.io

staging/src/k8s.io/api/node/v1alpha1/types.go

@@ -60,22 +60,30 @@ type RuntimeClassSpec struct {
 	// and is immutable.
 	RuntimeHandler string `json:"runtimeHandler" protobuf:"bytes,1,opt,name=runtimeHandler"`
 
-	// Topology specifies the scheduling constrains that are necessary to assign
+	// Topology describes the set of nodes in the cluster that support this
-	// pods to the right node
+	// RuntimeClass. The rules are applied applied to pods running with this
+	// RuntimeClass and semantically merged with other scheduling constraints on
+	// the pod.
+	// If topology is nil, this RuntimeClass is assumed to be supported by all
+	// nodes.
 	// +optional
 	Topology *Topology `json:"topology,omitempty" protobuf:"bytes,3,opt,name=topology"`
 }
 
-// Topology specifies the structure of scheduling constrains for the runtime class
+// Topology specifies the scheduling constraints for nodes supporting a
+// RuntimeClass.
 type Topology struct {
-	// nodeSelector selects the set of nodes that support this RuntimeClass.
+	// NodeSelector selects the set of nodes that support this RuntimeClass.
 	// Pods using this RuntimeClass can only be scheduled to a node matched by
-	// this selector. The nodeSelector is intersected (AND) with a pod's other
+	// this selector. The NodeSelector is intersected (AND) with a pod's other
-	// node affinity or node selector requirements.
+	// NodeAffinity or NodeSelector requirements.
+	// A nil NodeSelector selects all nodes.
 	// +optional
 	NodeSelector *v1.NodeSelector `json:"nodeSelector,omitempty" protobuf:"bytes,1,opt,name=nodeSelector"`
 
-	// tolerations adds tolerations to pods running with this RuntimeClass.
+	// Tolerations are appended (excluding duplicates) to pods running with this
+	// RuntimeClass during admission, effectively unioning the set of nodes
+	// tolerated by the pod and the RuntimeClass.
 	// +optional
 	Tolerations []v1.Toleration `json:"tolerations,omitempty" protobuf:"bytes,2,rep,name=tolerations"`
 }

staging/src/k8s.io/api/node/v1beta1/doc.go

@@ -15,6 +15,7 @@ limitations under the License.
 */
 
 // +k8s:deepcopy-gen=package
+// +k8s:protobuf-gen=package
 // +k8s:openapi-gen=true
 
 // +groupName=node.k8s.io

staging/src/k8s.io/api/node/v1beta1/types.go

@@ -50,24 +50,30 @@ type RuntimeClass struct {
 	// immutable.
 	Handler string `json:"handler" protobuf:"bytes,2,opt,name=handler"`
 
-	// Topology describes the set of nodes in the cluster that support this RuntimeClass. The rules are applied to the pod during scheduling time.
+	// Topology describes the set of nodes in the cluster that support this
-	// If topology is nil, this RuntimeClass is assumed to be supported by all nodes.
+	// RuntimeClass. The rules are applied applied to pods running with this
-	// pods to the right node
+	// RuntimeClass and semantically merged with other scheduling constraints on
+	// the pod.
+	// If topology is nil, this RuntimeClass is assumed to be supported by all
+	// nodes.
 	// +optional
 	Topology *Topology `json:"topology,omitempty" protobuf:"bytes,3,opt,name=topology"`
 }
 
-// Topology specifies the scheduling constraints for nodes supporting a RuntimeClass.
+// Topology specifies the scheduling constraints for nodes supporting a
+// RuntimeClass.
 type Topology struct {
-	// nodeSelector selects the set of nodes that support this RuntimeClass.
+	// NodeSelector selects the set of nodes that support this RuntimeClass.
 	// Pods using this RuntimeClass can only be scheduled to a node matched by
-	// this selector. The nodeSelector is intersected (AND) with a pod's other
+	// this selector. The NodeSelector is intersected (AND) with a pod's other
-	// node affinity or node selector requirements. A nil nodeSelector selects all nodes.
+	// NodeAffinity or NodeSelector requirements.
+	// A nil NodeSelector selects all nodes.
 	// +optional
 	NodeSelector *v1.NodeSelector `json:"nodeSelector,omitempty" protobuf:"bytes,1,opt,name=nodeSelector"`
 
-	// tolerations adds tolerations to pods running with this RuntimeClass.
+	// Tolerations are appended (excluding duplicates) to pods running with this
-	// the tolerations are appended (excluding duplicates) to the pod's tolerations during admission.
+	// RuntimeClass during admission, effectively unioning the set of nodes
+	// tolerated by the pod and the RuntimeClass.
 	// +optional
 	Tolerations []v1.Toleration `json:"tolerations,omitempty" protobuf:"bytes,2,rep,name=tolerations"`
 }

staging/src/k8s.io/api/roundtrip_test.go

@@ -40,6 +40,8 @@ import (
 	extensionsv1beta1 "k8s.io/api/extensions/v1beta1"
 	imagepolicyv1alpha1 "k8s.io/api/imagepolicy/v1alpha1"
 	networkingv1 "k8s.io/api/networking/v1"
+	nodev1alpha1 "k8s.io/api/node/v1alpha1"
+	nodev1beta1 "k8s.io/api/node/v1beta1"
 	policyv1beta1 "k8s.io/api/policy/v1beta1"
 	rbacv1 "k8s.io/api/rbac/v1"
 	rbacv1alpha1 "k8s.io/api/rbac/v1alpha1"
@@ -83,6 +85,8 @@ var groups = []runtime.SchemeBuilder{
 	extensionsv1beta1.SchemeBuilder,
 	imagepolicyv1alpha1.SchemeBuilder,
 	networkingv1.SchemeBuilder,
+	nodev1alpha1.SchemeBuilder,
+	nodev1beta1.SchemeBuilder,
 	policyv1beta1.SchemeBuilder,
 	rbacv1alpha1.SchemeBuilder,
 	rbacv1beta1.SchemeBuilder,