Document G8sControlPlane CRD

docs/cr/infrastructure.giantswarm.io_v1alpha2_g8scontrolplane.yaml

@@ -0,0 +1,14 @@
+apiVersion: infrastructure.giantswarm.io/v1alpha2
+kind: Cluster
+metadata:
+  annotations:
+    giantswarm.io/docs: https://pkg.go.dev/github.com/giantswarm/apiextensions@v0.2.5/pkg/apis/infrastructure/v1alpha2?tab=doc#G8sControlPlane
+  creationTimestamp: null
+  name: 0p8h5
+spec:
+  infrastructureRef:
+    apiVersion: infrastructure.giantswarm.io/v1alpha2
+    kind: AWSControlPlane
+    name: 0p8h5
+    namespace: default
+  replicas: 1

docs/crd/infrastructure.giantswarm.io_g8scontrolplane.yaml

@@ -0,0 +1,55 @@
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  creationTimestamp: null
+  name: g8scontrolplanes.infrastructure.giantswarm.io
+spec:
+  conversion:
+    strategy: None
+  group: infrastructure.giantswarm.io
+  names:
+    kind: G8sControlPlane
+    plural: g8scontrolplanes
+    singular: g8scontrolplane
+  scope: Namespaced
+  subresources:
+    status: {}
+  versions:
+  - name: v1alpha1
+    served: false
+    storage: false
+  - name: v1alpha2
+    schema:
+      openAPIV3Schema:
+        description: |
+          This resource represents an abstract control plane (Kubernetes master node and Etcd server)
+          of a tenant cluster in a Giant Swarm installation. It is reconciled by cluster-operator.
+          For implementation details it references a provider specific resource.
+        properties:
+          spec:
+            properties:
+              infrastructureRef:
+                description: |
+                  Reference to an [AWSControlPlane](https://docs.giantswarm.io/reference/cp-k8s-api/awscontrolplanes.infrastructure.giantswarm.io/)
+                  resource defining provider specific details for the c
+                properties:
+                  apiVersion:
+                    type: string
+                  kind:
+                    type: string
+                  name:
+                    type: string
+                  namespace:
+                    type: string
+                type: object
+              replicas:
+                description: |
+                  Number of master nodes and Etcd instances to set up.
+                enum:
+                - 1
+                - 3
+                type: integer
+            type: object
+        type: object
+    served: true
+    storage: true

pkg/apis/infrastructure/v1alpha2/g8s_control_plane_types.go

@@ -8,7 +8,8 @@ import (
 )
 
 const (
-	kindG8sControlPlane = "G8sControlPlane"
+	kindG8sControlPlane              = "G8sControlPlane"
+	g8sControlPlaneDocumentationLink = "https://pkg.go.dev/github.com/giantswarm/apiextensions@v0.2.5/pkg/apis/infrastructure/v1alpha2?tab=doc#G8sControlPlane"
 )
 
 const g8sControlPlaneCRDYAML = `
@@ -36,12 +37,19 @@ spec:
       storage: true
       schema:
         openAPIV3Schema:
+          description: |
+            This resource represents an abstract control plane (Kubernetes master node and Etcd server)
+            of a tenant cluster in a Giant Swarm installation. It is reconciled by cluster-operator.
+            For implementation details it references a provider specific resource.
           type: object
           properties:
             spec:
               type: object
               properties:
                 infrastructureRef:
+                  description: |
+                    Reference to an [AWSControlPlane](https://docs.giantswarm.io/reference/cp-k8s-api/awscontrolplanes.infrastructure.giantswarm.io/)
+                    resource defining provider specific details for the c
                   type: object
                   properties:
                     apiVersion:
@@ -53,6 +61,8 @@ spec:
                     namespace:
                       type: string
                 replicas:
+                  description: |
+                    Number of master nodes and Etcd instances to set up.
                   type: integer
                   enum:
                     - 1
@@ -79,6 +89,18 @@ func NewG8sControlPlaneTypeMeta() metav1.TypeMeta {
 	}
 }
 
+// NewG8sControlPlaneCR returns a G8sControlPlane Custom Resource.
+func NewG8sControlPlaneCR() *G8sControlPlane {
+	return &G8sControlPlane{
+		ObjectMeta: metav1.ObjectMeta{
+			Annotations: map[string]string{
+				crDocsAnnotation: g8sControlPlaneDocumentationLink,
+			},
+		},
+		TypeMeta: NewClusterTypeMeta(),
+	}
+}
+
 // +genclient
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 

pkg/apis/infrastructure/v1alpha2/g8s_control_plane_types_test.go

@@ -1,6 +1,19 @@
 package v1alpha2
 
-import "testing"
+import (
+	"bytes"
+	"fmt"
+	"io/ioutil"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	corev1 "k8s.io/api/core/v1"
+	"k8s.io/apimachinery/pkg/runtime"
+	"sigs.k8s.io/yaml"
+)
 
 func Test_NewG8sControlPlaneCRD(t *testing.T) {
 	crd := NewG8sControlPlaneCRD()
@@ -11,3 +24,78 @@ func Test_NewG8sControlPlaneCRD(t *testing.T) {
 		t.Error("G8sControlPlane CRD name was empty")
 	}
 }
+
+func Test_GenerateG8sControlPlaneYAML(t *testing.T) {
+	crd := NewG8sControlPlaneCRD()
+
+	crdGroup := crd.Spec.Group
+	crdKindLower := strings.ToLower(crd.Spec.Names.Kind)
+
+	testCases := []struct {
+		category string
+		name     string
+		resource runtime.Object
+	}{
+		{
+			category: "crd",
+			name:     fmt.Sprintf("%s_%s.yaml", crdGroup, crdKindLower),
+			resource: crd,
+		},
+		{
+			category: "cr",
+			name:     fmt.Sprintf("%s_%s_%s.yaml", crdGroup, version, crdKindLower),
+			resource: newG8sControlPlaneExampleCR(),
+		},
+	}
+
+	docs := filepath.Join(root, "..", "..", "..", "..", "docs")
+	for i, tc := range testCases {
+		t.Run(fmt.Sprintf("case %d: generates %s successfully", i, tc.name), func(t *testing.T) {
+			rendered, err := yaml.Marshal(tc.resource)
+			if err != nil {
+				t.Fatal(err)
+			}
+			directory := filepath.Join(docs, tc.category)
+			path := filepath.Join(directory, tc.name)
+
+			// We don't want a status in the docs YAML for the CR and CRD so that they work with `kubectl create -f <file>.yaml`.
+			// This just strips off the top level `status:` and everything following.
+			statusRegex := regexp.MustCompile(`(?ms)^status:.*$`)
+			rendered = statusRegex.ReplaceAll(rendered, []byte(""))
+
+			if *update {
+				err := ioutil.WriteFile(path, rendered, 0644)
+				if err != nil {
+					t.Fatal(err)
+				}
+			}
+			goldenFile, err := ioutil.ReadFile(path)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			if !bytes.Equal(rendered, goldenFile) {
+				t.Fatalf("\n\n%s\n", cmp.Diff(string(goldenFile), string(rendered)))
+			}
+		})
+	}
+}
+
+func newG8sControlPlaneExampleCR() *G8sControlPlane {
+	cr := NewG8sControlPlaneCR()
+
+	cr.Name = "0p8h5"
+	cr.Spec = G8sControlPlaneSpec{
+		// ClusterNetwork does not occur in our practice, so leaving it empty.
+		//ClusterNetwork:    &apiv1alpha2.ClusterNetwork{},
+		InfrastructureRef: corev1.ObjectReference{
+			APIVersion: "infrastructure.giantswarm.io/v1alpha2",
+			Kind:       "AWSControlPlane",
+			Name:       "0p8h5",
+			Namespace:  "default",
+		},
+		Replicas: 1,
+	}
+
+	return cr
+}