Don't generate description on metadata of CRD structural schema

kubernetes-sigs · Nov 9, 2020 · 3e8c2d0 · 3e8c2d0
1 parent ede1d01
commit 3e8c2d0
Show file tree

Hide file tree

Showing 6 changed files with 88 additions and 4 deletions.
diff --git a/pkg/crd/gen.go b/pkg/crd/gen.go
@@ -285,7 +285,7 @@ func FindKubeKinds(parser *Parser, metav1Pkg *loader.Package) map[schema.GroupKi
 		pkg.NeedTypesInfo()
 		typesInfo := pkg.TypesInfo
 
-		for _, field := range info.Fields {
+		for i, field := range info.Fields {
 			if field.Name != "" {
 				// type and object meta are embedded,
 				// so they can't be this
@@ -312,6 +312,11 @@ func FindKubeKinds(parser *Parser, metav1Pkg *loader.Package) map[schema.GroupKi
 			switch namedField.Obj().Name() {
 			case "ObjectMeta":
 				hasObjectMeta = true
+				// Clear the godoc comment from the ObjectMeta field
+				// so it does not show up as the description, because
+				// description is not allowed in metadata of CRD structural schema.
+				field.Doc = ""
+				info.Fields[i] = field
 			case "TypeMeta":
 				hasTypeMeta = true
 			}

diff --git a/pkg/crd/gen_integration_test.go b/pkg/crd/gen_integration_test.go
@@ -31,7 +31,7 @@ import (
 	"sigs.k8s.io/controller-tools/pkg/markers"
 )
 
-var _ = Describe("CRD Generation proper defaulting", func() {
+var _ = Describe("CRD Generation integration tests", func() {
 	var ctx *genall.GenerationContext
 	var out *outputRule
 	BeforeEach(func() {
@@ -91,6 +91,20 @@ var _ = Describe("CRD Generation proper defaulting", func() {
 		Expect(out.buf.Bytes()).To(Equal(expectedFile))
 
 	})
+
+	It("should ignore godoc comments on ObjectMetadata and not create a description", func() {
+		By("calling Generate")
+		gen := &crd.Generator{}
+		Expect(gen.Generate(ctx)).NotTo(HaveOccurred())
+
+		By("loading the desired YAML")
+		expectedFile, err := ioutil.ReadFile("./testdata/gen/foo_crd_valid_metadata.yaml")
+		Expect(err).NotTo(HaveOccurred())
+
+		By("comparing the two")
+		Expect(out.buf.Bytes()).To(Equal(expectedFile))
+	})
+
 })
 
 type outputRule struct {

diff --git a/pkg/crd/testdata/gen/foo_crd_v1.yaml b/pkg/crd/testdata/gen/foo_crd_v1.yaml
@@ -33,6 +33,7 @@ spec:
           metadata:
             type: object
           spec:
+            description: Spec comments SHOULD appear in the CRD spec
             properties:
               defaultedString:
                 default: fooDefaultString
@@ -43,6 +44,7 @@ spec:
             - defaultedString
             type: object
           status:
+            description: Status comments SHOULD appear in the CRD spec
             type: object
         type: object
     served: true

diff --git a/pkg/crd/testdata/gen/foo_crd_v1beta1.yaml b/pkg/crd/testdata/gen/foo_crd_v1beta1.yaml
@@ -31,6 +31,7 @@ spec:
         metadata:
           type: object
         spec:
+          description: Spec comments SHOULD appear in the CRD spec
           properties:
             defaultedString:
               description: This tests that defaulted fields are stripped for v1beta1,
@@ -40,6 +41,7 @@ spec:
           - defaultedString
           type: object
         status:
+          description: Status comments SHOULD appear in the CRD spec
           type: object
       type: object
   version: foo

diff --git a/pkg/crd/testdata/gen/foo_crd_valid_metadata.yaml b/pkg/crd/testdata/gen/foo_crd_valid_metadata.yaml
@@ -0,0 +1,57 @@
+
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  annotations:
+    controller-gen.kubebuilder.io/version: (unknown)
+  creationTimestamp: null
+  name: foos.bar.example.com
+spec:
+  group: bar.example.com
+  names:
+    kind: Foo
+    listKind: FooList
+    plural: foos
+    singular: foo
+  scope: Namespaced
+  versions:
+  - name: foo
+    schema:
+      openAPIV3Schema:
+        properties:
+          apiVersion:
+            description: 'APIVersion defines the versioned schema of this representation
+              of an object. Servers should convert recognized schemas to the latest
+              internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#resources'
+            type: string
+          kind:
+            description: 'Kind is a string value representing the REST resource this
+              object represents. Servers may infer this from the endpoint the client
+              submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds'
+            type: string
+          metadata:
+            type: object
+          spec:
+            description: Spec comments SHOULD appear in the CRD spec
+            properties:
+              defaultedString:
+                default: fooDefaultString
+                description: This tests that defaulted fields are stripped for v1beta1,
+                  but not for v1
+                type: string
+            required:
+            - defaultedString
+            type: object
+          status:
+            description: Status comments SHOULD appear in the CRD spec
+            type: object
+        type: object
+    served: true
+    storage: true
+status:
+  acceptedNames:
+    kind: ""
+    plural: ""
+  conditions: []
+  storedVersions: []
diff --git a/pkg/crd/testdata/gen/foo_types.go b/pkg/crd/testdata/gen/foo_types.go
@@ -30,9 +30,13 @@ type FooSpec struct {
 type FooStatus struct{}
 
 type Foo struct {
-	metav1.TypeMeta   `json:",inline"`
+	// TypeMeta comments should NOT appear in the CRD spec
+	metav1.TypeMeta `json:",inline"`
+	// ObjectMeta comments should NOT appear in the CRD spec
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   FooSpec   `json:"spec,omitempty"`
+	// Spec comments SHOULD appear in the CRD spec
+	Spec FooSpec `json:"spec,omitempty"`
+	// Status comments SHOULD appear in the CRD spec
 	Status FooStatus `json:"status,omitempty"`
 }