Version: v1.2

基础入门

CUE 是 KubeVela 的核心依赖，也是用户实现自定义扩展的主要方式。本章节将详细介绍 CUE 的基础知识，帮助你更好地使用 KubeVela。

概述

KubeVela 将 CUE 作为应用交付核心依赖和扩展方式的原因如下：：

  • CUE 本身就是为大规模配置而设计。 CUE 能够感知非常复杂的配置文件，并且能够安全地更改可修改配置中成千上万个对象的值。这非常符合 KubeVela 的目标，即以可编程的方式，去定义和交付生产级别的应用程序。
  • CUE 支持一流的代码生成和自动化。 CUE 原生支持与现有工具以及工作流进行集成，反观其他工具则需要自定义复杂的方案才能实现。例如，需要手动使用 Go 代码生成 OpenAPI 模式。KubeVela 也是依赖 CUE 该特性进行构建开发工具和 GUI 界面的。
  • CUE 与 Go 完美集成。 KubeVela 像 Kubernetes 系统中的大多数项目一样使用 GO 进行开发。CUE 已经在 Go 中实现并提供了丰富的 API。KubeVela 以 CUE 为核心实现 Kubernetes 控制器。借助 CUE，KubeVela 可以轻松处理数据约束问题。

更多细节请查看 The Configuration Complexity Curse 以及 The Logic of CUE。

前提

请确保你的环境中已经安装如下命令行：

  • cue v0.2.2 目前 KubeVela 暂时只支持 CUE v0.2.2 版本，将在后续迭代中升级支持新的 CUE 版本。
  • vela >= v1.1.0

学习 CUE 命令行

CUE 是 JSON 的超集， 我们可以像使用 JSON 一样使用 CUE，并具备以下特性：

  • C 语言风格的注释
  • 字段名称可以用双引号括起来，注意字段名称中不可以带特殊字符
  • 可选字段末尾是否有逗号
  • 允许数组中最后一个元素末尾带逗号
  • 外大括号可选

请先复制以下信息，保存为一个 first.cue 文件：

  1. a: 1.5
  3. a: float
  5. b: 1
  7. b: int
  9. d: [1, 2, 3]
  11. g: {
  13.     h: "abc"
  15. }
  17. e: string

接下来，我们以上面这个文件为例子，来学习 CUE 命令行的相关指令：

  • 如何格式化 CUE 文件。（如果你使用 Goland 或者类似 JetBrains IDE， 可以参考该文章配置自动格式化插件 使用 Goland 设置 cuelang 的自动格式化。）

    该命令不仅可以格式化 CUE 文件，还能提示错误的模型，相当好用的命令。

    1. cue fmt first.cue

  • 如何校验模型。除了 cue fmt，你还可以使用 cue vet 来校验模型。

    ``` $ cue vet first.cue

    some instances are incomplete; use the -c flag to show errors or suppress this message

  1. $ cue vet first.cue -c
  3. e: incomplete value string
  8. ```
  10. 提示我们：这个文件里的 e 这个变量，有数据类型 `string` 但并没有赋值。

  • 如何计算/渲染结果。 cue eval 可以计算 CUE 文件并且渲染出最终结果。 我们看到最终结果中并不包含 a: float 和 b: int，这是因为这两个变量已经被计算填充。 其中 e: string 没有被明确的赋值, 故保持不变.

    1. $ cue eval first.cue
    3. a: 1.5
    5. b: 1
    7. d: [1, 2, 3]
    9. g: {
    11. h: "abc"
    13. }
    15. e: string

  • 如何指定渲染的结果。例如，我们仅想知道文件中 b 的渲染结果，则可以使用该参数 -e。

    1. $ cue eval -e b first.cue
    3. 1

  • 如何导出渲染结果。 cue export 可以导出最终渲染结果。如果一些变量没有被定义执行该命令将会报错。

    1. $ cue export first.cue
    3. e: incomplete value string

    我们更新一下 first.cue 文件，给 e 赋值：

    1. a: 1.5
    3. a: float
    5. b: 1
    7. b: int
    9. d: [1, 2, 3]
    11. g: {
    13.   h: "abc"
    15. }
    17. e: string
    19. e: "abc"

    然后，该命令就可以正常工作。默认情况下, 渲染结果会被格式化为 JSON 格式。

    1. $ cue export first.cue
    3. {
    5.     "a": 1.5,
    7.     "b": 1,
    9.     "d": [
    11.         1,
    13.         2,
    15.         3
    17.     ],
    19.     "g": {
    21.         "h": "abc"
    23.     },
    25.     "e": "abc"
    27. }

  • 如何导出 YAML 格式的渲染结果。

    1. $ cue export first.cue --out yaml
    3. a: 1.5
    5. b: 1
    7. d:
    9. - 1
    11. - 2
    13. - 3
    15. g:
    17.   h: abc
    19. e: abc

  • 如何导出指定变量的结果。

    1. $ cue export -e g first.cue
    3. {
    5.     "h": "abc"
    7. }

以上, 你已经学习完所有常用的 CUE 命令行指令。

学习 CUE 语言

在熟悉完常用 CUE 命令行指令后，我们来进一步学习 CUE 语言。

先了解 CUE 的数据类型。以下是它的基础数据类型：

  1. // float
  3. a: 1.5
  8. // int
  10. b: 1
  15. // string
  17. c: "blahblahblah"
  22. // array
  24. d: [1, 2, 3, 1, 2, 3, 1, 2, 3]
  29. // bool
  31. e: true
  36. // struct
  38. f: {
  40.     a: 1.5
  42.     b: 1
  44.     d: [1, 2, 3, 1, 2, 3, 1, 2, 3]
  46.     g: {
  48.         h: "abc"
  50.     }
  52. }
  57. // null
  59. j: null

如何自定义 CUE 类型？使用 # 符号来指定一些表示 CUE 类型的变量。

  1. #abc: string

我们将上述内容保存到 second.cue 文件。 执行 cue export 不会报 #abc 是一个类型不完整的值。

  1. $ cue export second.cue
  3. {}

你还可以定义更复杂的自定义结构，比如：

  1. #abc: {
  3.   x: int
  5.   y: string
  7.   z: {
  9.     a: float
  11.     b: bool
  13.   }
  15. }

自定义结构在 KubeVela 中被广泛用于模块定义（X-Definitions）和进行验证。

定义一个 CUE 模板

下面，我们开始尝试利用刚刚学习到的知识，来定义 CUE 模版。

  1. 定义结构体变量 parameter.
  1. parameter: {
  3.     name: string
  5.     image: string
  7. }

保存上述变量到文件 deployment.cue.

  1. 定义更复杂的结构变量 template 同时引用变量 parameter.
  1. template: {
  3.     apiVersion: "apps/v1"
  5.     kind:       "Deployment"
  7.     spec: {
  9.         selector: matchLabels: {
  11.             "app.oam.dev/component": parameter.name
  13.         }
  15.         template: {
  17.             metadata: labels: {
  19.                 "app.oam.dev/component": parameter.name
  21.             }
  23.             spec: {
  25.                 containers: [{
  27.                     name:  parameter.name
  29.                     image: parameter.image
  31.                 }]
  33.             }}}
  35. }

熟悉 Kubernetes 的你可能已经知道，这是 Kubernetes Deployment 的模板。 parameter 为模版的参数部分。

添加上述内容到文件 deployment.cue.

  1. 随后, 我们通过更新以下内容来完成变量赋值:
  1. parameter:{
  3.    name: "mytest"
  5.    image: "nginx:v1"
  7. }
  1. 最后, 导出渲染结果为 YAML 格式:
  1. $ cue export deployment.cue -e template --out yaml
  6. apiVersion: apps/v1
  8. kind: Deployment
  10. spec:
  12.   selector:
  14.     matchLabels:
  16.       app.oam.dev/component: mytest
  18.   template:
  20.     metadata:
  22.       labels:
  24.         app.oam.dev/component: mytest
  26.     spec:
  28.       containers:
  30.       - name: mytest
  32.         image: nginx:v1

以上，你就得到了一个 Kubernetes Deployment 类型的模板。

CUE 的更多用法

  • 设计开放的结构体和数组。如果在数组或者结构体中使用 ...，则说明该对象为开放的。

    • 数组对象 [...string] ，说明该对象可以容纳多个字符串元素。 如果不添加 ..., 该对象 [string] 说明数组只能容纳一个类型为 string 的元素。

    • 如下所示的结构体说明可以包含未知字段。

      1. {
      3.   abc: string   
      5.   ...
      7. }

  • 使用运算符 | 来表示两种类型的值。如下所示，变量 a 表示类型可以是字符串或者整数类型。

  1. a: string | int
  • 使用符号 * 定义变量的默认值。通常它与符号 | 配合使用， 代表某种类型的默认值。如下所示，变量 a 类型为 int，默认值为 1。
  1. a: *1 | int
  • 让一些变量可被选填。 某些情况下，一些变量不一定被使用，这些变量就是可选变量，我们可以使用 ?: 定义此类变量。 如下所示, a 是可选变量, 自定义 #my 对象中 x 和 z 为可选变量， 而 y 为必填字段。
  1. a ?: int
  6. #my: {
  8. x ?: string
  10. y : int
  12. z ?:float
  14. }

选填变量可以被跳过，这经常和条件判断逻辑一起使用。 具体来说，如果某些字段不存在，则 CUE 语法为 if _variable_！= _ | _ ，如下所示：

  1. parameter: {
  3.     name: string
  5.     image: string
  7.     config?: [...#Config]
  9. }
  11. output: {
  13.     ...
  15.     spec: {
  17.         containers: [{
  19.             name:  parameter.name
  21.             image: parameter.image
  23.             if parameter.config != _|_ {
  25.                 config: parameter.config
  27.             }
  29.         }]
  31.     }
  33.     ...
  35. }
  • 使用运算符 & 来运算两个变量。
  1. a: *1 | int
  3. b: 3
  5. c: a & b

保存上述内容到 third.cue 文件。

你可以使用 cue eval 来验证结果：

  1. $ cue eval third.cue
  3. a: 1
  5. b: 3
  7. c: 3
  • 需要执行条件判断。当你执行一些级联操作时，不同的值会影响不同的结果，条件判断就非常有用。 因此，你可以在模版中执行 if..else 的逻辑。
  1. price: number
  3. feel: *"good" | string
  5. // Feel bad if price is too high
  7. if price > 100 {
  9.     feel: "bad"
  11. }
  13. price: 200

保存上述内容到 fourth.cue 文件。

你可以使用 cue eval 来验证结果：

  1. $ cue eval fourth.cue
  3. price: 200
  5. feel:  "bad"

另一个示例是将布尔类型作为参数。

  1. parameter: {
  3.     name:   string
  5.     image:  string
  7.     useENV: bool
  9. }
  11. output: {
  13.     ...
  15.     spec: {
  17.         containers: [{
  19.             name:  parameter.name
  21.             image: parameter.image
  23.             if parameter.useENV == true {
  25.                 env: [{name: "my-env", value: "my-value"}]
  27.             }
  29.         }]
  31.     }
  33.     ...
  35. }

  • 使用 For 循环。 我们为了避免减少重复代码，常常使用 For 循环。

    • 映射遍历。

      1. parameter: {
      3.     name:  string
      5.     image: string
      7.     env: [string]: string
      9. }
      11. output: {
      13.     spec: {
      15.         containers: [{
      17.             name:  parameter.name
      19.             image: parameter.image
      21.             env: [
      23.                 for k, v in parameter.env {
      25.                     name:  k
      27.                     value: v
      29.                 },
      31.             ]
      33.         }]
      35.     }
      37. }

    • 类型遍历。

      ```

      a: {

      1. "hello": "Barcelona"
      3. "nihao": "Shanghai"

      }

  1.     for k, v in #a {
  3.         "\(k)": {
  5.             nameLen: len(v)
  7.             value:   v
  9.         }
  11.     }
  13.     ```
  15. -   切片遍历。
  17.     ```
  18.     parameter: {
  20.         name:  string
  22.         image: string
  24.         env: [...{name:string,value:string}]
  26.     }
  28.     output: {
  30.       ...
  32.          spec: {
  34.             containers: [{
  36.                 name:  parameter.name
  38.                 image: parameter.image
  40.                 env: [
  42.                     for _, v in parameter.env {
  44.                         name:  v.name
  46.                         value: v.value
  48.                     },
  50.                 ]
  52.             }]
  54.         }
  56.     }
  58.     ```

另外，可以使用 "\( _my-statement_ )" 进行字符串内部计算，比如上面类型循环示例中，获取值的长度等等操作。

导入 CUE 内部包

CUE 有很多 internal packages 可以被 KubeVela 使用，这样可以满足更多的开发需求。

比如，使用 strings.Join 方法将字符串数组拼接成字符串。

  1. import ("strings")
  6. parameter: {
  8.     outputs: [{ip: "1.1.1.1", hostname: "xxx.com"}, {ip: "2.2.2.2", hostname: "yyy.com"}]
  10. }
  12. output: {
  14.     spec: {
  16.         if len(parameter.outputs) > 0 {
  18.             _x: [ for _, v in parameter.outputs {
  20.                 "\(v.ip) \(v.hostname)"
  22.             }]
  24.             message: "Visiting URL: " + strings.Join(_x, "")
  26.         }
  28.     }
  30. }

导入 Kubernetes 包

KubeVela 会从 Kubernetes 集群中读取 OpenAPI，并将 Kubernetes 所有资源自动构建为内部包。

你可以在 KubeVela 的 CUE 模版中通过 kube/<apiVersion> 导入这些包，就像使用 CUE 内部包一样。

比如，Deployment 可以这样使用：

  1. import (
  3.    apps "kube/apps/v1"
  5. )
  10. parameter: {
  12.     name:  string
  14. }
  19. output: apps.#Deployment
  21. output: {
  23.     metadata: name: parameter.name
  25. }

Service 可以这样使用（无需使用别名导入软件包）：

  1. import ("kube/v1")
  6. output: v1.#Service
  8. output: {
  10.     metadata: {
  12.         "name": parameter.name
  14.     }
  16.     spec: type: "ClusterIP",
  18. }
  23. parameter: {
  25.     name:  "myapp"
  27. }

甚至已经安装的 CRD 也可以导入使用：

  1. import (
  3.   oam  "kube/core.oam.dev/v1alpha2"
  5. )
  10. output: oam.#Application
  12. output: {
  14.     metadata: {
  16.         "name": parameter.name
  18.     }
  20. }
  25. parameter: {
  27.     name:  "myapp"
  29. }

下一步