资源状态查询

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

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

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

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

    1. http://127.0.0.1:8000/api/v1/query?velaql=此处填写查询语句

    下面我们讲解如何编写 VelaQL，从命名上可以看出 VelaQL 对标的是 PromQL ，我们期望能够成为应用监控领域的 Prometheus。 在查询语法上，我们也和 PromQL 对齐，提供了和 PromQL 类似的查询语句，方便用户简单快捷的查询应用状态。VelaQL的基本语法如下：

    1. view{parameter1=value1,parameter2=value2}

    其中 view 代表查询视图，可以类比于数据库中视图的概念，VelaQL 中的 view 是一个对 k8s这个“数据库”进行资源状态查询的集合。 大括号内是一组kv键值对的集合，使用逗号隔开，代表了进行查询时的过滤条件。目前 value 类型只支持：字符串、整数类型、浮点数、布尔类型。

    查询视图

    velaux 内置了3种通用的查询视图，方便用户查询，下面我们分别介绍这几种视图的使用方法：

    component-pod-view

    component-pod-view 表示对应用下某个组件创建出的 pod 的状态查询。

    1. curl --location -g --request GET \
    2. 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 相应的事件。

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

    component-pod-view 查询结果

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

    resource-view

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

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

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

    在很多场景下，内置的视图不能满足我们的需求，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 的整体结构如下：

    1. import (
    2.   "vela/ql"
    3. )
    5. // parameter 和 VelaQL 中的参数一一对应
    6. parameter: {
    7.   appName:    string
    8.   appNs:      string
    9.   name?:      string
    10.   cluster?:   string
    11.   clusterNs?: string
    12. }
    13. ... 
    14. 用 cue 来实现的查询语句
    16. // VelaQL 的查询结果会默认返回 status 字段的内容，所以请把需要查询的结果汇总在 status 字段下 
    17. status: podList: {...}

    我们提供了 vela/ql 包帮助你查询资源。下面介绍可使用的 cue 操作符:

    列出Application创建的所有资源

    操作参数

    • app: 填写需要查询的应用的基本信息，包括应用名称，应用命名空间，app 下的 filter 字段用于筛选应用创建出的资源，可筛选项包括资源所在的集群、集群命名空间以及所在组件
    • list: 操作成功执行后，会获取到查询结果，list 是一个由所有资源组成的列表，资源的 k8s 描述存储在 object 字段
    • err: 如果读取操作发生错误，这里会以字符串的方式指示错误信息
    1. #ListResourcesInApp: {
    2.     app: {
    3.         name:      string
    4.         namespace: string
    5.         filter?: {
    6.             cluster?:          string
    7.             clusterNamespace?: string
    8.             components?: [...string]
    9.         }
    10.     }
    11.     list?: [...{
    12.         cluster:   string
    13.         component: string
    14.         revision:  string
    15.         object: {...}
    16.     }]
    17.   err?: string
    18. }

    用法示例

    CollectPods

    列出某一工作负载下创建的所有 pods

    操作参数

    • value: 想要查询的工作负载资源的定义
    • cluster: 工作负载所在的集群
    • list: 操作成功执行后，会获取到查询结果，list是一个由所有pod资源组成的列表
    • err: 如果读取操作发生错误，这里会以字符串的方式指示错误信息。
    1. #CollectPods: {
    2.     value: {...}
    3.     cluster: string
    4.     list?:[... v1.Pod]
    5.     err?: string
    6. }

    用法示例

    1. import (
    2. )
    4. parameter: {
    5.     name: string
    6. }
    8. resources: ql.#CollectPods & {
    9.   value: {
    10.     kind: "Deployment"
    11.     apiVersion: "apps/v1"
    12.     metadata: name: parameter.name
    13.   }
    14. }
    16. status: pods: resources.list

    读取 k8s 集群中的资源。

    操作参数

    • value: 需要用户描述读取资源的元数据，比如 kind、name 等，操作完成后，集群中资源的数据会被填充到 value 上。
    • err: 如果读取操作发生错误，这里会以字符串的方式指示错误信息。
    1. #Read: {
    2.   value: {}
    3.   err?: string
    4. }

    用法示例

    List

    列出 k8s 集群中的某类资源。

    操作参数

    • resource: 需要用户描述读取资源的元数据，apiVersion、Kind
    • filter: namespace用于选择命名空间，matchingLabels 字段填写筛选标签
    • err: 如果读取操作发生错误，这里会以字符串的方式指示错误信息。
    1. #List: {
    2.     cluster:   *"" | string
    3.     resource: {
    4.         apiVersion: string
    5.         kind:       string
    6.     }
    7.     filter?: {
    8.         namespace?: *"" | string
    9.         matchingLabels?: {...}
    10.     }
    11.     list?: {...}
    12.     err?: string
    13. }