Explain the usage of trait `service-binding` (#258)

* Explain the usage of trait `service-binding` Explained how to consume cloud resources by `service-binding` and also added outputs for each cloud resource * add outputs in each cloud resource definition doc in Chinese
2021-09-10 09:19:54 +08:00 · 2021-09-10 09:19:54 +08:00 · 1344c6d71f
parent b080e31b50
commit 1344c6d71f
13 changed files with 157 additions and 45 deletions
--- a/docs/end-user/binding-traits.md
+++ b/docs/end-user/binding-traits.md
@ -288,5 +288,5 @@ When the built-in Trait cannot meet your needs, you can freely customize the mai

 ## Next

- [Integrated Cloud Services](./cloud-services), learn how to integrate cloud services from various cloud vendors
+- [Integrated Cloud Services](./components/cloud-services/provider-and-consume-cloud-services), learn how to integrate cloud services from various cloud vendors
 - [Rollout & Scaler](./rollout-scaler)
--- a/docs/end-user/components/cloud-services/provider-and-consume-cloud-services.md
+++ b/docs/end-user/components/cloud-services/provider-and-consume-cloud-services.md
@ -2,6 +2,16 @@
 title: Provision and Consume Cloud Services
 ---

+Cloud-oriented development is now becoming the norm, there is an urgent need to integrate cloud resources from different
+sources and types. Whether it is the most basic object storage, cloud database, or load balancing, it is all faced with
+the challenges of hybrid cloud, multi-cloud and other complex environments. KubeVela is perfect to satisfy the needs.
+
+KubeVela efficiently and securely integrates different types of cloud resources through resource binding capabilities in
+cloud resource Components and Traits. At present, you can directly use the default components of AliCloud Kubernetes(ACK),
+AliCloud Object Storage Service (OSS) and AliCloud Relational Database Service (RDS). At the same time, more new cloud
+resources will gradually become the default option under the support of the community in the future. You can use cloud
+resources of various manufacturers in a standardized and unified way.
+
 This tutorial will talk about how to provision and consume Cloud Resources by Terraform.

 > ⚠️ This section requires your platform engineers have already enabled [add-on 'terraform/provider-alicloud'](../../../platform-engineers/components/component-terraform).
@ -18,7 +28,6 @@ Terraform | Alibaba Cloud | [ACK](./terraform/alibaba-ack) | Terraform configura

 All supported Terraform cloud resources can be seen in the list above. You can also filter them by command by `vela components --label type=terraform`.

-
 Let's deploy
 the [application](https://github.com/oam-dev/kubevela/tree/master/docs/examples/terraform/cloud-resource-provision-and-consume/application.yaml)
 below to provision Alibaba Cloud OSS and RDS cloud resources, and consume them by the web component.
@ -70,7 +79,9 @@ spec:
          name: oss-conn
 ```

-The component `express-server` consume OSS and RDS by trait [Service Binding](../../traits/service-binding).
+The component `sample-db` will generate secret `db-conn` with [these keys](./terraform/alibaba-rds#outputs), and the component
+`sample-oss` will generate secret `oss-conn`. These secrets are binded to the Envs of component `express-server` by trait
+[Service Binding](../../traits/service-binding). Then the component can consume instances of OSS and RDS.

 Deploy and verify the application.

@ -91,4 +102,10 @@ Handling connection for 80
 Handling connection for 80
 ```

-![](../../../resources/crossplane-visit-application.jpg)
+![](../../../resources/crossplane-visit-application-v3.jpg)
+
+## Next
+
+- [Component Observability](../../component-observability)
+- [Data Pass Between Components ](../../component-dependency-parameter)
+- [Multi-Cluster and Environment](../../../case-studies/multi-app-env-cluster)
--- a/docs/end-user/components/cloud-services/terraform/alibaba-ack.md
+++ b/docs/end-user/components/cloud-services/terraform/alibaba-ack.md
@ -64,4 +64,13 @@ writeConnectionSecretToRef | The secret which the cloud resource connection will
 Name | Description | Type | Required | Default
 ------------ | ------------- | ------------- | ------------- | ------------- 
 name | The secret name which the cloud resource connection will be written to | string | false |
-namespace | The secret namespace which the cloud resource connection will be written to | string | false |  
+namespace | The secret namespace which the cloud resource connection will be written to | string | false |
+
+## Outputs
+
+If `writeConnectionSecretToRef` is set, a secret will be generated with these keys as below:
+
+Name | Description
+------------ | -------------
+name | ACK Kubernetes cluster name |
+kubeconfig | The KubeConfig string for the ACK Kubernetes cluster |
--- a/docs/end-user/components/cloud-services/terraform/alibaba-oss.md
+++ b/docs/end-user/components/cloud-services/terraform/alibaba-oss.md
@ -42,3 +42,12 @@ Name | Description | Type | Required | Default
 ------------ | ------------- | ------------- | ------------- | ------------- 
 name | The secret name which the cloud resource connection will be written to | string | true |
 namespace | The secret namespace which the cloud resource connection will be written to | string | false |  
+
+
+## Outputs
+
+If `writeConnectionSecretToRef` is set, a secret will be generated with these keys as below:
+
+Name | Description
+------------ | -------------
+BUCKET_NAME | OSS bucket name |
--- a/docs/end-user/components/cloud-services/terraform/alibaba-rds.md
+++ b/docs/end-user/components/cloud-services/terraform/alibaba-rds.md
@ -43,4 +43,16 @@ writeConnectionSecretToRef | The secret which the cloud resource connection will
 Name | Description | Type | Required | Default
 ------------ | ------------- | ------------- | ------------- | ------------- 
 name | The secret name which the cloud resource connection will be written to | string | true |
-namespace | The secret namespace which the cloud resource connection will be written to | string | false |  
+namespace | The secret namespace which the cloud resource connection will be written to | string | false |
+
+## Outputs
+
+If `writeConnectionSecretToRef` is set, a secret will be generated with these keys as below:
+
+Name | Description
+------------ | -------------
+DB_NAME | RDS instance name |
+DB_USER | RDS instance username |
+DB_PORT | RDS instance port |
+DB_HOST | RDS instance host |
+DB_PASSWORD | RDS instance password |
--- a/docs/end-user/traits/service-binding.md
+++ b/docs/end-user/traits/service-binding.md
@ -6,37 +6,78 @@ Service binding trait will bind data from Kubernetes `Secret` to the application

 ## Specification

-```
-$ vela show service-binding
-# Properties
-+-------------+------------------------------------------------+------------------+----------+---------+
-|    NAME     |                  DESCRIPTION                   |       TYPE       | REQUIRED | DEFAULT |
-+-------------+------------------------------------------------+------------------+----------+---------+
-| envMappings | The mapping of environment variables to secret | map[string]#KeySecret | true     |         |
-+-------------+------------------------------------------------+------------------+----------+---------+
+### Properties
+Name | Description | Type | Required | Default
+------------ | ------------- | ------------- | ------------- | -------------
+envMappings | The mapping of environment variables to secret | map[string]#KeySecret | true |

-## KeySecret
-+--------+---------------------------------------------------+-------------------+----------+---------+
-|  NAME  |                    DESCRIPTION                    |       TYPE        | REQUIRED | DEFAULT |
-+--------+---------------------------------------------------+-------------------+----------+---------+
+#### KeySecret
+Name | Description | Type | Required | Default
+------------ | ------------- | ------------- | ------------- | -------------
 | key  | if key is empty, we will use envMappings key instead              | string            | false     |         |
 | secret | Kubernetes secret name | string | true     |         |
-+--------+---------------------------------------------------+-------------------+----------+---------+


-```
-
 ## How to use

-1. Creat a Kubernetes Secret
+1. Prepare a Kubernetes Secret

-```shell
-$ kubectl create secret generic db-conn-example --from-literal=password=123  --from-literal=endpoint=https://xxx.com --from-literal=username=myname
-secret/db-conn-example created
+The secret can be manually created, or generated by other component or external system.
+
+For example, we have a secret `db-conn-example` whose data is as below:
+
+```yaml
+endpoint: https://xxx.com
+password: 123
+username: myname
 ```

 2. Bind the Secret into your component by `service-binding` trait

+For example, we have a webservice component who needs to consume a database. The database connection string should be set
+to Pod environments: `endpoint`, `username` and `DB_PASSWORD`.
+
+We can set the properties for envMappings as below. For each environment, `secret` represents the secret name, and `key`
+represents the key of the secret.
+
+Here is the complete properties for the trait.
+
+```yaml
+traits:
+- type: service-binding
+  properties:
+    envMappings:
+      DB_PASSWORD:
+        secret: db-conn-example
+        key: password            
+      endpoint:
+        secret: db-conn-example
+        key: endpoint
+      username:
+        secret: db-conn-example
+        key: username
+```
+
+In particular, if the environment name, like `endpoint`, is same to the `key` of the secret, we can omit the `key`.
+So we can simplify the properties as below.
+
+```yaml
+traits:
+- type: service-binding
+  properties:
+    envMappings:
+      DB_PASSWORD:
+        secret: db-conn-example
+        key: password            
+      endpoint:
+        secret: db-conn-example
+      username:
+        secret: db-conn-example
+```
+
+We can finally prepare an Application for the business component `binding-test-comp` to consume the secret, which is a
+representative of a database cloud resource.
+
 ```yaml
 apiVersion: core.oam.dev/v1beta1
 kind: Application
@ -58,8 +99,9 @@ spec:
                secret: db-conn-example
                key: password            
              endpoint:
-                secret: db-conn-example          ß
+                secret: db-conn-example
              username:
                secret: db-conn-example
 ```
-Deploy this YAML and the Secret `db-conn-example` will be binding into environment of workload.
+
+Deploy this YAML and the Secret `db-conn-example` will be binding into environment of workload.
--- a/docs/resources/crossplane-visit-application-v3.jpg
+++ b/docs/resources/crossplane-visit-application-v3.jpg
--- a/i18n/zh/docusaurus-plugin-content-docs/current/end-user/binding-traits.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/end-user/binding-traits.md
@ -306,5 +306,5 @@ kubectl logs -f log-gen-worker-7bb65dcdd6-tpbdh count-log

 ## 下一步

- [集成云资源](./cloud-services)，了解如何集成各类云厂商的云资源
+- [集成云资源](./components/cloud-services/provider-and-consume-cloud-services.md)，了解如何集成各类云厂商的云资源
 - [灰度发布和扩缩容](./rollout-scaler)
--- a/i18n/zh/docusaurus-plugin-content-docs/current/end-user/components/cloud-services/provider-and-consume-cloud-services.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/end-user/components/cloud-services/provider-and-consume-cloud-services.md
@ -2,12 +2,16 @@
 title:  集成云资源
 ---

-在面向云开发逐渐成为范式的这个时代，我们希望集成来源不同、类型不同云资源的需求非常迫切。不管是最基本的对象存储、云数据库，还是更多的负载均衡等等，也面临着混合云、多云等复杂环境所带来的挑战，而 KubeVela 都可以很好满足你的需要。
+在面向云开发逐渐成为范式的这个时代，我们希望集成来源不同、类型不同云资源的需求非常迫切。不管是最基本的对象存储、云数据库，还是更多的负载均衡等等，
+也面临着混合云、多云等复杂环境所带来的挑战，而 KubeVela 都可以很好满足你的需要。

-KubeVela 通过云资源组件（Component）和运维特征（Trait）里的资源绑定功能，高效安全地完成不同类型云资源的集成工作。目前你可以直接调用阿里云容器服务 Kubernetes 版（ACK ）、阿里云对象存储服务（OSS）和阿里云关系型数据库服务（RDS）这些默认组件。同时在未来，更多新的云资源也会在社区的支撑下逐渐成为默认选项，让你标准化统一地去使用各种厂商的云资源。
+KubeVela 通过云资源组件（Component）和运维特征（Trait）里的资源绑定功能，高效安全地完成不同类型云资源的集成工作。目前你可以直接调用阿里云容器
+服务 Kubernetes 版（ACK ）、阿里云对象存储服务（OSS）和阿里云关系型数据库服务（RDS）这些默认组件。同时在未来，更多新的云资源也会在社区的支撑下
+逐渐成为默认选项，让你标准化统一地去使用各种厂商的云资源。

 > ⚠️ 请确认管理员已经安装了 [Terraform 插件 'terraform/provider-alicloud'](../../../platform-engineers/components/component-terraform).

+
 ## 支持的云资源列表
 编排类型 | 云服务商 | 云资源 | 描述
 ------------ | ------------- | ------------- | -------------
@ -15,22 +19,13 @@ Terraform | Alibaba Cloud | [ACK](./terraform/alibaba-ack) | 用于部署阿里
 | |  | [OSS](./terraform/alibaba-oss) | 用于部署阿里云 OSS 的 Terraform Configuration 的 ComponentDefinition
 | |  | [RDS](./terraform/alibaba-rds) | 用于部署阿里云 RDS 的 Terraform Configuration 的 ComponentDefinition

-## 查看 KubeVela 的云资源组件
+## Terraform

-我们通过 [KubeVela CLI](../../../install#3-安装-kubevela-cli)来查看，当前系统中可用的云资源组件类型：
-
-```shell
-$ vela components --label type=terraform
-NAME        NAMESPACE  	WORKLOAD                             	DESCRIPTION                                                            
-alibaba-ack	vela-system	configurations.terraform.core.oam.dev	Terraform configuration for Alibaba Cloud ACK cluster       
-alibaba-oss	vela-system	configurations.terraform.core.oam.dev	Terraform configuration for Alibaba Cloud OSS object        
-alibaba-rds	vela-system	configurations.terraform.core.oam.dev	Terraform configuration for Alibaba Cloud RDS object        
-```
+KubeVela 支持的所有由 Terraform 编排的云资源如上所示，你也可以通过命令 `vela components --label type=terraform` 查看。

 下面我们以阿里云关系型数据库（RDS）的例子，作为示例进行讲解。

-### 部署云资源
-接下来，请直接复制一个编写好的应用部署计划，在命令行中执行：
+首先请直接复制一个编写好的应用部署计划，在命令行中执行：

 ```shell
 cat <<EOF | kubectl apply -f -
@ -72,7 +67,6 @@ webapp               	rds-server    	webservice 	service-binding   	running	heal
 └─                 	sample-db     	alibaba-rds	                  	running	healthy	Cloud resources are deployed and ready to use.	2021-08-30 20:04:03 +0800 CST
 ```

-### 绑定云资源到服务组件
 有了 RDS 的服务器，又有了正常运行的云资源，是时候让它们之间映射起来了：使用运维特征 service-binding。我们对 YAML 文件进行更新后，再次部署：

 ```shell
@ -113,11 +107,11 @@ EOF
 ```
 可以看到，db-conn 负责将密钥的账户、密码等信息转发给 rds-server 这个组件来使用。

-剩下的云资源如何使用，请前往管理员手册里的内置云资源进行查看，并查看各云资源对应的详细配置项信息。
+![](../../../resources/crossplane-visit-application-v3.jpg)

 ## 自定义云资源

-如果我们提供的开箱即用云资源没有覆盖你的研发需求，你依然可以通过灵活的[Terraform 组件](../../../platform-engineers/components/component-terraform)去自定义业务所需要的云资源。
+如果我们提供的开箱即用云资源没有覆盖你的研发需求，你依然可以通过灵活的[Terraform 组件](../../../platform-engineers/components/component-terraform.md)去自定义业务所需要的云资源。

 ## 下一步

--- a/i18n/zh/docusaurus-plugin-content-docs/current/end-user/components/cloud-services/terraform/alibaba-ack.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/end-user/components/cloud-services/terraform/alibaba-ack.md
@ -64,3 +64,12 @@ writeConnectionSecretToRef | 云资源连接信息即将写入的 secret 的信
 ------------ | ------------- | ------------- | ------------- | ------------- 
 name | 云资源连接信息即将写入的 secret 的名字 | string | 是 |
 namespace | 云资源连接信息即将写入的 secret 的 namespace | string | 否 |
+
+## 输出
+
+如果设置了 `writeConnectionSecretToRef`，一个 Kubernetes Secret 将会被创建，并且，它的数据里有这些键（key）。
+
+名字 | 描述
+------------ | -------------
+name | ACK Kubernetes 集群名字 |
+kubeconfig | ACK Kubernetes 集群 KubeConfig 的字符串 |
--- a/i18n/zh/docusaurus-plugin-content-docs/current/end-user/components/cloud-services/terraform/alibaba-oss.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/end-user/components/cloud-services/terraform/alibaba-oss.md
@ -42,3 +42,11 @@ writeConnectionSecretToRef | 云资源连接信息即将写入的 secret 的信
 ------------ | ------------- | ------------- | ------------- | ------------- 
 name | 云资源连接信息即将写入的 secret 的名字 | string | 是 |
 namespace | 云资源连接信息即将写入的 secret 的 namespace | string | 否 |
+
+## 输出
+
+如果设置了 `writeConnectionSecretToRef`，一个 Kubernetes Secret 将会被创建，并且，它的数据里有这些键（key）。
+
+名字 | 描述
+------------ | -------------
+BUCKET_NAME | OSS bucket 名字 |
--- a/i18n/zh/docusaurus-plugin-content-docs/current/end-user/components/cloud-services/terraform/alibaba-rds.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/end-user/components/cloud-services/terraform/alibaba-rds.md
@ -44,3 +44,15 @@ writeConnectionSecretToRef | 云资源连接信息即将写入的 secret 的信
 ------------ | ------------- | ------------- | ------------- | ------------- 
 name | 云资源连接信息即将写入的 secret 的名字 | string | 是 |
 namespace | 云资源连接信息即将写入的 secret 的 namespace | string | 否 |
+
+## 输出
+
+如果设置了 `writeConnectionSecretToRef`，一个 Kubernetes Secret 将会被创建，并且，它的数据里有这些键（key）。
+
+名字 | 描述
+------------ | -------------
+DB_NAME | RDS 实例名 |
+DB_USER | RDS 实例的用户名 |
+DB_PORT | RDS 实例的端口 |
+DB_HOST | RDS 实例的主机名 |
+DB_PASSWORD | RDS 实例的密码 |
--- a/i18n/zh/docusaurus-plugin-content-docs/current/resources/crossplane-visit-application-v3.jpg
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/resources/crossplane-visit-application-v3.jpg