版本:v1.3

自定义运维特征

本节介绍如何自定义运维特征,为用户的组件增添任何需要的运维特征能力。

请先阅读和理解 运维特征定义

我们首先为你展示一个简单的示例,比如直接引用已有的 Kubernetes API 资源 Ingress。来编写一个下面这样的 YAML 文件:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: TraitDefinition
  3. metadata:
  4. name: customize-ingress
  5. spec:
  6. definitionRef:
  7. name: ingresses.networking.k8s.io

为了和我们已经内置的 ingress 有所区分,我们将其命名为 customize-ingress。然后我们部署到运行时集群:

  1. $ kubectl apply -f customize-ingress.yaml
  2. traitdefinition.core.oam.dev/customize-ingress created

创建成功。这时候,你的用户可以通过 vela traits 查看到这个能力:

  1. $ vela traits
  2. NAME NAMESPACE APPLIES-TO CONFLICTS-WITH POD-DISRUPTIVE DESCRIPTION
  3. customize-ingress default false description not defined
  4. ingress default false description not defined
  5. annotations vela-system deployments.apps true Add annotations for your Workload.
  6. configmap vela-system deployments.apps true Create/Attach configmaps to workloads.
  7. cpuscaler vela-system deployments.apps false Automatically scale the component based on CPU usage.
  8. expose vela-system deployments.apps false Expose port to enable web traffic for your component.
  9. hostalias vela-system deployment.apps false Add host aliases to workloads.
  10. labels vela-system deployments.apps true Add labels for your Workload.
  11. lifecycle vela-system deployments.apps true Add lifecycle hooks to workloads.
  12. resource vela-system deployments.apps true Add resource requests and limits to workloads.
  13. rollout vela-system false rollout the component
  14. scaler vela-system deployments.apps false Manually scale the component.
  15. service-binding vela-system webservice,worker false Binding secrets of cloud resources to component env
  16. sidecar vela-system deployments.apps true Inject a sidecar container to the component.
  17. volumes vela-system deployments.apps true Add volumes for your Workload.

最后用户只需要把这个自定义的运维特征,放入一个与之匹配的组件中进行使用即可:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4. name: testapp
  5. spec:
  6. components:
  7. - name: express-server
  8. type: webservice
  9. properties:
  10. cmd:
  11. - node
  12. - server.js
  13. image: oamdev/testapp:v1
  14. port: 8080
  15. traits:
  16. - type: customize-ingress
  17. properties:
  18. rules:
  19. - http:
  20. paths:
  21. - path: /testpath
  22. pathType: Prefix
  23. backend:
  24. service:
  25. name: test
  26. port:
  27. number: 80

参照上面的开发过程,你可以继续自定义其它需要的 Kubernetes 资源来提供给你的用户。

请注意:这种自定义运维特征的方式中,是无法设置诸如 annotations 这样的元信息(metadata),来作为运维特征属性的。也就是说,当你只想简单引入自己的 CRD 资源或者控制器作为运维特征时,可以遵循这种做法。

我们更推荐你使用 CUE 模版来自定义运维特征。这种方法给你可以模版化任何资源和资源的灵活性。比如,我们可以组合自定义 Serviceingeress 成为一个运维特征来使用。

在用法上,你需要把所有的运维特征定义在 outputs 里(注意,不是 output),格式如下:

  1. outputs: <unique-name>:
  2. <full template data>

我们下面同样使用一个 ingressService 的示例进行讲解:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: TraitDefinition
  3. metadata:
  4. name: cue-ingress
  5. spec:
  6. podDisruptive: false
  7. schematic:
  8. cue:
  9. template: |
  10. parameter: {
  11. domain: string
  12. http: [string]: int
  13. }
  14. // 我们可以在一个运维特征 CUE 模版定义多个 outputs
  15. outputs: service: {
  16. apiVersion: "v1"
  17. kind: "Service"
  18. metadata: {
  19. annotations: {
  20. address-type: "intranet"
  21. }
  22. }
  23. spec: {
  24. selector:
  25. app: context.name
  26. ports: [
  27. for k, v in parameter.http {
  28. port: v
  29. targetPort: v
  30. },
  31. ]
  32. type: "LoadBalancer"
  33. }
  34. }
  35. outputs: ingress: {
  36. apiVersion: "networking.k8s.io/v1beta1"
  37. kind: "Ingress"
  38. metadata:
  39. name: context.name
  40. spec: {
  41. rules: [{
  42. host: parameter.domain
  43. http: {
  44. paths: [
  45. for k, v in parameter.http {
  46. path: k
  47. backend: {
  48. serviceName: context.name
  49. servicePort: v
  50. }
  51. },
  52. ]
  53. }
  54. }]
  55. }
  56. }

可以看到,parameter 字段让我们可以自由自定义和传递业务参数。同时在 metadataannotations 里可以标记任何你们需要的信息,我们上文的例子里标记了 Service 是一个给内网使用的负载均衡。

接下来我们把这个 cue-ingress YMAL 部署到运行时集群,成功之后用户同样可以通过 vela traits 命令,查看到这个新生成的运维特征:

  1. $ kubectl apply -f cue-ingress.yaml
  2. traitdefinition.core.oam.dev/cue-ingress created
  3. $ vela traits
  4. NAME NAMESPACE APPLIES-TO CONFLICTS-WITH POD-DISRUPTIVE DESCRIPTION
  5. cue-ingress default false description not defined
  6. ingress default false description not defined
  7. annotations vela-system deployments.apps true Add annotations for your Workload.
  8. configmap vela-system deployments.apps true Create/Attach configmaps to workloads.
  9. cpuscaler vela-system deployments.apps false Automatically scale the component based on CPU usage.
  10. expose vela-system deployments.apps false Expose port to enable web traffic for your component.
  11. hostalias vela-system deployment.apps false Add host aliases to workloads.
  12. labels vela-system deployments.apps true Add labels for your Workload.
  13. lifecycle vela-system deployments.apps true Add lifecycle hooks to workloads.
  14. resource vela-system deployments.apps true Add resource requests and limits to workloads.
  15. rollout vela-system false rollout the component
  16. scaler vela-system deployments.apps false Manually scale the component.
  17. service-binding vela-system webservice,worker false Binding secrets of cloud resources to component env
  18. sidecar vela-system deployments.apps true Inject a sidecar container to the component.
  19. volumes vela-system deployments.apps true Add volumes for your Workload.

最后用户将这个运维特征放入对应组件,通过应用部署计划完成交付:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4. name: testapp
  5. spec:
  6. components:
  7. - name: express-server
  8. type: webservice
  9. properties:
  10. cmd:
  11. - node
  12. - server.js
  13. image: oamdev/testapp:v1
  14. port: 8080
  15. traits:
  16. - type: cue-ingress
  17. properties:
  18. domain: test.my.domain
  19. http:
  20. "/api": 8080

基于 CUE 的运维特征定义方式,也提供了满足于更多业务场景的用法,比如给运维特征打补丁、传递数据等等。后面的文档将进一步介绍相关内容。

Last updated on 2022年11月1日 by Tianxin Dong