chore: update api-reference doc (#6618)

Co-authored-by: huangzhangshu <[email protected]>

.github/utils/utils.sh

@@ -511,6 +511,12 @@ get_trigger_mode() {
             pkg/cli/cmd/*)
                 add_trigger_mode "[cli][test]"
             ;;
+            apis/*)
+                add_trigger_mode "[apis][test]"
+            ;;
+            pkg/lorry/ctl/*)
+                add_trigger_mode "[lorry][test]"
+            ;;
             *)
                 add_trigger_mode "[test]"
             ;;

.github/workflows/cicd-push.yml

@@ -236,3 +236,41 @@ jobs:
       WORKFLOW_ID: "deploy.yml"
       APECD_REF: "v0.1.43"
     secrets: inherit
+
+  apis-doc:
+    needs: [ trigger-mode ]
+    runs-on: ubuntu-latest
+    if: ${{ contains(needs.trigger-mode.outputs.trigger-mode, '[apis]') || contains(needs.trigger-mode.outputs.trigger-mode, '[lorry]') }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: install lib
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libbtrfs-dev \
+            libdevmapper-dev
+
+      - name: Setup Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: "${{ env.GO_VERSION }}"
+
+      - name: Check apis doc
+        id: check-apis-doc
+        run: |
+          make doc
+          FILE_CHANGES=`git diff --name-only ${{ github.sha }}`
+          if [[ ! -z "$FILE_CHANGES" ]]; then
+            echo $FILE_CHANGES
+            git config --local user.name "$GITHUB_ACTOR"
+            git config --local user.email "[email protected]"
+            git commit -a -m "chore: auto update apis doc changes"
+          fi
+          echo file_changes=$FILE_CHANGES >> $GITHUB_OUTPUT
+
+      - name: Push apis doc changes
+        uses: ad-m/github-push-action@master
+        if: ${{ steps.check-apis-doc.outputs.file_changes }}
+        with:
+          github_token: ${{ env.GITHUB_TOKEN }}
+          branch: ${{ github.ref }}

Makefile

@@ -263,6 +263,8 @@ lorryctl-doc: generate test-go-generate ## generate CLI command reference manual
 api-doc:  ## generate API reference manual.
 	@./hack/docgen/api/generate.sh
 
+.PHONY: doc
+doc: lorryctl-doc api-doc ## generate all documents.
 
 ##@ Operator Controller Manager
 

apis/apps/v1alpha1/cluster_types.go

@@ -289,7 +289,7 @@ type ClusterStatus struct {
 // ShardingSpec defines the sharding spec.
 type ShardingSpec struct {
 	// name defines sharding name, this name is also part of Service DNS name, so this name will comply with IANA Service Naming rule.
-	// The name is also used to generate the name of the underlying components with the naming pattern <ShardingSpec.Name>-<ShardID>.
+	// The name is also used to generate the name of the underlying components with the naming pattern `$(ShardingSpec.Name)-$(ShardID)`.
 	// At the same time, the name of component template defined in ShardingSpec.Template.Name will be ignored.
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MaxLength=15

apis/apps/v1alpha1/doc.go

@@ -17,7 +17,7 @@ You should have received a copy of the GNU Affero General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-//go:generate go run ../../../hack/docgen/api/main.go -api-dir . -config ../../../hack/docgen/api/gen-api-doc-config.json -template-dir ../../../hack/docgen/api/template -out-file ../../../docs/user_docs/api-reference/cluster.md
+//go:generate go run ../../../hack/docgen/api/main.go -api-dir . -config ../../../hack/docgen/api/gen-api-doc-config.json -template-dir ../../../hack/docgen/api/template -out-file ../../../docs/developer_docs/api-reference/cluster.md
 
 // +k8s:deepcopy-gen=package,register
 // +k8s:openapi-gen=true

apis/apps/v1alpha1/opsdefinition_types.go

@@ -64,12 +64,12 @@ type ComponentDefinitionRef struct {
 	Name string `json:"name"`
 
 	// the account name of the component.
-	// will inject the account username and password to KB_ACCOUNT_USERNAME and KB_ACCOUNT_PASSWORD in env of the job.
+	// will inject the account username and password to `KB_ACCOUNT_USERNAME` and `KB_ACCOUNT_PASSWORD` in env of the job.
 	// +optional
 	AccountName string `json:"accountName,omitempty"`
 
 	// reference the services[*].name.
-	// will map the service name and ports to KB_COMP_SVC_NAME and KB_COMP_SVC_PORT_<portName> in env of the job.
+	// will map the service name and ports to `KB_COMP_SVC_NAME` and `KB_COMP_SVC_PORT_$(portName)` in env of the job.
 	// portName will replace the characters '-' to '_' and convert to uppercase.
 	// +optional
 	ServiceName string `json:"serviceName,omitempty"`
@@ -215,7 +215,7 @@ type OpsDefinition struct {
 	Status OpsDefinitionStatus `json:"status,omitempty"`
 }
 
-//+kubebuilder:object:root=true
+// +kubebuilder:object:root=true
 
 // OpsDefinitionList contains a list of OpsDefinition
 type OpsDefinitionList struct {

apis/apps/v1alpha1/type.go

@@ -622,8 +622,8 @@ type ComponentService struct {
 
 	// GeneratePodOrdinalService indicates whether to create a corresponding Service for each Pod of the selected Component.
 	// If sets to true, a set of Service will be automatically generated for each Pod. And Service.RoleSelector will be ignored.
-	// They can be referred to by adding the PodOrdinal to the defined ServiceName with named pattern <Service.ServiceName>-<PodOrdinal>.
-	// And the Service.Name will also be generated with named pattern <Service.Name>-<PodOrdinal>.
+	// They can be referred to by adding the PodOrdinal to the defined ServiceName with named pattern `$(Service.ServiceName)-$(PodOrdinal)`.
+	// And the Service.Name will also be generated with named pattern `$(Service.Name)-$(PodOrdinal)`.
 	// The PodOrdinal is zero-based, and the number of generated Services is equal to the number of replicas of the Component.
 	// For example, a Service might be defined as follows:
 	// - name: my-service
@@ -651,8 +651,8 @@ type Service struct {
 
 	// ServiceName defines the name of the underlying service object.
 	// If not specified, the default service name with different patterns will be used:
-	//  - <CLUSTER_NAME>: for cluster-level services
-	//  - <CLUSTER_NAME>-<COMPONENT_NAME>: for component-level services
+	//  - CLUSTER_NAME: for cluster-level services
+	//  - CLUSTER_NAME-COMPONENT_NAME: for component-level services
 	// Only one default service name is allowed.
 	// Cannot be updated.
 	// +optional
@@ -797,7 +797,7 @@ type ServiceVarSelector struct {
 
 	// GeneratePodOrdinalServiceVar indicates whether to create a corresponding ServiceVars reference variable for each Pod.
 	// If set to true, a set of ServiceVars that can be referenced will be automatically generated for each Pod Ordinal.
-	// They can be referred to by adding the PodOrdinal to the defined name template with named pattern $<Vars[x].Name>_<PodOrdinal>.
+	// They can be referred to by adding the PodOrdinal to the defined name template with named pattern `$(Vars[x].Name)_$(PodOrdinal)`.
 	// For example, a ServiceVarRef might be defined as follows:
 	// - name: MY_SERVICE_PORT
 	//   valueFrom:

apis/dataprotection/v1alpha1/doc.go

@@ -17,7 +17,7 @@ You should have received a copy of the GNU Affero General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-//go:generate go run ../../../hack/docgen/api/main.go -api-dir . -config ../../../hack/docgen/api/gen-api-doc-config.json -template-dir ../../../hack/docgen/api/template -out-file ../../../docs/user_docs/api-reference/backup.md
+//go:generate go run ../../../hack/docgen/api/main.go -api-dir . -config ../../../hack/docgen/api/gen-api-doc-config.json -template-dir ../../../hack/docgen/api/template -out-file ../../../docs/developer_docs/api-reference/backup.md
 
 // +k8s:deepcopy-gen=package,register
 // +k8s:openapi-gen=true

apis/dataprotection/v1alpha1/restore_types.go

@@ -227,7 +227,7 @@ type RestoreVolumeClaimsTemplate struct {
 	Templates []RestoreVolumeClaim `json:"templates"`
 
 	// the replicas of persistent volume claim which need to be created and restored.
-	// the format of created claim name is "<template-name>-<index>".
+	// the format of created claim name is `$(template-name)-$(index)`.
 	// +kubebuilder:validation:Minimum=1
 	// +kubebuilder:validation:Required
 	Replicas int32 `json:"replicas"`
@@ -337,7 +337,7 @@ type RestoreStatusAction struct {
 	// +kubebuilder:validation:Required
 	ObjectKey string `json:"objectKey"`
 
-	// message is a human readable message indicating details about the object condition.
+	// message is a human-readable message indicating details about the object condition.
 	// +optional
 	Message string `json:"message,omitempty"`
 

apis/extensions/v1alpha1/addon_types.go

@@ -32,16 +32,22 @@ import (
 // AddonSpec defines the desired state of an add-on.
 // +kubebuilder:validation:XValidation:rule="has(self.type) && self.type == 'Helm' ?  has(self.helm) : !has(self.helm)",message="spec.helm is required when spec.type is Helm, and forbidden otherwise"
 type AddonSpec struct {
-	// Addon description.
+	// Add-on description.
 	// +optional
 	Description string `json:"description,omitempty"`
 
 	// Add-on type. The valid value is helm.
 	// +unionDiscriminator
 	// +kubebuilder:validation:Required
-	Type     AddonType `json:"type"`
-	Version  string    `json:"version,omitempty"`
-	Provider string    `json:"provider,omitempty"`
+	Type AddonType `json:"type"`
+
+	// Add-on version.
+	// +optional
+	Version string `json:"version,omitempty"`
+
+	// Add-on provider.
+	// +optional
+	Provider string `json:"provider,omitempty"`
 
 	// Helm installation spec. It's processed only when type=helm.
 	// +optional
@@ -307,7 +313,7 @@ type DataObjectKeySelector struct {
 type AddonDefaultInstallSpecItem struct {
 	AddonInstallSpec `json:",inline"`
 
-	// Addon installs parameters selectors by default. If multiple selectors are provided,
+	// Add-on installs parameters selectors by default. If multiple selectors are provided,
 	// all selectors must evaluate to true.
 	// +optional
 	Selectors []SelectorRequirement `json:"selectors,omitempty"`

apis/extensions/v1alpha1/doc.go

@@ -17,7 +17,7 @@ You should have received a copy of the GNU Affero General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-//go:generate go run ../../../hack/docgen/api/main.go -api-dir . -config ../../../hack/docgen/api/gen-api-doc-config.json -template-dir ../../../hack/docgen/api/template -out-file ../../../docs/user_docs/api-reference/add-on.md
+//go:generate go run ../../../hack/docgen/api/main.go -api-dir . -config ../../../hack/docgen/api/gen-api-doc-config.json -template-dir ../../../hack/docgen/api/template -out-file ../../../docs/developer_docs/api-reference/add-on.md
 
 // +k8s:deepcopy-gen=package,register
 // +k8s:openapi-gen=true

config/crd/bases/apps.kubeblocks.io_clusters.yaml

@@ -1020,10 +1020,10 @@ spec:
                     serviceName:
                       description: 'ServiceName defines the name of the underlying
                         service object. If not specified, the default service name
-                        with different patterns will be used: - <CLUSTER_NAME>: for
-                        cluster-level services - <CLUSTER_NAME>-<COMPONENT_NAME>:
-                        for component-level services Only one default service name
-                        is allowed. Cannot be updated.'
+                        with different patterns will be used: - CLUSTER_NAME: for
+                        cluster-level services - CLUSTER_NAME-COMPONENT_NAME: for
+                        component-level services Only one default service name is
+                        allowed. Cannot be updated.'
                       type: string
                     shardingSelector:
                       description: ShardingSelector extends the ServiceSpec.Selector
@@ -1396,7 +1396,7 @@ spec:
                       description: name defines sharding name, this name is also part
                         of Service DNS name, so this name will comply with IANA Service
                         Naming rule. The name is also used to generate the name of
-                        the underlying components with the naming pattern <ShardingSpec.Name>-<ShardID>.
+                        the underlying components with the naming pattern `$(ShardingSpec.Name)-$(ShardID)`.
                         At the same time, the name of component template defined in
                         ShardingSpec.Template.Name will be ignored.
                       maxLength: 15

config/crd/bases/apps.kubeblocks.io_componentdefinitions.yaml

@@ -11506,9 +11506,9 @@ spec:
                         Component. If sets to true, a set of Service will be automatically
                         generated for each Pod. And Service.RoleSelector will be ignored.
                         They can be referred to by adding the PodOrdinal to the defined
-                        ServiceName with named pattern <Service.ServiceName>-<PodOrdinal>.
+                        ServiceName with named pattern `$(Service.ServiceName)-$(PodOrdinal)`.
                         And the Service.Name will also be generated with named pattern
-                        <Service.Name>-<PodOrdinal>. The PodOrdinal is zero-based,
+                        `$(Service.Name)-$(PodOrdinal)`. The PodOrdinal is zero-based,
                         and the number of generated Services is equal to the number
                         of replicas of the Component. For example, a Service might
                         be defined as follows: - name: my-service serviceName: my-service
@@ -11533,10 +11533,10 @@ spec:
                     serviceName:
                       description: 'ServiceName defines the name of the underlying
                         service object. If not specified, the default service name
-                        with different patterns will be used: - <CLUSTER_NAME>: for
-                        cluster-level services - <CLUSTER_NAME>-<COMPONENT_NAME>:
-                        for component-level services Only one default service name
-                        is allowed. Cannot be updated.'
+                        with different patterns will be used: - CLUSTER_NAME: for
+                        cluster-level services - CLUSTER_NAME-COMPONENT_NAME: for
+                        component-level services Only one default service name is
+                        allowed. Cannot be updated.'
                       type: string
                     spec:
                       description: Spec defines the behavior of a service. https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
@@ -12122,7 +12122,7 @@ spec:
                                 that can be referenced will be automatically generated
                                 for each Pod Ordinal. They can be referred to by adding
                                 the PodOrdinal to the defined name template with named
-                                pattern $<Vars[x].Name>_<PodOrdinal>. For example,
+                                pattern `$(Vars[x].Name)_$(PodOrdinal)`. For example,
                                 a ServiceVarRef might be defined as follows: - name:
                                 MY_SERVICE_PORT valueFrom: serviceVarRef: compDef:
                                 my-component-definition name: my-service optional:

config/crd/bases/apps.kubeblocks.io_opsdefinitions.yaml

@@ -57,16 +57,16 @@ spec:
                   properties:
                     accountName:
                       description: the account name of the component. will inject
-                        the account username and password to KB_ACCOUNT_USERNAME and
-                        KB_ACCOUNT_PASSWORD in env of the job.
+                        the account username and password to `KB_ACCOUNT_USERNAME`
+                        and `KB_ACCOUNT_PASSWORD` in env of the job.
                       type: string
                     name:
                       description: refer to componentDefinition name.
                       maxLength: 32
                       type: string
                     serviceName:
                       description: reference the services[*].name. will map the service
-                        name and ports to KB_COMP_SVC_NAME and KB_COMP_SVC_PORT_<portName>
+                        name and ports to `KB_COMP_SVC_NAME` and `KB_COMP_SVC_PORT_$(portName)`
                         in env of the job. portName will replace the characters '-'
                         to '_' and convert to uppercase.
                       type: string

config/crd/bases/dataprotection.kubeblocks.io_restores.yaml

@@ -1724,7 +1724,7 @@ spec:
                       replicas:
                         description: the replicas of persistent volume claim which
                           need to be created and restored. the format of created claim
-                          name is "<template-name>-<index>".
+                          name is `$(template-name)-$(index)`.
                         format: int32
                         minimum: 1
                         type: integer
@@ -2360,7 +2360,7 @@ spec:
                           format: date-time
                           type: string
                         message:
-                          description: message is a human readable message indicating
+                          description: message is a human-readable message indicating
                             details about the object condition.
                           type: string
                         name:
@@ -2401,7 +2401,7 @@ spec:
                           format: date-time
                           type: string
                         message:
-                          description: message is a human readable message indicating
+                          description: message is a human-readable message indicating
                             details about the object condition.
                           type: string
                         name:

config/crd/bases/extensions.kubeblocks.io_addons.yaml

@@ -22,6 +22,14 @@ spec:
       jsonPath: .spec.type
       name: TYPE
       type: string
+    - description: addon version
+      jsonPath: .spec.version
+      name: VERSION
+      type: string
+    - description: addon provider
+      jsonPath: .spec.provider
+      name: PROVIDER
+      type: string
     - description: status phase
       jsonPath: .status.phase
       name: STATUS
@@ -164,7 +172,7 @@ spec:
                           type: object
                       type: object
                     selectors:
-                      description: Addon installs parameters selectors by default.
+                      description: Add-on installs parameters selectors by default.
                         If multiple selectors are provided, all selectors must evaluate
                         to true.
                       items:
@@ -216,7 +224,7 @@ spec:
                 minItems: 1
                 type: array
               description:
-                description: Addon description.
+                description: Add-on description.
                 type: string
               helm:
                 description: Helm installation spec. It's processed only when type=helm.
@@ -602,11 +610,17 @@ spec:
                 required:
                 - autoInstall
                 type: object
+              provider:
+                description: Add-on provider.
+                type: string
               type:
                 description: Add-on type. The valid value is helm.
                 enum:
                 - Helm
                 type: string
+              version:
+                description: Add-on version.
+                type: string
             required:
             - defaultInstallValues
             - type