From d2a87d5afc3cd745b9c5ee989bc7c2ad60baee36 Mon Sep 17 00:00:00 2001 From: Tim Allclair Date: Tue, 23 Apr 2019 17:06:09 -0700 Subject: [PATCH] Clean up RuntimeClass Topology documentation --- pkg/apis/node/types.go | 28 +++-- pkg/apis/node/v1alpha1/BUILD | 2 + pkg/apis/node/v1alpha1/conversion_test.go | 101 +++++++++++++++--- pkg/apis/node/v1beta1/BUILD | 1 - pkg/apis/node/v1beta1/conversion.go | 25 ----- pkg/apis/node/v1beta1/register.go | 7 -- staging/src/k8s.io/api/node/v1alpha1/doc.go | 1 + staging/src/k8s.io/api/node/v1alpha1/types.go | 22 ++-- staging/src/k8s.io/api/node/v1beta1/doc.go | 1 + staging/src/k8s.io/api/node/v1beta1/types.go | 24 +++-- staging/src/k8s.io/api/roundtrip_test.go | 4 + 11 files changed, 141 insertions(+), 75 deletions(-) delete mode 100644 pkg/apis/node/v1beta1/conversion.go diff --git a/pkg/apis/node/types.go b/pkg/apis/node/types.go index 5db5600f9ba..0bf1808578b 100644 --- a/pkg/apis/node/types.go +++ b/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 - // pods to the right node + // Topology describes the set of nodes in the cluster that support this + // 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 - // node affinity or node selector requirements. + // this selector. The NodeSelector is intersected (AND) with a pod's other + // 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 diff --git a/pkg/apis/node/v1alpha1/BUILD b/pkg/apis/node/v1alpha1/BUILD index 061c744953c..216b1e4f2b7 100644 --- a/pkg/apis/node/v1alpha1/BUILD +++ b/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", diff --git a/pkg/apis/node/v1alpha1/conversion_test.go b/pkg/apis/node/v1alpha1/conversion_test.go index 6c794ef6c78..124643820f0 100644 --- a/pkg/apis/node/v1alpha1/conversion_test.go +++ b/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{ - ObjectMeta: metav1.ObjectMeta{Name: name}, - Handler: handler, - } - v1alpha1RC := v1alpha1.RuntimeClass{ - ObjectMeta: metav1.ObjectMeta{Name: name}, - Spec: v1alpha1.RuntimeClassSpec{ - RuntimeHandler: handler, + 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{ + 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{} - require.NoError(t, - Convert_v1alpha1_RuntimeClass_To_node_RuntimeClass(&v1alpha1RC, &convertedInternal, nil)) - assert.Equal(t, internalRC, convertedInternal) + for name, test := range tests { + t.Run(name, func(t *testing.T) { + convertedInternal := &node.RuntimeClass{} + require.NoError(t, + Convert_v1alpha1_RuntimeClass_To_node_RuntimeClass(test.external, convertedInternal, nil)) + assert.Equal(t, test.internal, convertedInternal, "external -> internal") - convertedV1alpha1 := v1alpha1.RuntimeClass{} - require.NoError(t, - Convert_node_RuntimeClass_To_v1alpha1_RuntimeClass(&internalRC, &convertedV1alpha1, nil)) - assert.Equal(t, v1alpha1RC, convertedV1alpha1) + convertedV1alpha1 := &v1alpha1.RuntimeClass{} + require.NoError(t, + Convert_node_RuntimeClass_To_v1alpha1_RuntimeClass(test.internal, convertedV1alpha1, nil)) + assert.Equal(t, test.external, convertedV1alpha1, "internal -> external") + }) + } } diff --git a/pkg/apis/node/v1beta1/BUILD b/pkg/apis/node/v1beta1/BUILD index 53b756e3a77..07ef4b482b2 100644 --- a/pkg/apis/node/v1beta1/BUILD +++ b/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", diff --git a/pkg/apis/node/v1beta1/conversion.go b/pkg/apis/node/v1beta1/conversion.go deleted file mode 100644 index b7d88363d2d..00000000000 --- a/pkg/apis/node/v1beta1/conversion.go +++ /dev/null @@ -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() -} diff --git a/pkg/apis/node/v1beta1/register.go b/pkg/apis/node/v1beta1/register.go index 19250848d01..e018e3b70e4 100644 --- a/pkg/apis/node/v1beta1/register.go +++ b/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) -} diff --git a/staging/src/k8s.io/api/node/v1alpha1/doc.go b/staging/src/k8s.io/api/node/v1alpha1/doc.go index f7f8b78b42a..dfe99540b53 100644 --- a/staging/src/k8s.io/api/node/v1alpha1/doc.go +++ b/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 diff --git a/staging/src/k8s.io/api/node/v1alpha1/types.go b/staging/src/k8s.io/api/node/v1alpha1/types.go index a0c133cfb6e..e061335d4ce 100644 --- a/staging/src/k8s.io/api/node/v1alpha1/types.go +++ b/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 - // pods to the right node + // Topology describes the set of nodes in the cluster that support this + // 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 - // node affinity or node selector requirements. + // this selector. The NodeSelector is intersected (AND) with a pod's other + // 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"` } diff --git a/staging/src/k8s.io/api/node/v1beta1/doc.go b/staging/src/k8s.io/api/node/v1beta1/doc.go index 0e8338cf7ab..e87583cea93 100644 --- a/staging/src/k8s.io/api/node/v1beta1/doc.go +++ b/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 diff --git a/staging/src/k8s.io/api/node/v1beta1/types.go b/staging/src/k8s.io/api/node/v1beta1/types.go index 628507be25c..8d65785803a 100644 --- a/staging/src/k8s.io/api/node/v1beta1/types.go +++ b/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. - // If topology is nil, this RuntimeClass is assumed to be supported by all nodes. - // pods to the right node + // Topology describes the set of nodes in the cluster that support this + // 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 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 - // node affinity or node selector requirements. A nil nodeSelector selects all nodes. + // this selector. The NodeSelector is intersected (AND) with a pod's other + // 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. - // the tolerations are appended (excluding duplicates) to the pod's tolerations during admission. + // 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"` } diff --git a/staging/src/k8s.io/api/roundtrip_test.go b/staging/src/k8s.io/api/roundtrip_test.go index a36721f10a8..910732174f0 100644 --- a/staging/src/k8s.io/api/roundtrip_test.go +++ b/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,