Add support for ListType and ListMapKeys

These two new markers allow support for associative lists and sets.

Author: Antoine Pelisse

pkg/crd/markers/topology.go

@@ -0,0 +1,89 @@
+/*
+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 markers
+
+import (
+	"fmt"
+
+	apiext "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
+	"sigs.k8s.io/controller-tools/pkg/markers"
+)
+
+// ToplogyMarkers list topology markers (i.e. markers that specify if a
+// list is an associative-list or a set, or if a map is atomic or not).
+var TopologyMarkers = []*definitionWithHelp{
+	must(markers.MakeDefinition("listMapKey", markers.DescribesField, ListMapKey(""))).
+		WithHelp(ListMapKey("").Help()),
+	must(markers.MakeDefinition("listType", markers.DescribesField, ListType(""))).
+		WithHelp(ListType("").Help()),
+}
+
+func init() {
+	AllDefinitions = append(AllDefinitions, TopologyMarkers...)
+}
+
+// +controllertools:marker:generateHelp:category="CRD topology"
+
+// ListType specifies the type of data-structure that the list
+// represents (map, set, atomic).
+//
+// Possible data-structure types of a list are:
+//
+// - "map": it needs to have a key field, which will be used to build an
+//   associative list. A typical example is a the pod container list,
+//   which is indexed by the container name.
+//
+// - "set": Fields need to be "scalar", and there can be only one
+//   occurrence of each.
+//
+// - "atomic": All the fields in the list are treated as a single value,
+//   are typically manipulated together by the same actor.
+type ListType string
+
+// +controllertools:marker:generateHelp:category="CRD topology"
+
+// ListMapKey specifies the keys to map listTypes.
+//
+// It indicates the index of a map list. They can be repeated if multiple keys
+// must be used. It can only be used when ListType is set to map, and the keys
+// should be scalar types.
+type ListMapKey string
+
+func (l ListType) ApplyToSchema(schema *apiext.JSONSchemaProps) error {
+	if schema.Type != "array" {
+		return fmt.Errorf("must apply listType to an array")
+	}
+	if l != "map" && l != "atomic" && l != "set" {
+		return fmt.Errorf(`ListType must be either "map", "set" or "atomic"`)
+	}
+	p := string(l)
+	schema.XListType = &p
+	return nil
+}
+
+func (l ListType) ApplyFirst() {}
+
+func (l ListMapKey) ApplyToSchema(schema *apiext.JSONSchemaProps) error {
+	if schema.Type != "array" {
+		return fmt.Errorf("must apply listMapKey to an array")
+	}
+	if schema.XListType == nil || *schema.XListType != "map" {
+		return fmt.Errorf("must apply listMapKey to an associative-list")
+	}
+	schema.XListMapKeys = append(schema.XListMapKeys, string(l))
+	return nil
+}

pkg/crd/markers/zz_generated.markerhelp.go

@@ -126,6 +126,12 @@ type CronJobSpec struct {
 	// +kubebuilder:validation:EmbeddedResource
 	// +kubebuilder:validation:nullable
 	UnprunedEmbeddedResource runtime.RawExtension `json:"unprunedEmbeddedResource"`
+
+	// This tests that associative lists work.
+	// +listType=map
+	// +listMapKey=name
+	// +listMapKey=secondary
+	AssociativeList []AssociativeType `json:"associativeList"`
 }
 
 type NestedObject struct {
@@ -137,6 +143,12 @@ type RootObject struct {
 	Nested NestedObject `json:"nested"`
 }
 
+type AssociativeType struct {
+	Name      string `json:"name"`
+	Secondary int    `json:"secondary"`
+	Foo       string `json:"foo"`
+}
+
 // +kubebuilder:validation:MinLength=4
 // This tests that markers that are allowed on both fields and types are applied to types
 type LongerString string

pkg/crd/testdata/cronjob_types.go

@@ -36,6 +36,26 @@ spec:
           spec:
             description: CronJobSpec defines the desired state of CronJob
             properties:
+              associativeList:
+                description: This tests that associative lists work.
+                items:
+                  properties:
+                    foo:
+                      type: string
+                    name:
+                      type: string
+                    secondary:
+                      type: integer
+                  required:
+                  - foo
+                  - name
+                  - secondary
+                  type: object
+                type: array
+                x-kubernetes-list-map-keys:
+                - name
+                - secondary
+                x-kubernetes-list-type: map
               binaryName:
                 description: This tests byte slice schema generation.
                 format: byte
@@ -1602,6 +1622,10 @@ spec:
                                         - containerPort
                                         type: object
                                       type: array
+                                      x-kubernetes-list-map-keys:
+                                      - containerPort
+                                      - protocol
+                                      x-kubernetes-list-type: map
                                     readinessProbe:
                                       description: 'Periodic probe of container service
                                         readiness. Container will be removed from
@@ -2795,6 +2819,10 @@ spec:
                                         - containerPort
                                         type: object
                                       type: array
+                                      x-kubernetes-list-map-keys:
+                                      - containerPort
+                                      - protocol
+                                      x-kubernetes-list-type: map
                                     readinessProbe:
                                       description: 'Periodic probe of container service
                                         readiness. Container will be removed from
@@ -5018,6 +5046,7 @@ spec:
                 type: object
                 x-kubernetes-preserve-unknown-fields: true
             required:
+            - associativeList
             - binaryName
             - canBeNull
             - defaultedObject