Autogenerate API Reference Documentation (#546)

This PR allows auto generation of the API Reference documentation from the api/ directory in the repo.

Running make api-reference, or any other make target that requires auto generation of code, will cause the reference docs to be regenerated. They now live at docs/api/rabbitmq.com.ref.asciidoc. This format can be interpreted by GitHub and rendered as HTML.

Allowing this documentation to be autogenerated will prevent API elements/descriptions being updated without the API reference docs being updated alongside.

This PR also includes a GitHub Action to take the generated Asciidoc and insert it into our GitHub Wiki, so that our API reference is neatly packaged together with the source code.

Author: coro

.github/workflows/update-api-ref.yml

@@ -0,0 +1,29 @@
+name: "Update API Reference Wiki page"
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  update-api-reference:
+    name: Update API Reference Wiki
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout operator codebase
+        uses: actions/checkout@v2
+        with:
+          path: cluster-operator
+      - name: Checkout wiki codebase
+        uses: actions/checkout@v2
+        with:
+          repository: ${{ github.repository }}.wiki
+          path: wiki
+      - name: Push to wiki
+        run: |
+          cd wiki
+          git config --local user.email "[email protected]"
+          git config --local user.name "github-actions"
+          cp ../cluster-operator/docs/api/rabbitmq.com.ref.asciidoc ./API_Reference.asciidoc
+          git add .
+          git diff-index --quiet HEAD || git commit -m "Update API Reference" && git push

Makefile

@@ -23,6 +23,14 @@ manifests: install-tools ## Generate manifests e.g. CRD, RBAC etc.
 	./hack/add-notice-to-yaml.sh config/rbac/role.yaml
 	./hack/add-notice-to-yaml.sh config/crd/bases/rabbitmq.com_rabbitmqclusters.yaml
 
+api-reference: install-tools ## Generate API reference documentation
+	crd-ref-docs \
+		--source-path ./api/v1beta1 \
+		--config ./docs/api/autogen/config.yaml \
+		--templates-dir ./docs/api/autogen/templates \
+		--output-path ./docs/api/rabbitmq.com.ref.asciidoc \
+		--max-depth 30
+
 # Run go fmt against code
 fmt:
 	go fmt ./...
@@ -31,8 +39,8 @@ fmt:
 vet:
 	go vet ./...
 
-# Generate code
-generate: install-tools
+# Generate code & docs
+generate: install-tools api-reference
 	controller-gen object:headerFile=./hack/NOTICE.go.txt paths=./api/...
 	controller-gen object:headerFile=./hack/NOTICE.go.txt paths=./internal/status/...
 

api/v1beta1/rabbitmqcluster_types.go

@@ -22,44 +22,60 @@ import (
 
 // +kubebuilder:object:root=true
 
-// RabbitmqCluster is the Schema for the rabbitmqclusters API
+// RabbitmqCluster is the Schema for the RabbitmqCluster API. Each instance of this object
+// corresponds to a single RabbitMQ cluster.
 // +kubebuilder:subresource:status
 // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
 // +kubebuilder:printcolumn:name="Status",type="string",JSONPath=".status.clusterStatus"
 // +kubebuilder:resource:shortName={"rmq"}
 type RabbitmqCluster struct {
+	// Embedded metadata identifying a Kind and API Verison of an object.
+	// For more info, see: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#TypeMeta
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   RabbitmqClusterSpec   `json:"spec,omitempty"`
+	// Spec is the desired state of the RabbitmqCluster Custom Resource.
+	Spec RabbitmqClusterSpec `json:"spec,omitempty"`
+	// Status presents the observed state of RabbitmqCluster
 	Status RabbitmqClusterStatus `json:"status,omitempty"`
 }
 
 // Spec is the desired state of the RabbitmqCluster Custom Resource.
 type RabbitmqClusterSpec struct {
 	// Replicas is the number of nodes in the RabbitMQ cluster. Each node is deployed as a Replica in a StatefulSet. Only 1, 3, 5 replicas clusters are tested.
+	// This value should be an odd number to ensure the resultant cluster can establish exactly one quorum of nodes
+	// in the event of a fragmenting network partition.
 	// +optional
 	// +kubebuilder:validation:Minimum:=0
 	// +kubebuilder:default:=1
 	Replicas *int32 `json:"replicas,omitempty"`
 	// Image is the name of the RabbitMQ docker image to use for RabbitMQ nodes in the RabbitmqCluster.
+	// Must be provided together with ImagePullSecrets in order to use an image in a private registry.
 	// +kubebuilder:default:="rabbitmq:3.8.9-management"
 	Image string `json:"image,omitempty"`
 	// List of Secret resource containing access credentials to the registry for the RabbitMQ image. Required if the docker registry is private.
 	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`
+	// The desired state of the Kubernetes Service to create for the cluster.
 	// +kubebuilder:default:={type: "ClusterIP"}
 	Service RabbitmqClusterServiceSpec `json:"service,omitempty"`
+	// The desired persistent storage configuration for each Pod in the cluster.
 	// +kubebuilder:default:={storage: "10Gi"}
 	Persistence RabbitmqClusterPersistenceSpec `json:"persistence,omitempty"`
+	// The desired compute resource requirements of Pods in the cluster.
 	// +kubebuilder:default:={limits: {cpu: "2000m", memory: "2Gi"}, requests: {cpu: "1000m", memory: "2Gi"}}
 	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`
-	Affinity  *corev1.Affinity             `json:"affinity,omitempty"`
+	// Affinity scheduling rules to be applied on created Pods.
+	Affinity *corev1.Affinity `json:"affinity,omitempty"`
 	// Tolerations is the list of Toleration resources attached to each Pod in the RabbitmqCluster.
-	Tolerations []corev1.Toleration              `json:"tolerations,omitempty"`
-	Rabbitmq    RabbitmqClusterConfigurationSpec `json:"rabbitmq,omitempty"`
-	TLS         TLSSpec                          `json:"tls,omitempty"`
-	Override    RabbitmqClusterOverrideSpec      `json:"override,omitempty"`
+	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`
+	// Configuration options for RabbitMQ Pods created in the cluster.
+	Rabbitmq RabbitmqClusterConfigurationSpec `json:"rabbitmq,omitempty"`
+	// TLS-related configuration for the RabbitMQ cluster.
+	TLS TLSSpec `json:"tls,omitempty"`
+	// Provides the ability to override the generated manifest of several child resources.
+	Override RabbitmqClusterOverrideSpec `json:"override,omitempty"`
 	// If unset, or set to false, the cluster will run `rabbitmq-queues rebalance all` whenever the cluster is updated.
+	// Set to true to prevent the operator rebalancing queue leaders after a cluster update.
 	// Has no effect if the cluster only consists of one node.
 	// For more information, see https://www.rabbitmq.com/rabbitmq-queues.8.html#rebalance
 	SkipPostDeploySteps bool `json:"skipPostDeploySteps,omitempty"`
@@ -71,20 +87,27 @@ type RabbitmqClusterSpec struct {
 	TerminationGracePeriodSeconds *int64 `json:"terminationGracePeriodSeconds,omitempty"`
 }
 
+// Provides the ability to override the generated manifest of several child resources.
 type RabbitmqClusterOverrideSpec struct {
+	// Override configuration for the RabbitMQ StatefulSet.
 	StatefulSet *StatefulSet `json:"statefulSet,omitempty"`
-	Service     *Service     `json:"service,omitempty"`
+	// Override configuration for the Service created to serve traffic to the cluster.
+	Service *Service `json:"service,omitempty"`
 }
 
+// Override configuration for the Service created to serve traffic to the cluster.
+// Allows for the manifest of the created Service to be overwritten with custom configuration.
 type Service struct {
 	// +optional
 	*EmbeddedLabelsAnnotations `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
-	// Spec defines the behavior of a service.
+	// Spec defines the behavior of a Service.
 	// https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
 	// +optional
 	Spec *corev1.ServiceSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"`
 }
 
+// Override configuration for the RabbitMQ StatefulSet.
+// Allows for the manifest of the created StatefulSet to be overwritten with custom configuration.
 type StatefulSet struct {
 	// +optional
 	*EmbeddedLabelsAnnotations `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
@@ -97,9 +120,8 @@ type StatefulSet struct {
 // Field RevisionHistoryLimit is omitted.
 // Every field is made optional.
 type StatefulSetSpec struct {
-	// replicas is the desired number of replicas of the given Template.
-	// These are replicas in the sense that they are instantiations of the
-	// same Template, but individual replicas also have a consistent identity.
+	// replicas corresponds to the desired number of Pods in the StatefulSet.
+	// For more info, see https://pkg.go.dev/k8s.io/api/apps/v1#StatefulSetSpec
 	// +optional
 	Replicas *int32 `json:"replicas,omitempty" protobuf:"varint,1,opt,name=replicas"`
 
@@ -151,7 +173,8 @@ type StatefulSetSpec struct {
 	UpdateStrategy *appsv1.StatefulSetUpdateStrategy `json:"updateStrategy,omitempty" protobuf:"bytes,7,opt,name=updateStrategy"`
 }
 
-// It is used in Service and StatefulSet
+// EmbeddedLabelsAnnotations is an embedded subset of the fields included in k8s.io/apimachinery/pkg/apis/meta/v1.ObjectMeta.
+// Only labels and annotations are included.
 type EmbeddedLabelsAnnotations struct {
 	// Map of string keys and values that can be used to organize and categorize
 	// (scope and select) objects. May match selectors of replication controllers
@@ -168,9 +191,8 @@ type EmbeddedLabelsAnnotations struct {
 	Annotations map[string]string `json:"annotations,omitempty" protobuf:"bytes,12,rep,name=annotations"`
 }
 
-// EmbeddedObjectMeta contains a subset of the fields included in k8s.io/apimachinery/pkg/apis/meta/v1.ObjectMeta
+// EmbeddedObjectMeta is an embedded subset of the fields included in k8s.io/apimachinery/pkg/apis/meta/v1.ObjectMeta.
 // Only fields which are relevant to embedded resources are included.
-// It is used in PersistentVolumeClaim and PodTemplate
 type EmbeddedObjectMeta struct {
 	// Name must be unique within a namespace. Is required when creating resources, although
 	// some resources may allow a client to request the generation of an appropriate name
@@ -223,6 +245,8 @@ type PodTemplateSpec struct {
 // It contains TypeMeta and a reduced ObjectMeta.
 // Field status is omitted.
 type PersistentVolumeClaim struct {
+	// Embedded metadata identifying a Kind and API Verison of an object.
+	// For more info, see: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#TypeMeta
 	metav1.TypeMeta `json:",inline"`
 	// +optional
 	EmbeddedObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
@@ -233,12 +257,15 @@ type PersistentVolumeClaim struct {
 	Spec corev1.PersistentVolumeClaimSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"`
 }
 
+// Allows for the configuration of TLS certificates to be used by RabbitMQ. Also allows for non-TLS traffic to be disabled.
 type TLSSpec struct {
 	// Name of a Secret in the same Namespace as the RabbitmqCluster, containing the server's private key & public certificate for TLS.
 	// The Secret must store these as tls.key and tls.crt, respectively.
+	// This Secret can be created by running `kubectl create secret tls tls-secret --cert=path/to/tls.cert --key=path/to/tls.key`
 	SecretName string `json:"secretName,omitempty"`
 	// Name of a Secret in the same Namespace as the RabbitmqCluster, containing the Certificate Authority's public certificate for TLS.
 	// The Secret must store this as ca.crt.
+	// This Secret can be created by running `kubectl create secret generic ca-secret --from-file=ca.crt=path/to/ca.cert`
 	// Used for mTLS, and TLS for rabbitmq_web_stomp and rabbitmq_web_mqtt.
 	CaSecretName string `json:"caSecretName,omitempty"`
 	// When set to true, the RabbitmqCluster disables non-TLS listeners for RabbitMQ, management plugin and for any enabled plugins in the following list: stomp, mqtt, web_stomp, web_mqtt.
@@ -252,33 +279,41 @@ type TLSSpec struct {
 // +kubebuilder:validation:MaxLength=100
 type Plugin string
 
-// Rabbitmq related configurations
+// RabbitMQ-related configuration.
 type RabbitmqClusterConfigurationSpec struct {
 	// List of plugins to enable in addition to essential plugins: rabbitmq_management, rabbitmq_prometheus, and rabbitmq_peer_discovery_k8s.
 	// +kubebuilder:validation:MaxItems:=100
 	AdditionalPlugins []Plugin `json:"additionalPlugins,omitempty"`
-	// Modify to add to the rabbitmq.conf file in addition to default configurations set by the operator. Modifying this property on an existing RabbitmqCluster will trigger a StatefulSet rolling restart and will cause rabbitmq downtime.
+	// Modify to add to the rabbitmq.conf file in addition to default configurations set by the operator.
+	// Modifying this property on an existing RabbitmqCluster will trigger a StatefulSet rolling restart and will cause rabbitmq downtime.
+	// For more information on this config, see https://www.rabbitmq.com/configure.html#config-file
 	// +kubebuilder:validation:MaxLength:=2000
 	AdditionalConfig string `json:"additionalConfig,omitempty"`
-	// Specify any rabbitmq advanced.config configurations
+	// Specify any rabbitmq advanced.config configurations to apply to the cluster.
+	// For more information on advanced config, see https://www.rabbitmq.com/configure.html#advanced-config-file
 	// +kubebuilder:validation:MaxLength:=100000
 	AdvancedConfig string `json:"advancedConfig,omitempty"`
 	// Modify to add to the rabbitmq-env.conf file. Modifying this property on an existing RabbitmqCluster will trigger a StatefulSet rolling restart and will cause rabbitmq downtime.
+	// For more information on env config, see https://www.rabbitmq.com/man/rabbitmq-env.conf.5.html
 	// +kubebuilder:validation:MaxLength:=100000
 	EnvConfig string `json:"envConfig,omitempty"`
 }
 
 // The settings for the persistent storage desired for each Pod in the RabbitmqCluster.
 type RabbitmqClusterPersistenceSpec struct {
-	// StorageClassName is the name of the StorageClass to claim a PersistentVolume from.
+	// The name of the StorageClass to claim a PersistentVolume from.
 	StorageClassName *string `json:"storageClassName,omitempty"`
 	// The requested size of the persistent volume attached to each Pod in the RabbitmqCluster.
+	// The format of this field matches that defined by kubernetes/apimachinery.
+	// See https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity for more info on the format of this field.
 	// +kubebuilder:default:="10Gi"
 	Storage *k8sresource.Quantity `json:"storage,omitempty"`
 }
 
 // Settable attributes for the Service resource.
 type RabbitmqClusterServiceSpec struct {
+	// Type of Service to create for the cluster. Must be one of: ClusterIP, LoadBalancer, NodePort.
+	// For more info see https://pkg.go.dev/k8s.io/api/core/v1#ServiceType
 	// +kubebuilder:validation:Enum=ClusterIP;LoadBalancer;NodePort
 	// +kubebuilder:default:="ClusterIP"
 	Type corev1.ServiceType `json:"type,omitempty"`
@@ -288,6 +323,7 @@ type RabbitmqClusterServiceSpec struct {
 
 // Status presents the observed state of RabbitmqCluster
 type RabbitmqClusterStatus struct {
+	// Unused.
 	ClusterStatus string `json:"clusterStatus,omitempty"`
 	// Set of Conditions describing the current state of the RabbitmqCluster
 	Conditions []status.RabbitmqClusterCondition `json:"conditions"`
@@ -296,19 +332,30 @@ type RabbitmqClusterStatus struct {
 	DefaultUser *RabbitmqClusterDefaultUser `json:"defaultUser,omitempty"`
 }
 
+// Contains references to resources created with the RabbitmqCluster resource.
 type RabbitmqClusterDefaultUser struct {
-	SecretReference  *RabbitmqClusterSecretReference  `json:"secretReference,omitempty"`
+	// Reference to the Kubernetes Secret containing the credentials of the default
+	// user.
+	SecretReference *RabbitmqClusterSecretReference `json:"secretReference,omitempty"`
+	// Reference to the Kubernetes Service serving the cluster.
 	ServiceReference *RabbitmqClusterServiceReference `json:"serviceReference,omitempty"`
 }
 
+// Reference to the Kubernetes Secret containing the credentials of the default user.
 type RabbitmqClusterSecretReference struct {
-	Name      string            `json:"name"`
-	Namespace string            `json:"namespace"`
-	Keys      map[string]string `json:"keys"`
+	// Name of the Secret containing the default user credentials
+	Name string `json:"name"`
+	// Namespace of the Secret containing the default user credentials
+	Namespace string `json:"namespace"`
+	// Key-value pairs in the Secret corresponding to `username` and `password`
+	Keys map[string]string `json:"keys"`
 }
 
+// Reference to the Kubernetes Service serving the cluster.
 type RabbitmqClusterServiceReference struct {
-	Name      string `json:"name"`
+	// Name of the Service serving the cluster
+	Name string `json:"name"`
+	// Namespace of the Service serving the cluster
 	Namespace string `json:"namespace"`
 }
 
@@ -392,11 +439,14 @@ func (clusterStatus *RabbitmqClusterStatus) SetCondition(condType status.Rabbitm
 
 // +kubebuilder:object:root=true
 
-// RabbitmqClusterList contains a list of RabbitmqCluster
+// RabbitmqClusterList contains a list of RabbitmqClusters.
 type RabbitmqClusterList struct {
+	// Embedded metadata identifying a Kind and API Verison of an object.
+	// For more info, see: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#TypeMeta
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`
-	Items           []RabbitmqCluster `json:"items"`
+	// Array of RabbitmqCluster resources.
+	Items []RabbitmqCluster `json:"items"`
 }
 
 func (cluster RabbitmqCluster) ChildResourceName(name string) string {