Doc: add velaql doc (#374)
* Doc: add velaql doc Signed-off-by: yangsoon <yangsoonlx@gmail.com> * Update docs/platform-engineers/system-operation/velaql.md Co-authored-by: Wei (段少) <davidduan0916@gmail.com> Co-authored-by: Jianbo Sun <wonderflow.sun@gmail.com> Co-authored-by: Wei (段少) <davidduan0916@gmail.com>
This commit is contained in:
yangsoon
GitHub
parent
f56acdce3d
commit
4662edd872
|
|
@ -0,0 +1,311 @@
|
|||
---
|
||||
title: VelaQL
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
```shell
|
||||
vela addon enable velaux
|
||||
```
|
||||
|
||||
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"
|
||||
```
|
||||
|
||||
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`.
|
||||
|
||||
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:
|
||||
|
||||
#### component-pod-view
|
||||
|
||||
`component-pod-view` indicates the status query of pods which created by a component.
|
||||
|
||||
**Parameter List**
|
||||
|
||||
|
||||
| name | type | describe |
|
||||
| --- | --- | --- |
|
||||
| appName | string | application name |
|
||||
| appNs | string | application namespace|
|
||||
| name | string | component name |
|
||||
| cluster | string | the cluster the pod is deployed to |
|
||||
| clusterNs | string | the namespace the pod is deployed to |
|
||||
|
||||
Let's show how to use `component-pod-view` to query resources.
|
||||
|
||||
```shell
|
||||
curl --location -g --request GET \
|
||||
http://127.0.0.1:8000/api/v1/query?velaql=component-pod-view{appNs=default,appName=demo,name=demo}
|
||||
```
|
||||
|
||||
|
||||
|
||||
podList includes a list of pods created by the application.
|
||||
|
||||
#### pod-view
|
||||
|
||||
`pod-view` queries the detailed status of a pod, including container status and pod-related events.
|
||||
|
||||
| name | type | describe |
|
||||
| --- | --- | --- |
|
||||
| name | string | pod name |
|
||||
| namespace | string | pod namespace |
|
||||
| cluster | string | the cluster the pod is deployed to |
|
||||
|
||||
Let's show how to use `pod-view` to query resources.
|
||||
|
||||
```shell
|
||||
curl --location -g --request GET \
|
||||
http://127.0.0.1:8000/api/v1/query?velaql=pod-view{name=demo-1-bf6799bb5-dpmk6,namespace=default}
|
||||
```
|
||||
|
||||
|
||||
|
||||
The query result contains the status information of the container and various events associated with the pod when it is created.
|
||||
|
||||
#### resource-view
|
||||
|
||||
`resource-view` get a list of certain types of resources in the cluster。
|
||||
|
||||
| name | type | describe |
|
||||
| --- | --- | --- |
|
||||
| type | string | Resource type, optional types are "ns", "secret", "configMap", "pvc", "storageClass" |
|
||||
| namespace | string | namespace |
|
||||
| cluster | string | cluster |
|
||||
|
||||
Let's show how to use `resource-view` to query resources.
|
||||
|
||||
```shell
|
||||
curl --location -g --request GET \
|
||||
'http://127.0.0.1:8000/api/v1/query?velaql=resource-view{type=ns}'
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Advanced view
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
```
|
||||
import (
|
||||
"vela/ql"
|
||||
)
|
||||
|
||||
// The parameter here corresponds to the parameter in velaQL
|
||||
parameter: {
|
||||
appName: string
|
||||
appNs: string
|
||||
name?: string
|
||||
cluster?: string
|
||||
clusterNs?: string
|
||||
}
|
||||
|
||||
// query statement implemented with cue
|
||||
...
|
||||
|
||||
// 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: {...}
|
||||
```
|
||||
|
||||
We provide the `vela/ql` package to help you query resources. The following explains the cue operators that can be used:
|
||||
|
||||
### ListResourcesInApp
|
||||
|
||||
List all resources created by Application
|
||||
|
||||
#### Action Parameter
|
||||
|
||||
- app: fill in the basic information of the application that needs to be queried, including the application name and application namespace，The `filter` field is used to filter the resources created by the application. The options include the cluster where the resource is located, the cluster namespace, and the component to which it belongs
|
||||
- list: after the operation is successful, this field will be filled. `list` is a list of all resources, the k8s description of the resource is stored in the object field.
|
||||
- err: if an error occurs in the operation, the error message will be displayed as a string.
|
||||
|
||||
```
|
||||
#ListResourcesInApp: {
|
||||
app: {
|
||||
name: string
|
||||
namespace: string
|
||||
filter?: {
|
||||
cluster?: string
|
||||
clusterNamespace?: string
|
||||
components?: [...string]
|
||||
}
|
||||
}
|
||||
list?: [...{
|
||||
cluster: string
|
||||
component: string
|
||||
revision: string
|
||||
object: {...}
|
||||
}]
|
||||
err?: string
|
||||
}
|
||||
```
|
||||
|
||||
#### Usage
|
||||
|
||||
```
|
||||
import (
|
||||
"vela/ql"
|
||||
)
|
||||
|
||||
// The parameter here corresponds to the parameter in velaQL
|
||||
parameter: {
|
||||
appName: string
|
||||
appNs: string
|
||||
name?: string
|
||||
cluster?: string
|
||||
clusterNs?: string
|
||||
}
|
||||
|
||||
resources: ql.#ListResourcesInApp & {
|
||||
app: {
|
||||
name: parameter.appName
|
||||
namespace: parameter.appNs
|
||||
filter: {
|
||||
if parameter.cluster != _|_ {
|
||||
cluster: parameter.cluster
|
||||
}
|
||||
if parameter.clusterNs != _|_ {
|
||||
clusterNamespace: parameter.clusterNs
|
||||
}
|
||||
if parameter.name != _|_ {
|
||||
components: [parameter.name]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// velaQL returns the value of the status field by default
|
||||
status: resourcesList: resources.list
|
||||
```
|
||||
|
||||
### CollectPods
|
||||
|
||||
List all pods created by the workload
|
||||
|
||||
#### Action Parameter
|
||||
|
||||
- value: definition of the workload resource you want to query
|
||||
- cluster: cluster
|
||||
- list: after the operation is successful, this field will be filled. `list` is a list of all pod resources
|
||||
- err: if an error occurs in the operation, the error message will be displayed as a string.
|
||||
|
||||
```
|
||||
#CollectPods: {
|
||||
value: {...}
|
||||
cluster: string
|
||||
list?:[... v1.Pod]
|
||||
err?: string
|
||||
}
|
||||
```
|
||||
|
||||
#### Usage
|
||||
```
|
||||
import (
|
||||
"vela/ql"
|
||||
)
|
||||
|
||||
parameter: {
|
||||
name: string
|
||||
}
|
||||
|
||||
resources: ql.#CollectPods & {
|
||||
value: {
|
||||
kind: "Deployment"
|
||||
apiVersion: "apps/v1"
|
||||
metadata: name: parameter.name
|
||||
}
|
||||
}
|
||||
|
||||
status: pods: resources.list
|
||||
```
|
||||
|
||||
### Read
|
||||
|
||||
Get resource in Kubernetes cluster.
|
||||
|
||||
#### Action Parameter
|
||||
|
||||
- value: the resource metadata to be get. And after successful execution, value will be updated with resource definition in cluster.
|
||||
- err: if an error occurs, the err will contain the error message.
|
||||
|
||||
```
|
||||
#Read: {
|
||||
value: {}
|
||||
err?: string
|
||||
}
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
```
|
||||
// You can use configmap.value.data after this action.
|
||||
configmap: ql.#Read & {
|
||||
value: {
|
||||
kind: "ConfigMap"
|
||||
apiVersion: "v1"
|
||||
metadata: {
|
||||
name: "configmap-name"
|
||||
namespace: "configmap-ns"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### List
|
||||
|
||||
List resources in the k8s cluster.
|
||||
|
||||
#### Action Parameter
|
||||
|
||||
- resource: the resource metadata to be get
|
||||
- filter: namespace is used to select a namespace, and the matchingLabels field is used to filter labels
|
||||
- err: if an error occurs, the err will contain the error message.
|
||||
|
||||
```
|
||||
#List: {
|
||||
cluster: *"" | string
|
||||
resource: {
|
||||
apiVersion: string
|
||||
kind: string
|
||||
}
|
||||
filter?: {
|
||||
namespace?: *"" | string
|
||||
matchingLabels?: {...}
|
||||
}
|
||||
list?: {...}
|
||||
err?: string
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -0,0 +1,307 @@
|
|||
---
|
||||
title: VelaQL
|
||||
---
|
||||
|
||||
## 简介
|
||||
velaQL(全称vela Query Language)，是面向 KubeVela 的资源查询语言，用于查询应用级别的资源状态。
|
||||
|
||||
|
||||
KubeVela 的 Application 对象对底层资源进行封装，虽然给用户带来了屏蔽了底层基础架构的便捷，但是也给平台开发者带来了诸多不便: 对Application创建资源状态的监控，只能依赖Application的状态透出，但状态信息简略、状态实时反馈性差，
|
||||
Application 的抽象功能对用户屏蔽了实际创建出的资源，当 Application 的状态和实际部署资源状态出现偏差时，用户也很难排查出问题。
|
||||
|
||||
|
||||
velaQL的目的是帮用户和平台开发者揭开 Application 的神秘面纱，用户可以通过 velaQL 查询应用部署状态，或者利用 velaQL 提供的可扩展接口自定义查询资源信息，提升Application的可观测性，能够在应用出现问题时及时做出响应。
|
||||
|
||||
## 使用
|
||||
|
||||
### 安装
|
||||
|
||||
目前想要使用 velaQL 的查询能力，需要安装 velaux，借助 apiserver 的能力进行状态查询，未来我们会提供更多的交互方式。现在只需一个简单的指令就能安装 velaux。
|
||||
|
||||
```shell
|
||||
vela addon enable velaux
|
||||
```
|
||||
|
||||
确保 velaux 安装成功之后，可以通过访问 apiserver 暴露出的服务接口进行状态查询。假设我们在 `http://127.0.0.1:8000` 启动了 apiserver 服务。通过下面的方式使用 velaQL
|
||||
|
||||
```shell
|
||||
http://127.0.0.1:8000/api/v1/query?velaql=此处填写查询语句
|
||||
```
|
||||
|
||||
下面我们讲解如何编写 velaQL，从命名上可以看出 velaQL 对标的是 PromQL ，我们期望能够成为应用监控领域的 Prometheus。
|
||||
在查询语法上，我们也和 PromQL 对齐，提供了和 PromQL 类似的查询语句，方便用户简单快捷的查询应用状态。velaQL的基本语法如下：
|
||||
|
||||
```
|
||||
view{parameter1=value1,parameter2=value2}
|
||||
```
|
||||
|
||||
其中 `view` 代表查询视图，可以类比于数据库中视图的概念，velaQL 中的 `view` 是一个对 `k8s`这个“数据库”进行资源状态查询的集合。
|
||||
大括号内是一组kv键值对的集合，使用逗号隔开，代表了进行查询时的过滤条件。目前 value 类型只支持：字符串、整数类型、浮点数、布尔类型。
|
||||
|
||||
### 查询视图
|
||||
|
||||
velaux 内置了3种通用的查询视图，方便用户查询，下面我们分别介绍这几种视图的使用方法：
|
||||
|
||||
#### component-pod-view
|
||||
|
||||
`component-pod-view` 表示对应用下某个组件创建出的 pod 的状态查询。
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
| --- | --- | --- |
|
||||
| appName | string | 应用名称 |
|
||||
| appNs | string | 应用所在的命名空间 |
|
||||
| name | string | 组件名称 |
|
||||
| cluster | string | 组件创建出的资源所在的集群 |
|
||||
| clusterNs | string | 组件创建出的资源所在的命名空间 |
|
||||
|
||||
我们演示一下使用 `component-pod-view` 查询资源后的结果。
|
||||
|
||||
```shell
|
||||
curl --location -g --request GET \
|
||||
http://127.0.0.1:8000/api/v1/query?velaql=component-pod-view{appNs=default,appName=demo,name=demo}
|
||||
```
|
||||
|
||||
|
||||
|
||||
查询结果返回的 podList 是应用创建出的 pod 列表。
|
||||
|
||||
#### pod-view
|
||||
|
||||
`pod-view` 对一个 pod 详细状态的查询，包括容器状态以及 pod 相应的事件。
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
| --- | --- | --- |
|
||||
| name | string | pod名称 |
|
||||
| namespace | string | pod所在的命名空间 |
|
||||
| cluster | string | pod所在的集群 |
|
||||
|
||||
我们演示使用 `pod-view` 查询资源后的结果。
|
||||
|
||||
```shell
|
||||
curl --location -g --request GET \
|
||||
http://127.0.0.1:8000/api/v1/query?velaql=pod-view{name=demo-1-bf6799bb5-dpmk6,namespace=default}
|
||||
```
|
||||
|
||||
|
||||
|
||||
查询结果中包含了pod中容器的状态信息，以及pod在创建和执行时产生的各种事件。
|
||||
|
||||
#### resource-view
|
||||
|
||||
`resource-view` 获取集群中某类资源的列表。
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
| --- | --- | --- |
|
||||
| type | string | 资源类型，可选类型有 "ns"、"secret"、"configMap"、"pvc"、"storageClass" |
|
||||
| namespace | string | 资源所在的命名空间 |
|
||||
| cluster | string | 资源所在的集群 |
|
||||
|
||||
我们演示一下使用`resource-view`查询资源后的结果。
|
||||
|
||||
```shell
|
||||
curl --location -g --request GET \
|
||||
'http://127.0.0.1:8000/api/v1/query?velaql=resource-view{type=ns}'
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 视图进阶
|
||||
|
||||
在很多场景下，内置的视图不能满足我们的需求，Application 下封装的资源也都不仅仅是 k8s 的原生资源。针对很多自定义的资源，用户会有不同的查询需求，这时候你需要自己编写特定的视图来完成查询。本节就来告诉大家如何编写一个自定义的视图。
|
||||
|
||||
目前velaQL中的视图依赖 k8s 中的 configMap 作为存储介质，你可以参考：[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)。configMap data 字段中的 template 存储着视图的核心逻辑，template 是一段 cue 语言描述的查询语句。
|
||||
|
||||
每次使用 velaQL 时，系统都会从 vela-system 命名空间下查找和视图同名的 configMap 提取出 template 来进行查询操作，所以请保证你的自定义视图存储在 vela-system 下。
|
||||
|
||||
一个 template 的整体结构如下：
|
||||
```
|
||||
import (
|
||||
"vela/ql"
|
||||
)
|
||||
|
||||
// parameter 和 velaQL 中的参数一一对应
|
||||
parameter: {
|
||||
appName: string
|
||||
appNs: string
|
||||
name?: string
|
||||
cluster?: string
|
||||
clusterNs?: string
|
||||
}
|
||||
|
||||
...
|
||||
用 cue 来实现的查询语句
|
||||
|
||||
// velaQL 的查询结果会默认返回 status 字段的内容，所以请把需要查询的结果汇总在 status 字段下
|
||||
status: podList: {...}
|
||||
```
|
||||
|
||||
我们提供了 `vela/ql` 包帮助你查询资源。下面介绍可使用的 cue 操作符:
|
||||
|
||||
### ListResourcesInApp
|
||||
|
||||
列出Application创建的所有资源
|
||||
|
||||
#### 操作参数
|
||||
|
||||
- app: 填写需要查询的应用的基本信息，包括应用名称，应用命名空间，app 下的 filter 字段用于筛选应用创建出的资源，可筛选项包括资源所在的集群、集群命名空间以及所在组件
|
||||
- list: 操作成功执行后，会获取到查询结果，list 是一个由所有资源组成的列表，资源的 k8s 描述存储在 object 字段
|
||||
- err: 如果读取操作发生错误，这里会以字符串的方式指示错误信息
|
||||
|
||||
```
|
||||
#ListResourcesInApp: {
|
||||
app: {
|
||||
name: string
|
||||
namespace: string
|
||||
filter?: {
|
||||
cluster?: string
|
||||
clusterNamespace?: string
|
||||
components?: [...string]
|
||||
}
|
||||
}
|
||||
list?: [...{
|
||||
cluster: string
|
||||
component: string
|
||||
revision: string
|
||||
object: {...}
|
||||
}]
|
||||
err?: string
|
||||
}
|
||||
```
|
||||
|
||||
#### 用法示例
|
||||
|
||||
```
|
||||
import (
|
||||
"vela/ql"
|
||||
)
|
||||
|
||||
// parameter 和velaQL中的参数一一对应
|
||||
parameter: {
|
||||
appName: string
|
||||
appNs: string
|
||||
name?: string
|
||||
cluster?: string
|
||||
clusterNs?: string
|
||||
}
|
||||
|
||||
resources: ql.#ListResourcesInApp & {
|
||||
app: {
|
||||
name: parameter.appName
|
||||
namespace: parameter.appNs
|
||||
filter: {
|
||||
if parameter.cluster != _|_ {
|
||||
cluster: parameter.cluster
|
||||
}
|
||||
if parameter.clusterNs != _|_ {
|
||||
clusterNamespace: parameter.clusterNs
|
||||
}
|
||||
if parameter.name != _|_ {
|
||||
components: [parameter.name]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// velaQL 默认返回 status 字段的值
|
||||
status: resourcesList: resources.list
|
||||
```
|
||||
|
||||
### CollectPods
|
||||
|
||||
列出某一工作负载下创建的所有 pods
|
||||
|
||||
#### 操作参数
|
||||
|
||||
- value: 想要查询的工作负载资源的定义
|
||||
- cluster: 工作负载所在的集群
|
||||
- list: 操作成功执行后，会获取到查询结果，list是一个由所有pod资源组成的列表
|
||||
- err: 如果读取操作发生错误，这里会以字符串的方式指示错误信息。
|
||||
|
||||
```
|
||||
#CollectPods: {
|
||||
value: {...}
|
||||
cluster: string
|
||||
list?:[... v1.Pod]
|
||||
err?: string
|
||||
}
|
||||
```
|
||||
|
||||
#### 用法示例
|
||||
```
|
||||
import (
|
||||
"vela/ql"
|
||||
)
|
||||
|
||||
parameter: {
|
||||
name: string
|
||||
}
|
||||
|
||||
resources: ql.#CollectPods & {
|
||||
value: {
|
||||
kind: "Deployment"
|
||||
apiVersion: "apps/v1"
|
||||
metadata: name: parameter.name
|
||||
}
|
||||
}
|
||||
|
||||
status: pods: resources.list
|
||||
```
|
||||
|
||||
### Read
|
||||
|
||||
读取 k8s 集群中的资源。
|
||||
|
||||
#### 操作参数
|
||||
|
||||
- value: 需要用户描述读取资源的元数据，比如 kind、name 等，操作完成后，集群中资源的数据会被填充到 value 上。
|
||||
- err: 如果读取操作发生错误，这里会以字符串的方式指示错误信息。
|
||||
|
||||
```
|
||||
#Read: {
|
||||
value: {}
|
||||
err?: string
|
||||
}
|
||||
```
|
||||
|
||||
### 用法示例
|
||||
|
||||
```
|
||||
// 操作完成后，你可以通过 configmap.value.data 使用 configmap 里面的数据
|
||||
configmap: ql.#Read & {
|
||||
value: {
|
||||
kind: "ConfigMap"
|
||||
apiVersion: "v1"
|
||||
metadata: {
|
||||
name: "configmap-name"
|
||||
namespace: "configmap-ns"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### List
|
||||
|
||||
列出 k8s 集群中的某类资源。
|
||||
|
||||
#### 操作参数
|
||||
|
||||
- resource: 需要用户描述读取资源的元数据，apiVersion、Kind
|
||||
- filter: namespace用于选择命名空间，matchingLabels 字段填写筛选标签
|
||||
- err: 如果读取操作发生错误，这里会以字符串的方式指示错误信息。
|
||||
|
||||
```
|
||||
#List: {
|
||||
cluster: *"" | string
|
||||
resource: {
|
||||
apiVersion: string
|
||||
kind: string
|
||||
}
|
||||
filter?: {
|
||||
namespace?: *"" | string
|
||||
matchingLabels?: {...}
|
||||
}
|
||||
list?: {...}
|
||||
err?: string
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -154,6 +154,7 @@ module.exports = {
|
|||
'platform-engineers/system-operation/managing-clusters',
|
||||
'platform-engineers/system-operation/observability',
|
||||
'platform-engineers/system-operation/performance-finetuning',
|
||||
'platform-engineers/system-operation/velaql',
|
||||
]
|
||||
},
|
||||
{
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 96 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 152 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 142 KiB |
Loading…
Reference in New Issue