Chore: clean up some docs
Signed-off-by: Jianbo Sun <jianbo.sjb@alibaba-inc.com>
This commit is contained in:
Jianbo Sun
parent
0fdeff0642
commit
0a6f4a76db
|
|
@ -145,6 +145,3 @@ Version: 0.1.2
|
|||
|
||||
Refer to the [blog post](/blog/2021/09/02/kubevela-jenkins-cicd) for more details about deploying Jenkins + KubeVela and more comprehensive demo for application rolling update.
|
||||
|
||||
## Next Step
|
||||
|
||||
- Learn how to do [GitOps](./gitops) with KubeVela.
|
||||
|
|
|
|||
|
|
@ -1,10 +0,0 @@
|
|||
---
|
||||
title: Restful API
|
||||
---
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl';
|
||||
|
||||
<a
|
||||
target="_blank"
|
||||
href={useBaseUrl('/restful-api')}>
|
||||
KubeVela Restful API
|
||||
</a>
|
||||
|
|
@ -2,322 +2,7 @@
|
|||
title: Definition Objects
|
||||
---
|
||||
|
||||
This documentation explains `ComponentDefinition` and `TraitDefinition` in detail.
|
||||
|
||||
## Overview
|
||||
|
||||
Essentially, a definition object in KubeVela is a programmable build block. A definition object normally includes several information to model a certain platform capability that would used in further application deployment:
|
||||
- **Capability Indicator**
|
||||
- `ComponentDefinition` uses `spec.workload` to indicate the workload type of this component.
|
||||
- `TraitDefinition` uses `spec.definitionRef` to indicate the provider of this trait.
|
||||
- **Interoperability Fields**
|
||||
- they are for the platform to ensure a trait can work with given workload type. Hence only `TraitDefinition` has these fields.
|
||||
- **Capability Encapsulation and Abstraction** defined by `spec.schematic`
|
||||
- this defines the **templating and parametering** (i.e. encapsulation) of this capability.
|
||||
|
||||
Hence, the basic structure of definition object is as below:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: XxxDefinition
|
||||
metadata:
|
||||
name: <definition name>
|
||||
spec:
|
||||
...
|
||||
schematic:
|
||||
cue:
|
||||
# cue template ...
|
||||
helm:
|
||||
# Helm chart ...
|
||||
# ... interoperability fields
|
||||
```
|
||||
|
||||
Let's explain these fields one by one.
|
||||
|
||||
### Capability Indicator
|
||||
|
||||
In `ComponentDefinition`, the indicator of workload type is declared as `spec.workload`.
|
||||
|
||||
Below is a definition for *Web Service* in KubeVela:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
metadata:
|
||||
name: webservice
|
||||
namespace: default
|
||||
annotations:
|
||||
definition.oam.dev/description: "Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers."
|
||||
spec:
|
||||
workload:
|
||||
definition:
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
...
|
||||
```
|
||||
|
||||
In above example, it claims to leverage Kubernetes Deployment (`apiVersion: apps/v1`, `kind: Deployment`) as the workload type for component.
|
||||
|
||||
### Interoperability Fields
|
||||
|
||||
The interoperability fields are **trait only**. An overall view of interoperability fields in a `TraitDefinition` is show as below.
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: TraitDefinition
|
||||
metadata:
|
||||
name: ingress
|
||||
spec:
|
||||
appliesToWorkloads:
|
||||
- deployments.apps
|
||||
conflictsWith:
|
||||
- service
|
||||
workloadRefPath: spec.workloadRef
|
||||
podDisruptive: false
|
||||
```
|
||||
|
||||
Let's explain them in detail.
|
||||
|
||||
#### `.spec.appliesToWorkloads`
|
||||
|
||||
This field defines the constraints that what kinds of workloads this trait is allowed to apply to.
|
||||
- It accepts an array of string as value.
|
||||
- Each item in the array refers to one or a group of workload types to which this trait is allowed to apply.
|
||||
|
||||
There are three approaches to denote one or a group of workload types.
|
||||
|
||||
- `ComponentDefinition` definition reference (CRD name), e.g., `deployments.apps`
|
||||
- Resource group of `ComponentDefinition` definition reference prefixed with `*.`, e.g., `*.apps`, `*.oam.dev`. This means the trait is allowed to apply to any workloads in this group.
|
||||
- `*` means this trait is allowed to apply to any workloads
|
||||
|
||||
If this field is omitted, it means this trait is allowed to apply to any workload types.
|
||||
|
||||
KubeVela will raise an error if a trait is applied to a workload type which is NOT included in the `appliesToWorkloads`.
|
||||
This documentation has been merged into [Definition Protocol](./oam/x-definition).
|
||||
|
||||
|
||||
##### `.spec.conflictsWith`
|
||||
|
||||
This field defines that constraints that what kinds of traits are conflicting with this trait, if they are applied to the same workload.
|
||||
- It accepts an array of string as value.
|
||||
- Each item in the array refers to one or a group of traits.
|
||||
|
||||
There are four approaches to denote one or a group of workload types.
|
||||
|
||||
- `TraitDefinition` name, e.g., `ingress`
|
||||
- Resource group of `TraitDefinition` definition reference prefixed with `*.`, e.g., `*.networking.k8s.io`. This means the trait is conflicting with any traits in this group.
|
||||
- `*` means this trait is conflicting with any other trait.
|
||||
|
||||
If this field is omitted, it means this trait is NOT conflicting with any traits.
|
||||
|
||||
##### `.spec.workloadRefPath`
|
||||
|
||||
This field defines the field path of the trait which is used to store the reference of the workload to which the trait is applied.
|
||||
- It accepts a string as value, e.g., `spec.workloadRef`.
|
||||
|
||||
If this field is set, KubeVela core will automatically fill the workload reference into target field of the trait. Then the trait controller can get the workload reference from the trait latter. So this field usually accompanies with the traits whose controllers relying on the workload reference at runtime.
|
||||
|
||||
Please check [scaler](https://github.com/kubevela/kubevela/blob/master/charts/vela-core/templates/defwithtemplate/scaler.yaml) trait as a demonstration of how to set this field.
|
||||
|
||||
##### `.spec.podDisruptive`
|
||||
|
||||
This field defines that adding/updating the trait will disruptive the pod or not.
|
||||
In this example, the answer is not, so the field is `false`, it will not affect the pod when the trait is added or updated.
|
||||
If the field is `true`, then it will cause the pod to disruptive and restart when the trait is added or updated.
|
||||
By default, the value is `false` which means this trait will not affect.
|
||||
Please take care of this field, it's really important and useful for serious large scale production usage scenarios.
|
||||
|
||||
### Capability Encapsulation and Abstraction
|
||||
|
||||
The programmable template of given capability are defined in `spec.schematic` field. For example, below is the full definition of *Web Service* type in KubeVela:
|
||||
|
||||
<details>
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
metadata:
|
||||
name: webservice
|
||||
namespace: default
|
||||
annotations:
|
||||
definition.oam.dev/description: "Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers."
|
||||
spec:
|
||||
workload:
|
||||
definition:
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
schematic:
|
||||
cue:
|
||||
template: |
|
||||
output: {
|
||||
apiVersion: "apps/v1"
|
||||
kind: "Deployment"
|
||||
spec: {
|
||||
selector: matchLabels: {
|
||||
"app.oam.dev/component": context.name
|
||||
}
|
||||
|
||||
template: {
|
||||
metadata: labels: {
|
||||
"app.oam.dev/component": context.name
|
||||
}
|
||||
|
||||
spec: {
|
||||
containers: [{
|
||||
name: context.name
|
||||
image: parameter.image
|
||||
|
||||
if parameter["cmd"] != _|_ {
|
||||
command: parameter.cmd
|
||||
}
|
||||
|
||||
if parameter["env"] != _|_ {
|
||||
env: parameter.env
|
||||
}
|
||||
|
||||
if context["config"] != _|_ {
|
||||
env: context.config
|
||||
}
|
||||
|
||||
ports: [{
|
||||
containerPort: parameter.port
|
||||
}]
|
||||
|
||||
if parameter["cpu"] != _|_ {
|
||||
resources: {
|
||||
limits:
|
||||
cpu: parameter.cpu
|
||||
requests:
|
||||
cpu: parameter.cpu
|
||||
}
|
||||
}
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
parameter: {
|
||||
// +usage=Which image would you like to use for your service
|
||||
// +short=i
|
||||
image: string
|
||||
|
||||
// +usage=Commands to run in the container
|
||||
cmd?: [...string]
|
||||
|
||||
// +usage=Which port do you want customer traffic sent to
|
||||
// +short=p
|
||||
port: *80 | int
|
||||
// +usage=Define arguments by using environment variables
|
||||
env?: [...{
|
||||
// +usage=Environment variable name
|
||||
name: string
|
||||
// +usage=The value of the environment variable
|
||||
value?: string
|
||||
// +usage=Specifies a source the value of this var should come from
|
||||
valueFrom?: {
|
||||
// +usage=Selects a key of a secret in the pod's namespace
|
||||
secretKeyRef: {
|
||||
// +usage=The name of the secret in the pod's namespace to select from
|
||||
name: string
|
||||
// +usage=The key of the secret to select from. Must be a valid secret key
|
||||
key: string
|
||||
}
|
||||
}
|
||||
}]
|
||||
// +usage=Number of CPU units for the service, like `0.5` (0.5 CPU core), `1` (1 CPU core)
|
||||
cpu?: string
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
The specification of `schematic` is explained in following CUE and Helm specific documentations.
|
||||
|
||||
Also, the `schematic` filed enables you to render UI forms directly based on them, please check the [Generate Forms from Definitions](openapi-v3-json-schema) section about how to.
|
||||
|
||||
## Definition Revisions
|
||||
|
||||
In KubeVela, definition entities are mutable. Each time a `ComponentDefinition` or `TraitDefinition` is updated, a corresponding `DefinitionRevision` will be generated to snapshot this change. Hence, KubeVela allows user to reference a specific revision of definition to declare an application.
|
||||
|
||||
For example, we can design a new parameter named `args` for the `webservice` component definition by applying a new definition with same name as below.
|
||||
|
||||
```shell
|
||||
vela show webservice
|
||||
```
|
||||
```console
|
||||
# Properties
|
||||
+-------+----------------------------------------------------+----------+----------+---------+
|
||||
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
|
||||
+-------+----------------------------------------------------+----------+----------+---------+
|
||||
| cmd | Commands to run in the container | []string | false | |
|
||||
... // skip
|
||||
```
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubevela/kubevela/master/docs/examples/definition-revision/webservice-v2.yaml
|
||||
```
|
||||
|
||||
The change will take effect immediately.
|
||||
|
||||
```shell
|
||||
vela show webservice
|
||||
```
|
||||
```console
|
||||
# Properties
|
||||
+-------+----------------------------------------------------+----------+----------+---------+
|
||||
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
|
||||
+-------+----------------------------------------------------+----------+----------+---------+
|
||||
| cmd | Commands to run in the container | []string | false | |
|
||||
| args | Arguments to the cmd | []string | false | |
|
||||
... // skip
|
||||
```
|
||||
|
||||
We will see a new definition revision will be automatically generated, `v2` is the latest version, `v1` is the previous one.
|
||||
|
||||
```shell
|
||||
kubectl get definitionrevision -l="componentdefinition.oam.dev/name=webservice" -n vela-system
|
||||
```
|
||||
```console
|
||||
NAME REVISION HASH TYPE
|
||||
webservice-v1 1 3f6886d9832021ba Component
|
||||
webservice-v2 2 b3b9978e7164d973 Component
|
||||
```
|
||||
|
||||
### Specify Definition Revision in Application
|
||||
|
||||
Users can specify the revision with `@version` approach, for example, if a user want to stick to using the `v1` revision of `webservice` component:
|
||||
|
||||
```yaml
|
||||
# testapp.yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: testapp
|
||||
spec:
|
||||
components:
|
||||
- name: server
|
||||
type: webservice@v1
|
||||
properties:
|
||||
image: foo
|
||||
cmd:
|
||||
- sleep
|
||||
- '1000'
|
||||
```
|
||||
If no revision is specified, KubeVela will always use the latest revision for a given component definition.
|
||||
|
||||
```yaml
|
||||
# testapp.yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: testapp
|
||||
spec:
|
||||
components:
|
||||
- name: server
|
||||
type: webservice # type: webservice@v2
|
||||
properties:
|
||||
image: foo
|
||||
cmd:
|
||||
- sleep
|
||||
- '1000'
|
||||
args:
|
||||
- wait
|
||||
```
|
||||
The definition revision part has been migrated to [here](./x-def-version).
|
||||
|
|
|
|||
|
|
@ -6,6 +6,36 @@ KubeVela is fully programmable via [CUE](https://cuelang.org), while it leverage
|
|||
|
||||
You can [manage the definition](../cue/definition-edit) in CUE and the `vela def` command will render it into Kubernetes API with the following protocol.
|
||||
|
||||
## Overview
|
||||
|
||||
Essentially, a definition object in KubeVela is a programmable building block. A definition object normally includes several information to model a certain platform capability that would used in further application deployment:
|
||||
- **Capability Indicator**
|
||||
- `ComponentDefinition` uses `spec.workload` to indicate the workload type of this component.
|
||||
- `TraitDefinition` uses `spec.definition` to indicate the provider of this trait.
|
||||
- These indicators can be auto detected, so they're not necessary.
|
||||
- **Interoperability Fields**
|
||||
- they are for the platform to ensure a trait can work with given workload type. Hence only `TraitDefinition` has these fields.
|
||||
- **Capability Encapsulation and Abstraction** defined by `spec.schematic`
|
||||
- this defines the **templating and parametering** (i.e. encapsulation) of this capability.
|
||||
|
||||
Hence, the basic structure of definition object is as below:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: XxxDefinition
|
||||
metadata:
|
||||
name: <definition name>
|
||||
spec:
|
||||
...
|
||||
schematic:
|
||||
cue:
|
||||
# cue template ...
|
||||
helm:
|
||||
# Helm chart ...
|
||||
# ... interoperability fields
|
||||
```
|
||||
|
||||
Let's explain them one by one.
|
||||
|
||||
## ComponentDefinition
|
||||
|
||||
|
|
@ -25,7 +55,7 @@ metadata:
|
|||
annotations:
|
||||
definition.oam.dev/description: <Function description>
|
||||
spec:
|
||||
workload: # Workload description
|
||||
workload: # Workload Capability Indicator
|
||||
definition:
|
||||
apiVersion: <Kubernetes Workload resource group>
|
||||
kind: <Kubernetes Workload types>
|
||||
|
|
@ -33,7 +63,32 @@ spec:
|
|||
cue: # Details of components defined by CUE language
|
||||
template: <CUE format template>
|
||||
```
|
||||
Here is a complete example to introduce how to use ComponentDefinition.
|
||||
|
||||
The indicator of workload type is declared as `spec.workload`.
|
||||
|
||||
Below is a definition for *Web Service* in KubeVela:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
metadata:
|
||||
name: webservice
|
||||
namespace: default
|
||||
annotations:
|
||||
definition.oam.dev/description: "Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers."
|
||||
spec:
|
||||
workload:
|
||||
definition:
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
...
|
||||
```
|
||||
|
||||
In above example, it claims to leverage Kubernetes Deployment (`apiVersion: apps/v1`, `kind: Deployment`) as the workload type for component.
|
||||
|
||||
The programmable template of given capability are defined in `spec.schematic` field. For example, below is the full definition of *Helm* type in KubeVela:
|
||||
|
||||
<details>
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
|
|
@ -135,6 +190,9 @@ spec:
|
|||
...
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
The specification of `schematic` is explained in the [CUE with KubeVela](../cue/basic) documentations.
|
||||
|
||||
## TraitDefinition
|
||||
|
||||
|
|
@ -168,6 +226,56 @@ spec:
|
|||
template: <CUE format template>
|
||||
```
|
||||
|
||||
The interoperability fields are **trait only**. Let's explain them in detail.
|
||||
|
||||
### `.spec.appliesToWorkloads`
|
||||
|
||||
This field defines the constraints that what kinds of workloads this trait is allowed to apply to.
|
||||
- It accepts an array of string as value.
|
||||
- Each item in the array refers to one or a group of workload types to which this trait is allowed to apply.
|
||||
|
||||
There are three approaches to denote one or a group of workload types.
|
||||
|
||||
- `ComponentDefinition` definition reference (CRD name), e.g., `deployments.apps`
|
||||
- Resource group of `ComponentDefinition` definition reference prefixed with `*.`, e.g., `*.apps`, `*.oam.dev`. This means the trait is allowed to apply to any workloads in this group.
|
||||
- `*` means this trait is allowed to apply to any workloads
|
||||
|
||||
If this field is omitted, it means this trait is allowed to apply to any workload types.
|
||||
|
||||
KubeVela will raise an error if a trait is applied to a workload type which is NOT included in the `appliesToWorkloads`.
|
||||
|
||||
|
||||
### `.spec.conflictsWith`
|
||||
|
||||
This field defines that constraints that what kinds of traits are conflicting with this trait, if they are applied to the same workload.
|
||||
- It accepts an array of string as value.
|
||||
- Each item in the array refers to one or a group of traits.
|
||||
|
||||
There are four approaches to denote one or a group of workload types.
|
||||
|
||||
- `TraitDefinition` name, e.g., `ingress`
|
||||
- Resource group of `TraitDefinition` definition reference prefixed with `*.`, e.g., `*.networking.k8s.io`. This means the trait is conflicting with any traits in this group.
|
||||
- `*` means this trait is conflicting with any other trait.
|
||||
|
||||
If this field is omitted, it means this trait is NOT conflicting with any traits.
|
||||
|
||||
### `.spec.workloadRefPath`
|
||||
|
||||
This field defines the field path of the trait which is used to store the reference of the workload to which the trait is applied.
|
||||
- It accepts a string as value, e.g., `spec.workloadRef`.
|
||||
|
||||
If this field is set, KubeVela core will automatically fill the workload reference into target field of the trait. Then the trait controller can get the workload reference from the trait latter. So this field usually accompanies with the traits whose controllers relying on the workload reference at runtime.
|
||||
|
||||
Please check [scaler](https://github.com/kubevela/kubevela/blob/master/charts/vela-core/templates/defwithtemplate/scaler.yaml) trait as a demonstration of how to set this field.
|
||||
|
||||
### `.spec.podDisruptive`
|
||||
|
||||
This field defines that adding/updating the trait will disruptive the pod or not.
|
||||
In this example, the answer is not, so the field is `false`, it will not affect the pod when the trait is added or updated.
|
||||
If the field is `true`, then it will cause the pod to disruptive and restart when the trait is added or updated.
|
||||
By default, the value is `false` which means this trait will not affect.
|
||||
Please take care of this field, it's really important and useful for serious large scale production usage scenarios.
|
||||
|
||||
Let's look at a practical example:
|
||||
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -2,6 +2,8 @@
|
|||
title: Version Control for Definition
|
||||
---
|
||||
|
||||
> A better version control management is comming in v1.5, refer to [this issue](https://github.com/kubevela/kubevela/issues/4131) to learn the progress.
|
||||
|
||||
When the capabilities(Component or Trait) changes, KubeVela will generate a definition revision automatically.
|
||||
|
||||
* Check ComponentDefinition Revision
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ $ vela addon disable kruise-rollout
|
|||
|
||||
## Usage
|
||||
|
||||
Kurise rollout addon help to canary rollout your workload no matter defined with [webservice](../../end-user/components/cue/webservice) or contained in a [helm](../../tutorials/helm).
|
||||
Kurise rollout addon help to canary rollout your workload no matter defined with [webservice](../../tutorials/webservice) or contained in a [helm](../../tutorials/helm).
|
||||
|
||||
If your workload is in a helm chart please refer to [doc](../../tutorials/helm-rollout) for more usage info, otherwise please refer to usage of webservice [component](../../end-user/traits/rollout).
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ This section will introduce how to use Rollout Trait to perform a rolling update
|
|||
|
||||
The component supported for rollout is:
|
||||
|
||||
* [webservice](../../end-user/components/cue/webservice)
|
||||
* webservice
|
||||
* worker
|
||||
|
||||
## How to
|
||||
|
|
|
|||
|
|
@ -2,237 +2,7 @@
|
|||
title: 定义CRD
|
||||
---
|
||||
|
||||
在本部分中，我们会对 `ComponentDefinition` 和 `TraitDefinition` 进行详细介绍。
|
||||
This documentation has been merged into [Definition Protocol](./oam/x-definition).
|
||||
|
||||
> 所有的定义对象都应由平台团队来进行维护和安装。在此背景下，可以把平台团队理解为平台中的*能力提供者*。
|
||||
|
||||
## 概述
|
||||
|
||||
本质上，KubeVela 中的定义对象由三个部分组成：
|
||||
|
||||
- **能力指示器 （Capability Indicator）**
|
||||
- `ComponentDefinition` 使用 `spec.workload` 指出此组件的 workload 类型.
|
||||
- `TraitDefinition` 使用 `spec.definitionRef` 指出此 trait 的提供者。
|
||||
- **互操作字段 （Interoperability Fields）**
|
||||
- 他们是为平台所设计的，用来确保给定的 workload 类型可以和某个 trait 一起工作。因此只有 `TraitDefinition` 有这些字段。
|
||||
- **能力封装和抽象 （Capability Encapsulation and Abstraction）** （由 `spec.schematic` 定义）
|
||||
- 它定义了此 capability 的**模板和参数** ，比如封装。
|
||||
|
||||
因此，定义对象的基本结构如下所示：
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: XxxDefinition
|
||||
metadata:
|
||||
name: <definition name>
|
||||
spec:
|
||||
...
|
||||
schematic:
|
||||
cue:
|
||||
# cue template ...
|
||||
helm:
|
||||
# Helm chart ...
|
||||
# ... interoperability fields
|
||||
```
|
||||
|
||||
我们接下来详细解释每个字段。
|
||||
|
||||
### 能力指示器 （Capability Indicator）
|
||||
|
||||
在 `ComponentDefinition` 中，workload 类型的指示器被声明为 `spec.workload`
|
||||
|
||||
下面的示例是在 KubeVela 中，一个给 *Web Service* 的定义：
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
metadata:
|
||||
name: webservice
|
||||
namespace: default
|
||||
annotations:
|
||||
definition.oam.dev/description: "Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers."
|
||||
spec:
|
||||
workload:
|
||||
definition:
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
...
|
||||
```
|
||||
|
||||
在上面的示例中，它声称利用 Kubernetes 的 Deployment （`apiVersion: apps/v1`, `kind: Deployment`）作为组件的 workload 类型。
|
||||
|
||||
### 互操作字段 （Interoperability Fields）
|
||||
|
||||
**只有 trait** 有互操作字段。在一个 `TraitDefinition` 中，互操作字段的大体示例如下所示：
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: TraitDefinition
|
||||
metadata:
|
||||
name: ingress
|
||||
spec:
|
||||
appliesToWorkloads:
|
||||
- deployments.apps
|
||||
- webservice
|
||||
conflictsWith:
|
||||
- service
|
||||
workloadRefPath: spec.workloadRef
|
||||
podDisruptive: false
|
||||
```
|
||||
|
||||
我们来详细解释一下。
|
||||
|
||||
#### `.spec.appliesToWorkloads`
|
||||
|
||||
该字段定义了此 trait 允许应用于哪些类型的 workload 的约束。
|
||||
|
||||
- 它使用一个字符串的数组作为其值。
|
||||
- 数组中的每一个元素指向允许应用此 trait 的一个或一组 workload 类型。
|
||||
|
||||
有四种来表示一个或者一组 workload 类型。
|
||||
|
||||
- `ComponentDefinition` 命名， 例如 `webservice`， `worker`
|
||||
- `ComponentDefinition` 定义引用（CRD 命名），例如 `deployments.apps`
|
||||
- 以`*.`为前缀的 `ComponentDefinition` 定义引用的资源组，例如`*.apps` 和 `*.oam.dev`。这表示 trait 被允许应用于该组中的任意 workload。
|
||||
- `*` 表示 trait 被允许应用于任意 workload。
|
||||
|
||||
如果省略此字段，则表示该 trait 允许应用于任意 workload 类型。
|
||||
|
||||
如果将一个 trait 应用于未包含在 `appliesToWorkloads` 中的 workload，KubeVela 将会报错。
|
||||
|
||||
##### `.spec.conflictsWith`
|
||||
|
||||
如果将某些种类的 trait 应用于该 workload，该字段定义了其中哪些 trait 与该 trait 冲突的约束。
|
||||
|
||||
- 它使用一个字符串的数组作为其值。
|
||||
- 数组中的每一个元素指向一个或一组 trait。
|
||||
|
||||
有四种来表示一个或者一组 workload 类型。
|
||||
|
||||
- `TraitDefinition` 命名，比如 `ingress`
|
||||
- 以`*.`为前缀的 `TraitDefinition` 定义引用的资源组，例如`*.networking.k8s.io`。这表示当前 trait 与该组中的任意 trait 相冲突。
|
||||
- `*` 表示当前 trait 与任意 trait 相冲突。
|
||||
|
||||
如果省略此字段，则表示该 trait 没有和其他任何 trait 相冲突。
|
||||
|
||||
##### `.spec.workloadRefPath`
|
||||
|
||||
该字段定义 trait 的字段路径，该路径用于存储对其应用 trait 的 workload 的引用。
|
||||
|
||||
- 它使用一个字符串作为其值，比如 `spec.workloadRef`.
|
||||
|
||||
如果设置了此字段，KubeVela core 会自动将 workload 引用填充到 trait 的目标字段中。然后，trait controller 可以之后从 trait 中获取 workload 引用。因此，此字段通常和 trait 一起出现，其 controller 在运行时依赖于 workload 引用。
|
||||
|
||||
如何设置此字段的具体细节，请查阅 [scaler](https://github.com/kubevela/kubevela/blob/master/charts/vela-core/templates/defwithtemplate/manualscale.yaml) trait 作为演示。
|
||||
|
||||
##### `.spec.podDisruptive`
|
||||
|
||||
此字段定义了添加或者更新 trait 会不会破坏 pod。在此示例中，因为答案是不会，所以该字段为 `false`，当添加或更新 trait 时，它不会影响 pod。如果此字段是 `true`，则它会导致 pod 在 trait 被添加或者更新时被破坏并重启。默认情况下，该值为 `false`，这意味着该 trait 不会影响 pod。请小心处理此字段。对于严肃的大规模生产使用场景而言，它非常重要和有用。
|
||||
|
||||
### 能力封装和抽象 （Capability Encapsulation and Abstraction）
|
||||
|
||||
给定的能力的模板和封装被定义在 `spec.schematic` 字段中。如下所示范例是一个 KubeVela 中的*Web Service* 类型的完整定义：
|
||||
|
||||
<details>
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
metadata:
|
||||
name: webservice
|
||||
namespace: default
|
||||
annotations:
|
||||
definition.oam.dev/description: "Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers."
|
||||
spec:
|
||||
workload:
|
||||
definition:
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
schematic:
|
||||
cue:
|
||||
template: |
|
||||
output: {
|
||||
apiVersion: "apps/v1"
|
||||
kind: "Deployment"
|
||||
spec: {
|
||||
selector: matchLabels: {
|
||||
"app.oam.dev/component": context.name
|
||||
}
|
||||
|
||||
template: {
|
||||
metadata: labels: {
|
||||
"app.oam.dev/component": context.name
|
||||
}
|
||||
|
||||
spec: {
|
||||
containers: [{
|
||||
name: context.name
|
||||
image: parameter.image
|
||||
|
||||
if parameter["cmd"] != _|_ {
|
||||
command: parameter.cmd
|
||||
}
|
||||
|
||||
if parameter["env"] != _|_ {
|
||||
env: parameter.env
|
||||
}
|
||||
|
||||
if context["config"] != _|_ {
|
||||
env: context.config
|
||||
}
|
||||
|
||||
ports: [{
|
||||
containerPort: parameter.port
|
||||
}]
|
||||
|
||||
if parameter["cpu"] != _|_ {
|
||||
resources: {
|
||||
limits:
|
||||
cpu: parameter.cpu
|
||||
requests:
|
||||
cpu: parameter.cpu
|
||||
}
|
||||
}
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
parameter: {
|
||||
// +usage=Which image would you like to use for your service
|
||||
// +short=i
|
||||
image: string
|
||||
|
||||
// +usage=Commands to run in the container
|
||||
cmd?: [...string]
|
||||
|
||||
// +usage=Which port do you want customer traffic sent to
|
||||
// +short=p
|
||||
port: *80 | int
|
||||
// +usage=Define arguments by using environment variables
|
||||
env?: [...{
|
||||
// +usage=Environment variable name
|
||||
name: string
|
||||
// +usage=The value of the environment variable
|
||||
value?: string
|
||||
// +usage=Specifies a source the value of this var should come from
|
||||
valueFrom?: {
|
||||
// +usage=Selects a key of a secret in the pod's namespace
|
||||
secretKeyRef: {
|
||||
// +usage=The name of the secret in the pod's namespace to select from
|
||||
name: string
|
||||
// +usage=The key of the secret to select from. Must be a valid secret key
|
||||
key: string
|
||||
}
|
||||
}
|
||||
}]
|
||||
// +usage=Number of CPU units for the service, like `0.5` (0.5 CPU core), `1` (1 CPU core)
|
||||
cpu?: string
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
`schematic` 的技术规范在接下来的 CUE 和 Helm 相关的文档中有详细解释。
|
||||
|
||||
同时，`schematic` 字段使你可以直接根据他们来渲染UI表单。详细操作请见[从定义中生成表单](/docs/platform-engineers/openapi-v3-json-schema)部分。
|
||||
The definition revision part has been migrated to [here](./x-def-version).
|
||||
|
|
|
|||
|
|
@ -8,6 +8,36 @@ KubeVela 是完全可编程的，它可以轻松的根据你的需求实现原
|
|||
|
||||
当前 OAM 模型支持的模块定义（X-Definition）包括组件定义（ComponentDefinition），运维特征定义（TraitDefinition）、应用策略定义（PolicyDefinition），工作流节点定义（WorkflowStepDefinition）等，随着系统演进，OAM 模型未来可能会根据场景需要进一步增加新的模块定义。
|
||||
|
||||
## 概述
|
||||
|
||||
本质上，KubeVela 中的定义对象由三个部分组成：
|
||||
|
||||
- **能力指示器 （Capability Indicator）**
|
||||
- `ComponentDefinition` 使用 `spec.workload` 指出此组件的 workload 类型.
|
||||
- `TraitDefinition` 使用 `spec.definition` 指出此 trait 的提供者。
|
||||
- **互操作字段 （Interoperability Fields）**
|
||||
- 他们是为平台所设计的，用来确保给定的 workload 类型可以和某个 trait 一起工作。因此只有 `TraitDefinition` 有这些字段。
|
||||
- **能力封装和抽象 （Capability Encapsulation and Abstraction）** （由 `spec.schematic` 定义）
|
||||
- 它定义了此 capability 的**模板和参数** ，比如封装。
|
||||
|
||||
因此，定义对象的基本结构如下所示：
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: XxxDefinition
|
||||
metadata:
|
||||
name: <definition name>
|
||||
spec:
|
||||
...
|
||||
schematic:
|
||||
cue:
|
||||
# cue template ...
|
||||
helm:
|
||||
# Helm chart ...
|
||||
# ... interoperability fields
|
||||
```
|
||||
|
||||
我们接下来详细解释每一种类型。
|
||||
|
||||
## 组件定义（ComponentDefinition）
|
||||
|
||||
|
|
@ -60,6 +90,8 @@ spec:
|
|||
|
||||
具体抽象方式和交付方式的编写可以查阅对应的文档，这里以一个完整的例子介绍组件定义的工作流程。
|
||||
|
||||
<detail>
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
|
|
@ -160,6 +192,7 @@ spec:
|
|||
...
|
||||
}
|
||||
```
|
||||
</detail>
|
||||
|
||||
如上所示，这个组件定义的名字叫 `helm`，一经注册，最终用户在 Application 的组件类型（`components[*].type`）字段就可以填写这个类型。
|
||||
|
||||
|
|
@ -204,15 +237,33 @@ spec:
|
|||
|
||||
从上述运维特征的格式和功能中我们可以看到，运维特征定义提供了一系列运维能力和组件之间衔接的方式，使得相同功能的运维功能可以适配到不同的组件中。具体的字段功能如下所示：
|
||||
|
||||
* 运维特征能够适配的工作负载名称列表（`.spec.appliesToWorkloads`）,可缺省字段，字符串数组类型，申明这个运维特征可以用于的工作负载类型，填写的是工作负载的 CRD 名称，格式为 `<resources>.<api-group>`
|
||||
* 与该运维特征冲突的其他运维特征名称列表（`.spec.conflictsWith`）,可缺省字段，字符串数组类型，申明这个运维特征与哪些运维特征冲突，填写的是运维特征名称的列表。
|
||||
* 运维特征能够适配的工作负载名称列表（`.spec.appliesToWorkloads`）,可缺省字段，字符串数组类型，申明这个运维特征可以用于的一种或一组工作负载类型，有四种填写方法：
|
||||
- 填写工作负载的 CRD 名称，格式为 `<resources>.<api-group>`
|
||||
- 填写 `ComponentDefinition` 命名， 例如 `webservice`， `worker`
|
||||
- 以`*.`为前缀的 `ComponentDefinition` 定义引用的资源组，例如`*.apps` 和 `*.oam.dev`。这表示 trait 被允许应用于该组中的任意 workload。
|
||||
- `*` 表示 trait 被允许应用于任意 workload。
|
||||
如果省略此字段，则表示该 trait 允许应用于任意 workload 类型。
|
||||
|
||||
* 与该运维特征冲突的其他运维特征名称列表（`.spec.conflictsWith`）,可缺省字段，字符串数组类型，申明这个运维特征与哪些运维特征冲突，填写的是运维特征名称的列表。有四种来表示：
|
||||
- `TraitDefinition` 命名，比如 `ingress`
|
||||
- 以`*.`为前缀的 `TraitDefinition` 定义引用的资源组，例如`*.networking.k8s.io`。这表示当前 trait 与该组中的任意 trait 相冲突。
|
||||
- `*` 表示当前 trait 与任意 trait 相冲突。
|
||||
- 如果省略此字段，则表示该 trait 没有和其他任何 trait 相冲突。
|
||||
|
||||
* 特征描述（对应`.spec.schematic`）字段定义了具体的运维动作。目前主要通过 [`CUE`][4] 来实现，同时也包含一系列诸如[`patch-trait`][5]这样的高级用法。
|
||||
|
||||
* 运维特征对应的 Kubernetes 资源定义（`.spec.definition`字段），可缺省字段，如果运维能力通过 Kubernetes 的 CRD 方式提供可以填写，其中 `apiVersion` 和 `kind` 分别描述了背后对应的 Kubernetes 资源组和资源类型。
|
||||
|
||||
* 运维能力中对于工作负载对象的引用字段路径（`.spec.workloadRefPath`字段），可缺省字段，运维能力中如果涉及到工作负载的引用，可以填写这样一个路径地址（如操作弹性扩缩容的 [HPA][6]对象，就可以填写`spec.scaleTargetRef`），然后 KubeVela 会自动将工作负载的实例化引用注入到运维能力的实例对象中。
|
||||
|
||||
* 运维能力的参数更新会不会引起底层资源（pod）重启（`.spec.podDisruptive`字段），可缺省字段，bool 类型，主要用于向用户标识 trait 的更新会不会导致底层资源（pod）的重启。这个标识通常可以提醒用户，改动这样一个trait可能应该再结合一个灰度发布，以免大量资源重启引入服务不可用和其他风险。
|
||||
|
||||
* 是否由该运维特征管理工作负载（`.spec.manageWorkload`）,可缺省字段，bool 类型，设置为 true 则标识这个运维特征会负责工作负载的创建、更新、以及资源回收，通常是灰度发布的运维特征会具备这个能力。
|
||||
|
||||
* 该运维特征是否不计入版本变化的计算（`.spec.skipRevisionAffect`）,可缺省字段，bool 类型，设置为 true 则标识这个运维特征的修改不计入版本的变化，即用户在应用中纯粹修改这个运维特征的字段不会触发应用本身的版本变化。
|
||||
|
||||
* 运维能力是否感知组件版本的变化（`.spec.revisionEnabled`）字段，可缺省字段，bool 类型，设置为 true 表示组件会生成的资源后缀会带版本后缀。
|
||||
|
||||
* 运维能力产生的资源是否部署到管控集群（`.spec.controlPlaneOnly`）字段，可缺省字段，bool 类型，设置为 true 表示 trait 生成的资源会被部署到管控集群，即`local`
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ title: 灰度发布和扩缩容
|
|||
|
||||
目前灰度发布运维特征支持的组件类型为：
|
||||
|
||||
* [webservice](../../end-user/components/cue/webservice)
|
||||
* webservice
|
||||
* worker
|
||||
|
||||
## 如何使用
|
||||
|
|
|
|||
|
|
@ -4,53 +4,31 @@ title: 使用 FluxCD 做 GitOps
|
|||
|
||||
在本文中，我们主要讲解直接使用 KubeVela 在 GitOps 模式下进行交付的步骤。
|
||||
|
||||
交付的面向人员有以下两种，我们将分别介绍：
|
||||
> 请确保你已经开启了 FluxCD Addon。
|
||||
|
||||
1. 面向平台管理员/运维人员的基础设施交付，用户可以通过直接更新仓库中的配置文件，从而更新集群中的基础设施配置，如系统的依赖软件、安全策略、存储、网络等基础设施配置。
|
||||
2. 面向终端开发者的交付，用户的代码一旦合并到应用代码仓库，就自动化触发集群中应用的更新，可以更高效的完成应用的迭代，与 KubeVela 的灰度发布、流量调拨、多集群部署等功能结合可以形成更为强大的自动化发布能力。
|
||||
|
||||
> 提示：你也可以通过类似的步骤使用 ArgoCD 等 GitOps 工具来间接使用 KubeVela，细节的操作文档我们会在后续发布中提供。
|
||||
|
||||
## 面向平台管理员/运维人员的交付
|
||||
|
||||
如图所示，对于平台管理员/运维人员而言，他们并不需要关心应用的代码，所以只需要准备一个 Git 配置仓库并部署 KubeVela 配置文件，后续对于应用及基础设施的配置变动，便可通过直接更新 Git 配置仓库来完成，使得每一次配置变更可追踪。
|
||||
|
||||
|
||||
## 监听 Git 仓库并自动同步
|
||||
|
||||
### 准备配置仓库
|
||||
|
||||
> 具体的配置可参考 [示例仓库](https://github.com/kubevela/samples/tree/master/09.GitOps_Demo/for-SREs)。
|
||||
GitOps 模式会自动同步仓库的配置到集群中，首先，我们需要一个仓库，里面存放着所有你需要的配置文件：如一些 Kubernetes 原生资源 Deployment，Secret，ConfigMap 等。当然，你可以在直接在仓库中存放 KubeVela 的 Application。
|
||||
|
||||
在本例中，我们将部署一个 MySQL 数据库软件作为项目的基础设施，同时部署一个业务应用，使用这个数据库。配置仓库的目录结构如下:
|
||||
|
||||
* `clusters/` 中包含集群中的 KubeVela GitOps 配置，用户需要将 `clusters/` 中的文件手动部署到集群中。这个是一次性的管控操作，执行完成后，KubeVela 便能自动监听配置仓库中的文件变动且自动更新集群中的配置。其中，`clusters/apps.yaml` 将监听 `apps/` 下所有应用的变化，`clusters/infra.yaml` 将监听 `infrastructure/` 下所有基础设施的变化。
|
||||
* `apps/` 目录中包含业务应用的所有配置，在本例中为一个使用数据库的业务应用。
|
||||
* `infrastructure/` 中包含一些基础设施相关的配置和策略，在本例中为 MySQL 数据库。
|
||||
假设在我们的仓库中，有一个叫做 `infrastructure` 的文件夹，里面有一个叫做 `server` 的 KubeVela Application 以及一个叫做 `server-config` 的 ConfigMap。
|
||||
|
||||
配置仓库的目录结构如下:
|
||||
|
||||
```shell
|
||||
├── apps
|
||||
│ └── my-app.yaml
|
||||
├── clusters
|
||||
│ ├── apps.yaml
|
||||
│ └── infra.yaml
|
||||
└── infrastructure
|
||||
└── mysql.yaml
|
||||
├── infrastructure
|
||||
├── server-config.yaml
|
||||
└── server.yaml
|
||||
```
|
||||
|
||||
> KubeVela 建议使用如上的目录结构管理你的 GitOps 仓库。`clusters/` 中存放相关的 KubeVela GitOps 配置并需要被手动部署到集群中，`apps/` 和 `infrastructure/` 中分别存放你的应用和基础设施配置。通过把应用和基础配置分开，能够更为合理的管理你的部署环境，隔离应用的变动影响。
|
||||
|
||||
#### `clusters/` 目录
|
||||
|
||||
首先，我们来看下 clusters 目录，这也是 KubeVela 对接 GitOps 的初始化操作配置目录
|
||||
|
||||
以 `clusters/infra.yaml` 为例：
|
||||
部署如下 KubeVela GitOps 应用：
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: infra
|
||||
name: infra-gitops
|
||||
spec:
|
||||
components:
|
||||
- name: database-config
|
||||
|
|
@ -65,19 +43,71 @@ spec:
|
|||
pullInterval: 10m
|
||||
git:
|
||||
# 监听变动的分支
|
||||
branch: main
|
||||
branch: infra
|
||||
# 监听变动的路径，指向仓库中 infrastructure 目录下的文件
|
||||
path: ./infrastructure
|
||||
```
|
||||
|
||||
`apps.yaml` 与 `infra.yaml` 几乎保持一致，只不过监听的文件目录有所区别。
|
||||
在 `apps.yaml` 中，`properties.path` 的值将改为 `./apps`，表明监听 `apps/` 目录下的文件变动。
|
||||
查看该 GitOps 应用状态：
|
||||
|
||||
cluster 文件夹中的 GitOps 管控配置文件需要在初始化的时候一次性手动部署到集群中，在此之后 KubeVela 将自动监听 `apps/` 以及 `infrastructure/` 目录下的配置文件并定期更新同步。
|
||||
```yaml
|
||||
$ vela status infra-gitops
|
||||
About:
|
||||
|
||||
#### `apps/` 目录
|
||||
Name: infra-gitops
|
||||
Namespace: default
|
||||
Created at: 2022-06-30 14:52:33 +0800 CST
|
||||
Status: running
|
||||
|
||||
`apps/` 目录中存放着应用配置文件，这是一个配置了数据库信息以及 Ingress 的简单应用。该应用将连接到一个 MySQL 数据库，并简单地启动服务。在默认的服务路径下，会显示当前版本号。在 `/db` 路径下，会列出当前数据库中的信息。
|
||||
Workflow:
|
||||
|
||||
mode: DAG
|
||||
finished: true
|
||||
Suspend: false
|
||||
Terminated: false
|
||||
Steps
|
||||
- id:dgatat8jag
|
||||
name:database-config
|
||||
type:apply-component
|
||||
phase:succeeded
|
||||
message:
|
||||
|
||||
Services:
|
||||
|
||||
- Name: database-config
|
||||
Cluster: local Namespace: default
|
||||
Type: kustomize
|
||||
Healthy
|
||||
No trait applied
|
||||
```
|
||||
|
||||
可以看到，该 GitOps 应用已经正常运行。此时，该应用会以 10 分钟的间隔不断拉取仓库中的配置并在集群中进行同步。
|
||||
|
||||
查看集群中的资源，可以发现 `server` Application 以及 `server-config` ConfigMap 都已经被自动部署了。
|
||||
|
||||
```bash
|
||||
$ vela ls
|
||||
APP COMPONENT TYPE TRAITS PHASE HEALTHY STATUS CREATED-TIME
|
||||
infra-gitops database-config kustomize running healthy 2022-06-30 14:52:33 +0800 CST
|
||||
server server webservice running healthy Ready:1/1 2022-06-30 14:52:35 +0800 CST
|
||||
|
||||
$ kubectl get configmap
|
||||
NAME DATA AGE
|
||||
server-config 1 2m58s
|
||||
```
|
||||
|
||||
## 监听镜像仓库并自动同步
|
||||
|
||||
GitOps 也可以通过监听你的镜像仓库，获得最新镜像版本，并用最新版本来更新你代码仓库中的配置，从而达到自动更新镜像的目的。
|
||||
|
||||
假设我们代码仓库的目录结构如下:
|
||||
|
||||
```shell
|
||||
├── application
|
||||
└── my-app.yaml
|
||||
```
|
||||
|
||||
application 中 my-app.yaml 如下：
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
|
|
@ -87,263 +117,68 @@ metadata:
|
|||
namespace: default
|
||||
spec:
|
||||
components:
|
||||
- name: my-server
|
||||
- name: my-app
|
||||
type: webservice
|
||||
properties:
|
||||
image: ghcr.io/fogdong/test-fog:master-cba5605f-1632714412
|
||||
port: 8088
|
||||
env:
|
||||
- name: DB_HOST
|
||||
value: mysql-cluster-mysql.default.svc.cluster.local:3306
|
||||
- name: DB_PASSWORD
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: mysql-secret
|
||||
key: ROOT_PASSWORD
|
||||
traits:
|
||||
- type: ingress
|
||||
properties:
|
||||
domain: testsvc.example.com
|
||||
http:
|
||||
/: 8088
|
||||
image: nginx # {"$imagepolicy": "default:image-gitops"}
|
||||
```
|
||||
|
||||
#### `infrastructure/` 目录
|
||||
> 注意，image 字段后有 `# {"$imagepolicy": "default:image-gitops"}` 的注释。KubeVela 会通过该注释去更新对应的镜像字段。`default:image-gitops` 是我们即将部署的 GitOps 应用组件对应的命名空间和名称。
|
||||
|
||||
`infrastructure/` 目录下存放一些基础设施的配置。此处我们使用 [mysql controller](https://github.com/bitpoke/mysql-operator) 来部署了一个 MySQL 集群。
|
||||
|
||||
> 注意，请确保你的集群中有一个 secret，并通过 `ROOT_PASSWORD` 声明了 MySQL 密码。
|
||||
部署如下 KubeVela GitOps 应用：
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: mysql
|
||||
namespace: default
|
||||
name: image-gitops
|
||||
spec:
|
||||
components:
|
||||
- name: mysql-controller
|
||||
type: helm
|
||||
properties:
|
||||
repoType: helm
|
||||
url: https://presslabs.github.io/charts
|
||||
chart: mysql-operator
|
||||
version: "0.4.0"
|
||||
- name: mysql-cluster
|
||||
type: raw
|
||||
dependsOn:
|
||||
- mysql-controller
|
||||
properties:
|
||||
apiVersion: mysql.presslabs.org/v1alpha1
|
||||
kind: MysqlCluster
|
||||
metadata:
|
||||
name: mysql-cluster
|
||||
spec:
|
||||
replicas: 1
|
||||
# 关联 secret 名称
|
||||
secretName: mysql-secret
|
||||
- name: image-gitops
|
||||
type: kustomize
|
||||
properties:
|
||||
repoType: git
|
||||
# 将此处替换成你需要监听的 git 配置仓库地址
|
||||
url: https://github.com/FogDong/KubeVela-GitOps-Infra-Demo
|
||||
# 需要在此处声明你的 git secret，因为 GitOps 会用最新的镜像更新你仓库中的文件，需要写权限
|
||||
secretRef: git-secret
|
||||
pullInterval: 1m
|
||||
git:
|
||||
# 监听变动的分支
|
||||
branch: image
|
||||
# 监听变动的路径，指向仓库中 application 目录下的文件
|
||||
path: ./application
|
||||
imageRepository:
|
||||
# 将此处替换成你需要的镜像地址
|
||||
image: ghcr.io/fogdong/test-fog
|
||||
# 如果这是一个私有的镜像仓库，可以通过 `kubectl create secret docker-registry` 创建对应的镜像秘钥并相关联
|
||||
# secretRef: imagesecret
|
||||
filterTags:
|
||||
# 可对镜像 tag 进行过滤
|
||||
pattern: '^master-[a-f0-9]+-(?P<ts>[0-9]+)'
|
||||
extract: '$ts'
|
||||
# 通过 policy 筛选出最新的镜像 Tag 并用于更新
|
||||
policy:
|
||||
numerical:
|
||||
order: asc
|
||||
# 追加提交信息
|
||||
commitMessage: "Image: {{range .Updated.Images}}{{println .}}{{end}}"
|
||||
```
|
||||
|
||||
#### 部署 `clusters/` 目录下的文件
|
||||
应用部署成功后，可以看到 `my-app` 应用也已经被自动部署。此时，`my-app` 中的镜像为 `nginx`：
|
||||
|
||||
配置完以上文件并存放到 Git 配置仓库后，我们需要在集群中手动部署 `clusters/` 目录下的 KubeVela GitOps 配置文件。
|
||||
|
||||
首先，在集群中部署 `clusters/infra.yaml`。可以看到它自动在集群中拉起了 `infrastructure/` 目录下的 MySQL 部署文件：
|
||||
|
||||
```shell
|
||||
vela up -f clusters/infra.yaml
|
||||
```
|
||||
|
||||
```shell
|
||||
```bash
|
||||
$ vela ls
|
||||
|
||||
APP COMPONENT TYPE TRAITS PHASE HEALTHY STATUS CREATED-TIME
|
||||
infra database-config kustomize running healthy 2021-09-26 20:48:09 +0800 CST
|
||||
mysql mysql-controller helm running healthy 2021-09-26 20:48:11 +0800 CST
|
||||
└─ mysql-cluster raw running healthy 2021-09-26 20:48:11 +0800 CST
|
||||
APP COMPONENT TYPE TRAITS PHASE HEALTHY STATUS CREATED-TIME
|
||||
image-gitops image-gitops kustomize running healthy 2022-06-30 15:16:30 +0800 CST
|
||||
my-app my-app webservice running healthy Ready:1/1 2022-06-30 15:16:31 +0800 CST
|
||||
```
|
||||
|
||||
接着，在集群中部署 `clusters/apps.yaml`，可以看到它自动拉起了 `apps/` 目录下的应用部署文件：
|
||||
隔了一段时间之后，我们配置的 imageRepository 会自动拉取到我们希望的最新镜像，并更新仓库中的应用镜像。
|
||||
|
||||
```shell
|
||||
vela up -f clusters/apps.yaml
|
||||
```
|
||||
此时，可以看到配置仓库中有一条来自 `kubevelabot` 的提交，该提交将 `nginx` 镜像替换成了我们自己仓库的最新镜像。提交信息均带有 `Update image automatically.` 前缀。你也可以通过 `{{range .Updated.Images}}{{println .}}{{end}}` 在 `commitMessage` 字段中追加你所需要的信息。
|
||||
|
||||
```shell
|
||||
APP COMPONENT TYPE TRAITS PHASE HEALTHY STATUS CREATED-TIME
|
||||
apps apps kustomize running healthy 2021-09-27 16:55:53 +0800 CST
|
||||
infra database-config kustomize running healthy 2021-09-26 20:48:09 +0800 CST
|
||||
my-app my-server webservice ingress running healthy 2021-09-27 16:55:55 +0800 CST
|
||||
mysql mysql-controller helm running healthy 2021-09-26 20:48:11 +0800 CST
|
||||
└─ mysql-cluster raw running healthy 2021-09-26 20:48:11 +0800 CST
|
||||
```
|
||||
|
||||
至此，我们通过部署 KubeVela GitOps 配置文件，自动在集群中拉起了应用及数据库。
|
||||
|
||||
通过 curl 应用的 Ingress，可以看到目前的版本是 0.1.5，并且成功地连接到了数据库：
|
||||
|
||||
```shell
|
||||
$ kubectl get ingress
|
||||
NAME CLASS HOSTS ADDRESS PORTS AGE
|
||||
my-server <none> testsvc.example.com <ingress-ip> 80 162m
|
||||
|
||||
$ curl -H "Host:testsvc.example.com" http://<ingress-ip>
|
||||
Version: 0.1.5
|
||||
|
||||
$ curl -H "Host:testsvc.example.com" http://<ingress-ip>/db
|
||||
User: KubeVela
|
||||
Description: It's a test user
|
||||
```
|
||||
|
||||
### 修改配置
|
||||
|
||||
完成了首次部署后，我们可以通过修改配置仓库中的配置，来完成集群中应用的配置更新。
|
||||
|
||||
修改应用 Ingress 的 Domain：
|
||||
|
||||
```yaml
|
||||
...
|
||||
traits:
|
||||
- type: ingress
|
||||
properties:
|
||||
domain: kubevela.example.com
|
||||
http:
|
||||
/: 8089
|
||||
```
|
||||
|
||||
经过一段时间后，重新查看集群中的 Ingress：
|
||||
|
||||
```shell
|
||||
NAME CLASS HOSTS ADDRESS PORTS AGE
|
||||
my-server <none> kubevela.example.com <ingress-ip> 80 162m
|
||||
```
|
||||
|
||||
可以看到，Ingress 的 Host 地址已被成功更新。
|
||||
|
||||
通过这种方式，我们可以方便地通过更新 Git 配置仓库中的文件，从而自动化更新集群中的配置。
|
||||
|
||||
## 面向终端开发者的交付
|
||||
|
||||
如图所示，对于终端开发者而言，在 KubeVela Git 配置仓库以外，还需要准备一个应用代码仓库。在用户更新了应用代码仓库中的代码后，需要配置一个 CI 来自动构建镜像并推送至镜像仓库中。KubeVela 会监听镜像仓库中的最新镜像，并自动更新配置仓库中的镜像配置，最后再更新集群中的应用配置。使用户可以达成在更新代码后，集群中的配置也自动更新的效果。
|
||||
|
||||
|
||||
|
||||
### 准备代码仓库
|
||||
|
||||
准备一个代码仓库，里面包含一些源代码以及对应的 Dockerfile。
|
||||
|
||||
这些代码将连接到一个 MySQL 数据库，并简单地启动服务。在默认的服务路径下，会显示当前版本号。在 `/db` 路径下，会列出当前数据库中的信息。
|
||||
|
||||
```go
|
||||
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
|
||||
_, _ = fmt.Fprintf(w, "Version: %s\n", VERSION)
|
||||
})
|
||||
http.HandleFunc("/db", func(w http.ResponseWriter, r *http.Request) {
|
||||
rows, err := db.Query("select * from userinfo;")
|
||||
if err != nil {
|
||||
_, _ = fmt.Fprintf(w, "Error: %v\n", err)
|
||||
}
|
||||
for rows.Next() {
|
||||
var username string
|
||||
var desc string
|
||||
err = rows.Scan(&username, &desc)
|
||||
if err != nil {
|
||||
_, _ = fmt.Fprintf(w, "Scan Error: %v\n", err)
|
||||
}
|
||||
_, _ = fmt.Fprintf(w, "User: %s \nDescription: %s\n\n", username, desc)
|
||||
}
|
||||
})
|
||||
|
||||
if err := http.ListenAndServe(":8088", nil); err != nil {
|
||||
panic(err.Error())
|
||||
}
|
||||
```
|
||||
|
||||
我们希望用户改动代码进行提交后，自动构建出最新的镜像并推送到镜像仓库。这一步 CI 可以通过集成 GitHub Actions、Jenkins 或者其他 CI 工具来实现。在本例中，我们通过借助 GitHub Actions 来完成持续集成。具体的代码文件及配置可参考 [示例仓库](https://github.com/kubevela/samples/tree/master/09.GitOps_Demo/for-developers/app-code)。
|
||||
|
||||
### 配置秘钥信息
|
||||
|
||||
在新的镜像推送到镜像仓库后，KubeVela 会识别到新的镜像，并更新仓库及集群中的 `Application` 配置文件。因此，我们需要一个含有 Git 信息的 Secret，使 KubeVela 向 Git 仓库进行提交。部署如下文件，将其中的用户名和密码替换成你的 Git 用户名及密码（或 Token）：
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: git-secret
|
||||
type: kubernetes.io/basic-auth
|
||||
stringData:
|
||||
username: <your username>
|
||||
password: <your password>
|
||||
```
|
||||
|
||||
### 准备配置仓库
|
||||
|
||||
配置仓库与之前面向运维人员的配置大同小异，只需要加上与镜像仓库相关的配置即可。具体配置请参考 [示例仓库](https://github.com/kubevela/samples/tree/master/09.GitOps_Demo/for-developers/kubevela-config)。
|
||||
|
||||
修改 `clusters/` 中的 `apps.yaml`，该 GitOps 配置会监听仓库中 `apps/` 下的应用文件变动以及镜像仓库中的镜像更新：
|
||||
|
||||
```yaml
|
||||
...
|
||||
imageRepository:
|
||||
# 镜像地址
|
||||
image: <your image>
|
||||
# 如果这是一个私有的镜像仓库，可以通过 `kubectl create secret docker-registry` 创建对应的镜像秘钥并相关联
|
||||
# secretRef: imagesecret
|
||||
filterTags:
|
||||
# 可对镜像 tag 进行过滤
|
||||
pattern: '^master-[a-f0-9]+-(?P<ts>[0-9]+)'
|
||||
extract: '$ts'
|
||||
# 通过 policy 筛选出最新的镜像 Tag 并用于更新
|
||||
policy:
|
||||
numerical:
|
||||
order: asc
|
||||
# 追加提交信息
|
||||
commitMessage: "Image: {{range .Updated.Images}}{{println .}}{{end}}"
|
||||
```
|
||||
|
||||
修改 `apps/my-app.yaml` 中的 image 字段，在后面加上 `# {"$imagepolicy": "default:apps"}` 的注释。KubeVela 会通过该注释去更新对应的镜像字段。`default:apps` 是上面 GitOps 配置对应的命名空间和名称。
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
components:
|
||||
- name: my-server
|
||||
type: webservice
|
||||
properties:
|
||||
image: ghcr.io/fogdong/test-fog:master-cba5605f-1632714412 # {"$imagepolicy": "default:apps"}
|
||||
```
|
||||
|
||||
将 `clusters/` 中包含镜像仓库配置的文件更新到集群中后，我们便可以通过修改代码来完成应用的更新。
|
||||
|
||||
### 修改代码
|
||||
|
||||
将代码文件中的 `Version` 改为 `0.1.6`，并修改数据库中的数据:
|
||||
|
||||
```go
|
||||
const VERSION = "0.1.6"
|
||||
|
||||
...
|
||||
|
||||
func InsertInitData(db *sql.DB) {
|
||||
stmt, err := db.Prepare(insertInitData)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
defer stmt.Close()
|
||||
|
||||
_, err = stmt.Exec("KubeVela2", "It's another test user")
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
提交该改动至代码仓库，可以看到，我们配置的 CI 流水线开始构建镜像并推送至镜像仓库。
|
||||
|
||||
而 KubeVela 会通过监听镜像仓库，根据最新的镜像 Tag 来更新配置仓库中 `apps/` 下的应用 `my-app`。
|
||||
|
||||
此时，可以看到配置仓库中有一条来自 `kubevelabot` 的提交，提交信息均带有 `Update image automatically.` 前缀。你也可以通过 `{{range .Updated.Images}}{{println .}}{{end}}` 在 `commitMessage` 字段中追加你所需要的信息。
|
||||
|
||||
|
||||
|
||||
|
||||
> 值得注意的是，如果你希望将代码和配置放在同一个仓库，需要过滤掉来自 `kubevelabot` 的提交来防止流水线的重复构建。可以在 CI 中通过如下配置过滤：
|
||||
>
|
||||
|
|
@ -359,30 +194,6 @@ func InsertInitData(db *sql.DB) {
|
|||
> * 当 Git 仓库中的配置文件被更新时，KubeVela 将根据最新的配置更新集群中的应用。
|
||||
> * 当镜像仓库中多了新的 Tag 时，KubeVela 将根据你配置的 policy 规则，筛选出最新的镜像 Tag，并更新到 Git 仓库中。而当代码仓库中的文件被更新后，KubeVela 将重复第一步，更新集群中的文件，从而达到了自动部署的效果。
|
||||
|
||||
通过 `curl` 对应的 `Ingress` 查看当前版本和数据库信息：
|
||||
## 获取更多
|
||||
|
||||
```shell
|
||||
$ kubectl get ingress
|
||||
NAME CLASS HOSTS ADDRESS PORTS AGE
|
||||
my-server <none> kubevela.example.com <ingress-ip> 80 162m
|
||||
|
||||
$ curl -H "Host:kubevela.example.com" http://<ingress-ip>
|
||||
Version: 0.1.6
|
||||
|
||||
$ curl -H "Host:kubevela.example.com" http://<ingress-ip>/db
|
||||
User: KubeVela
|
||||
Description: It's a test user
|
||||
|
||||
User: KubeVela2
|
||||
Description: It's another test user
|
||||
```
|
||||
|
||||
版本已被成功更新！至此，我们完成了从变更代码，到自动部署至集群的全部操作。
|
||||
|
||||
## 总结
|
||||
|
||||
在运维侧，如若需要更新基础设施（如数据库）的配置，或是应用的配置项，只需要修改配置仓库中的文件，KubeVela 将自动把配置同步到集群中，简化了部署流程。
|
||||
|
||||
在研发侧，用户修改代码仓库中的代码后，KubeVela 将自动更新配置仓库中的镜像。从而进行应用的版本更新。
|
||||
|
||||
通过与 GitOps 的结合，KubeVela 加速了应用从开发到部署的整个流程。
|
||||
你还可以查看 GitOps [博客](https://kubevela.io/blog/2021/10/10/kubevela-gitops) 以及 [视频实践](https://kubevela.io/videos/best-practice/gitops) 来更好地体验以及使用 GitOps 功能。
|
||||
|
|
|
|||
|
|
@ -2,237 +2,7 @@
|
|||
title: 定义CRD
|
||||
---
|
||||
|
||||
在本部分中，我们会对 `ComponentDefinition` 和 `TraitDefinition` 进行详细介绍。
|
||||
This documentation has been merged into [Definition Protocol](./oam/x-definition).
|
||||
|
||||
> 所有的定义对象都应由平台团队来进行维护和安装。在此背景下，可以把平台团队理解为平台中的*能力提供者*。
|
||||
|
||||
## 概述
|
||||
|
||||
本质上，KubeVela 中的定义对象由三个部分组成：
|
||||
|
||||
- **能力指示器 （Capability Indicator）**
|
||||
- `ComponentDefinition` 使用 `spec.workload` 指出此组件的 workload 类型.
|
||||
- `TraitDefinition` 使用 `spec.definitionRef` 指出此 trait 的提供者。
|
||||
- **互操作字段 （Interoperability Fields）**
|
||||
- 他们是为平台所设计的，用来确保给定的 workload 类型可以和某个 trait 一起工作。因此只有 `TraitDefinition` 有这些字段。
|
||||
- **能力封装和抽象 （Capability Encapsulation and Abstraction）** （由 `spec.schematic` 定义）
|
||||
- 它定义了此 capability 的**模板和参数** ，比如封装。
|
||||
|
||||
因此，定义对象的基本结构如下所示：
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: XxxDefinition
|
||||
metadata:
|
||||
name: <definition name>
|
||||
spec:
|
||||
...
|
||||
schematic:
|
||||
cue:
|
||||
# cue template ...
|
||||
helm:
|
||||
# Helm chart ...
|
||||
# ... interoperability fields
|
||||
```
|
||||
|
||||
我们接下来详细解释每个字段。
|
||||
|
||||
### 能力指示器 （Capability Indicator）
|
||||
|
||||
在 `ComponentDefinition` 中，workload 类型的指示器被声明为 `spec.workload`
|
||||
|
||||
下面的示例是在 KubeVela 中，一个给 *Web Service* 的定义：
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
metadata:
|
||||
name: webservice
|
||||
namespace: default
|
||||
annotations:
|
||||
definition.oam.dev/description: "Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers."
|
||||
spec:
|
||||
workload:
|
||||
definition:
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
...
|
||||
```
|
||||
|
||||
在上面的示例中，它声称利用 Kubernetes 的 Deployment （`apiVersion: apps/v1`, `kind: Deployment`）作为组件的 workload 类型。
|
||||
|
||||
### 互操作字段 （Interoperability Fields）
|
||||
|
||||
**只有 trait** 有互操作字段。在一个 `TraitDefinition` 中，互操作字段的大体示例如下所示：
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: TraitDefinition
|
||||
metadata:
|
||||
name: ingress
|
||||
spec:
|
||||
appliesToWorkloads:
|
||||
- deployments.apps
|
||||
- webservice
|
||||
conflictsWith:
|
||||
- service
|
||||
workloadRefPath: spec.workloadRef
|
||||
podDisruptive: false
|
||||
```
|
||||
|
||||
我们来详细解释一下。
|
||||
|
||||
#### `.spec.appliesToWorkloads`
|
||||
|
||||
该字段定义了此 trait 允许应用于哪些类型的 workload 的约束。
|
||||
|
||||
- 它使用一个字符串的数组作为其值。
|
||||
- 数组中的每一个元素指向允许应用此 trait 的一个或一组 workload 类型。
|
||||
|
||||
有四种来表示一个或者一组 workload 类型。
|
||||
|
||||
- `ComponentDefinition` 命名， 例如 `webservice`， `worker`
|
||||
- `ComponentDefinition` 定义引用（CRD 命名），例如 `deployments.apps`
|
||||
- 以`*.`为前缀的 `ComponentDefinition` 定义引用的资源组，例如`*.apps` 和 `*.oam.dev`。这表示 trait 被允许应用于该组中的任意 workload。
|
||||
- `*` 表示 trait 被允许应用于任意 workload。
|
||||
|
||||
如果省略此字段，则表示该 trait 允许应用于任意 workload 类型。
|
||||
|
||||
如果将一个 trait 应用于未包含在 `appliesToWorkloads` 中的 workload，KubeVela 将会报错。
|
||||
|
||||
##### `.spec.conflictsWith`
|
||||
|
||||
如果将某些种类的 trait 应用于该 workload，该字段定义了其中哪些 trait 与该 trait 冲突的约束。
|
||||
|
||||
- 它使用一个字符串的数组作为其值。
|
||||
- 数组中的每一个元素指向一个或一组 trait。
|
||||
|
||||
有四种来表示一个或者一组 workload 类型。
|
||||
|
||||
- `TraitDefinition` 命名，比如 `ingress`
|
||||
- 以`*.`为前缀的 `TraitDefinition` 定义引用的资源组，例如`*.networking.k8s.io`。这表示当前 trait 与该组中的任意 trait 相冲突。
|
||||
- `*` 表示当前 trait 与任意 trait 相冲突。
|
||||
|
||||
如果省略此字段，则表示该 trait 没有和其他任何 trait 相冲突。
|
||||
|
||||
##### `.spec.workloadRefPath`
|
||||
|
||||
该字段定义 trait 的字段路径，该路径用于存储对其应用 trait 的 workload 的引用。
|
||||
|
||||
- 它使用一个字符串作为其值，比如 `spec.workloadRef`.
|
||||
|
||||
如果设置了此字段，KubeVela core 会自动将 workload 引用填充到 trait 的目标字段中。然后，trait controller 可以之后从 trait 中获取 workload 引用。因此，此字段通常和 trait 一起出现，其 controller 在运行时依赖于 workload 引用。
|
||||
|
||||
如何设置此字段的具体细节，请查阅 [scaler](https://github.com/kubevela/kubevela/blob/master/charts/vela-core/templates/defwithtemplate/manualscale.yaml) trait 作为演示。
|
||||
|
||||
##### `.spec.podDisruptive`
|
||||
|
||||
此字段定义了添加或者更新 trait 会不会破坏 pod。在此示例中，因为答案是不会，所以该字段为 `false`，当添加或更新 trait 时，它不会影响 pod。如果此字段是 `true`，则它会导致 pod 在 trait 被添加或者更新时被破坏并重启。默认情况下，该值为 `false`，这意味着该 trait 不会影响 pod。请小心处理此字段。对于严肃的大规模生产使用场景而言，它非常重要和有用。
|
||||
|
||||
### 能力封装和抽象 （Capability Encapsulation and Abstraction）
|
||||
|
||||
给定的能力的模板和封装被定义在 `spec.schematic` 字段中。如下所示范例是一个 KubeVela 中的*Web Service* 类型的完整定义：
|
||||
|
||||
<details>
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
metadata:
|
||||
name: webservice
|
||||
namespace: default
|
||||
annotations:
|
||||
definition.oam.dev/description: "Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers."
|
||||
spec:
|
||||
workload:
|
||||
definition:
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
schematic:
|
||||
cue:
|
||||
template: |
|
||||
output: {
|
||||
apiVersion: "apps/v1"
|
||||
kind: "Deployment"
|
||||
spec: {
|
||||
selector: matchLabels: {
|
||||
"app.oam.dev/component": context.name
|
||||
}
|
||||
|
||||
template: {
|
||||
metadata: labels: {
|
||||
"app.oam.dev/component": context.name
|
||||
}
|
||||
|
||||
spec: {
|
||||
containers: [{
|
||||
name: context.name
|
||||
image: parameter.image
|
||||
|
||||
if parameter["cmd"] != _|_ {
|
||||
command: parameter.cmd
|
||||
}
|
||||
|
||||
if parameter["env"] != _|_ {
|
||||
env: parameter.env
|
||||
}
|
||||
|
||||
if context["config"] != _|_ {
|
||||
env: context.config
|
||||
}
|
||||
|
||||
ports: [{
|
||||
containerPort: parameter.port
|
||||
}]
|
||||
|
||||
if parameter["cpu"] != _|_ {
|
||||
resources: {
|
||||
limits:
|
||||
cpu: parameter.cpu
|
||||
requests:
|
||||
cpu: parameter.cpu
|
||||
}
|
||||
}
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
parameter: {
|
||||
// +usage=Which image would you like to use for your service
|
||||
// +short=i
|
||||
image: string
|
||||
|
||||
// +usage=Commands to run in the container
|
||||
cmd?: [...string]
|
||||
|
||||
// +usage=Which port do you want customer traffic sent to
|
||||
// +short=p
|
||||
port: *80 | int
|
||||
// +usage=Define arguments by using environment variables
|
||||
env?: [...{
|
||||
// +usage=Environment variable name
|
||||
name: string
|
||||
// +usage=The value of the environment variable
|
||||
value?: string
|
||||
// +usage=Specifies a source the value of this var should come from
|
||||
valueFrom?: {
|
||||
// +usage=Selects a key of a secret in the pod's namespace
|
||||
secretKeyRef: {
|
||||
// +usage=The name of the secret in the pod's namespace to select from
|
||||
name: string
|
||||
// +usage=The key of the secret to select from. Must be a valid secret key
|
||||
key: string
|
||||
}
|
||||
}
|
||||
}]
|
||||
// +usage=Number of CPU units for the service, like `0.5` (0.5 CPU core), `1` (1 CPU core)
|
||||
cpu?: string
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
`schematic` 的技术规范在接下来的 CUE 和 Helm 相关的文档中有详细解释。
|
||||
|
||||
同时，`schematic` 字段使你可以直接根据他们来渲染UI表单。详细操作请见[从定义中生成表单](/docs/platform-engineers/openapi-v3-json-schema)部分。
|
||||
The definition revision part has been migrated to [here](./x-def-version).
|
||||
|
|
|
|||
|
|
@ -8,6 +8,36 @@ KubeVela 是完全可编程的，它可以轻松的根据你的需求实现原
|
|||
|
||||
当前 OAM 模型支持的模块定义（X-Definition）包括组件定义（ComponentDefinition），运维特征定义（TraitDefinition）、应用策略定义（PolicyDefinition），工作流节点定义（WorkflowStepDefinition）等，随着系统演进，OAM 模型未来可能会根据场景需要进一步增加新的模块定义。
|
||||
|
||||
## 概述
|
||||
|
||||
本质上，KubeVela 中的定义对象由三个部分组成：
|
||||
|
||||
- **能力指示器 （Capability Indicator）**
|
||||
- `ComponentDefinition` 使用 `spec.workload` 指出此组件的 workload 类型.
|
||||
- `TraitDefinition` 使用 `spec.definition` 指出此 trait 的提供者。
|
||||
- **互操作字段 （Interoperability Fields）**
|
||||
- 他们是为平台所设计的，用来确保给定的 workload 类型可以和某个 trait 一起工作。因此只有 `TraitDefinition` 有这些字段。
|
||||
- **能力封装和抽象 （Capability Encapsulation and Abstraction）** （由 `spec.schematic` 定义）
|
||||
- 它定义了此 capability 的**模板和参数** ，比如封装。
|
||||
|
||||
因此，定义对象的基本结构如下所示：
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: XxxDefinition
|
||||
metadata:
|
||||
name: <definition name>
|
||||
spec:
|
||||
...
|
||||
schematic:
|
||||
cue:
|
||||
# cue template ...
|
||||
helm:
|
||||
# Helm chart ...
|
||||
# ... interoperability fields
|
||||
```
|
||||
|
||||
我们接下来详细解释每一种类型。
|
||||
|
||||
## 组件定义（ComponentDefinition）
|
||||
|
||||
|
|
@ -60,6 +90,8 @@ spec:
|
|||
|
||||
具体抽象方式和交付方式的编写可以查阅对应的文档，这里以一个完整的例子介绍组件定义的工作流程。
|
||||
|
||||
<detail>
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
|
|
@ -160,6 +192,7 @@ spec:
|
|||
...
|
||||
}
|
||||
```
|
||||
</detail>
|
||||
|
||||
如上所示，这个组件定义的名字叫 `helm`，一经注册，最终用户在 Application 的组件类型（`components[*].type`）字段就可以填写这个类型。
|
||||
|
||||
|
|
@ -204,15 +237,33 @@ spec:
|
|||
|
||||
从上述运维特征的格式和功能中我们可以看到，运维特征定义提供了一系列运维能力和组件之间衔接的方式，使得相同功能的运维功能可以适配到不同的组件中。具体的字段功能如下所示：
|
||||
|
||||
* 运维特征能够适配的工作负载名称列表（`.spec.appliesToWorkloads`）,可缺省字段，字符串数组类型，申明这个运维特征可以用于的工作负载类型，填写的是工作负载的 CRD 名称，格式为 `<resources>.<api-group>`
|
||||
* 与该运维特征冲突的其他运维特征名称列表（`.spec.conflictsWith`）,可缺省字段，字符串数组类型，申明这个运维特征与哪些运维特征冲突，填写的是运维特征名称的列表。
|
||||
* 运维特征能够适配的工作负载名称列表（`.spec.appliesToWorkloads`）,可缺省字段，字符串数组类型，申明这个运维特征可以用于的一种或一组工作负载类型，有四种填写方法：
|
||||
- 填写工作负载的 CRD 名称，格式为 `<resources>.<api-group>`
|
||||
- 填写 `ComponentDefinition` 命名， 例如 `webservice`， `worker`
|
||||
- 以`*.`为前缀的 `ComponentDefinition` 定义引用的资源组，例如`*.apps` 和 `*.oam.dev`。这表示 trait 被允许应用于该组中的任意 workload。
|
||||
- `*` 表示 trait 被允许应用于任意 workload。
|
||||
如果省略此字段，则表示该 trait 允许应用于任意 workload 类型。
|
||||
|
||||
* 与该运维特征冲突的其他运维特征名称列表（`.spec.conflictsWith`）,可缺省字段，字符串数组类型，申明这个运维特征与哪些运维特征冲突，填写的是运维特征名称的列表。有四种来表示：
|
||||
- `TraitDefinition` 命名，比如 `ingress`
|
||||
- 以`*.`为前缀的 `TraitDefinition` 定义引用的资源组，例如`*.networking.k8s.io`。这表示当前 trait 与该组中的任意 trait 相冲突。
|
||||
- `*` 表示当前 trait 与任意 trait 相冲突。
|
||||
- 如果省略此字段，则表示该 trait 没有和其他任何 trait 相冲突。
|
||||
|
||||
* 特征描述（对应`.spec.schematic`）字段定义了具体的运维动作。目前主要通过 [`CUE`][4] 来实现，同时也包含一系列诸如[`patch-trait`][5]这样的高级用法。
|
||||
|
||||
* 运维特征对应的 Kubernetes 资源定义（`.spec.definition`字段），可缺省字段，如果运维能力通过 Kubernetes 的 CRD 方式提供可以填写，其中 `apiVersion` 和 `kind` 分别描述了背后对应的 Kubernetes 资源组和资源类型。
|
||||
|
||||
* 运维能力中对于工作负载对象的引用字段路径（`.spec.workloadRefPath`字段），可缺省字段，运维能力中如果涉及到工作负载的引用，可以填写这样一个路径地址（如操作弹性扩缩容的 [HPA][6]对象，就可以填写`spec.scaleTargetRef`），然后 KubeVela 会自动将工作负载的实例化引用注入到运维能力的实例对象中。
|
||||
|
||||
* 运维能力的参数更新会不会引起底层资源（pod）重启（`.spec.podDisruptive`字段），可缺省字段，bool 类型，主要用于向用户标识 trait 的更新会不会导致底层资源（pod）的重启。这个标识通常可以提醒用户，改动这样一个trait可能应该再结合一个灰度发布，以免大量资源重启引入服务不可用和其他风险。
|
||||
|
||||
* 是否由该运维特征管理工作负载（`.spec.manageWorkload`）,可缺省字段，bool 类型，设置为 true 则标识这个运维特征会负责工作负载的创建、更新、以及资源回收，通常是灰度发布的运维特征会具备这个能力。
|
||||
|
||||
* 该运维特征是否不计入版本变化的计算（`.spec.skipRevisionAffect`）,可缺省字段，bool 类型，设置为 true 则标识这个运维特征的修改不计入版本的变化，即用户在应用中纯粹修改这个运维特征的字段不会触发应用本身的版本变化。
|
||||
|
||||
* 运维能力是否感知组件版本的变化（`.spec.revisionEnabled`）字段，可缺省字段，bool 类型，设置为 true 表示组件会生成的资源后缀会带版本后缀。
|
||||
|
||||
* 运维能力产生的资源是否部署到管控集群（`.spec.controlPlaneOnly`）字段，可缺省字段，bool 类型，设置为 true 表示 trait 生成的资源会被部署到管控集群，即`local`
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ title: 灰度发布和扩缩容
|
|||
|
||||
目前灰度发布运维特征支持的组件类型为：
|
||||
|
||||
* [webservice](../../end-user/components/cue/webservice)
|
||||
* webservice
|
||||
* worker
|
||||
|
||||
## 如何使用
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 185 KiB |
|
|
@ -111,6 +111,7 @@ module.exports = {
|
|||
'how-to/dashboard/application/create-application',
|
||||
'end-user/version-control',
|
||||
'end-user/workflow/component-dependency-parameter',
|
||||
'case-studies/initialize-env',
|
||||
'end-user/policies/apply-once',
|
||||
'end-user/policies/gc',
|
||||
],
|
||||
|
|
|
|||
|
|
@ -145,6 +145,3 @@ Version: 0.1.2
|
|||
|
||||
Refer to the [blog post](/blog/2021/09/02/kubevela-jenkins-cicd) for more details about deploying Jenkins + KubeVela and more comprehensive demo for application rolling update.
|
||||
|
||||
## Next Step
|
||||
|
||||
- Learn how to do [GitOps](./gitops) with KubeVela.
|
||||
|
|
|
|||
|
|
@ -1,10 +0,0 @@
|
|||
---
|
||||
title: Restful API
|
||||
---
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl';
|
||||
|
||||
<a
|
||||
target="_blank"
|
||||
href={useBaseUrl('/restful-api')}>
|
||||
KubeVela Restful API
|
||||
</a>
|
||||
|
|
@ -2,57 +2,33 @@
|
|||
title: GitOps with FluxCD
|
||||
---
|
||||
|
||||
> You need to enable the [fluxcd](../../reference/addons/fluxcd) addon.
|
||||
In this section, we will introduce how to use KubeVela to deliver in GitOps mode.
|
||||
|
||||
As a best practice, this article will separate into two perspectives simulating to the real scenarios:
|
||||
> Please make sure you have enabled the [fluxcd](../../reference/addons/fluxcd) addon.
|
||||
|
||||
1. For platform administrators/SREs, they can update the config in Git repo. It will trigger automated re-deployment.
|
||||
## Watch the Git repositories and sync automatically
|
||||
|
||||
2. For developers, they can update the app source code and then push it to Git. It will trigger building latest image and re-deployment.
|
||||
### Preparing the configuration repository
|
||||
|
||||
## For platform administrators/SREs
|
||||
GitOps will automatically synchronize the configuration in the repository to the cluster. First, we need a repository that stores all the configuration files you need: such as some Kubernetes native resources Deployment, Secret, ConfigMap, etc. Also, you can store KubeVela's Application in the repository.
|
||||
|
||||
Platform administrators/SREs prepares the Git repo for operational config. There will have a gitops agent watch the git server events, every changes of the configuration will be traceable by that.
|
||||
Suppose in our repository, there is a folder called `infrastructure`, which has a KubeVela Application called `server` and a ConfigMap called `server-config`.
|
||||
|
||||
In this scenario, KubeVela will watch the repo and apply changes to the clusters.
|
||||
|
||||
|
||||
|
||||
### Setup Config Repository to watch
|
||||
|
||||
> The configuration files are from the [Example Repo](https://github.com/kubevela/samples/tree/master/09.GitOps_Demo/for-SREs).
|
||||
|
||||
In this example, we will deploy an application and a database, the application uses the database to store data.
|
||||
|
||||
The structure of the config repository looks below:
|
||||
|
||||
* The `clusters/` contains the GitOps config. It will command KubeVela to watch the specified repo and apply latest changes.
|
||||
* The `apps/` contains the Application yaml for deploying the user-facing app.
|
||||
* The `infrastructure/` contains infrastructure tools, i.e. MySQL database.
|
||||
The directory structure of the repository is as follows:
|
||||
|
||||
```shell
|
||||
├── apps
|
||||
│ └── my-app.yaml
|
||||
├── clusters
|
||||
│ ├── apps.yaml
|
||||
│ └── infra.yaml
|
||||
└── infrastructure
|
||||
└── mysql.yaml
|
||||
├── infrastructure
|
||||
├── server-config.yaml
|
||||
└── server.yaml
|
||||
```
|
||||
|
||||
> KubeVela recommends using the directory structure above to manage your GitOps repository. `clusters/` holds the associated KubeVela GitOps configuration that need to be applied to cluster manually, `apps/` holds your application and `infrastructure/` holds your base configuration. By separating applications from basic configurations, you can manage your deployment environment more reasonably and isolate application changes.
|
||||
|
||||
#### Directory `clusters/`
|
||||
|
||||
The `clusters/` is the initialize configuration directory for KubeVela GitOps.
|
||||
|
||||
Below is how the `clusters/infra.yaml` looks like:
|
||||
Deploy the following KubeVela GitOps application:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: infra
|
||||
name: infra-gitops
|
||||
spec:
|
||||
components:
|
||||
- name: database-config
|
||||
|
|
@ -67,18 +43,71 @@ spec:
|
|||
pullInterval: 10m
|
||||
git:
|
||||
# the branch name
|
||||
branch: main
|
||||
branch: infra
|
||||
# the path to sync
|
||||
path: ./infrastructure
|
||||
```
|
||||
|
||||
`apps.yaml` and `infra.yaml` in `clusters/` are similar. Their difference is to watch different directories. In `apps.yaml`, the `properties.path` will be `./apps`.
|
||||
Check the status of this GitOps application:
|
||||
|
||||
Apply the files in `clusters/` manually. They will sync the files in `infrastructure/` and `apps/` dir of the Git repo.
|
||||
```yaml
|
||||
$ vela status infra-gitops
|
||||
About:
|
||||
|
||||
#### Directory `apps/`
|
||||
Name: infra-gitops
|
||||
Namespace: default
|
||||
Created at: 2022-06-30 14:52:33 +0800 CST
|
||||
Status: running
|
||||
|
||||
The file in `apps/` is a simple application with database information and Ingress. The app serves HTTP service and connects to a MySQL database. In the '/' path, it will display the version in the code; in the `/db` path, it will list the data in database.
|
||||
Workflow:
|
||||
|
||||
mode: DAG
|
||||
finished: true
|
||||
Suspend: false
|
||||
Terminated: false
|
||||
Steps
|
||||
- id:dgatat8jag
|
||||
name:database-config
|
||||
type:apply-component
|
||||
phase:succeeded
|
||||
message:
|
||||
|
||||
Services:
|
||||
|
||||
- Name: database-config
|
||||
Cluster: local Namespace: default
|
||||
Type: kustomize
|
||||
Healthy
|
||||
No trait applied
|
||||
```
|
||||
|
||||
As you can see, the GitOps application is running successfully. At this point, the application continuously pulls the configuration from the repository and syncs across the cluster at 10-minute intervals.
|
||||
|
||||
Looking at the resources in the cluster, you can find that the `server` Application and the `server-config` ConfigMap have been automatically deployed.
|
||||
|
||||
```bash
|
||||
$ vela ls
|
||||
APP COMPONENT TYPE TRAITS PHASE HEALTHY STATUS CREATED-TIME
|
||||
infra-gitops database-config kustomize running healthy 2022-06-30 14:52:33 +0800 CST
|
||||
server server webservice running healthy Ready:1/1 2022-06-30 14:52:35 +0800 CST
|
||||
|
||||
$ kubectl get configmap
|
||||
NAME DATA AGE
|
||||
server-config 1 2m58s
|
||||
```
|
||||
|
||||
## Watch the image repositories and synchronize automatically
|
||||
|
||||
GitOps can also watch your image repository, get the latest image version, and update the configuration in your code repository with the latest version, so as to achieve the purpose of automatically updating the image.
|
||||
|
||||
Suppose the directory structure of our repository is as follows:
|
||||
|
||||
```shell
|
||||
├── application
|
||||
└── my-app.yaml
|
||||
```
|
||||
|
||||
The `my-app.yaml` in the application is as follows:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
|
|
@ -88,265 +117,68 @@ metadata:
|
|||
namespace: default
|
||||
spec:
|
||||
components:
|
||||
- name: my-server
|
||||
- name: my-app
|
||||
type: webservice
|
||||
properties:
|
||||
image: <your image address> # {"$imagepolicy": "default:apps"}
|
||||
port: 8088
|
||||
env:
|
||||
- name: DB_HOST
|
||||
value: mysql-cluster-mysql.default.svc.cluster.local:3306
|
||||
- name: DB_PASSWORD
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: mysql-secret
|
||||
key: ROOT_PASSWORD
|
||||
traits:
|
||||
- type: ingress
|
||||
properties:
|
||||
domain: testsvc.example.com
|
||||
http:
|
||||
/: 8088
|
||||
image: nginx # {"$imagepolicy": "default:image-gitops"}
|
||||
```
|
||||
|
||||
#### Directory `infrastructure/`
|
||||
> Note that there is a `# {"$imagepolicy": "default:image-gitops"}` comment after the image field. KubeVela will update the corresponding image field through this annotation. `default:image-gitops` is the namespace and name of the GitOps application component we will deploy.
|
||||
|
||||
The `infrastructure/` contains the config of some infrastructures like database. In the following, we will use [MySQL operator](https://github.com/bitpoke/mysql-operator) to deploy a MySQL cluster.
|
||||
|
||||
> Notice that there must be a secret in your cluster with MySQL password specified in key `ROOT_PASSWORD`.
|
||||
Deploy the following KubeVela GitOps application:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: mysql
|
||||
namespace: default
|
||||
name: image-gitops
|
||||
spec:
|
||||
components:
|
||||
- name: mysql-controller
|
||||
type: helm
|
||||
properties:
|
||||
repoType: helm
|
||||
url: https://presslabs.github.io/charts
|
||||
chart: mysql-operator
|
||||
version: "0.4.0"
|
||||
- name: mysql-cluster
|
||||
type: raw
|
||||
dependsOn:
|
||||
- mysql-controller
|
||||
properties:
|
||||
apiVersion: mysql.presslabs.org/v1alpha1
|
||||
kind: MysqlCluster
|
||||
metadata:
|
||||
name: mysql-cluster
|
||||
spec:
|
||||
replicas: 1
|
||||
# replace it with your secret
|
||||
secretName: mysql-secret
|
||||
- name: image-gitops
|
||||
type: kustomize
|
||||
properties:
|
||||
repoType: git
|
||||
# replace it with your repo url
|
||||
url: https://github.com/FogDong/KubeVela-GitOps-Infra-Demo
|
||||
# replace it with your git secret, GitOps will update the files in your repository with the latest image, which requires write permission
|
||||
secretRef: git-secret
|
||||
pullInterval: 1m
|
||||
git:
|
||||
# the branch name
|
||||
branch: image
|
||||
# the path to sync
|
||||
path: ./application
|
||||
imageRepository:
|
||||
# replace it with your image url
|
||||
image: ghcr.io/fogdong/test-fog
|
||||
# if it's a private image registry, use `kubectl create secret docker-registry` to create the secret
|
||||
# secretRef: imagesecret
|
||||
filterTags:
|
||||
# filter the image tag
|
||||
pattern: '^master-[a-f0-9]+-(?P<ts>[0-9]+)'
|
||||
extract: '$ts'
|
||||
# use the policy to sort the latest image tag and update
|
||||
policy:
|
||||
numerical:
|
||||
order: asc
|
||||
# add more commit message
|
||||
commitMessage: "Image: {{range .Updated.Images}}{{println .}}{{end}}"
|
||||
```
|
||||
|
||||
#### Apply the files in `clusters/`
|
||||
After the application is deployed successfully, you can see that the `my-app` application has also been automatically deployed. At this point, the image in `my-app` is `nginx`:
|
||||
|
||||
After storing bellow files in the Git config repo, we need to apply the GitOps config files in `clusters/` manually.
|
||||
|
||||
First, apply the `clusters/infra.yaml` to cluster, we can see that the MySQL in `infrastructure/` is automatically deployed:
|
||||
|
||||
```shell
|
||||
vela up -f clusters/infra.yaml
|
||||
```
|
||||
|
||||
```shell
|
||||
```bash
|
||||
$ vela ls
|
||||
|
||||
APP COMPONENT TYPE TRAITS PHASE HEALTHY STATUS CREATED-TIME
|
||||
infra database-config kustomize running healthy 2021-09-26 20:48:09 +0800 CST
|
||||
mysql mysql-controller helm running healthy 2021-09-26 20:48:11 +0800 CST
|
||||
└─ mysql-cluster raw running healthy 2021-09-26 20:48:11 +0800 CST
|
||||
APP COMPONENT TYPE TRAITS PHASE HEALTHY STATUS CREATED-TIME
|
||||
image-gitops image-gitops kustomize running healthy 2022-06-30 15:16:30 +0800 CST
|
||||
my-app my-app webservice running healthy Ready:1/1 2022-06-30 15:16:31 +0800 CST
|
||||
```
|
||||
|
||||
Apply the `clusters/apps.yaml` to cluster, we can see that the application in `apps/` is automatically deployed:
|
||||
After a period of time, the imageRepository we configured will automatically pull the latest image we want and update the application image in the repository.
|
||||
|
||||
```shell
|
||||
vela up -f clusters/apps.yaml
|
||||
```
|
||||
At this point, you can see a commit from `kubevelabot` in the config repository, which replaces the `nginx` image with the latest image from our own repository. Commits are prefixed with `Update image automatically.`. You can also append the information you want in the `commitMessage` field with `{{range .Updated.Images}}{{println .}}{{end}}`.
|
||||
|
||||
```shell
|
||||
APP COMPONENT TYPE TRAITS PHASE HEALTHY STATUS CREATED-TIME
|
||||
apps apps kustomize running healthy 2021-09-27 16:55:53 +0800 CST
|
||||
infra database-config kustomize running healthy 2021-09-26 20:48:09 +0800 CST
|
||||
my-app my-server webservice ingress running healthy 2021-09-27 16:55:55 +0800 CST
|
||||
mysql mysql-controller helm running healthy 2021-09-26 20:48:11 +0800 CST
|
||||
└─ mysql-cluster raw running healthy 2021-09-26 20:48:11 +0800 CST
|
||||
```
|
||||
|
||||
By deploying the KubeVela GitOps config files, we now automatically apply the application and database in cluster.
|
||||
|
||||
`curl` the Ingress of the app, we can see that the current version is `0.1.5` and the application is connected to the database successfully:
|
||||
|
||||
```shell
|
||||
$ kubectl get ingress
|
||||
NAME CLASS HOSTS ADDRESS PORTS AGE
|
||||
my-server <none> testsvc.example.com <ingress-ip> 80 162m
|
||||
|
||||
$ curl -H "Host:testsvc.example.com" http://<ingress-ip>
|
||||
Version: 0.1.5
|
||||
|
||||
$ curl -H "Host:testsvc.example.com" http://<ingress-ip>/db
|
||||
User: KubeVela
|
||||
Description: It's a test user
|
||||
```
|
||||
|
||||
### Modify the config for GitOps trigger
|
||||
|
||||
After the first deployment, we can modify the files in config repo to update the applications in the cluster.
|
||||
|
||||
Modify the domain of the application's Ingress:
|
||||
|
||||
```yaml
|
||||
...
|
||||
traits:
|
||||
- type: ingress
|
||||
properties:
|
||||
domain: kubevela.example.com
|
||||
http:
|
||||
/: 8089
|
||||
```
|
||||
|
||||
Check the Ingress in cluster after a while:
|
||||
|
||||
```shell
|
||||
NAME CLASS HOSTS ADDRESS PORTS AGE
|
||||
my-server <none> kubevela.example.com <ingress-ip> 80 162m
|
||||
```
|
||||
|
||||
The host of the Ingress has been updated successfully!
|
||||
|
||||
In this way, we can edit the files in the Git repo to update the cluster.
|
||||
|
||||
## For developers
|
||||
|
||||
Developers writes the application source code and push it to a Git repo (aka app repo). Once app repo updates, the CI will build the image and push it to the image registry. KubeVela watches the image registry, and updates the image in config repo. Finally, it will apply the config to the cluster.
|
||||
|
||||
User can update the configuration in the cluster automatically when the code is updated.
|
||||
|
||||
|
||||
|
||||
### Setup App Code Repository
|
||||
|
||||
Setup a Git repository with source code and Dockerfile.
|
||||
|
||||
The app serves HTTP service and connects to a MySQL database. In the '/' path, it will display the version in the code; in the `/db` path, it will list the data in database.
|
||||
|
||||
```go
|
||||
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
|
||||
_, _ = fmt.Fprintf(w, "Version: %s\n", VERSION)
|
||||
})
|
||||
http.HandleFunc("/db", func(w http.ResponseWriter, r *http.Request) {
|
||||
rows, err := db.Query("select * from userinfo;")
|
||||
if err != nil {
|
||||
_, _ = fmt.Fprintf(w, "Error: %v\n", err)
|
||||
}
|
||||
for rows.Next() {
|
||||
var username string
|
||||
var desc string
|
||||
err = rows.Scan(&username, &desc)
|
||||
if err != nil {
|
||||
_, _ = fmt.Fprintf(w, "Scan Error: %v\n", err)
|
||||
}
|
||||
_, _ = fmt.Fprintf(w, "User: %s \nDescription: %s\n\n", username, desc)
|
||||
}
|
||||
})
|
||||
|
||||
if err := http.ListenAndServe(":8088", nil); err != nil {
|
||||
panic(err.Error())
|
||||
}
|
||||
```
|
||||
|
||||
In this tutorial, we will setup a CI pipeline using GitHub Actions to build the image and push it to a registry. The code and configuration files are from the [Example Repo](https://github.com/kubevela/samples/tree/master/09.GitOps_Demo/for-developers/app-code).
|
||||
|
||||
## Create Git Secret for KubeVela committing to Config Repo
|
||||
|
||||
After the new image is pushed to the image registry, KubeVela will be notified and update the `Application` file in the Git repository and cluster. Therefore, we need a secret with Git information for KubeVela to commit to the Git repository. Fill the following yaml files with your password and apply it to the cluster:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: my-secret
|
||||
type: kubernetes.io/basic-auth
|
||||
stringData:
|
||||
username: <your username>
|
||||
password: <your password>
|
||||
```
|
||||
|
||||
## Setup Config Repository
|
||||
|
||||
The configuration repository is almost the same as the previous configuration, you only need to add the image registry config to the file. For more details, please refer to [Example Repository](https://github.com/kubevela/samples/tree/master/09.GitOps_Demo/for-developers/kubevela-config).
|
||||
|
||||
Add the config of image registry in `clusters/apps.yaml`, it listens for image updates in the image registry:
|
||||
|
||||
```yaml
|
||||
...
|
||||
imageRepository:
|
||||
image: <your image>
|
||||
# if it's a private image registry, use `kubectl create secret docker-registry` to create the secret
|
||||
# secretRef: imagesecret
|
||||
filterTags:
|
||||
# filter the image tag
|
||||
pattern: '^master-[a-f0-9]+-(?P<ts>[0-9]+)'
|
||||
extract: '$ts'
|
||||
# use the policy to sort the latest image tag and update
|
||||
policy:
|
||||
numerical:
|
||||
order: asc
|
||||
# add more commit message
|
||||
commitMessage: "Image: {{range .Updated.Images}}{{println .}}{{end}}"
|
||||
```
|
||||
|
||||
Modify the image field in `apps/my-app.yaml` and add annotation `# {"$imagepolicy": "default:apps"}`.
|
||||
Notice that KubeVela will only be able to modify the image field if the annotation is added after the field. `default:apps` is `namespace:name` of the GitOps config file above.
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
components:
|
||||
- name: my-server
|
||||
type: webservice
|
||||
properties:
|
||||
image: ghcr.io/fogdong/test-fog:master-cba5605f-1632714412 # {"$imagepolicy": "default:apps"}
|
||||
```
|
||||
|
||||
After update the files in `clusters/` to cluster, we can then update the application by modifying the code.
|
||||
|
||||
## Modify the code
|
||||
|
||||
Change the `Version` to `0.1.6` and modify the data in database:
|
||||
|
||||
```go
|
||||
const VERSION = "0.1.6"
|
||||
|
||||
...
|
||||
|
||||
func InsertInitData(db *sql.DB) {
|
||||
stmt, err := db.Prepare(insertInitData)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
defer stmt.Close()
|
||||
|
||||
_, err = stmt.Exec("KubeVela2", "It's another test user")
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Commit the change to the Git Repository, we can see that our CI pipelines has built the image and push it to the image registry.
|
||||
|
||||
KubeVela will listen to the image registry and update the `apps/my-app.yaml` in Git Repository with the latest image tag.
|
||||
|
||||
We can see that there is a commit form `kubevelabot`, the commit message is always with a prefix `Update image automatically.` You can use format like `{{range .Updated.Images}}{{println .}}{{end}}` to specify the image name in the `commitMessage` field.
|
||||
|
||||
|
||||
|
||||
|
||||
> Note that if you want to put the code and config in the same repository, you need to filter out the commit from KubeVela in CI configuration like below to avoid the repeat build of pipeline.
|
||||
>
|
||||
|
|
@ -356,36 +188,12 @@ We can see that there is a commit form `kubevelabot`, the commit message is alwa
|
|||
> if: "!contains(github.event.head_commit.message, 'Update image automatically')"
|
||||
> ```
|
||||
|
||||
Re-check the `Application` in cluster, we can see that the image of the `my-app` has been updated after a while.
|
||||
Re-check the Application in cluster, we can see that the image of the `my-app` has been updated after a while.
|
||||
|
||||
> KubeVela polls the latest information from the code and image repo periodically (at an interval that can be customized):
|
||||
> * When the `Application` file in the Git repository is updated, KubeVela will update the `Application` in the cluster based on the latest configuration.
|
||||
> * When the Application file in the Git repository is updated, KubeVela will update the Application in the cluster based on the latest configuration.
|
||||
> * When a new tag is added to the image registry, KubeVela will filter out the latest tag based on your policy and update it to Git repository. When the files in the repository are updated, KubeVela repeats the first step and updates the files in the cluster, thus achieving automatic deployment.
|
||||
|
||||
We can `curl` to `Ingress` to see the current version and data:
|
||||
## More
|
||||
|
||||
```shell
|
||||
$ kubectl get ingress
|
||||
NAME CLASS HOSTS ADDRESS PORTS AGE
|
||||
my-server <none> kubevela.example.com <ingress-ip> 80 162m
|
||||
|
||||
$ curl -H "Host:kubevela.example.com" http://<ingress-ip>
|
||||
Version: 0.1.6
|
||||
|
||||
$ curl -H "Host:kubevela.example.com" http://<ingress-ip>/db
|
||||
User: KubeVela
|
||||
Description: It's a test user
|
||||
|
||||
User: KubeVela2
|
||||
Description: It's another test user
|
||||
```
|
||||
|
||||
The `Version` has been updated successfully! Now we're done with everything from changing the code to automatically applying to the cluster.
|
||||
|
||||
## Summary
|
||||
|
||||
For platform admins/SREs, they update the config repo to operate the application and infrastructure. KubeVela will synchronize the config to the cluster, simplifying the deployment process.
|
||||
|
||||
For end users/developers, they write the source code, push it to Git, and then re-deployment will happen. It will make CI to build the image. KubeVela will then update the image field and apply the deployment config.
|
||||
|
||||
By integrating with GitOps, KubeVela helps users speed up deployment and simplify continuous deployment.
|
||||
You can also check out GitOps [blog](https://kubevela.io/blog/2021/10/10/kubevela-gitops) and [video practice](https://kubevela.io/videos/best-practice/gitops ) to better experience and use GitOps.
|
||||
|
|
|
|||
|
|
@ -2,322 +2,7 @@
|
|||
title: Definition Objects
|
||||
---
|
||||
|
||||
This documentation explains `ComponentDefinition` and `TraitDefinition` in detail.
|
||||
|
||||
## Overview
|
||||
|
||||
Essentially, a definition object in KubeVela is a programmable build block. A definition object normally includes several information to model a certain platform capability that would used in further application deployment:
|
||||
- **Capability Indicator**
|
||||
- `ComponentDefinition` uses `spec.workload` to indicate the workload type of this component.
|
||||
- `TraitDefinition` uses `spec.definitionRef` to indicate the provider of this trait.
|
||||
- **Interoperability Fields**
|
||||
- they are for the platform to ensure a trait can work with given workload type. Hence only `TraitDefinition` has these fields.
|
||||
- **Capability Encapsulation and Abstraction** defined by `spec.schematic`
|
||||
- this defines the **templating and parametering** (i.e. encapsulation) of this capability.
|
||||
|
||||
Hence, the basic structure of definition object is as below:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: XxxDefinition
|
||||
metadata:
|
||||
name: <definition name>
|
||||
spec:
|
||||
...
|
||||
schematic:
|
||||
cue:
|
||||
# cue template ...
|
||||
helm:
|
||||
# Helm chart ...
|
||||
# ... interoperability fields
|
||||
```
|
||||
|
||||
Let's explain these fields one by one.
|
||||
|
||||
### Capability Indicator
|
||||
|
||||
In `ComponentDefinition`, the indicator of workload type is declared as `spec.workload`.
|
||||
|
||||
Below is a definition for *Web Service* in KubeVela:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
metadata:
|
||||
name: webservice
|
||||
namespace: default
|
||||
annotations:
|
||||
definition.oam.dev/description: "Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers."
|
||||
spec:
|
||||
workload:
|
||||
definition:
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
...
|
||||
```
|
||||
|
||||
In above example, it claims to leverage Kubernetes Deployment (`apiVersion: apps/v1`, `kind: Deployment`) as the workload type for component.
|
||||
|
||||
### Interoperability Fields
|
||||
|
||||
The interoperability fields are **trait only**. An overall view of interoperability fields in a `TraitDefinition` is show as below.
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: TraitDefinition
|
||||
metadata:
|
||||
name: ingress
|
||||
spec:
|
||||
appliesToWorkloads:
|
||||
- deployments.apps
|
||||
conflictsWith:
|
||||
- service
|
||||
workloadRefPath: spec.workloadRef
|
||||
podDisruptive: false
|
||||
```
|
||||
|
||||
Let's explain them in detail.
|
||||
|
||||
#### `.spec.appliesToWorkloads`
|
||||
|
||||
This field defines the constraints that what kinds of workloads this trait is allowed to apply to.
|
||||
- It accepts an array of string as value.
|
||||
- Each item in the array refers to one or a group of workload types to which this trait is allowed to apply.
|
||||
|
||||
There are three approaches to denote one or a group of workload types.
|
||||
|
||||
- `ComponentDefinition` definition reference (CRD name), e.g., `deployments.apps`
|
||||
- Resource group of `ComponentDefinition` definition reference prefixed with `*.`, e.g., `*.apps`, `*.oam.dev`. This means the trait is allowed to apply to any workloads in this group.
|
||||
- `*` means this trait is allowed to apply to any workloads
|
||||
|
||||
If this field is omitted, it means this trait is allowed to apply to any workload types.
|
||||
|
||||
KubeVela will raise an error if a trait is applied to a workload type which is NOT included in the `appliesToWorkloads`.
|
||||
This documentation has been merged into [Definition Protocol](./oam/x-definition).
|
||||
|
||||
|
||||
##### `.spec.conflictsWith`
|
||||
|
||||
This field defines that constraints that what kinds of traits are conflicting with this trait, if they are applied to the same workload.
|
||||
- It accepts an array of string as value.
|
||||
- Each item in the array refers to one or a group of traits.
|
||||
|
||||
There are four approaches to denote one or a group of workload types.
|
||||
|
||||
- `TraitDefinition` name, e.g., `ingress`
|
||||
- Resource group of `TraitDefinition` definition reference prefixed with `*.`, e.g., `*.networking.k8s.io`. This means the trait is conflicting with any traits in this group.
|
||||
- `*` means this trait is conflicting with any other trait.
|
||||
|
||||
If this field is omitted, it means this trait is NOT conflicting with any traits.
|
||||
|
||||
##### `.spec.workloadRefPath`
|
||||
|
||||
This field defines the field path of the trait which is used to store the reference of the workload to which the trait is applied.
|
||||
- It accepts a string as value, e.g., `spec.workloadRef`.
|
||||
|
||||
If this field is set, KubeVela core will automatically fill the workload reference into target field of the trait. Then the trait controller can get the workload reference from the trait latter. So this field usually accompanies with the traits whose controllers relying on the workload reference at runtime.
|
||||
|
||||
Please check [scaler](https://github.com/kubevela/kubevela/blob/master/charts/vela-core/templates/defwithtemplate/scaler.yaml) trait as a demonstration of how to set this field.
|
||||
|
||||
##### `.spec.podDisruptive`
|
||||
|
||||
This field defines that adding/updating the trait will disruptive the pod or not.
|
||||
In this example, the answer is not, so the field is `false`, it will not affect the pod when the trait is added or updated.
|
||||
If the field is `true`, then it will cause the pod to disruptive and restart when the trait is added or updated.
|
||||
By default, the value is `false` which means this trait will not affect.
|
||||
Please take care of this field, it's really important and useful for serious large scale production usage scenarios.
|
||||
|
||||
### Capability Encapsulation and Abstraction
|
||||
|
||||
The programmable template of given capability are defined in `spec.schematic` field. For example, below is the full definition of *Web Service* type in KubeVela:
|
||||
|
||||
<details>
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
metadata:
|
||||
name: webservice
|
||||
namespace: default
|
||||
annotations:
|
||||
definition.oam.dev/description: "Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers."
|
||||
spec:
|
||||
workload:
|
||||
definition:
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
schematic:
|
||||
cue:
|
||||
template: |
|
||||
output: {
|
||||
apiVersion: "apps/v1"
|
||||
kind: "Deployment"
|
||||
spec: {
|
||||
selector: matchLabels: {
|
||||
"app.oam.dev/component": context.name
|
||||
}
|
||||
|
||||
template: {
|
||||
metadata: labels: {
|
||||
"app.oam.dev/component": context.name
|
||||
}
|
||||
|
||||
spec: {
|
||||
containers: [{
|
||||
name: context.name
|
||||
image: parameter.image
|
||||
|
||||
if parameter["cmd"] != _|_ {
|
||||
command: parameter.cmd
|
||||
}
|
||||
|
||||
if parameter["env"] != _|_ {
|
||||
env: parameter.env
|
||||
}
|
||||
|
||||
if context["config"] != _|_ {
|
||||
env: context.config
|
||||
}
|
||||
|
||||
ports: [{
|
||||
containerPort: parameter.port
|
||||
}]
|
||||
|
||||
if parameter["cpu"] != _|_ {
|
||||
resources: {
|
||||
limits:
|
||||
cpu: parameter.cpu
|
||||
requests:
|
||||
cpu: parameter.cpu
|
||||
}
|
||||
}
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
parameter: {
|
||||
// +usage=Which image would you like to use for your service
|
||||
// +short=i
|
||||
image: string
|
||||
|
||||
// +usage=Commands to run in the container
|
||||
cmd?: [...string]
|
||||
|
||||
// +usage=Which port do you want customer traffic sent to
|
||||
// +short=p
|
||||
port: *80 | int
|
||||
// +usage=Define arguments by using environment variables
|
||||
env?: [...{
|
||||
// +usage=Environment variable name
|
||||
name: string
|
||||
// +usage=The value of the environment variable
|
||||
value?: string
|
||||
// +usage=Specifies a source the value of this var should come from
|
||||
valueFrom?: {
|
||||
// +usage=Selects a key of a secret in the pod's namespace
|
||||
secretKeyRef: {
|
||||
// +usage=The name of the secret in the pod's namespace to select from
|
||||
name: string
|
||||
// +usage=The key of the secret to select from. Must be a valid secret key
|
||||
key: string
|
||||
}
|
||||
}
|
||||
}]
|
||||
// +usage=Number of CPU units for the service, like `0.5` (0.5 CPU core), `1` (1 CPU core)
|
||||
cpu?: string
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
The specification of `schematic` is explained in following CUE and Helm specific documentations.
|
||||
|
||||
Also, the `schematic` filed enables you to render UI forms directly based on them, please check the [Generate Forms from Definitions](openapi-v3-json-schema) section about how to.
|
||||
|
||||
## Definition Revisions
|
||||
|
||||
In KubeVela, definition entities are mutable. Each time a `ComponentDefinition` or `TraitDefinition` is updated, a corresponding `DefinitionRevision` will be generated to snapshot this change. Hence, KubeVela allows user to reference a specific revision of definition to declare an application.
|
||||
|
||||
For example, we can design a new parameter named `args` for the `webservice` component definition by applying a new definition with same name as below.
|
||||
|
||||
```shell
|
||||
vela show webservice
|
||||
```
|
||||
```console
|
||||
# Properties
|
||||
+-------+----------------------------------------------------+----------+----------+---------+
|
||||
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
|
||||
+-------+----------------------------------------------------+----------+----------+---------+
|
||||
| cmd | Commands to run in the container | []string | false | |
|
||||
... // skip
|
||||
```
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubevela/kubevela/master/docs/examples/definition-revision/webservice-v2.yaml
|
||||
```
|
||||
|
||||
The change will take effect immediately.
|
||||
|
||||
```shell
|
||||
vela show webservice
|
||||
```
|
||||
```console
|
||||
# Properties
|
||||
+-------+----------------------------------------------------+----------+----------+---------+
|
||||
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
|
||||
+-------+----------------------------------------------------+----------+----------+---------+
|
||||
| cmd | Commands to run in the container | []string | false | |
|
||||
| args | Arguments to the cmd | []string | false | |
|
||||
... // skip
|
||||
```
|
||||
|
||||
We will see a new definition revision will be automatically generated, `v2` is the latest version, `v1` is the previous one.
|
||||
|
||||
```shell
|
||||
kubectl get definitionrevision -l="componentdefinition.oam.dev/name=webservice" -n vela-system
|
||||
```
|
||||
```console
|
||||
NAME REVISION HASH TYPE
|
||||
webservice-v1 1 3f6886d9832021ba Component
|
||||
webservice-v2 2 b3b9978e7164d973 Component
|
||||
```
|
||||
|
||||
### Specify Definition Revision in Application
|
||||
|
||||
Users can specify the revision with `@version` approach, for example, if a user want to stick to using the `v1` revision of `webservice` component:
|
||||
|
||||
```yaml
|
||||
# testapp.yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: testapp
|
||||
spec:
|
||||
components:
|
||||
- name: server
|
||||
type: webservice@v1
|
||||
properties:
|
||||
image: foo
|
||||
cmd:
|
||||
- sleep
|
||||
- '1000'
|
||||
```
|
||||
If no revision is specified, KubeVela will always use the latest revision for a given component definition.
|
||||
|
||||
```yaml
|
||||
# testapp.yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: testapp
|
||||
spec:
|
||||
components:
|
||||
- name: server
|
||||
type: webservice # type: webservice@v2
|
||||
properties:
|
||||
image: foo
|
||||
cmd:
|
||||
- sleep
|
||||
- '1000'
|
||||
args:
|
||||
- wait
|
||||
```
|
||||
The definition revision part has been migrated to [here](./x-def-version).
|
||||
|
|
|
|||
|
|
@ -6,6 +6,36 @@ KubeVela is fully programmable via [CUE](https://cuelang.org), while it leverage
|
|||
|
||||
You can [manage the definition](../cue/definition-edit) in CUE and the `vela def` command will render it into Kubernetes API with the following protocol.
|
||||
|
||||
## Overview
|
||||
|
||||
Essentially, a definition object in KubeVela is a programmable building block. A definition object normally includes several information to model a certain platform capability that would used in further application deployment:
|
||||
- **Capability Indicator**
|
||||
- `ComponentDefinition` uses `spec.workload` to indicate the workload type of this component.
|
||||
- `TraitDefinition` uses `spec.definition` to indicate the provider of this trait.
|
||||
- These indicators can be auto detected, so they're not necessary.
|
||||
- **Interoperability Fields**
|
||||
- they are for the platform to ensure a trait can work with given workload type. Hence only `TraitDefinition` has these fields.
|
||||
- **Capability Encapsulation and Abstraction** defined by `spec.schematic`
|
||||
- this defines the **templating and parametering** (i.e. encapsulation) of this capability.
|
||||
|
||||
Hence, the basic structure of definition object is as below:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: XxxDefinition
|
||||
metadata:
|
||||
name: <definition name>
|
||||
spec:
|
||||
...
|
||||
schematic:
|
||||
cue:
|
||||
# cue template ...
|
||||
helm:
|
||||
# Helm chart ...
|
||||
# ... interoperability fields
|
||||
```
|
||||
|
||||
Let's explain them one by one.
|
||||
|
||||
## ComponentDefinition
|
||||
|
||||
|
|
@ -25,7 +55,7 @@ metadata:
|
|||
annotations:
|
||||
definition.oam.dev/description: <Function description>
|
||||
spec:
|
||||
workload: # Workload description
|
||||
workload: # Workload Capability Indicator
|
||||
definition:
|
||||
apiVersion: <Kubernetes Workload resource group>
|
||||
kind: <Kubernetes Workload types>
|
||||
|
|
@ -33,7 +63,32 @@ spec:
|
|||
cue: # Details of components defined by CUE language
|
||||
template: <CUE format template>
|
||||
```
|
||||
Here is a complete example to introduce how to use ComponentDefinition.
|
||||
|
||||
The indicator of workload type is declared as `spec.workload`.
|
||||
|
||||
Below is a definition for *Web Service* in KubeVela:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
metadata:
|
||||
name: webservice
|
||||
namespace: default
|
||||
annotations:
|
||||
definition.oam.dev/description: "Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers."
|
||||
spec:
|
||||
workload:
|
||||
definition:
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
...
|
||||
```
|
||||
|
||||
In above example, it claims to leverage Kubernetes Deployment (`apiVersion: apps/v1`, `kind: Deployment`) as the workload type for component.
|
||||
|
||||
The programmable template of given capability are defined in `spec.schematic` field. For example, below is the full definition of *Helm* type in KubeVela:
|
||||
|
||||
<details>
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
|
|
@ -135,6 +190,9 @@ spec:
|
|||
...
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
The specification of `schematic` is explained in the [CUE with KubeVela](../cue/basic) documentations.
|
||||
|
||||
## TraitDefinition
|
||||
|
||||
|
|
@ -168,6 +226,56 @@ spec:
|
|||
template: <CUE format template>
|
||||
```
|
||||
|
||||
The interoperability fields are **trait only**. Let's explain them in detail.
|
||||
|
||||
### `.spec.appliesToWorkloads`
|
||||
|
||||
This field defines the constraints that what kinds of workloads this trait is allowed to apply to.
|
||||
- It accepts an array of string as value.
|
||||
- Each item in the array refers to one or a group of workload types to which this trait is allowed to apply.
|
||||
|
||||
There are three approaches to denote one or a group of workload types.
|
||||
|
||||
- `ComponentDefinition` definition reference (CRD name), e.g., `deployments.apps`
|
||||
- Resource group of `ComponentDefinition` definition reference prefixed with `*.`, e.g., `*.apps`, `*.oam.dev`. This means the trait is allowed to apply to any workloads in this group.
|
||||
- `*` means this trait is allowed to apply to any workloads
|
||||
|
||||
If this field is omitted, it means this trait is allowed to apply to any workload types.
|
||||
|
||||
KubeVela will raise an error if a trait is applied to a workload type which is NOT included in the `appliesToWorkloads`.
|
||||
|
||||
|
||||
### `.spec.conflictsWith`
|
||||
|
||||
This field defines that constraints that what kinds of traits are conflicting with this trait, if they are applied to the same workload.
|
||||
- It accepts an array of string as value.
|
||||
- Each item in the array refers to one or a group of traits.
|
||||
|
||||
There are four approaches to denote one or a group of workload types.
|
||||
|
||||
- `TraitDefinition` name, e.g., `ingress`
|
||||
- Resource group of `TraitDefinition` definition reference prefixed with `*.`, e.g., `*.networking.k8s.io`. This means the trait is conflicting with any traits in this group.
|
||||
- `*` means this trait is conflicting with any other trait.
|
||||
|
||||
If this field is omitted, it means this trait is NOT conflicting with any traits.
|
||||
|
||||
### `.spec.workloadRefPath`
|
||||
|
||||
This field defines the field path of the trait which is used to store the reference of the workload to which the trait is applied.
|
||||
- It accepts a string as value, e.g., `spec.workloadRef`.
|
||||
|
||||
If this field is set, KubeVela core will automatically fill the workload reference into target field of the trait. Then the trait controller can get the workload reference from the trait latter. So this field usually accompanies with the traits whose controllers relying on the workload reference at runtime.
|
||||
|
||||
Please check [scaler](https://github.com/kubevela/kubevela/blob/master/charts/vela-core/templates/defwithtemplate/scaler.yaml) trait as a demonstration of how to set this field.
|
||||
|
||||
### `.spec.podDisruptive`
|
||||
|
||||
This field defines that adding/updating the trait will disruptive the pod or not.
|
||||
In this example, the answer is not, so the field is `false`, it will not affect the pod when the trait is added or updated.
|
||||
If the field is `true`, then it will cause the pod to disruptive and restart when the trait is added or updated.
|
||||
By default, the value is `false` which means this trait will not affect.
|
||||
Please take care of this field, it's really important and useful for serious large scale production usage scenarios.
|
||||
|
||||
Let's look at a practical example:
|
||||
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -2,6 +2,8 @@
|
|||
title: Version Control for Definition
|
||||
---
|
||||
|
||||
> A better version control management is comming in v1.5, refer to [this issue](https://github.com/kubevela/kubevela/issues/4131) to learn the progress.
|
||||
|
||||
When the capabilities(Component or Trait) changes, KubeVela will generate a definition revision automatically.
|
||||
|
||||
* Check ComponentDefinition Revision
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ $ vela addon disable kruise-rollout
|
|||
|
||||
## Usage
|
||||
|
||||
Kurise rollout addon help to canary rollout your workload no matter defined with [webservice](../../end-user/components/cue/webservice) or contained in a [helm](../../tutorials/helm).
|
||||
Kurise rollout addon help to canary rollout your workload no matter defined with [webservice](../../tutorials/webservice) or contained in a [helm](../../tutorials/helm).
|
||||
|
||||
If your workload is in a helm chart please refer to [doc](../../tutorials/helm-rollout) for more usage info, otherwise please refer to usage of webservice [component](../../end-user/traits/rollout).
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ This section will introduce how to use Rollout Trait to perform a rolling update
|
|||
|
||||
The component supported for rollout is:
|
||||
|
||||
* [webservice](../../end-user/components/cue/webservice)
|
||||
* webservice
|
||||
* worker
|
||||
|
||||
## How to
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 185 KiB |
|
|
@ -116,6 +116,7 @@
|
|||
"how-to/dashboard/application/create-application",
|
||||
"end-user/version-control",
|
||||
"end-user/workflow/component-dependency-parameter",
|
||||
"case-studies/initialize-env",
|
||||
"end-user/policies/apply-once",
|
||||
"end-user/policies/gc"
|
||||
]
|
||||
|
|
|
|||
Loading…
Reference in New Issue