Add X-Definition EN (#242)
* Add X-Definition EN * updates * Update docs/platform-engineers/oam/x-definition.md Co-authored-by: Tianxin Dong <wuwuglu19@gmail.com> * fix Co-authored-by: 段少 <duanwei.duan@alibaba-inc.com> Co-authored-by: Tianxin Dong <wuwuglu19@gmail.com>
This commit is contained in:
Wei (段少)
GitHub
parent
b2df3453cb
commit
7bfa37db18
|
|
@ -71,7 +71,7 @@ In this example, the `kustomize-patch` will patch the content for all Pods with
|
|||
|
||||
## kustomize-json-patch Specification
|
||||
|
||||
可以以 [JSON6902 格式](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/patchesjson6902/)进行 patch。先来了解其信息：
|
||||
You could use [JSON6902 format](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/patchesjson6902/) to patch the component. Get to know it first:
|
||||
|
||||
```shell
|
||||
vela show kustomize-json-patch
|
||||
|
|
|
|||
|
|
@ -2,4 +2,399 @@
|
|||
title: X-Definition
|
||||
---
|
||||
|
||||
TBD
|
||||
In OAM model, [Application][1] used by end user consists many declarative moduels such as Component, Trait, Policy and Workflow etc. These types are actually shaped by many definitions behind them. The module definition (X-Definition) supported by the current OAM model includes ComponentDefinition, TraitDefinition, PolicyDefinition and WorkflowStepDefinition etc.
|
||||
|
||||
## ComponentDefinition
|
||||
|
||||
The design goal of ComponentDefinition is to allow platform administrators to encapsulate any type of deployable products into "components" to be delivered. Once defined, this type of component can be referenced, instantiated and delivered by users in the `Application`.
|
||||
|
||||
Common component types include Helm Chart, Kustomize directory, a set of Kubernetes YAML files, container images, cloud resource IaC files, or CUE configuration file modules, etc. The component supplier corresponds to the real-world role, which is generally a third-party software distributor (ISV), a DevOps team engineer, or a code package and image generated by the CI system you built.
|
||||
|
||||
ComponentDefinition can be shared and reused. For example, for an `Alibaba Cloud RDS` component type, end users can select the same `Alibaba Cloud RDS` component type in different applications and instantiate them into cloud database instances with different specifications and different parameter configurations.
|
||||
|
||||
Let's take a look at the frame format of ComponentDefinition:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
metadata:
|
||||
name: <ComponentDefinition name>
|
||||
annotations:
|
||||
definition.oam.dev/description: <Function description>
|
||||
spec:
|
||||
workload: # Workload description
|
||||
definition:
|
||||
apiVersion: <Kubernetes Workload resource group>
|
||||
kind: <Kubernetes Workload types>
|
||||
schematic: # Component description
|
||||
cue: # Details of components defined by CUE language
|
||||
template: <CUE format template>
|
||||
```
|
||||
Here is a complete example to introduce how to use ComponentDefinition.
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
metadata:
|
||||
name: helm
|
||||
namespace: vela-system
|
||||
annotations:
|
||||
definition.oam.dev/description: "helm release is a group of K8s resources from either git repository or helm repo"
|
||||
spec:
|
||||
workload:
|
||||
type: autodetects.core.oam.dev
|
||||
schematic:
|
||||
cue:
|
||||
template: |
|
||||
output: {
|
||||
apiVersion: "source.toolkit.fluxcd.io/v1beta1"
|
||||
metadata: {
|
||||
name: context.name
|
||||
}
|
||||
if parameter.repoType == "git" {
|
||||
kind: "GitRepository"
|
||||
spec: {
|
||||
url: parameter.repoUrl
|
||||
ref:
|
||||
branch: parameter.branch
|
||||
interval: parameter.pullInterval
|
||||
}
|
||||
}
|
||||
if parameter.repoType == "helm" {
|
||||
kind: "HelmRepository"
|
||||
spec: {
|
||||
interval: parameter.pullInterval
|
||||
url: parameter.repoUrl
|
||||
if parameter.secretRef != _|_ {
|
||||
secretRef: {
|
||||
name: parameter.secretRef
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
outputs: release: {
|
||||
apiVersion: "helm.toolkit.fluxcd.io/v2beta1"
|
||||
kind: "HelmRelease"
|
||||
metadata: {
|
||||
name: context.name
|
||||
}
|
||||
spec: {
|
||||
interval: parameter.pullInterval
|
||||
chart: {
|
||||
spec: {
|
||||
chart: parameter.chart
|
||||
version: parameter.version
|
||||
sourceRef: {
|
||||
if parameter.repoType == "git" {
|
||||
kind: "GitRepository"
|
||||
}
|
||||
if parameter.repoType == "helm" {
|
||||
kind: "HelmRepository"
|
||||
}
|
||||
name: context.name
|
||||
namespace: context.namespace
|
||||
}
|
||||
interval: parameter.pullInterval
|
||||
}
|
||||
}
|
||||
if parameter.targetNamespace != _|_ {
|
||||
targetNamespace: parameter.targetNamespace
|
||||
}
|
||||
if parameter.values != _|_ {
|
||||
values: parameter.values
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
parameter: {
|
||||
repoType: "git" | "helm"
|
||||
// +usage=The Git or Helm repository URL, accept HTTP/S or SSH address as git url.
|
||||
repoUrl: string
|
||||
// +usage=The interval at which to check for repository and relese updates.
|
||||
pullInterval: *"5m" | string
|
||||
// +usage=1.The relative path to helm chart for git source. 2. chart name for helm resource
|
||||
chart: string
|
||||
// +usage=Chart version
|
||||
version?: string
|
||||
// +usage=The Git reference to checkout and monitor for changes, defaults to master branch.
|
||||
branch: *"master" | string
|
||||
// +usage=The name of the secret containing authentication credentials for the Helm repository.
|
||||
secretRef?: string
|
||||
// +usage=The namespace for helm chart
|
||||
targetNamespace?: string
|
||||
// +usage=Chart version
|
||||
value?: #nestedmap
|
||||
}
|
||||
|
||||
#nestedmap: {
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## TraitDefinition
|
||||
|
||||
TraitDefinition provides a series of DevOps actions for the component that can be bound on demand. These operation and maintenance actions are usually provided by the platform administrator, such as adding a load balancing strategy, routing strategy, or performing scaler, gray release strategy, etc.
|
||||
|
||||
The format and field functions of the TraitDefinition are as follows:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: TraitDefinition
|
||||
metadata:
|
||||
name: <TraitDefinition name>
|
||||
annotations:
|
||||
definition.oam.dev/description: <function description>
|
||||
spec:
|
||||
definition:
|
||||
apiVersion: <corresponding Kubernetes resource group>
|
||||
kind: <corresponding Kubernetes resource type>
|
||||
workloadRefPath: <The path to the reference field of the Workload object in the Trait>
|
||||
podDisruptive: <whether the parameter update of Trait cause the underlying resource (pod) to restart>
|
||||
manageWorkload: <Whether the workload is managed by this Trait>
|
||||
skipRevisionAffect: <Whether this Trait is not included in the calculation of version changes>
|
||||
appliesToWorkloads:
|
||||
- <Workload that TraitDefinition can adapt to>
|
||||
conflictsWith:
|
||||
- <other Traits that conflict with this><>
|
||||
revisionEnabled: <whether Trait is aware of changes in component version>
|
||||
schematic: # Abstract
|
||||
cue: # There are many abstracts
|
||||
template: <CUE format template>
|
||||
```
|
||||
|
||||
Let's look at a practical example:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: TraitDefinition
|
||||
metadata:
|
||||
annotations:
|
||||
definition.oam.dev/description: "configure k8s Horizontal Pod Autoscaler for Component which using Deployment as worklaod"
|
||||
name: hpa
|
||||
spec:
|
||||
appliesToWorkloads:
|
||||
- deployments.apps
|
||||
workloadRefPath: spec.scaleTargetRef
|
||||
schematic:
|
||||
cue:
|
||||
template: |
|
||||
outputs: hpa: {
|
||||
apiVersion: "autoscaling/v2beta2"
|
||||
kind: "HorizontalPodAutoscaler"
|
||||
spec: {
|
||||
minReplicas: parameter.min
|
||||
maxReplicas: parameter.max
|
||||
metrics: [{
|
||||
type: "Resource"
|
||||
resource: {
|
||||
name: "cpu"
|
||||
target: {
|
||||
type: "Utilization"
|
||||
averageUtilization: parameter.cpuUtil
|
||||
}
|
||||
}
|
||||
}]
|
||||
}
|
||||
}
|
||||
parameter: {
|
||||
min: *1 | int
|
||||
max: *10 | int
|
||||
cpuUtil: *50 | int
|
||||
}
|
||||
```
|
||||
|
||||
## PolicyDefinition
|
||||
|
||||
PolicyDefinition is simimarly to TraitDefinition, the difference is that TraitDefinition acts on a single component but PolicyDefinition is to act on the entire application as a whole (multiple components).
|
||||
|
||||
It can provide global policy for applications, commonly including global security policies (such as RBAC permissions, auditing, and key management), application insights (such as application SLO management, etc.).
|
||||
|
||||
The format is as follows:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: PolicyDefinition
|
||||
metadata:
|
||||
name: <PolicyDefinition name>
|
||||
annotations:
|
||||
definition.oam.dev/description: <function description>
|
||||
spec:
|
||||
schematic: # strategy description
|
||||
cue:
|
||||
template: <CUE format template>
|
||||
```
|
||||
A specific example is shown below:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: PolicyDefinition
|
||||
metadata:
|
||||
name: env-binding
|
||||
annotations:
|
||||
definition.oam.dev/description: <Provide differentiated configuration and environmental scheduling strategies for applications>
|
||||
spec:
|
||||
schematic:
|
||||
cue:
|
||||
template: |
|
||||
output: {
|
||||
apiVersion: "core.oam.dev/v1alpha1"
|
||||
kind: "EnvBinding"
|
||||
spec: {
|
||||
engine: parameter.engine
|
||||
appTemplate: {
|
||||
apiVersion: "core.oam.dev/v1beta1"
|
||||
kind: "Application"
|
||||
metadata: {
|
||||
name: context.appName
|
||||
namespace: context.namespace
|
||||
}
|
||||
spec: {
|
||||
components: context.components
|
||||
}
|
||||
}
|
||||
envs: parameter.envs
|
||||
}
|
||||
}
|
||||
|
||||
#Env: {
|
||||
name: string
|
||||
patch: components: [...{
|
||||
name: string
|
||||
type: string
|
||||
properties: {...}
|
||||
}]
|
||||
placement: clusterSelector: {
|
||||
labels?: [string]: string
|
||||
name?: string
|
||||
}
|
||||
}
|
||||
|
||||
parameter: {
|
||||
engine: *"ocm" | string
|
||||
envs: [...#Env]
|
||||
}
|
||||
```
|
||||
|
||||
## WorkflowStepDefinition
|
||||
|
||||
WorkflowStepDefinition is used to describe a series of steps that can be declared in the workflow, such as the deployment of execution resources, status check, data output, dependent input, external script call, etc.
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: WorkflowStepDefinition
|
||||
metadata:
|
||||
name: <WorkflowStepDefinition name>
|
||||
annotations:
|
||||
definition.oam.dev/description: <function description>
|
||||
spec:
|
||||
schematic: # node description
|
||||
cue:
|
||||
template: <CUE format template>
|
||||
```
|
||||
|
||||
An actual WorkflowStepDefinition is as follows:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: WorkflowStepDefinition
|
||||
metadata:
|
||||
name: apply-component
|
||||
spec:
|
||||
schematic:
|
||||
cue:
|
||||
template: |
|
||||
import ("vela/op")
|
||||
parameter: {
|
||||
component: string
|
||||
}
|
||||
|
||||
// load component from application
|
||||
component: op.#Load & {
|
||||
component: parameter.component
|
||||
}
|
||||
|
||||
// apply workload to kubernetes cluster
|
||||
apply: op.#ApplyComponent & {
|
||||
component: parameter.name
|
||||
}
|
||||
|
||||
// wait until workload.status equal "Running"
|
||||
wait: op.#ConditionalWait & {
|
||||
continue: apply.status.phase =="Running"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## WorkloadDefinition
|
||||
|
||||
WorkloadDefinition is a system-level feature. It's not a field that users should care about but as metadata checked, verified, and used by the OAM system itself.
|
||||
|
||||
The format is as follows:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: WorkloadDefinition
|
||||
metadata:
|
||||
name: <WorkloadDefinition name>
|
||||
spec:
|
||||
definitionRef:
|
||||
name: <corresponding Kubernetes resource group>
|
||||
version: <corresponding Kubernetes resource version>
|
||||
podSpecPath: <path to the Pod field in the Workload>
|
||||
childResourceKinds:
|
||||
- apiVersion: <resource group>
|
||||
kind: <resource type>
|
||||
```
|
||||
|
||||
In addition, other Kubernetes resource type that need to be introduced into OAM model in the future will also be added as fields to the workload definition.
|
||||
|
||||
## The Standard Protocol Behind Abstraction
|
||||
|
||||
Once the application is created, KubeVela will tag the created resources with a series of tags, which include the version, name, type, etc. of the application. Through these standard protocols, application components, traits and policies can be coordinated. The specific metadata list is as follows:
|
||||
|
||||
| Label | Description |
|
||||
| :-------------------------------------------------: | :-------------------------------------------: |
|
||||
| `workload.oam.dev/type` | Corresponds to the name of `ComponentDefinition`|
|
||||
| `trait.oam.dev/type` | Corresponds to the name of `TraitDefinition` |
|
||||
| `app.oam.dev/name` | Application name |
|
||||
| `app.oam.dev/component` | Component name |
|
||||
| `trait.oam.dev/resource` | `outputs.\<resource type\>`in Trait |
|
||||
| `app.oam.dev/appRevision` | Application Revision Name |
|
||||
|
||||
## X-Definition Runtime Context
|
||||
|
||||
In the X-Definition, some runtime context information can be obtained through the `context` variable. The specific list is as follows, where the scope indicates which module definitions the Context variable can be used in:
|
||||
|
||||
| Context Variable | Description | Scope |
|
||||
| :------------------------------: | :------------------------------------------------------------------------------: | :----------------------------------: |
|
||||
| `context.appRevision` | The app version name corresponding to the current instance of the application | ComponentDefinition, TraitDefinition |
|
||||
| `context.appRevisionNum` | The app version number corresponding to the current instance of the application. | ComponentDefinition, TraitDefinition |
|
||||
| `context.appName` | The app name corresponding to the current instance of the application. | ComponentDefinition, TraitDefinition |
|
||||
| `context.name` | component name in ComponentDefinition and TraitDefinition，policy in PolicyDefinition | ComponentDefinition, TraitDefinition, PolicyDefinition |
|
||||
| `context.namespace` | The namespace of the current instance of the application | ComponentDefinition, TraitDefinition |
|
||||
| `context.revision` | The version name of the current component instance | ComponentDefinition, TraitDefinition |
|
||||
| `context.parameter` | The parameters of the current component instance, it can be obtained in the trait | TraitDefinition |
|
||||
| `context.output` | Object structure after instantiation of current component | ComponentDefinition, TraitDefinition |
|
||||
| `context.outputs.<resourceName>` | Structure after instantiation of current component and trait | ComponentDefinition, TraitDefinition |
|
||||
|
||||
At the same time, in the Workflow system, because the `context` has to act on the application level, it is very different from the above usage. We introduce it separately:
|
||||
|
||||
| Context Variable | Description | Scope |
|
||||
| :------------------------------: | :------------------------------------------------------------------------------: | :----------------------------------: |
|
||||
| `context.name` | The name of the current instance of the application | WorkflowStepDefinition |
|
||||
| `context.namespace` | The namespace of the current instance of the application | WorkflowStepDefinition |
|
||||
| `context.labels` | The labels of the current instance of the application | WorkflowStepDefinition |
|
||||
| `context.annotations` | The annotations of the current instance of the application | WorkflowStepDefinition |
|
||||
|
||||
|
||||
Please note that all the X-Definition concepts introduced in this section only need to be understood by the platform administrator when they want to expand the functions of KubeVela, and end users do not need to have any perception of these concepts.
|
||||
|
||||
[1]: ./oam-model
|
||||
[2]: ../cue/basic
|
||||
[3]: ../kube/component
|
||||
[4]: ../traits/customize-trait
|
||||
[5]: ../traits/advanced.md
|
||||
[6]: https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/
|
||||
[7]: ../cue/basic.md
|
||||
|
|
@ -402,7 +402,6 @@ spec:
|
|||
name: <工作负载定义对应的 Kubernetes 资源>
|
||||
version: <工作负载定义对应的 Kubernetes 资源版本>
|
||||
podSpecPath: <工作负载中 Pod 字段的路径>
|
||||
revisionLabel: <工作负载中可以明确版本的标签>
|
||||
childResourceKinds:
|
||||
- apiVersion: <资源组>
|
||||
kind: <资源类型>
|
||||
|
|
@ -436,9 +435,9 @@ spec:
|
|||
|
||||
| Context 变量 | 功能描述 | 作用范围 |
|
||||
| :------------------------------: | :------------------------------------------------------------------------------: | :----------------------------------: |
|
||||
| `context.appRevision` | 应用当前的实例对应的版本名称。 | 组件定义、运维特征定义 |
|
||||
| `context.appRevisionNum` | 应用当前的实例对应的版本数字。 | 组件定义、运维特征定义 |
|
||||
| `context.appName` | 应用当前的实例对应的名称。 | 组件定义、运维特征定义 |
|
||||
| `context.appRevision` | 应用当前的实例对应的版本名称 | 组件定义、运维特征定义 |
|
||||
| `context.appRevisionNum` | 应用当前的实例对应的版本数字 | 组件定义、运维特征定义 |
|
||||
| `context.appName` | 应用当前的实例对应的名称 | 组件定义、运维特征定义 |
|
||||
| `context.name` | 在组件定义和运维特征定义中表示的是组件名称，在应用策略定义中表示的是应用策略名称 | 组件定义、运维特征定义、应用策略定义 |
|
||||
| `context.namespace` | 应用当前实例所在的命名空间 | 组件定义、运维特征定义 |
|
||||
| `context.revision` | 当前组件实例的版本名称 | 组件定义、运维特征定义 |
|
||||
|
|
@ -446,6 +445,14 @@ spec:
|
|||
| `context.output` | 当前组件实例化后的对象结构体 | 组件定义、运维特征定义 |
|
||||
| `context.outputs.<resourceName>` | 当前组件和运维特征实例化以后的结构体 | 组件定义、运维特征定义 |
|
||||
|
||||
同时，在工作流系统当中，由于 `context` 要作用于应用级，与上述用法有很大不同。我们单独对其进行介绍：
|
||||
|
||||
| Context 变量 | 功能描述 | 作用范围 |
|
||||
| :------------------------------: | :------------------------------------------------------------------------------: | :----------------------------------: |
|
||||
| `context.name` | 应用当前实例对应的名称 | 工作流节点定义 |
|
||||
| `context.namespace` | 应用当前实例所在的命名空间 | 工作流节点定义 |
|
||||
| `context.labels` | 应用当前实例的标签 | 工作流节点定义 |
|
||||
| `context.annotations` | 应用当前实例的注释 | 工作流节点定义 |
|
||||
|
||||
最后请注意，在本节介绍的所有的模块化定义概念，都只需要平台的管理员在希望对 KubeVela 进行功能扩展时了解，最终用户对这些概念不需要有任何感知。
|
||||
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 75 KiB |
10
sidebars.js
10
sidebars.js
|
|
@ -123,11 +123,11 @@ module.exports = {
|
|||
'platform-engineers/cue/advanced',
|
||||
]
|
||||
},
|
||||
{
|
||||
'Environment System': [
|
||||
'platform-engineers/initializer/basic-initializer',
|
||||
]
|
||||
},
|
||||
// {
|
||||
// 'Environment System': [
|
||||
// 'platform-engineers/initializer/basic-initializer',
|
||||
// ]
|
||||
// },
|
||||
{
|
||||
'Addons': [
|
||||
'end-user/addons/introduction',
|
||||
|
|
|
|||
Loading…
Reference in New Issue