Version: v1.2

编辑管理模块定义

在 KubeVela CLI (>= v1.1.0) 工具中，vela def 命令组为开发者提供了一系列便捷的 X-Definition 编写工具，使得 Definition 的编写将全部在 CUE 文件中进行，避免将 Template CUE 与 Kubernetes 的 YAML 格式进行混合，方便进行格式化与校验。

init

vela def init 是一个用来帮助用户初始化新的 Definition 的脚手架命令。用户可以通过 vela def init my-trait -t trait --desc "My trait description." 来创建一个新的空白 TraitDefinition ，如下

  1. "my-trait": {
  3.         annotations: {}
  5.         attributes: {
  7.                 appliesToWorkloads: []
  9.                 conflictsWith: []
  11.                 definitionRef:   ""
  13.                 podDisruptive:   false
  15.                 workloadRefPath: ""
  17.         }
  19.         description: "My trait description."
  21.         labels: {}
  23.         type: "trait"
  25. }
  27. template: patch: {}

或者是采用 vela def init my-comp --interactive 来交互式地创建新的 Definition 。

  1. $ vela def init my-comp --interactive
  3. Please choose one definition type from the following values: component, trait, policy, workload, scope, workflow-step
  5. > Definition type: component
  7. > Definition description: My component definition.
  9. Please enter the location the template YAML file to build definition. Leave it empty to generate default template.
  11. > Definition template filename: 
  13. Please enter the output location of the generated definition. Leave it empty to print definition to stdout.
  15. > Definition output filename: my-component.cue
  17. Definition written to my-component.cue

除此之外，如果用户创建 ComponentDefinition 的目的是一个 Deployment（或者是其他的 Kubernetes Object ），而这个 Deployment 已经有了 YAML 格式的模版，用户还可以通过 --template-yaml 参数来完成从 YAML 到 CUE 的自动转换。例如如下的 my-deployment.yaml

  1. apiVersion: apps/v1
  3. kind: Deployment
  5. metadata:
  7.   name: hello-world
  9. spec:
  11.   replicas: 1
  13.   selector:
  15.     matchLabels:
  17.       app.kubernetes.io/name: hello-world
  19.   template:
  21.     metadata:
  23.       labels:
  25.         app.kubernetes.io/name: hello-world
  27.     spec:
  29.       containers:
  31.       - name: hello-world
  33.         image: somefive/hello-world
  35.         ports: 
  37.         - name: http
  39.           containerPort: 80
  41.           protocol: TCP
  43. ---
  45. apiVersion: v1
  47. kind: Service
  49. metadata:
  51.   name: hello-world-service
  53. spec:
  55.   selector:
  57.     app: hello-world
  59.   ports:
  61.   - name: http
  63.     protocol: TCP
  65.     port: 80
  67.     targetPort: 8080
  69.   type: LoadBalancer

运行 vela def init my-comp -t component --desc "My component." --template-yaml ./my-deployment.yaml 可以得到 CUE 格式的 ComponentDefinition

  1. "my-comp": {
  3.         annotations: {}
  5.         attributes: workload: definition: {
  7.                 apiVersion: "<change me> apps/v1"
  9.                 kind:       "<change me> Deployment"
  11.         }
  13.         description: "My component."
  15.         labels: {}
  17.         type: "component"
  19. }
  21. template: {
  23.         output: {
  25.                 metadata: name: "hello-world"
  27.                 spec: {
  29.                         replicas: 1
  31.                         selector: matchLabels: "app.kubernetes.io/name": "hello-world"
  33.                         template: {
  35.                                 metadata: labels: "app.kubernetes.io/name": "hello-world"
  37.                                 spec: containers: [{
  39.                                         name:  "hello-world"
  41.                                         image: "somefive/hello-world"
  43.                                         ports: [{
  45.                                                 name:          "http"
  47.                                                 containerPort: 80
  49.                                                 protocol:      "TCP"
  51.                                         }]
  53.                                 }]
  55.                         }
  57.                 }
  59.                 apiVersion: "apps/v1"
  61.                 kind:       "Deployment"
  63.         }
  65.         outputs: "hello-world-service": {
  67.                 metadata: name: "hello-world-service"
  69.                 spec: {
  71.                         ports: [{
  73.                                 name:       "http"
  75.                                 protocol:   "TCP"
  77.                                 port:       80
  79.                                 targetPort: 8080
  81.                         }]
  83.                         selector: app: "hello-world"
  85.                         type: "LoadBalancer"
  87.                 }
  89.                 apiVersion: "v1"
  91.                 kind:       "Service"
  93.         }
  95.         parameter: {}
  97. }

接下来，用户就可以在该文件的基础上进一步做进一步的修改了。比如将属性中对于 workload.definition 中的 \<change me> 去掉。

vet

在初始化 Definition 文件之后，可以运行 vela def vet my-comp.cue 来校验 Definition 是否在语法上有错误。比如如果少写了一个括号，该命令能够帮助用户识别出来。

  1. $ vela def vet my-comp.cue
  3. Validation succeed.

render / apply

确认 Definition 撰写无误后，开发者可以运行 vela def apply my-comp.cue --namespace my-namespace 来将该 Definition 应用在 Kubernetes 的 my-namespace 命名空间中。如果想了解一下 CUE 格式的 Definition 文件会被渲染成什么样的 Kubernetes YAML 文件，可以使用 vela def apply my-comp.cue --dry-run 或者 vela def render my-comp.cue -o my-comp.yaml 来预先渲染一下 YAML 文件进行确认。

  1. apiVersion: core.oam.dev/v1beta1
  3. kind: ComponentDefinition
  5. metadata:
  7.   annotations:
  9.     definition.oam.dev/description: My component.
  11.   labels: {}
  13.   name: my-comp
  15.   namespace: vela-system
  17. spec:
  19.   schematic:
  21.     cue:
  23.       template: |
  25.         output: {
  27.                 metadata: name: "hello-world"
  29.                 spec: {
  31.                         replicas: 1
  33.                         selector: matchLabels: "app.kubernetes.io/name": "hello-world"
  35.                         template: {
  37.                                 metadata: labels: "app.kubernetes.io/name": "hello-world"
  39.                                 spec: containers: [{
  41.                                         name:  "hello-world"
  43.                                         image: "somefive/hello-world"
  45.                                         ports: [{
  47.                                                 name:          "http"
  49.                                                 containerPort: 80
  51.                                                 protocol:      "TCP"
  53.                                         }]
  55.                                 }]
  57.                         }
  59.                 }
  61.                 apiVersion: "apps/v11"
  63.                 kind:       "Deployment"
  65.         }
  67.         outputs: "hello-world-service": {
  69.                 metadata: name: "hello-world-service"
  71.                 spec: {
  73.                         ports: [{
  75.                                 name:       "http"
  77.                                 protocol:   "TCP"
  79.                                 port:       80
  81.                                 targetPort: 8080
  83.                         }]
  85.                         selector: app: "hello-world"
  87.                         type: "LoadBalancer"
  89.                 }
  91.                 apiVersion: "v1"
  93.                 kind:       "Service"
  95.         }
  97.         parameter: {}
  99.   workload:
  101.     definition:
  103.       apiVersion: apps/v1
  105.       kind: Deployment
  1. $ vela def apply my-comp.cue -n my-namespace
  3. ComponentDefinition my-comp created in namespace my-namespace.

get / list / edit / del

在 apply 命令后，开发者可以采用原生的 kubectl 来对结果进行确认，但是正如我们上文提到的，YAML 格式的结果会相对复杂。使用 vela def get 命令可以自动将其转换成 CUE 格式，方便用户查看。

  1. $ vela def get my-comp -t component

或者用户可以通过 vela def list 命令来查看当前系统中安装的所有 Definition（可以指定命名空间及类型）。

  1. $ vela def list -n my-namespace -t component
  3. NAME                    TYPE                    NAMESPACE       DESCRIPTION  
  5. my-comp                 ComponentDefinition     my-namespace    My component.

同样的，在使用 vela def edit 命令来编辑 Definition 时，用户也只需要对转换过的 CUE 格式 Definition 进行修改，该命令会自动完成格式转换。用户也可以通过设定环境变量 EDITOR 来使用自己想要使用的编辑器。

  1. $ EDITOR=vim vela def edit my-comp

类似的，用户可以运行 vela def del 来删除相应的 Definition。

  1. $ vela def del my-comp -n my-namespace  
  3. Are you sure to delete the following definition in namespace my-namespace?
  5. ComponentDefinition my-comp: My component.
  7. [yes|no] > yes
  9. ComponentDefinition my-comp in namespace my-namespace deleted.

下一步