Skip to main content
版本:v1.3

VelaQL

简介

VelaQL(全称Vela Query Language),是面向 KubeVela 的资源查询语言,用于查询应用级别的资源状态。 ​

KubeVela 的 Application 对象对底层资源进行封装,虽然给用户带来了屏蔽了底层基础架构的便捷,但是也给平台开发者带来了诸多不便: 对Application创建资源状态的监控,只能依赖Application的状态透出,但状态信息简略、状态实时反馈性差, Application 的抽象功能对用户屏蔽了实际创建出的资源,当 Application 的状态和实际部署资源状态出现偏差时,用户也很难排查出问题。 ​

VelaQL的目的是帮用户和平台开发者揭开 Application 的神秘面纱,用户可以通过 VelaQL 查询应用部署状态,或者利用 VelaQL 提供的可扩展接口自定义查询资源信息,提升Application的可观测性,能够在应用出现问题时及时做出响应。

使用

安装

目前想要使用 VelaQL 的查询能力,需要安装 velaux,借助 apiserver 的能力进行状态查询,未来我们会提供更多的交互方式。现在只需一个简单的指令就能安装 velaux。

vela addon enable velaux

确保 velaux 安装成功之后,可以通过访问 apiserver 暴露出的服务接口进行状态查询。假设我们在 http://127.0.0.1:8000 启动了 apiserver 服务。通过下面的方式使用 VelaQL

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 的状态查询。

参数名类型描述
appNamestring应用名称
appNsstring应用所在的命名空间
namestring组件名称
clusterstring组件创建出的资源所在的集群
clusterNsstring组件创建出的资源所在的命名空间

我们演示一下使用 component-pod-view 查询资源后的结果。

curl --location -g --request GET \
http://127.0.0.1:8000/api/v1/query?velaql=component-pod-view{appNs=default,appName=demo,name=demo}

component-pod-view 查询结果

查询结果返回的 podList 是应用创建出的 pod 列表。

pod-view

pod-view 对一个 pod 详细状态的查询,包括容器状态以及 pod 相应的事件。

参数名类型描述
namestringpod名称
namespacestringpod所在的命名空间
clusterstringpod所在的集群

我们演示使用 pod-view 查询资源后的结果。

curl --location -g --request GET \
http://127.0.0.1:8000/api/v1/query?velaql=pod-view{name=demo-1-bf6799bb5-dpmk6,namespace=default}

component-pod-view 查询结果

查询结果中包含了pod中容器的状态信息,以及pod在创建和执行时产生的各种事件。

resource-view

resource-view 获取集群中某类资源的列表。

参数名类型描述
typestring资源类型,可选类型有 "ns"、"secret"、"configMap"、"pvc"、"storageClass"
namespacestring资源所在的命名空间
clusterstring资源所在的集群

我们演示一下使用resource-view查询资源后的结果。

curl --location -g --request GET \
'http://127.0.0.1:8000/api/v1/query?velaql=resource-view{type=ns}'

resource-view 查询结果

视图进阶

在很多场景下,内置的视图不能满足我们的需求,Application 下封装的资源也都不仅仅是 k8s 的原生资源。针对很多自定义的资源,用户会有不同的查询需求,这时候你需要自己编写特定的视图来完成查询。本节就来告诉大家如何编写一个自定义的视图。

目前VelaQL中的视图依赖 k8s 中的 configMap 作为存储介质,你可以参考:https://github.com/kubevela/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
}