Skip to main content
版本:v1.3

自定义运维特征

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

开始之前

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

如何使用

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

apiVersion: core.oam.dev/v1beta1
kind: TraitDefinition
metadata:
name: customize-ingress
spec:
definitionRef:
name: ingresses.networking.k8s.io

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

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

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

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

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

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: testapp
spec:
components:
- name: express-server
type: webservice
properties:
cmd:
- node
- server.js
image: oamdev/testapp:v1
port: 8080
traits:
- type: customize-ingress
properties:
rules:
- http:
paths:
- path: /testpath
pathType: Prefix
backend:
service:
name: test
port:
number: 80

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

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

使用 CUE 来自定义运维特征

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

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

outputs: <unique-name>: 
<full template data>

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

apiVersion: core.oam.dev/v1beta1
kind: TraitDefinition
metadata:
name: cue-ingress
spec:
podDisruptive: false
schematic:
cue:
template: |
parameter: {
domain: string
http: [string]: int
}

// 我们可以在一个运维特征 CUE 模版定义多个 outputs
outputs: service: {
apiVersion: "v1"
kind: "Service"
metadata: {
annotations: {
address-type: "intranet"
}
}
spec: {
selector:
app: context.name
ports: [
for k, v in parameter.http {
port: v
targetPort: v
},
]

type: "LoadBalancer"
}
}

outputs: ingress: {
apiVersion: "networking.k8s.io/v1beta1"
kind: "Ingress"
metadata:
name: context.name
spec: {
rules: [{
host: parameter.domain
http: {
paths: [
for k, v in parameter.http {
path: k
backend: {
serviceName: context.name
servicePort: v
}
},
]
}
}]
}
}

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

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

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

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

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: testapp
spec:
components:
- name: express-server
type: webservice
properties:
cmd:
- node
- server.js
image: oamdev/testapp:v1
port: 8080
traits:
- type: cue-ingress
properties:
domain: test.my.domain
http:
"/api": 8080

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