Skip to content

Commit

Permalink
refine zh docs
Browse files Browse the repository at this point in the history 
Signed-off-by: Jianbo Sun <[email protected]>
  • Loading branch information
@wonderflow
wonderflow committed Oct 19, 2022
1 parent 237fc9a commit 757d3b0
Show file tree
Hide file tree
Showing 55 changed files with 653 additions and 225 deletions.
9 changes: 8 additions & 1 deletion docs/case-studies/multi-cluster.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,13 @@ EOF
You can check the deploy result by running `vela status`

```bash
$ vela status basic-topology -n examples
vela status basic-topology -n examples
```

<details>
<summary>expected output</summary>

```
About:
Name: basic-topology
Expand Down Expand Up @@ -103,6 +109,7 @@ Services:
Traits:
✅ expose
```
</details>

### Debugging Multi-cluster Application

Expand Down
15 changes: 13 additions & 2 deletions docs/end-user/components/cloud-services/cloud-resource-scenarios.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,24 @@ description: This section introduces some scenarios of cloud resources managemen

Here're the scenarios KubeVela already supported by Using Terraform.

## Before Starting

- Make sure you have [terraform addon](../../../reference/addons/terraform) enabled.
```
vela addon enable terraform
```

:::tip
When you're using a specific cloud, you should also enable the corresponding cloud provider addon to make the component types exist.
:::

## Provision ECS

- [Provision ECS with EIP for proxy Intranet Service](https://kubevela.io/blog/2022/06/27/terraform-integrate-with-vela#part-2-fixing-the-developer-experience-of-kubernetes-port-forwarding).
- [Provision ECS with EIP for proxy Intranet Service](/blog/2022/06/27/terraform-integrate-with-vela#part-2-fixing-the-developer-experience-of-kubernetes-port-forwarding).

## Provision and use databases

- [Provision and Binding Cloud Resources](../../../tutorials/consume-cloud-services).
- [Provision and Binding Cloud Resources](./provision-and-consume-database).
- [Secure your Database Connection](./secure-your-database-connection).
- [Provision an RDS instance with more than one database](./provision-an-RDS-instance-with-more-than-one-database).
- [Provision a Database and Import a SQL File for initialization](./provision-and-initiate-database).
Expand Down
15 changes: 8 additions & 7 deletions ...ponents/cloud-services/provision-an-RDS-instance-with-more-than-one-database.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@
title: Provision an RDS instance with more than one database
---

:::tip
This section requires your platform engineers have already enabled [terraform addon](../../../reference/addons/terraform).
:::

In the guide [Provision and Binding Cloud Resources](../../../tutorials/consume-cloud-services) and [Provision a Database and Import a SQL File for initialization](./provision-and-initiate-database),
only one database will be created in an RDS instance. This tutorial will show you how to create more than one database in an RDS instance.

Expand All @@ -24,16 +28,13 @@ contains the following attributes: name, character_set, description.
]
```

| Name | Description | Type | Required | Default |
|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|----------|---------|
| database_name | Database name | string | false | |
| databases | The database list, each database is a map, the map contains the following attributes: name, character_set, description, like `[{"name":"test","character_set":"utf8","description":"test database"},]`. It conflicts with `database_name`. | list(map(string)) | false | |
| Name | Description | Type | Required | Default |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | -------- | ------- |
| database_name | Database name | string | false | |
| databases | The database list, each database is a map, the map contains the following attributes: name, character_set, description, like `[{"name":"test","character_set":"utf8","description":"test database"},]`. It conflicts with `database_name`. | list(map(string)) | false | |

Applying the following application can create more than one database in an RDS instance.

:::caution
This section requires your platform engineers have already enabled [cloud resources addon](../../../reference/addons/terraform).
:::

```yaml
apiVersion: core.oam.dev/v1beta1
Expand Down
8 changes: 4 additions & 4 deletions docs/end-user/components/cloud-services/provision-and-consume-database.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@
title: Provision and Binding Database
---

This tutorial will talk about how to provision and consume Alibaba Cloud RDS (and OSS) by Terraform.

:::caution
This section requires your platform engineers have already enabled [cloud resources addon](../../../reference/addons/terraform).
:::tip
This section requires your platform engineers have already enabled [terraform addon](../../../reference/addons/terraform).
:::

This tutorial will talk about how to provision and consume Alibaba Cloud RDS (and OSS) by Terraform.

Let's deploy the [application](https://github.com/kubevela/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.

Expand Down
5 changes: 5 additions & 0 deletions docs/end-user/components/more.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -273,6 +273,11 @@ For enabled addons, if no applications to use definitions, you can click the dis
If you're a system infra or operator, you can refer to extension documents to learn how to [make your own addon and registry](../../platform-engineers/addon/intro), including [extend cloud resources by addon](../../platform-engineers/addon/terraform).
:::tip
Here's a blog introduces [how to build addon from scratch using redis operator as example](/blog/2022/10/18/building-addon-introduction), you can read it as an end to end tutorial!
:::
## Extend KubeVela as a Developer
If you're extremely interested in KubeVela, you can also extend more features as a developer.
Expand Down
44 changes: 28 additions & 16 deletions docs/platform-engineers/addon/intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@
title: Make Your Own Addon
---

:::tip
Here's a blog introduces [how to build addon from scratch using redis operator as example](/blog/2022/10/18/building-addon-introduction), you can read it as an end to end tutorial!
:::

A KubeVela addon is a collection that can contain the following three types of files；
* `Basic information file` that contains `metadata.yaml` and `README.md`.
* `OAM module file` that defines KubeVela extensibility points, including [Definitions](../../getting-started/definition), [UI-Schema](../../reference/ui-schema) or [topology-rules](../../reference/topology-rule).
Expand Down Expand Up @@ -38,7 +42,9 @@ Not all of these directories or files are necessary, let's explain them one by o

### Basic information file

> This type of file is required in an addon.
:::caution
This type of file is required in an addon.
:::

#### metadata.yaml

Expand Down Expand Up @@ -69,18 +75,18 @@ invisible: false
Here's the usage of every field:
| Field | Required | Type | Usage |
|:----:|:---:|:--:|:------:|
| name | yes | string | The name of the addon. |
| version | yes | string | The version of addon, increase for every change and follow [SemVer](https://semver.org/) rule. |
| description | yes | string | Description of the addon. |
| icon | no | string | Icon of the addon, will display in addon dashboard. |
| url | no | string | The official website of the project behind the addon. |
| tags | no | []string | The tags to display and organize the addon. |
| dependencies | no | []{ name: string } | Names of other addons it depends on. KubeVela will make sure these dependencies are enabled before installing this addon. |
| system.vela | no | string | Required version of vela controller, vela CLI will block the installation if vela controller can't match the requirements. |
| system.kubernetes | no | string | Required version of Kubernetes, vela CLI will block the installation if Kubernetes cluster can't match the requirements. |
| deployTo.runtimeCluster | no | bool | By default, the addon will not be installed in the managed clusters. If it's `true`, it will be delivered to all managed clusters automatically. (This field only take effect when application template file is YAML typed) |
| Field | Required | Type | Usage |
| :---------------------: | :------: | :----------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| name | yes | string | The name of the addon. |
| version | yes | string | The version of addon, increase for every change and follow [SemVer](https://semver.org/) rule. |
| description | yes | string | Description of the addon. |
| icon | no | string | Icon of the addon, will display in addon dashboard. |
| url | no | string | The official website of the project behind the addon. |
| tags | no | []string | The tags to display and organize the addon. |
| dependencies | no | []{ name: string } | Names of other addons it depends on. KubeVela will make sure these dependencies are enabled before installing this addon. |
| system.vela | no | string | Required version of vela controller, vela CLI will block the installation if vela controller can't match the requirements. |
| system.kubernetes | no | string | Required version of Kubernetes, vela CLI will block the installation if Kubernetes cluster can't match the requirements. |
| deployTo.runtimeCluster | no | bool | By default, the addon will not be installed in the managed clusters. If it's `true`, it will be delivered to all managed clusters automatically. (This field only take effect when application template file is YAML typed) |

#### README.md (Required)

Expand All @@ -95,21 +101,27 @@ There is no restrict rules for an [experimental addon](https://github.com/kubeve

### OAM module file

> This type of file isn't required in an addon.
:::tip
This type of file is optional in an addon.
:::

#### Definition files (`definitions/` folder)

The `definitions/` folder is used to store `Definition`, which can be a YAML file of ComponentDefinition, TraitDefinitions or WorkflowStepDefinitions Kubernetes CustomResource. It can also be a CUE file that defines KubeVela [Definitions](../../getting-started/definition), which will be rendered into the corresponding Kubernetes objects and applied to the cluster when enabling the addon.

> Please notice: These definitions will only be applied to the control plane.
:::note
These definitions will only be applied to the control plane.
:::

#### UI-Schema (`schemas/` folder)

The `schemas/` folder is used to store the [UI schema](../../reference/ui-schema) files corresponding to `Definition`, which is used to enhance the display effect when displaying the parameters required by `Definition` in UX.

### Application description file

> This type of file isn't required in an addon.
:::tip
This type of file is optional in an addon.
:::

Through the above introduction, we know that the Definition of an addon usually should be supported by a Kubernetes operator. The operator should be defined in a KubeVela application and installed by KubeVela application controller. So the function of application description file is describing this application. Application description file contains two types of file: application template file (template.yaml or template.cue) and resources files which under `resources/` folder.

Expand Down
30 changes: 15 additions & 15 deletions docs/platform-engineers/system-operation/enable-addon-offline.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,33 +51,33 @@ Here's a list about images or helm charts of all community addons that should be

You need sync these images to your own image registry, and modify the related addon files to reference you own registry.

|Images|files|
|:----:|:----:|
| fluxcd/helm-controller:v0.11.1| fluxcd/resources/deployment/helm-controller.yaml|
| fluxcd/image-automation-controller:v0.14.0|fluxcd/resources/deployment/image-automation-controller.yaml |
|fluxcd/image-reflector-controller:v0.11.0|fluxcd/resources/deployment/image-reflector-controller.yaml|
|fluxcd/kustomize-controller:v0.13.1|fluxcd/resources/deployment/kustomize-controller.yaml|
|fluxcd/source-controller:v0.15.3|fluxcd/resources/deployment/source-controller.yaml|
| Images | files |
| :----------------------------------------: | :----------------------------------------------------------: |
| fluxcd/helm-controller:v0.11.1 | fluxcd/resources/deployment/helm-controller.yaml |
| fluxcd/image-automation-controller:v0.14.0 | fluxcd/resources/deployment/image-automation-controller.yaml |
| fluxcd/image-reflector-controller:v0.11.0 | fluxcd/resources/deployment/image-reflector-controller.yaml |
| fluxcd/kustomize-controller:v0.13.1 | fluxcd/resources/deployment/kustomize-controller.yaml |
| fluxcd/source-controller:v0.15.3 | fluxcd/resources/deployment/source-controller.yaml |

### 2. OCM

|Images|files|
| :----:| :----: |
|quay.io/open-cluster-management/registration-operator:latest|ocm-cluster-manager/resources/operator/operator.yaml|
| Images | files |
| :----------------------------------------------------------: | :--------------------------------------------------: |
| quay.io/open-cluster-management/registration-operator:latest | ocm-cluster-manager/resources/operator/operator.yaml |

### 3. VelaUX

There is no need to modify the addon files for enabling this addon, you only need to sync these images and enable this addon with repo args to reference your own registry.

|Images|
| :----:|
|oamdev/vela-apiserver:v1.2.3|
|oamdev/oamdev/velaux::v1.2.3|
| Images |
| :--------------------------: |
| oamdev/vela-apiserver:v1.2.3 |
| oamdev/oamdev/velaux::v1.2.3 |

eg：

```yaml
$ vela addon enable addons/velaux/ repo=<仓库地址>
$ vela addon enable addons/velaux/ repo=<addon-registry-url>
```

### 4. Terraform
Expand Down
2 changes: 1 addition & 1 deletion docs/platform-engineers/system-operation/vela-cli-image.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ The official KubeVela CLI Docker image is hosted on DockerHub in the `oamdev/vel
To run the KubeVela CLI Docker image, use the `docker run` command.

```
$ docker run --rm -it -v ~/.kube:/root/.kube oamdev/vela-cli <command>
docker run --rm -it -v ~/.kube:/root/.kube oamdev/vela-cli <command>
```

This is how the command functions:
Expand Down
4 changes: 2 additions & 2 deletions docs/platform-engineers/system-operation/working-with-ocm.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,13 @@ This section will introduce how to use OCM with KubeVela.
The installation of OCM is directly available through `vela addon`. There are two addons you need to install if you want to use KubeVela with OCM.

```shell
$ vela addon enable ocm-hub-control-plane
vela addon enable ocm-hub-control-plane
```

This addon allows you to use the basic capabilities provided by OCM. For example, you can create OCM ManifestWorks to dispatch resources directly. But KubeVela will not use OCM for its application management for now.

```shell
$ vela addon enable ocm-gateway-manager-addon
vela addon enable ocm-gateway-manager-addon
```

Enabling the second addon will allow you to let KubeVela use the underlying OCM managed clusters through cluster gateway.
Expand Down
5 changes: 4 additions & 1 deletion docs/tutorials/helm.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,10 @@ Starting from here, you will learn to use the KubeVela Addons to install plug-in

- Choose a Helm Chart you want to deploy. In the tutorial, we take [bitnami/redis](https://github.com/bitnami/charts/tree/master/bitnami/redis) as an example.
- Ensure that the cluster you deliver has a usable default StorageClass. Most of our delivery middleware requires data persistence, and the default StorageClass is needed to allocate PV.
- Enable the VelaUX addon for UI console. If you are only CLI users, you can skip to [Deploy via CLI](#deploy-via-cli)
- Make sure you have VelaUX addon enabled for UI console. If you are only CLI users, you can skip to [Deploy via CLI](#deploy-via-cli)
```
vela addon enable velaux
```

## Enable fluxcd addon

Expand Down
5 changes: 4 additions & 1 deletion docs/tutorials/webservice.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,10 @@ In this section, we will introduce how to deploy a container-based application w
## Before starting

- Containerize your business, you need a container image within your image registry that can be accessed by KubeVela.
- Enable the [VelaUX addon](../reference/addons/velaux) by running command `vela addon enable velaux`.
- Make sure you have [VelaUX addon](../reference/addons/velaux) enabled.
```
vela addon enable velaux
```

## Creating an application

Expand Down
2 changes: 1 addition & 1 deletion hack/linkcheck.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ func main() {
if idx < 1 {
continue
}
if strings.HasPrefix(s, "http://") || strings.HasPrefix(s, "https://") || strings.HasPrefix(s, "#") {
if strings.HasPrefix(s, "http://") || strings.HasPrefix(s, "https://") || strings.HasPrefix(s, "#") || strings.HasPrefix(s, "/blog") || strings.HasPrefix(s, "/zh/blog") {
continue
}
d := strings.Index(s, ")")
Expand Down
Loading

0 comments on commit 757d3b0

Please sign in to comment.