Add doc on how to generate JDBC connection string

Added a guide to walk through generating a JDBC connection string from
a database and use it in a business component

Signed-off-by: Zheng Xi Zhou <[email protected]>

Author: zzxwill

docs/end-user/components/cloud-services/prepare-jdbc-connection-string.md

@@ -0,0 +1,164 @@
+---
+title: Prepare JDBC connection string
+---
+
+It's common to use the JDBC connection string to connect to a database. This doc will focus on how to prepare the JDBC connection string
+and how to use it in the application.
+
+## How to generate the JDBC connection string for business component
+
+- Apply WorkflowStep `generate-jdbc-connection`
+
+> WorkflowStep `generate-jdbc-connection` will be automatically applied with KubeVela chart installation. It's not necessary
+> to apply it manually when this feature is released.
+
+```shell
+$ vela def apply generate-jdbc-connection.cue
+```
+
+```
+# generate-jdbc-connection.cue
+import (
+	"vela/op"
+	"encoding/base64"
+)
+
+"generate-jdbc-connection": {
+	type: "workflow-step"
+	annotations: {}
+	labels: {
+		"ui-hidden": "true"
+	}
+	description: "Generate a JDBC connection based on Component of alibaba-rds"
+}
+template: {
+	output: op.#Read & {
+		value: {
+			apiVersion: "v1"
+			kind:       "Secret"
+			metadata: {
+				name: parameter.name
+				if parameter.namespace != _|_ {
+					namespace: parameter.namespace
+				}
+			}
+		}
+	}
+
+	cluster: parameter.cluster
+
+	dbHost: op.#ConvertString & {bt: base64.Decode(null, output.value.data["DB_HOST"])}
+    dbPort: op.#ConvertString & {bt: base64.Decode(null, output.value.data["DB_PORT"])}
+	dbName: op.#ConvertString & {bt: base64.Decode(null, output.value.data["DB_NAME"])}
+	jdbc: [{name: "jdbc", value: "jdbc://" + dbHost.str + ":" + dbPort.str + "/" + dbName.str}]
+
+	parameter: {
+		// +usage=Specify the name of the secret generated by alibaba-rds
+		name: string
+		// +usage=Specify the namespace of the secret generated by alibaba-rds
+		namespace?: string
+		// +usage=Specify the cluster of the object
+		cluster: *"" | string
+	}
+}
+```
+
+The property `namespace` and `name` refers to the namespace and name of the secret generated by a database component.
+
+```
+$ vela show generate-jdbc-connection
+# Properties
++---------------+--------------------------------------------------------------+--------+----------+---------+
+|     NAME      |                         DESCRIPTION                          |  TYPE  | REQUIRED | DEFAULT |
++---------------+--------------------------------------------------------------+--------+----------+---------+
+| name          | Specify the name of the secret generated by alibaba-rds      | string | true     |         |
+| namespace     | Specify the namespace of the secret generated by alibaba-rds | string | false    |         |
+```
+
+[The keys of the secret]((./terraform/alibaba-rds#outputs)) are as below:
+
+| Name                | Description                    |
+|---------------------|--------------------------------|
+| DB_NAME             | RDS Instance Name              |
+| DB_USER             | RDS Instance User              |
+| DB_HOST             | RDS Instance Host              |
+| DB_PASSWORD         | RDS Instance Password          |
+| DB_PORT             | RDS Instance Port              |
+| DATABASE_NAME       | RDS Database Name              |
+
+> If the keys of the secret generated by a database component are not as above, the workflow could not work.
+
+- Apply an application which use the JDBC connection string
+
+```shell
+apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  name: jdbc
+spec:
+  components:
+    - name: db
+      type: alibaba-rds
+      properties:
+        instance_name: favorite-links
+        database_name: db1
+        account_name: oamtest
+        password: U34rfwefwefffaked
+        security_ips: [ "0.0.0.0/0" ]
+        privilege: ReadWrite
+        writeConnectionSecretToRef:
+          name: db-conn
+  - name: express-server
+    type: webservice
+    properties:
+      image: crccheck/hello-world
+      port: 8000
+      
+  workflow:
+    steps:
+    - name: jdbc
+      type: generate-jdbc-connection
+      outputs:
+        - name: jdbc
+          valueFrom: jdbc
+      properties:
+        name: db-conn
+        namespace: default
+    - name: apply
+      type: apply-component
+      inputs:
+        - from: jdbc
+          parameterKey: env
+      properties:
+        component: express-server
+
+```
+
+Apply the application above and check whether the jdbc environment is successfully set to component `express-server`.
+
+```shell
+$ kubectl get deploy express-server -o yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: express-server
+  namespace: default
+  resourceVersion: "67119228"
+  uid: 228493b2-7ee7-4147-91f6-b7b23bc78c3b
+spec:
+  ...
+  template:
+    metadata:
+      creationTimestamp: null
+      labels:
+        app.oam.dev/component: express-server
+        app.oam.dev/revision: express-server-v2
+    spec:
+      containers:
+      - env:
+        - name: jdbc
+          value: jdbc://rm-xxxx.mysql.rds.aliyuncs.com:3306/db1
+        image: crccheck/hello-world
+```
+
+We can see that the environment variable `jdbc` whose value is a JDBC connection string, is successfully set to the component `express-server`.

i18n/zh/docusaurus-plugin-content-docs/current/end-user/components/cloud-services/prepare-jdbc-connection-string.md

@@ -0,0 +1,5 @@
+---
+title: 生成 JDBC 连接字符串
+---
+
+The Chinese version is currently not available.

sidebars.js

@@ -98,6 +98,7 @@ module.exports = {
                 "end-user/components/cloud-services/provision-and-consume-cloud-services",
                 "end-user/components/cloud-services/provision-and-initiate-database",
                 "end-user/components/cloud-services/secure-your-database-connection",
+                "end-user/components/cloud-services/prepare-jdbc-connection-string",
               ],
             },
             "end-user/traits/rollout",