Merge pull request #1165 from keynslug/doc/refine-v2-crd

chore: refine descriptions of CRD API structures

Author: keynslug

Makefile

@@ -97,6 +97,17 @@ build: manifests generate fmt vet ## Build manager binary.
 run: manifests generate fmt vet ## Run a controller from your host.
 	go run ./cmd/main.go
 
+.PHONY: doc
+doc: crd-ref-docs manifests doc-crd-v2 ## Generate documentation for the CRDs.
+
+.PHONY: doc-crd-v2
+doc-crd-v2: ## Generate documentation for the `apps.emqx.io/v2` CRD.
+	$(CRD_REF_DOCS) \
+		--source-path=api/v2 \
+		--config=crd-ref-docs-config.yaml \
+		--output-path=docs/en_US/reference/v2-reference.md \
+		--renderer=markdown
+
 # If you wish to build the manager image targeting other platforms you can use the --platform flag.
 # (i.e. docker build --platform linux/arm64). However, you must enable docker buildKit for it.
 # More info: https://docs.docker.com/develop/develop-images/build_enhancements/
@@ -178,12 +189,14 @@ KUSTOMIZE ?= $(LOCALBIN)/kustomize
 CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
 ENVTEST ?= $(LOCALBIN)/setup-envtest
 GOLANGCI_LINT = $(LOCALBIN)/golangci-lint
+CRD_REF_DOCS ?= $(LOCALBIN)/crd-ref-docs
 
 ## Tool Versions
 KUSTOMIZE_VERSION ?= v5.5.0
 CONTROLLER_TOOLS_VERSION ?= v0.18.0
 ENVTEST_VERSION ?= release-0.19
 GOLANGCI_LINT_VERSION ?= v1.64.8
+CRD_REF_DOCS_VERSION ?= latest
 
 .PHONY: kustomize
 kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
@@ -205,6 +218,11 @@ golangci-lint: $(GOLANGCI_LINT) ## Download golangci-lint locally if necessary.
 $(GOLANGCI_LINT): $(LOCALBIN)
 	$(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/cmd/golangci-lint,$(GOLANGCI_LINT_VERSION))
 
+.PHONY: crd-ref-docs
+crd-ref-docs: $(CRD_REF_DOCS) ## Download crd-ref-docs locally if necessary.
+$(CRD_REF_DOCS): $(LOCALBIN)
+	$(call go-install-tool,$(CRD_REF_DOCS),github.com/elastic/crd-ref-docs,$(CRD_REF_DOCS_VERSION))
+
 # go-install-tool will 'go install' any package with custom target and name of binary, if it doesn't exist
 # $1 - target path with name of binary
 # $2 - package url which can be installed

api/v2/emqx_types.go

@@ -27,18 +27,18 @@ import (
 // +kubebuilder:printcolumn:name="Status",type="string",JSONPath=".status.conditions[?(@.status==\"True\")].type"
 // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
 
-// EMQX is the Schema for the emqxes API.
+// Custom Resource representing an EMQX cluster.
 type EMQX struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   EMQXSpec   `json:"spec,omitempty"`
+	// Specification of the desired state of the EMQX cluster.
+	Spec EMQXSpec `json:"spec,omitempty"`
+	// Current status of the EMQX cluster.
 	Status EMQXStatus `json:"status,omitempty"`
 }
 
 // +kubebuilder:object:root=true
-
-// EMQXList contains a list of EMQX.
 type EMQXList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`

api/v2/emqx_types_spec.go

@@ -24,19 +24,25 @@ import (
 
 // EMQXStatus defines the observed state of EMQX
 type EMQXStatus struct {
-	// Represents the latest available observations of a EMQX Custom Resource current state.
+	// Conditions representing the current status of the EMQX Custom Resource.
 	// +listType=map
 	// +listMapKey=type
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	CoreNodes       []EMQXNode      `json:"coreNodes,omitempty"`
+	// Status of each core node in the cluster.
+	CoreNodes []EMQXNode `json:"coreNodes,omitempty"`
+	// Summary status of the set of core nodes.
 	CoreNodesStatus EMQXNodesStatus `json:"coreNodesStatus,omitempty"`
 
-	ReplicantNodes       []EMQXNode      `json:"replicantNodes,omitempty"`
+	// Status of each replicant node in the cluster.
+	ReplicantNodes []EMQXNode `json:"replicantNodes,omitempty"`
+	// Summary status of the set of replicant nodes.
 	ReplicantNodesStatus EMQXNodesStatus `json:"replicantNodesStatus,omitempty"`
 
+	// Status of active node evacuations in the cluster.
 	NodeEvacuationsStatus []NodeEvacuationStatus `json:"nodeEvacuationsStatus,omitempty"`
-	DSReplication         DSReplicationStatus    `json:"dsReplication,omitempty"`
+	// Status of EMQX Durable Storage replication.
+	DSReplication DSReplicationStatus `json:"dsReplication,omitempty"`
 }
 
 type NodeEvacuationStatus struct {
@@ -48,24 +54,31 @@ type NodeEvacuationStatus struct {
 	State string `json:"state,omitempty"`
 	// Session recipients
 	// +kubebuilder:example={"[email protected]", "[email protected]"}
-	SessionRecipients      []string `json:"sessionRecipients,omitempty"`
-	SessionEvictionRate    int32    `json:"sessionEvictionRate,omitempty"`
-	ConnectionEvictionRate int32    `json:"connectionEvictionRate,omitempty"`
+	SessionRecipients []string `json:"sessionRecipients,omitempty"`
+	// Session eviction rate, in sessions per second.
+	SessionEvictionRate int32 `json:"sessionEvictionRate,omitempty"`
+	// Connection eviction rate, in connections per second.
+	ConnectionEvictionRate int32 `json:"connectionEvictionRate,omitempty"`
 	// Initial number of sessions on this node
 	InitialSessions int32 `json:"initialSessions,omitempty"`
 	// Initial number of connections to this node
 	InitialConnections int32 `json:"initialConnections,omitempty"`
 }
 
 type EMQXNodesStatus struct {
-	Replicas      int32 `json:"replicas,omitempty"`
+	// Total number of replicas.
+	Replicas int32 `json:"replicas,omitempty"`
+	// Number of ready replicas.
 	ReadyReplicas int32 `json:"readyReplicas,omitempty"`
-
+	// Current revision of the respective core or replicant set.
 	CurrentRevision string `json:"currentRevision,omitempty"`
-	CurrentReplicas int32  `json:"currentReplicas,omitempty"`
-
+	// Number of replicas running current revision.
+	CurrentReplicas int32 `json:"currentReplicas,omitempty"`
+	// Update revision of the respective core or replicant set.
+	// When different from the current revision, the set is being updated.
 	UpdateRevision string `json:"updateRevision,omitempty"`
-	UpdateReplicas int32  `json:"updateReplicas,omitempty"`
+	// Number of replicas running update revision.
+	UpdateReplicas int32 `json:"updateReplicas,omitempty"`
 
 	CollisionCount *int32 `json:"collisionCount,omitempty"`
 }