配置模版

有很多的场景需要用户输入格式化的数据,通常称之为配置。配置模版是用来定义配置的输入参数的类型和要求以及配置内容的结构。KubeVela 通过模版引导用户提供正确的配置数据。

配置数据默认存储为 Secret,但也可以通过配置模版定义多种输出资源类型和结构。甚至,你也可以通过定义扩展输出将配置内容输出到第三方 Nacos 配置管理服务中。

配置模版采用 CUE 语言进行定义,它的规范结构如下:

  1. metadata: {
  2. name: string
  3. alias?: string
  4. description?: string
  5. scope: "project" | "system"
  6. sensitive: bool
  7. }
  8. template: {
  9. parameter: {...}
  10. output?: #Secret
  11. outputs?: {#AnyResources}
  12. nacos?: {
  13. // The endpoint can not references the parameter.
  14. endpoint: {
  15. // Users must create a config base the nacos-server template firstly.
  16. name: string
  17. }
  18. format: "json" | "yaml" | "properties" | "toml"
  19. // could references the parameter
  20. metadata: {
  21. dataId: string
  22. group: string
  23. appName: string
  24. namespaceId: string
  25. tenant: string
  26. tag: string
  27. }
  28. content: {...}
  29. }
  30. }
  • metadata.name 这是必填字段,指明该模版的名称。
  • metadata.alias 指定该模版的别名。
  • metadata.description 指定该模版的描述信息。
  • metadata.scope 指定由该模版创建的配置生效范围。可选值包括 “system” 和 “project”。在 VelaUX 中,定义为 “project” 范围的模版可以在项目下创建配置,同时如果在系统层面创建的配置可以被所有项目共享分发和使用。
  • metadata.sensitive 指定由该模版创建的配置的敏感性,如果为 True 则代表该配置一旦创建不能二次读取和修改。只能通过挂载 Secret 的方式使用。

  • template.parameter 定义该配置需要用户输入的参数,以 CUE 的方式进行定义。

  • template.output 该字段不是必须的。如果你需要自定义 Secret 的存储结构时使用。默认情况下根据用户输入参数结构进行存储。

  • template.outputs 该字段不是必须的。如果你需要基于该配置生成除 Secret 以外的任何资源时进行定义。

  • template.nacos 该字段不是必须的,如果你需要将配置写入第三方 Nacos 服务时进行定义。其中 template.nacos.name 字段代表使用的 Nacos 服务,由内置的 nacos-server 类型的模版创建服务端点配置。

  • 查询所有模版,默认从 vela-system 命名空间下获取。

  1. vela config-template list
  • 创建一个模版
  1. vela config-template apply -f example.cue
  • 查询创建配置需要的参数及说明
  1. vela config-template show <Template Name>
  • 删除模版
  1. vela config-template delete <Template Name>

更多的操作方式,请参考:

  1. vela config-template --help

该用例自定义了 Secret,以符合 Kubernetes 使用该配置拉取私有镜像的要求。

  1. import (
  2. "encoding/base64"
  3. "encoding/json"
  4. "strconv"
  5. )
  6. metadata: {
  7. name: "image-registry"
  8. alias: "Image Registry"
  9. scope: "project"
  10. description: "Config information to authenticate image registry"
  11. sensitive: false
  12. }
  13. template: {
  14. output: {
  15. apiVersion: "v1"
  16. kind: "Secret"
  17. metadata: {
  18. name: context.name
  19. namespace: context.namespace
  20. labels: {
  21. "config.oam.dev/catalog": "velacore-config"
  22. "config.oam.dev/type": "image-registry"
  23. }
  24. }
  25. if parameter.auth != _|_ {
  26. type: "kubernetes.io/dockerconfigjson"
  27. }
  28. if parameter.auth == _|_ {
  29. type: "Opaque"
  30. }
  31. stringData: {
  32. if parameter.auth != _|_ && parameter.auth.username != _|_ {
  33. ".dockerconfigjson": json.Marshal({
  34. "auths": (parameter.registry): {
  35. "username": parameter.auth.username
  36. "password": parameter.auth.password
  37. if parameter.auth.email != _|_ {
  38. "email": parameter.auth.email
  39. }
  40. "auth": base64.Encode(null, (parameter.auth.username + ":" + parameter.auth.password))
  41. }
  42. })
  43. }
  44. if parameter.insecure != _|_ {
  45. "insecure-skip-verify": strconv.FormatBool(parameter.insecure)
  46. }
  47. if parameter.useHTTP != _|_ {
  48. "protocol-use-http": strconv.FormatBool(parameter.useHTTP)
  49. }
  50. }
  51. }
  52. parameter: {
  53. // +usage=Image registry FQDN, such as: index.docker.io
  54. registry: *"index.docker.io" | string
  55. // +usage=Authenticate the image registry
  56. auth?: {
  57. // +usage=Private Image registry username
  58. username: string
  59. // +usage=Private Image registry password
  60. password: string
  61. // +usage=Private Image registry email
  62. email?: string
  63. }
  64. // +usage=For the registry server that uses the self-signed certificate
  65. insecure?: bool
  66. // +usage=For the registry server that uses the HTTP protocol
  67. useHTTP?: bool
  68. }
  69. }

该用例作为一个最简配置用例,支持用户集成 Nacos 服务,服务于模版定义中的 Nacos 部分。

  1. metadata: {
  2. name: "nacos-server"
  3. alias: "Nacos Server"
  4. description: "Config the Nacos server connectors"
  5. sensitive: false
  6. scope: "system"
  7. }
  8. template: {
  9. parameter: {
  10. // +usage=Directly configure the Nacos server address
  11. servers?: [...{
  12. // +usage=the nacos server address
  13. ipAddr: string
  14. // +usage=nacos server port
  15. port: *8849 | int
  16. // +usage=nacos server grpc port, default=server port + 1000, this is not required
  17. grpcPort?: int
  18. }]
  19. // +usage=Discover the Nacos servers by the client.
  20. client?: {
  21. // +usage=the endpoint for get Nacos server addresses
  22. endpoint: string
  23. // +usage=the AccessKey for kms
  24. accessKey?: string
  25. // +usage=the SecretKey for kms
  26. secretKey?: string
  27. // +usage=the regionId for kms
  28. regionId?: string
  29. // +usage=the username for nacos auth
  30. username?: string
  31. // +usage=the password for nacos auth
  32. password?: string
  33. // +usage=it's to open kms,default is false. https://help.aliyun.com/product/28933.html
  34. openKMS?: bool
  35. }
  36. }
  37. }

该用例提供了如何将配置写入 Nacos 的参考,你可以根据需要进一步的定义配置具体类型的结构。

  1. metadata: {
  2. name: "nacos-config"
  3. alias: "Nacos Configuration"
  4. description: "Write the configuration to the nacos"
  5. sensitive: false
  6. scope: "system"
  7. }
  8. template: {
  9. nacos: {
  10. // The endpoint can not references the parameter.
  11. endpoint: {
  12. // Users must create a config base the nacos-server template firstly.
  13. name: "nacos"
  14. }
  15. format: parameter.contentType
  16. // could references the parameter
  17. metadata: {
  18. dataId: parameter.dataId
  19. group: parameter.group
  20. if parameter.appName != _|_ {
  21. appName: parameter.appName
  22. }
  23. if parameter.namespaceId != _|_ {
  24. namespaceId: parameter.namespaceId
  25. }
  26. if parameter.tenant != _|_ {
  27. tenant: parameter.tenant
  28. }
  29. if parameter.tag != _|_ {
  30. tag: parameter.tag
  31. }
  32. }
  33. content: parameter.content
  34. }
  35. parameter: {
  36. // +usage=Configuration ID
  37. dataId: string
  38. // +usage=Configuration group
  39. group: *"DEFAULT_GROUP" | string
  40. // +usage=The configuration content.
  41. content: {
  42. ...
  43. }
  44. contentType: *"json" | "yaml" | "properties" | "toml"
  45. // +usage=The app name of the configuration
  46. appName?: string
  47. // +usage=The namespaceId of the configuration
  48. namespaceId?: string
  49. // +usage=The tenant, corresponding to the namespace ID field of Nacos
  50. tenant?: string
  51. // +usage=The tag of the configuration
  52. tag?: string
  53. }
  54. }

该用例提供了生成其他类型资源的参考。这里生成了 Terraform 控制器可用的 Provider 资源。

  1. import "strings"
  2. metadata: {
  3. name: "terraform-alibaba"
  4. alias: "Terraform Provider for Alibaba Cloud"
  5. sensitive: true
  6. scope: "system"
  7. description: "Terraform Provider for Alibaba Cloud"
  8. }
  9. template: {
  10. outputs: {
  11. "provider": {
  12. apiVersion: "terraform.core.oam.dev/v1beta1"
  13. kind: "Provider"
  14. metadata: {
  15. name: parameter.name
  16. namespace: "default"
  17. labels: l
  18. }
  19. spec: {
  20. provider: "alibaba"
  21. region: parameter.ALICLOUD_REGION
  22. credentials: {
  23. source: "Secret"
  24. secretRef: {
  25. namespace: "vela-system"
  26. name: context.name
  27. key: "credentials"
  28. }
  29. }
  30. }
  31. }
  32. }
  33. output: {
  34. apiVersion: "v1"
  35. kind: "Secret"
  36. metadata: {
  37. name: context.name
  38. namespace: context.namespace
  39. }
  40. type: "Opaque"
  41. stringData: credentials: strings.Join([creds1, creds2], "\n")
  42. }
  43. creds1: "accessKeyID: " + parameter.ALICLOUD_ACCESS_KEY
  44. creds2: "accessKeySecret: " + parameter.ALICLOUD_SECRET_KEY
  45. l: {
  46. "config.oam.dev/catalog": "velacore-config"
  47. "config.oam.dev/type": "terraform-provider"
  48. "config.oam.dev/provider": "terraform-alibaba"
  49. }
  50. parameter: {
  51. //+usage=The name of Terraform Provider for Alibaba Cloud, default is `default`
  52. name: *"default" | string
  53. //+usage=Get ALICLOUD_ACCESS_KEY per this guide https://help.aliyun.com/knowledge_detail/38738.html
  54. ALICLOUD_ACCESS_KEY: string
  55. //+usage=Get ALICLOUD_SECRET_KEY per this guide https://help.aliyun.com/knowledge_detail/38738.html
  56. ALICLOUD_SECRET_KEY: string
  57. //+usage=Get ALICLOUD_REGION by picking one RegionId from Alibaba Cloud region list https://www.alibabacloud.com/help/doc-detail/72379.htm
  58. ALICLOUD_REGION: string
  59. }
  60. }

模版配置作为 插件 的一部分. 你可以在安装插件时获得已有的配置模版,也可以通过制作插件来分享配置模版。

Last updated on 2023年8月4日 by Daniel Higuero