Merge pull request #774 from sbueringer/pr-add-example-marker

✨ Add support for example marker

Author: k8s-ci-robot

pkg/crd/markers/validation.go

@@ -86,6 +86,9 @@ var FieldOnlyMarkers = []*definitionWithHelp{
 	must(markers.MakeAnyTypeDefinition("kubebuilder:default", markers.DescribesField, Default{})).
 		WithHelp(Default{}.Help()),
 
+	must(markers.MakeAnyTypeDefinition("kubebuilder:example", markers.DescribesField, Example{})).
+		WithHelp(Example{}.Help()),
+
 	must(markers.MakeDefinition("kubebuilder:validation:EmbeddedResource", markers.DescribesField, XEmbeddedResource{})).
 		WithHelp(XEmbeddedResource{}.Help()),
 
@@ -222,6 +225,19 @@ type Default struct {
 	Value interface{}
 }
 
+// +controllertools:marker:generateHelp:category="CRD validation"
+// Example sets the example value for this field.
+//
+// An example value will be accepted as any value valid for the
+// field. Formatting for common types include: boolean: `true`, string:
+// `Cluster`, numerical: `1.24`, array: `{1,2}`, object: `{policy:
+// "delete"}`). Examples should be defined in pruned form, and only best-effort
+// validation will be performed. Full validation of an example requires
+// submission of the containing CRD to an apiserver.
+type Example struct {
+	Value interface{}
+}
+
 // +controllertools:marker:generateHelp:category="CRD processing"
 // PreserveUnknownFields stops the apiserver from pruning fields which are not specified.
 //
@@ -465,6 +481,15 @@ func (m Default) ApplyToSchema(schema *apiext.JSONSchemaProps) error {
 	return nil
 }
 
+func (m Example) ApplyToSchema(schema *apiext.JSONSchemaProps) error {
+	marshalledExample, err := json.Marshal(m.Value)
+	if err != nil {
+		return err
+	}
+	schema.Example = &apiext.JSON{Raw: marshalledExample}
+	return nil
+}
+
 func (m XPreserveUnknownFields) ApplyToSchema(schema *apiext.JSONSchemaProps) error {
 	defTrue := true
 	schema.XPreserveUnknownFields = &defTrue

pkg/crd/markers/zz_generated.markerhelp.go

@@ -107,14 +107,17 @@ type CronJobSpec struct {
 
 	// This tests that primitive defaulting can be performed.
 	// +kubebuilder:default=forty-two
+	// +kubebuilder:example=forty-two
 	DefaultedString string `json:"defaultedString"`
 
 	// This tests that slice defaulting can be performed.
 	// +kubebuilder:default={a,b}
+	// +kubebuilder:example={a,b}
 	DefaultedSlice []string `json:"defaultedSlice"`
 
 	// This tests that object defaulting can be performed.
 	// +kubebuilder:default={{nested: {foo: "baz", bar: true}},{nested: {bar: false}}}
+	// +kubebuilder:example={{nested: {foo: "baz", bar: true}},{nested: {bar: false}}}
 	DefaultedObject []RootObject `json:"defaultedObject"`
 
 	// This tests that pattern validator is properly applied.

pkg/crd/testdata/cronjob_types.go

@@ -38,6 +38,7 @@ spec:
                 default: fooDefaultString
                 description: This tests that defaulted fields are stripped for v1beta1,
                   but not for v1
+                example: fooExampleString
                 type: string
             required:
             - defaultedString

pkg/crd/testdata/gen/bar.example.com_foos.yaml

@@ -28,6 +28,7 @@ type FooSpec struct {
 	// This tests that defaulted fields are stripped for v1beta1,
 	// but not for v1
 	// +kubebuilder:default=fooDefaultString
+	// +kubebuilder:example=fooExampleString
 	DefaultedString string `json:"defaultedString"`
 }
 type FooStatus struct{}

pkg/crd/testdata/gen/foo_types.go

@@ -38,6 +38,7 @@ spec:
                 default: zooDefaultString
                 description: This tests that defaulted fields are stripped for v1beta1,
                   but not for v1
+                example: zooExampleString
                 type: string
             required:
             - defaultedString

pkg/crd/testdata/gen/zoo/bar.example.com_zooes.yaml

@@ -28,6 +28,7 @@ type ZooSpec struct {
 	// This tests that defaulted fields are stripped for v1beta1,
 	// but not for v1
 	// +kubebuilder:default=zooDefaultString
+	// +kubebuilder:example=zooExampleString
 	DefaultedString string `json:"defaultedString"`
 }
 type ZooStatus struct{}

pkg/crd/testdata/gen/zoo/zoo_types.go

@@ -105,6 +105,12 @@ spec:
                 - nested:
                     bar: false
                 description: This tests that object defaulting can be performed.
+                example:
+                - nested:
+                    bar: true
+                    foo: baz
+                - nested:
+                    bar: false
                 items:
                   properties:
                     nested:
@@ -126,12 +132,16 @@ spec:
                 - a
                 - b
                 description: This tests that slice defaulting can be performed.
+                example:
+                - a
+                - b
                 items:
                   type: string
                 type: array
               defaultedString:
                 default: forty-two
                 description: This tests that primitive defaulting can be performed.
+                example: forty-two
                 type: string
               embeddedResource:
                 type: object