Fix: add and refactor more docs (#602)

Signed-off-by: Jianbo Sun <jianbo.sjb@alibaba-inc.com>
This commit is contained in:
Jianbo Sun 2022-04-14 17:41:43 +08:00 committed by GitHub
parent 77f60d2943
commit 6a76923f7e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
20 changed files with 192 additions and 139 deletions

View File

@ -534,4 +534,4 @@ No more add-hoc scripts or glue code, KubeVela will get the application delivery
## Next Step
* For using KubeVela with your own CI pipelines and other tools, please check [Jenkins CI Integration](./jenkins-cicd) for more real world examples.
* Refer to more examples about using KubeVela with [GitOps](./gitops).

View File

@ -64,5 +64,5 @@ Great! You have finished deploying your first KubeVela application, the simplest
## Next Step
* Learn how to do [Multi-Cluster App Delivery](../case-studies/multi-cluster),Components and traits are just the beginning of your vela sail, there're more powerful features around Policy and Workflow.
* Learn how to do [Multi-Cluster App Delivery](../case-studies/multi-cluster), Components and traits are just the beginning of your vela sail, there're more powerful features around Policy and Workflow.
* Refer to [VelaUX](../quick-start) for UI Console experience.

View File

@ -1,5 +1,5 @@
---
title: ServiceAccount Integration
title: ServiceAccount Integration for RBAC
---
KubeVela applies Components and runs Workflow with the controller service account, which allows you to manage components across namespaces.

View File

@ -44,7 +44,7 @@ This Rollout Trait has target size of 5 and two rollout batches. The first batch
Check the Application status whether the rollout is successful:
```shell
vela status rollout-trait-test
$ vela status rollout-trait-test
About:
Name: rollout-trait-test

View File

@ -179,4 +179,9 @@ vela addon enable ./your-addon-dir/
- Convenient local addon debugging methods and the follow-up plan is to provide a complete addon local debugging function on the CLI side.
- Install the addon in the subcluster. If the addon is not installed in the control plane, but only in subclusters, there are some issues.
- Install the addon in the subcluster. If the addon is not installed in the control plane, but only in subclusters, there are some issues.
## Extend Terraform Addon
* We have build some tool for more convenience to extend cloud resource addons, you can refer to the [extend terraform addon docs](./terraform).

View File

@ -1,5 +1,5 @@
---
title: Extend a Terraform Addon
title: Extend Terraform Addon
---
[Terraform Controller](https://github.com/oam-dev/terraform-controller) is the core controller to provision and manage

View File

@ -1,10 +1,8 @@
# KubeVela Offline Installation Guide
# Air-gapped Installation
KubeVela offline installation includes the installation of KubeVela core and KubeVela Addon.
Air-gapped Installation of KubeVela includes the installation of KubeVela core and addons, they all contain the configuration files and images.
## KubeVela Core offline installation
### KubeVela chart
## KubeVela Core
- Download Helm Chart package of vela-core
@ -57,4 +55,5 @@ charts/vela-core/templates/defwithtemplate/nocalhost.yaml: image: "
Repackage the Helm Chart package from the modified chart. Install it directly or install it from a dedicated Helm Chart
repository after you pushed the package into the repository.
## KubeVela Addon Offline installation
## Addon

View File

@ -1,46 +1,45 @@
---
title: VelaQL
title: VelaQL - Query Resources behind Application
---
## Introduction
velaQL(vela Query Language) is a resource query language for KubeVela, used to query application-level resource status.
KubeVela's Application encapsulates the underlying resources of the infra. Although it brings the convenience of shielding the underlying infrastructure to users, it also brings many inconveniences to platform developers: the monitoring of the resource status of Application creation can only rely on the CR object of Application. Moreover, the status information is simple and the real-time feedback is poor.
VelaQL(Vela Query Language) is a resource query language for KubeVela, used to query status of any extended resources in application-level.
The purpose of velaQL is to help users and platform developers uncover the mystery of Application. Users can query application deployment status through velaQL, or use the extensible interface provided by velaQL to customize query resource information to improve the observability of Application.
KubeVela's Application encapsulates the underlying resources from the infrastructure. It brings the infrastructure agonistic experience to app developers but also makes challenges for platform builders to maintain. For example, the monitoring of the resource status created by KubeVela Application can be hard. Moreover, the status information within Application is not detailed enough for trouble shooting and the real-time feedback is poor.
The purpose of VelaQL is to help users and platform builders to uncover the mysterious of the Application. Users can query application deployment status through VelaQL, or use the extensible interface provided by VelaQL to customize query information to improve the observability of one Application.
## Usage
### Install
At present, if you want to use the query capabilities of velaQL, you need to install velaux and query the resource status with the help of apiserver. In the future, we will provide more interactive methods. Now you can install velaux with a simple command.
At present, if you want to use the query capabilities of VelaQL, you need to install VelaUX and query the resource status with the help of apiserver. In the future, we will provide more interactive methods. Now you can install VelaUX with a simple command.
```shell
vela addon enable velaux
```
Assuming we started the apiserver at `http://127.0.0.1:8000`, you can use velaQL like:
Assuming we started the apiserver at `http://127.0.0.1:8000`, you can use VelaQL like:
```shell
http://127.0.0.1:8000/api/v1/query?velaql="write velaQL here"
http://127.0.0.1:8000/api/v1/query?velaql="write VelaQL here"
```
Below we explain how to write velaQL. The basic syntax of velaQL is as follows:
Below we explain how to write VelaQL. The basic syntax of VelaQL is as follows:
```
view{parameter1=value1,parameter2=value2}
```
`view` represents a query view, which can be compared to the concept of a view in a database.
The `view` in velaQL is a collection of resource queries on the `k8s`.
The `view` in VelaQL is a collection of resource queries on the `k8s`.
Filter conditions are placed in `{}` as the form of key-value pairs, currently the value type only supports: string, int, float, boolean.
### Query view
velaux has built-in 3 general query views. Below we will introduce the usage of these views:
VelaUX has built-in 3 general query views. Below we will introduce the usage of these views:
#### component-pod-view
@ -112,9 +111,9 @@ curl --location -g --request GET \
In many scenarios, the built-in views cannot meet our needs, and the resources encapsulated under Application are not just the native resources of k8s. For many custom resources, users will have different query requirements. At this time, you need to write your own specific views to complete the query. This section will tell you how to write a custom view.
The current view in velaQL relies on configMap in k8s as a storage medium, You can refer to [https://github.com/oam-dev/kubevela/blob/master/test/e2e-apiserver-test/testdata/component-pod-view.yaml](https://github.com/oam-dev/kubevela/blob/master/test/e2e-apiserver-test/testdata/component-pod-view.yaml). The template in the configMap data field stores the core logic of the view, template is a query statement implemented in cue language.
The current view in VelaQL relies on configMap in k8s as a storage medium, You can refer to [https://github.com/oam-dev/kubevela/blob/master/test/e2e-apiserver-test/testdata/component-pod-view.yaml](https://github.com/oam-dev/kubevela/blob/master/test/e2e-apiserver-test/testdata/component-pod-view.yaml). The template in the configMap data field stores the core logic of the view, template is a query statement implemented in cue language.
Every time you use velaQL, the system will look for the configMap with the same name as the view under the vela-system namespace, and extract the template for query operations, so please ensure that your custom view is stored under vela-system.
Every time you use VelaQL, the system will look for the configMap with the same name as the view under the vela-system namespace, and extract the template for query operations, so please ensure that your custom view is stored under vela-system.
The structure of a template is as follows:
```
@ -122,7 +121,7 @@ import (
"vela/ql"
)
// The parameter here corresponds to the parameter in velaQL
// The parameter here corresponds to the parameter in VelaQL
parameter: {
appName: string
appNs: string
@ -134,7 +133,7 @@ parameter: {
// query statement implemented with cue
...
// The query result of velaQL will return the content of the status field by default,
// The query result of VelaQL will return the content of the status field by default,
// so please summarize the results you need to query under the status field
status: podList: {...}
```
@ -179,7 +178,7 @@ import (
"vela/ql"
)
// The parameter here corresponds to the parameter in velaQL
// The parameter here corresponds to the parameter in VelaQL
parameter: {
appName: string
appNs: string
@ -206,7 +205,7 @@ resources: ql.#ListResourcesInApp & {
}
}
// velaQL returns the value of the status field by default
// VelaQL returns the value of the status field by default
status: resourcesList: resources.list
```

View File

@ -99,9 +99,9 @@
"message": "工作流系统",
"description": "The label for category Workflow System in sidebar docs"
},
"sidebar.docs.category.System Operation": {
"message": "系统运维",
"description": "The label for category System Operation in sidebar docs"
"sidebar.docs.category.Operator Manual": {
"message": "运维手册",
"description": "The label for category Operator Manual in sidebar docs"
},
"sidebar.docs.category.Customize Traits": {
"message": "自定义运维特征",
@ -238,5 +238,17 @@
"sidebar.docs.category.Custom Addons": {
"message": "自定义插件",
"description": "自定义插件"
},
"sidebar.docs.category.Multi-Cluster Delivery": {
"message": "多集群交付",
"description": "多集群交付"
},
"sidebar.docs.category.Day-2 Operations": {
"message": "应用运维",
"description": "应用运维"
},
"sidebar.docs.category.Advanced Features": {
"message": "其他高级功能",
"description": "其他高级功能"
}
}

View File

@ -57,18 +57,30 @@ module.exports = {
"end-user/components/cloud-services/provision-an-RDS-instance-with-more-than-one-database",
],
},
{
"Multi-Cluster Delivery": [
"platform-engineers/system-operation/managing-clusters",
],
},
"end-user/traits/ingress",
"end-user/traits/rollout",
"end-user/traits/service-binding",
"end-user/traits/sidecar",
"end-user/traits/more",
"end-user/policies/health",
"end-user/policies/apply-once",
"end-user/policies/gc",
"end-user/workflow/component-dependency-parameter",
"end-user/workflow/webhook-notification",
"end-user/version-control",
"how-to/cli/addon/addon",
{
"Day-2 Operations": [
"end-user/traits/rollout",
"end-user/traits/more",
],
},
{
"Advanced Features": [
"end-user/workflow/component-dependency-parameter",
"end-user/version-control",
"end-user/policies/apply-once",
"end-user/policies/gc",
],
},
],
},
],
@ -167,9 +179,9 @@ module.exports = {
],
},
{
"Custom Addons": [
"Addons": [
"how-to/cli/addon/addon",
"platform-engineers/addon/intro",
"platform-engineers/addon/terraform",
],
},
"platform-engineers/components/custom-component",
@ -196,19 +208,22 @@ module.exports = {
"platform-engineers/workflow/working-mechanism",
],
},
{
"System Operation": [
"platform-engineers/system-operation/bootstrap-parameters",
"platform-engineers/system-operation/managing-clusters",
"platform-engineers/system-operation/observability",
"platform-engineers/system-operation/performance-finetuning",
"platform-engineers/system-operation/velaql",
],
},
"platform-engineers/system-operation/velaql",
"platform-engineers/debug/dry-run",
"platform-engineers/x-def-version",
],
},
{
type: "category",
label: "Operator Manual",
items: [
"platform-engineers/system-operation/bootstrap-parameters",
"end-user/service-account-integration",
"platform-engineers/system-operation/offline-installation",
"platform-engineers/system-operation/observability",
"platform-engineers/system-operation/performance-finetuning",
],
},
{
type: "category",
label: "References",
@ -229,7 +244,6 @@ module.exports = {
"end-user/traits/references",
"end-user/policies/references",
"end-user/workflow/built-in-workflow-defs",
"end-user/service-account-integration",
"reference/ui-schema",
"reference/user-improvement-plan",
{

View File

@ -534,4 +534,4 @@ No more add-hoc scripts or glue code, KubeVela will get the application delivery
## Next Step
* For using KubeVela with your own CI pipelines and other tools, please check [Jenkins CI Integration](./jenkins-cicd) for more real world examples.
* Refer to more examples about using KubeVela with [GitOps](./gitops).

View File

@ -64,5 +64,5 @@ Great! You have finished deploying your first KubeVela application, the simplest
## Next Step
* Learn how to do [Multi-Cluster App Delivery](../case-studies/multi-cluster),Components and traits are just the beginning of your vela sail, there're more powerful features around Policy and Workflow.
* Learn how to do [Multi-Cluster App Delivery](../case-studies/multi-cluster), Components and traits are just the beginning of your vela sail, there're more powerful features around Policy and Workflow.
* Refer to [VelaUX](../quick-start) for UI Console experience.

View File

@ -1,5 +1,5 @@
---
title: ServiceAccount Integration
title: ServiceAccount Integration for RBAC
---
KubeVela applies Components and runs Workflow with the controller service account, which allows you to manage components across namespaces.

View File

@ -44,7 +44,7 @@ This Rollout Trait has target size of 5 and two rollout batches. The first batch
Check the Application status whether the rollout is successful:
```shell
vela status rollout-trait-test
$ vela status rollout-trait-test
About:
Name: rollout-trait-test

View File

@ -4,8 +4,8 @@ title: Project management
Project provides a logical separation of applications、environments and delivery targets, this is helpful when VelaUX is used by multiple teams. Project can provide the following features:
* restrict where applications may be deployed to (target clusters and namespaces).
* restrict what integration configs can be used (trusted Helm repositories, docker registries or cloud providers).
* restrict where applications can be deployed to (target clusters and namespaces).
* restrict which integrated configurations can be used (trusted Helm repositories, docker registries or cloud providers).
* restrict the different permission of each user, and provide a multiple-level permission control (RBAC).
## The Default Project

View File

@ -179,4 +179,9 @@ vela addon enable ./your-addon-dir/
- Convenient local addon debugging methods and the follow-up plan is to provide a complete addon local debugging function on the CLI side.
- Install the addon in the subcluster. If the addon is not installed in the control plane, but only in subclusters, there are some issues.
- Install the addon in the subcluster. If the addon is not installed in the control plane, but only in subclusters, there are some issues.
## Extend Terraform Addon
* We have build some tool for more convenience to extend cloud resource addons, you can refer to the [extend terraform addon docs](./terraform).

View File

@ -1,5 +1,5 @@
---
title: Extend a Terraform Addon
title: Extend Terraform Addon
---
[Terraform Controller](https://github.com/oam-dev/terraform-controller) is the core controller to provision and manage

View File

@ -1,10 +1,8 @@
# KubeVela Offline Installation Guide
# Air-gapped Installation
KubeVela offline installation includes the installation of KubeVela core and KubeVela Addon.
Air-gapped Installation of KubeVela includes the installation of KubeVela core and addons, they all contain the configuration files and images.
## KubeVela Core offline installation
### KubeVela chart
## KubeVela Core
- Download Helm Chart package of vela-core
@ -57,4 +55,5 @@ charts/vela-core/templates/defwithtemplate/nocalhost.yaml: image: "
Repackage the Helm Chart package from the modified chart. Install it directly or install it from a dedicated Helm Chart
repository after you pushed the package into the repository.
## KubeVela Addon Offline installation
## Addon

View File

@ -1,46 +1,45 @@
---
title: VelaQL
title: VelaQL - Query Resources behind Application
---
## Introduction
velaQL(vela Query Language) is a resource query language for KubeVela, used to query application-level resource status.
KubeVela's Application encapsulates the underlying resources of the infra. Although it brings the convenience of shielding the underlying infrastructure to users, it also brings many inconveniences to platform developers: the monitoring of the resource status of Application creation can only rely on the CR object of Application. Moreover, the status information is simple and the real-time feedback is poor.
VelaQL(Vela Query Language) is a resource query language for KubeVela, used to query status of any extended resources in application-level.
The purpose of velaQL is to help users and platform developers uncover the mystery of Application. Users can query application deployment status through velaQL, or use the extensible interface provided by velaQL to customize query resource information to improve the observability of Application.
KubeVela's Application encapsulates the underlying resources from the infrastructure. It brings the infrastructure agonistic experience to app developers but also makes challenges for platform builders to maintain. For example, the monitoring of the resource status created by KubeVela Application can be hard. Moreover, the status information within Application is not detailed enough for trouble shooting and the real-time feedback is poor.
The purpose of VelaQL is to help users and platform builders to uncover the mysterious of the Application. Users can query application deployment status through VelaQL, or use the extensible interface provided by VelaQL to customize query information to improve the observability of one Application.
## Usage
### Install
At present, if you want to use the query capabilities of velaQL, you need to install velaux and query the resource status with the help of apiserver. In the future, we will provide more interactive methods. Now you can install velaux with a simple command.
At present, if you want to use the query capabilities of VelaQL, you need to install VelaUX and query the resource status with the help of apiserver. In the future, we will provide more interactive methods. Now you can install VelaUX with a simple command.
```shell
vela addon enable velaux
```
Assuming we started the apiserver at `http://127.0.0.1:8000`, you can use velaQL like:
Assuming we started the apiserver at `http://127.0.0.1:8000`, you can use VelaQL like:
```shell
http://127.0.0.1:8000/api/v1/query?velaql="write velaQL here"
http://127.0.0.1:8000/api/v1/query?velaql="write VelaQL here"
```
Below we explain how to write velaQL. The basic syntax of velaQL is as follows:
Below we explain how to write VelaQL. The basic syntax of VelaQL is as follows:
```
view{parameter1=value1,parameter2=value2}
```
`view` represents a query view, which can be compared to the concept of a view in a database.
The `view` in velaQL is a collection of resource queries on the `k8s`.
The `view` in VelaQL is a collection of resource queries on the `k8s`.
Filter conditions are placed in `{}` as the form of key-value pairs, currently the value type only supports: string, int, float, boolean.
### Query view
velaux has built-in 3 general query views. Below we will introduce the usage of these views:
VelaUX has built-in 3 general query views. Below we will introduce the usage of these views:
#### component-pod-view
@ -112,9 +111,9 @@ curl --location -g --request GET \
In many scenarios, the built-in views cannot meet our needs, and the resources encapsulated under Application are not just the native resources of k8s. For many custom resources, users will have different query requirements. At this time, you need to write your own specific views to complete the query. This section will tell you how to write a custom view.
The current view in velaQL relies on configMap in k8s as a storage medium, You can refer to [https://github.com/oam-dev/kubevela/blob/master/test/e2e-apiserver-test/testdata/component-pod-view.yaml](https://github.com/oam-dev/kubevela/blob/master/test/e2e-apiserver-test/testdata/component-pod-view.yaml). The template in the configMap data field stores the core logic of the view, template is a query statement implemented in cue language.
The current view in VelaQL relies on configMap in k8s as a storage medium, You can refer to [https://github.com/oam-dev/kubevela/blob/master/test/e2e-apiserver-test/testdata/component-pod-view.yaml](https://github.com/oam-dev/kubevela/blob/master/test/e2e-apiserver-test/testdata/component-pod-view.yaml). The template in the configMap data field stores the core logic of the view, template is a query statement implemented in cue language.
Every time you use velaQL, the system will look for the configMap with the same name as the view under the vela-system namespace, and extract the template for query operations, so please ensure that your custom view is stored under vela-system.
Every time you use VelaQL, the system will look for the configMap with the same name as the view under the vela-system namespace, and extract the template for query operations, so please ensure that your custom view is stored under vela-system.
The structure of a template is as follows:
```
@ -122,7 +121,7 @@ import (
"vela/ql"
)
// The parameter here corresponds to the parameter in velaQL
// The parameter here corresponds to the parameter in VelaQL
parameter: {
appName: string
appNs: string
@ -134,7 +133,7 @@ parameter: {
// query statement implemented with cue
...
// The query result of velaQL will return the content of the status field by default,
// The query result of VelaQL will return the content of the status field by default,
// so please summarize the results you need to query under the status field
status: podList: {...}
```
@ -179,7 +178,7 @@ import (
"vela/ql"
)
// The parameter here corresponds to the parameter in velaQL
// The parameter here corresponds to the parameter in VelaQL
parameter: {
appName: string
appNs: string
@ -206,7 +205,7 @@ resources: ql.#ListResourcesInApp & {
}
}
// velaQL returns the value of the status field by default
// VelaQL returns the value of the status field by default
status: resourcesList: resources.list
```

View File

@ -115,12 +115,19 @@
]
},
{
"type": "doc",
"id": "version-v1.3/end-user/traits/ingress"
"collapsed": true,
"type": "category",
"label": "Multi-Cluster Delivery",
"items": [
{
"type": "doc",
"id": "version-v1.3/platform-engineers/system-operation/managing-clusters"
}
]
},
{
"type": "doc",
"id": "version-v1.3/end-user/traits/rollout"
"id": "version-v1.3/end-user/traits/ingress"
},
{
"type": "doc",
@ -130,37 +137,51 @@
"type": "doc",
"id": "version-v1.3/end-user/traits/sidecar"
},
{
"type": "doc",
"id": "version-v1.3/end-user/traits/more"
},
{
"type": "doc",
"id": "version-v1.3/end-user/policies/health"
},
{
"type": "doc",
"id": "version-v1.3/end-user/policies/apply-once"
},
{
"type": "doc",
"id": "version-v1.3/end-user/policies/gc"
},
{
"type": "doc",
"id": "version-v1.3/end-user/workflow/component-dependency-parameter"
},
{
"type": "doc",
"id": "version-v1.3/end-user/workflow/webhook-notification"
},
{
"type": "doc",
"id": "version-v1.3/end-user/version-control"
"collapsed": true,
"type": "category",
"label": "Day-2 Operations",
"items": [
{
"type": "doc",
"id": "version-v1.3/end-user/traits/rollout"
},
{
"type": "doc",
"id": "version-v1.3/end-user/traits/more"
}
]
},
{
"type": "doc",
"id": "version-v1.3/how-to/cli/addon/addon"
"collapsed": true,
"type": "category",
"label": "Advanced Features",
"items": [
{
"type": "doc",
"id": "version-v1.3/end-user/workflow/component-dependency-parameter"
},
{
"type": "doc",
"id": "version-v1.3/end-user/version-control"
},
{
"type": "doc",
"id": "version-v1.3/end-user/policies/apply-once"
},
{
"type": "doc",
"id": "version-v1.3/end-user/policies/gc"
}
]
}
]
}
@ -398,15 +419,15 @@
{
"collapsed": true,
"type": "category",
"label": "Custom Addons",
"label": "Addons",
"items": [
{
"type": "doc",
"id": "version-v1.3/platform-engineers/addon/intro"
"id": "version-v1.3/how-to/cli/addon/addon"
},
{
"type": "doc",
"id": "version-v1.3/platform-engineers/addon/terraform"
"id": "version-v1.3/platform-engineers/addon/intro"
}
]
},
@ -472,31 +493,8 @@
]
},
{
"collapsed": true,
"type": "category",
"label": "System Operation",
"items": [
{
"type": "doc",
"id": "version-v1.3/platform-engineers/system-operation/bootstrap-parameters"
},
{
"type": "doc",
"id": "version-v1.3/platform-engineers/system-operation/managing-clusters"
},
{
"type": "doc",
"id": "version-v1.3/platform-engineers/system-operation/observability"
},
{
"type": "doc",
"id": "version-v1.3/platform-engineers/system-operation/performance-finetuning"
},
{
"type": "doc",
"id": "version-v1.3/platform-engineers/system-operation/velaql"
}
]
"type": "doc",
"id": "version-v1.3/platform-engineers/system-operation/velaql"
},
{
"type": "doc",
@ -508,6 +506,33 @@
}
]
},
{
"collapsed": true,
"type": "category",
"label": "Operator Manual",
"items": [
{
"type": "doc",
"id": "version-v1.3/platform-engineers/system-operation/bootstrap-parameters"
},
{
"type": "doc",
"id": "version-v1.3/end-user/service-account-integration"
},
{
"type": "doc",
"id": "version-v1.3/platform-engineers/system-operation/offline-installation"
},
{
"type": "doc",
"id": "version-v1.3/platform-engineers/system-operation/observability"
},
{
"type": "doc",
"id": "version-v1.3/platform-engineers/system-operation/performance-finetuning"
}
]
},
{
"collapsed": true,
"type": "category",
@ -560,10 +585,6 @@
"type": "doc",
"id": "version-v1.3/end-user/workflow/built-in-workflow-defs"
},
{
"type": "doc",
"id": "version-v1.3/end-user/service-account-integration"
},
{
"type": "doc",
"id": "version-v1.3/reference/ui-schema"