github/kubevela
1
0
Fork 0
mirror of https://github.com/kubevela/kubevela.git synced 2026-08-27 16:17:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add user docs (#1472)

Browse Source
This commit is contained in:
Lei Zhang (Harry)
2021-04-13 15:20:39 +08:00
committed by GitHub
parent 63b348f4d8
commit d8eb7d687c
23 changed files with 560 additions and 680 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+14 -5
View File
@@ -22,13 +22,22 @@ KubeVela is a modern application engine that adapts to your application's needs,
- Gitter: [Discussion](https://gitter.im/oam-dev/community)
- Bi-weekly Community Call: [Meeting Notes](https://docs.google.com/document/d/1nqdFEyULekyksFHtFvgvFAYE-0AMHKoS3RMnaKsarjs)
## What problems does it solve?
## Introduction
Platform-as-a-Service (PaaS) systems enable easy application deployments and everything just works, but this happiness disappears when your application outgrows the capabilities of your platform. This is inevitable regardless of that PaaS is built on Kubernetes or not - the root cause is its inflexible abstractions.
*Developers simply want to deploy.*
KubeVela solves this problem by "Platform-as-Code". Essentially, KubeVela is a Kubernetes add-on that enables you to define platform features (such as workloads, operational behaviors, and cloud services) as reusable [CUE](https://cuelang.org/) or [Helm](https://helm.sh) components, per needs of your application deployment. And when your needs grow, your platform capabilities expand naturally in a programmable approach.
Traditional Platform-as-a-Service (PaaS) systems enable easy application deployments, but this happiness disappears when your application outgrows the capabilities of your platform. This is inevitable regardless of your PaaS is built on Kubernetes or not - the root cause is its inflexibility.
Perfect in flexibility, X-as-Code tends to lead to configuration drift (i.e. the running instances are not in line with the expected configuration). That's why KubeVela is fully built with Kubernetes (instead of a client-side tool), i.e. all its abstractions and capabilities are modeled as code but enforced via battle tested [Kubernetes Control Loop](https://kubernetes.io/docs/concepts/architecture/controller/) which will never leave configuration drift in your clusters.
KubeVela is a modern application deployment system that adapts to your needs. Essentially, KubeVela enables you to define platform capabilities (such as workloads, operational behaviors, and cloud services) as reusable [CUE](https://cuelang.org/) or [Helm](https://helm.sh) components, per needs of your application deployment. And when your needs grow, your platform capabilities expand naturally in a programmable approach.
Perfect in flexibility though, X-as-Code tends to lead to configuration drift. That's why KubeVela is fully built as a [Kubernetes Controller](https://kubernetes.io/docs/concepts/architecture/controller/) instead of a client-side tool, i.e. all its capabilities are modeled as code but enforced with battle tested reconciling loops which will never leave inconsistency in your clusters. Think about *Platform-as-Code* enabled by Kubernetes, CUE and Helm.
With developer experience in mind, KubeVela exposes those programmable platform capabilities as application-centric API shown as below:
- Components - deployable/provisionable entities that composed your application deployment
- e.g. a Kubernetes workload, a MySQL database, or a AWS OSS bucket
- Traits - attachable operational features per your needs
- e.g. autoscaling rules, rollout strategies, ingress rules, sidecars, security policies etc
- Application - full description of your application deployment assembled with components and traits.
## Getting Started
@@ -38,7 +47,7 @@ Perfect in flexibility, X-as-Code tends to lead to configuration drift (i.e. the
## Features
- **Zero-restriction platform** - design and express platform capabilities with CUE and Helm per needs of your application, and let Kubernetes controller guarantee the deployment determinism. GUI forms are automatically generated for capabilities so even your dashboard are fully extensible.
- **Zero-restriction application deployment system** - design and express platform capabilities with CUE and Helm per needs of your application, and let Kubernetes controller guarantee the determinism in the application deployment. GUI forms are automatically generated for capabilities so even your dashboard are fully extensible.
- **Generic progressive rollout framework** - built-in rollout framework and strategies to upgrade your microservice regardless of its workload type (e.g. stateless, stateful, or even custom operators etc).
- **Multi-cluster multi-revision application deployment** - built-in model to deploy or rollout your apps across hybrid infrastructures, with Service Mesh for traffic shifting.
- **Simple and native** - KubeVela is a just simple Kubernetes custom controller, all its capabilities are defined as [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) so they naturally work with any CI/CD or GitOps tools which work with Kubernetes.
docs/en/advanced-install.md
+126
View File
@@ -0,0 +1,126 @@
---
title: Advanced Topics for Installation
---
## Install KubeVela with cert-manager
KubeVela can use cert-manager generate certs for your application if it's available. Note that you need to install cert-manager **before** the KubeVela chart.
```shell script
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager --namespace cert-manager --version v1.2.0 --create-namespace --set installCRDs=true
```
Install kubevela with enabled certmanager:
```shell script
helm install --create-namespace -n vela-system --set admissionWebhooks.certManager.enabled=true kubevela kubevela/vela-core
```
## Install Pre-release
Add flag `--devel` in command `helm search` to choose a pre-release
version in format `<next_version>-rc-master`. It means a release candidate version build on `master` branch,
such as `0.4.0-rc-master`.
```shell script
helm search repo kubevela/vela-core -l --devel
```
```console
NAME CHART VERSION APP VERSION DESCRIPTION
kubevela/vela-core 0.4.0-rc-master 0.4.0-rc-master A Helm chart for KubeVela core
kubevela/vela-core 0.3.2 0.3.2 A Helm chart for KubeVela core
kubevela/vela-core 0.3.1 0.3.1 A Helm chart for KubeVela core
```
And try the following command to install it.
```shell script
helm install --create-namespace -n vela-system kubevela kubevela/vela-core --version <next_version>-rc-master
```
```console
NAME: kubevela
LAST DEPLOYED: Thu Apr 1 19:41:30 2021
NAMESPACE: vela-system
STATUS: deployed
REVISION: 1
NOTES:
Welcome to use the KubeVela! Enjoy your shipping application journey!
```
## Upgrade
### Step 1. Update Helm repo
```shell
helm repo update
```
you can get the new version kubevela chart by run:
```shell
helm search repo kubevela/vela-core -l
```
### Step 2. Upgrade KubeVela CRDs
```shell
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_componentdefinitions.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_workloaddefinitions.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_traitdefinitions.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_applications.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_approllouts.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_applicationrevisions.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_scopedefinitions.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_appdeployments.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_applicationcontexts.yaml
```
> Tips: If you see errors like `* is invalid: spec.scope: Invalid value: "Namespaced": filed is immutable`. Please delete the CRD which reports error and re-apply the kubevela crds.
```shell
kubectl delete crd \
scopedefinitions.core.oam.dev \
traitdefinitions.core.oam.dev \
workloaddefinitions.core.oam.dev
```
### Step 3. Upgrade KubeVela Helm chart
```shell
helm upgrade --install --create-namespace --namespace vela-system kubevela kubevela/vela-core --version <the_new_version>
```
## Clean Up
Run:
```shell script
helm uninstall -n vela-system kubevela
rm -r ~/.vela
```
This will uninstall KubeVela server component and its dependency components.
This also cleans up local CLI cache.
Then clean up CRDs (CRDs are not removed via helm by default):
```shell script
kubectl delete crd \
appdeployments.core.oam.dev \
applicationconfigurations.core.oam.dev \
applicationcontexts.core.oam.dev \
applicationdeployments.core.oam.dev \
applicationrevisions.core.oam.dev \
applications.core.oam.dev \
approllouts.core.oam.dev \
componentdefinitions.core.oam.dev \
components.core.oam.dev \
containerizedworkloads.core.oam.dev \
healthscopes.core.oam.dev \
manualscalertraits.core.oam.dev \
podspecworkloads.standard.oam.dev \
scopedefinitions.core.oam.dev \
traitdefinitions.core.oam.dev \
workloaddefinitions.core.oam.dev
```
docs/en/application.md
+47 -162
View File
@@ -1,14 +1,43 @@
---
title: Application CRD
title: Deploy Application
---
This documentation will walk through how to use `Application` object to define your apps with corresponding operational behaviors in declarative approach.
This documentation will walk through a full application deployment workflow on KubeVela platform.
## Example
## Introduction
The sample application below claimed a `backend` component with *Worker* workload type, and a `frontend` component with *Web Service* workload type.
KubeVela is a fully self-service platform. All capabilities an application deployment needs are maintained as building block modules in this platform. Specifically:
- Components - deployable/provisionable entities that composed your application deployment
- e.g. a Kubernetes workload, a MySQL database, or a AWS OSS bucket
- Traits - attachable operational features per your needs
- e.g. autoscaling rules, rollout strategies, ingress rules, sidecars, security policies etc
Moreover, the `frontend` component claimed `sidecar` and `autoscaler` traits which means the workload will be automatically injected with a `fluentd` sidecar and scale from 1-100 replicas triggered by CPU usage.
## Step 1: Check Capabilities in the Platform
As user of this platform, you could check available components you can deploy, and available traits you can attach.
```console
kubectl get componentdefinitions -n vela-system
NAME WORKLOAD-KIND DESCRIPTION AGE
task Job Describes jobs that run code or a script to completion. 5h52m
webservice Deployment Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers. 5h52m
worker Deployment Describes long-running, scalable, containerized services that running at backend. They do NOT have network endpoint to receive external network traffic. 5h52m
```
```console
kubectl get traitdefinitions -n vela-system
NAME APPLIES-TO DESCRIPTION AGE
ingress ["webservice","worker"] Configures K8s ingress and service to enable web traffic for your service. Please use route trait in cap center for advanced usage. 6h8m
scaler ["webservice","worker"] Configures replicas for your service. 6h8m
```
To show the specification for given capability, you could use `vela` CLI. For example, `vela show webservice` will return full schema of *Web Service* component and `vela show webservice --web` will open its capability reference documentation in your browser.
## Step 2: Design and Deploy Application
In KubeVela, `Application` is the main API to define your application deployment based on available capabilities. Every `Application` could contain multiple components, each of them can be attached with a number of traits per needs.
Now let's define an application composed by *Web Service* and *Worker* components.
```yaml
apiVersion: core.oam.dev/v1beta1
@@ -17,13 +46,6 @@ metadata:
name: website
spec:
components:
- name: backend
type: worker
properties:
image: busybox
cmd:
- sleep
- '1000'
- name: frontend
type: webservice
properties:
@@ -38,11 +60,20 @@ spec:
properties:
name: "sidecar-test"
image: "fluentd"
- name: backend
type: worker
properties:
image: busybox
cmd:
- sleep
- '1000'
```
In this sample, we also attached `sidecar` and `autoscaler` traits to the `frontend` component. So after deployed, the `frontend` component instance (a Kubernetes Deployment workload) will be automatically injected with a `fluentd` sidecar and automatically scale from 1-100 replicas based on CPU usage.
### Deploy the Application
Apply application yaml above, then you'll get the application started
Apply application YAML to Kubernetes, you'll get the application becomes `running`.
```shell
$ kubectl get application -o yaml
@@ -64,7 +95,9 @@ status:
```
You could see a Deployment named `frontend` with a container `fluentd` injected is running.
### Verify the Deployment
You could see a Deployment named `frontend` is running, with port exposed, and with a container `fluentd` injected.
```shell
$ kubectl get deploy frontend
@@ -87,151 +120,3 @@ $ kubectl get HorizontalPodAutoscaler frontend
NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE
frontend Deployment/frontend <unknown>/50% 1 10 1 101m
```
## Under the Hood
In above sample, the `type: worker` means the specification of this component (claimed in following `properties` section) will be enforced by a `ComponentDefinition` object named `worker` as below:
```yaml
apiVersion: core.oam.dev/v1beta1
kind: ComponentDefinition
metadata:
name: worker
annotations:
definition.oam.dev/description: "Describes long-running, scalable, containerized services that running at backend. They do NOT have network endpoint to receive external network traffic."
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
}
}]
}
}
}
}
parameter: {
image: string
cmd?: [...string]
}
```
Hence, the `properties` section of `backend` only supports two parameters: `image` and `cmd`, this is enforced by the `parameter` list of the `.spec.template` field of the definition.
The similar extensible abstraction mechanism also applies to traits.
For example, `type: autoscaler` in `frontend` means its trait specification (i.e. `properties` section)
will be enforced by a `TraitDefinition` object named `autoscaler` as below:
```yaml
apiVersion: core.oam.dev/v1beta1
kind: TraitDefinition
metadata:
annotations:
definition.oam.dev/description: "configure k8s HPA for Deployment"
name: hpa
spec:
appliesToWorkloads:
- webservice
- worker
schematic:
cue:
template: |
outputs: hpa: {
apiVersion: "autoscaling/v2beta2"
kind: "HorizontalPodAutoscaler"
metadata: name: context.name
spec: {
scaleTargetRef: {
apiVersion: "apps/v1"
kind: "Deployment"
name: context.name
}
minReplicas: parameter.min
maxReplicas: parameter.max
metrics: [{
type: "Resource"
resource: {
name: "cpu"
target: {
type: "Utilization"
averageUtilization: parameter.cpuUtil
}
}
}]
}
}
parameter: {
min: *1 | int
max: *10 | int
cpuUtil: *50 | int
}
```
The application also have a `sidecar` trait.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: TraitDefinition
metadata:
annotations:
definition.oam.dev/description: "add sidecar to the app"
name: sidecar
spec:
appliesToWorkloads:
- webservice
- worker
schematic:
cue:
template: |-
patch: {
// +patchKey=name
spec: template: spec: containers: [parameter]
}
parameter: {
name: string
image: string
command?: [...string]
}
```
All the definition objects are expected to be declared and installed by platform team and end users will only focus on `Application` resource.
Please note that the end users of KubeVela do NOT need to know about definition objects, they learn how to use a given capability with visualized forms (or the JSON schema of parameters if they prefer). Please check the [Generate Forms from Definitions](/docs/platform-engineers/openapi-v3-json-schema) section about how this is achieved.
### Conventions and "Standard Contract"
After the `Application` resource is applied to Kubernetes cluster,
the KubeVela runtime will generate and manage the underlying resources instances following below "standard contract" and conventions.
| Label | Description |
| :--: | :---------: |
|`workload.oam.dev/type=<component definition name>` | The name of its corresponding `ComponentDefinition` |
|`trait.oam.dev/type=<trait definition name>` | The name of its corresponding `TraitDefinition` |
|`app.oam.dev/name=<app name>` | The name of the application it belongs to |
|`app.oam.dev/component=<component name>` | The name of the component it belongs to |
|`trait.oam.dev/resource=<name of trait resource instance>` | The name of trait resource instance |
|`app.oam.dev/appRevision=<name of app revision>` | The name of the application revision it belongs to |
docs/en/concepts.md
+1 -1
View File
@@ -64,7 +64,7 @@ spec:
## Building the Abstraction
Unlike most of the higher level abstractions, the `Application` resource in KubeVela is a LEGO-style object and does not even have fixed schema. Instead, it is composed by building blocks (app components and traits etc.) that allow you to on-board platform capabilities to this application definition via your own abstractions.
The `Application` resource in KubeVela is a LEGO-style object and does not even have fixed schema. Instead, it is composed by building blocks (app components and traits etc.) that allow you to on-board platform capabilities to this application definition via your own abstractions.
The building blocks to abstraction and model platform capabilities named `ComponentDefinition` and `TraitDefinition`.
docs/en/developers/references/README.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
title: The Reference Documentation of Capabilities
title: Overview
---
In this documentation, we will show how to check the detailed schema of a given capability (i.e. component type or trait).
docs/en/developers/references/component-types/task.md
+1 -5
View File
@@ -11,11 +11,7 @@ Describes jobs that run code or a script to completion.
List of all configuration options for a `Task` workload type.
```yaml
name: my-app-name
services:
my-service-name:
type: task
...
image: perl
count: 10
cmd: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
docs/en/developers/references/component-types/webservice.md
+1 -5
View File
@@ -11,11 +11,7 @@ Describes long-running, scalable, containerized services that have a stable netw
List of all configuration options for a `Webservice` workload type.
```yaml
name: my-app-name
services:
my-service-name:
type: webservice # could be skipped
...
image: oamdev/testapp:v1
cmd: ["node", "server.js"]
port: 8080
docs/en/developers/references/component-types/worker.md
+1 -5
View File
@@ -11,11 +11,7 @@ Describes long-running, scalable, containerized services that running at backend
List of all configuration options for a `Worker` workload type.
```yaml
name: my-app-name
services:
my-service-name:
type: worker
...
image: oamdev/testapp:v1
cmd: ["node", "server.js"]
```
docs/en/developers/references/traits/autoscale.md
+10 -16
View File
@@ -11,22 +11,16 @@ Automatically scales workloads by resource utilization metrics or cron triggers.
List of all configuration options for a `Autoscale` trait.
```yaml
name: testapp
services:
express-server:
...
autoscale:
min: 1
max: 4
cron:
startAt: "14:00"
duration: "2h"
days: "Monday, Thursday"
replicas: 2
timezone: "America/Los_Angeles"
cpuPercent: 10
...
min: 1
max: 4
cron:
startAt: "14:00"
duration: "2h"
days: "Monday, Thursday"
replicas: 2
timezone: "America/Los_Angeles"
cpuPercent: 10
```
## Properties
docs/en/developers/references/traits/ingress.md
+6 -1
View File
@@ -10,7 +10,12 @@ Configures K8s ingress and service to enable web traffic for your service. Pleas
List of all configuration options for a `Ingress` trait.
```yaml```
```yaml
...
domain: testsvc.example.com
http:
/: 8000
```
## Properties
docs/en/developers/references/traits/metrics.md
+6 -11
View File
@@ -11,17 +11,12 @@ Configures monitoring metrics for your service.
List of all configuration options for a `Metrics` trait.
```yaml
name: my-app-name
services:
my-service-name:
...
metrics:
format: "prometheus"
port: 8080
path: "/metrics"
scheme: "http"
enabled: true
...
format: "prometheus"
port: 8080
path: "/metrics"
scheme: "http"
enabled: true
```
## Properties
docs/en/developers/references/traits/rollout.md
+1 -4
View File
@@ -11,10 +11,7 @@ Configures Canary deployment strategy for your application.
List of all configuration options for a `Rollout` trait.
```yaml
servcies:
express-server:
...
...
rollout:
replicas: 2
stepWeight: 50
docs/en/developers/references/traits/route.md
+6 -11
View File
@@ -11,17 +11,12 @@ Configures external access to your service.
List of all configuration options for a `Route` trait.
```yaml
name: my-app-name
services:
my-service-name:
...
route:
domain: example.com
issuer: tls
rules:
- path: /testapp
rewriteTarget: /
...
domain: example.com
issuer: tls
rules:
- path: /testapp
rewriteTarget: /
```
## Properties
docs/en/developers/references/traits/scaler.md
+1 -5
View File
@@ -11,11 +11,7 @@ Configures replicas for your service.
List of all configuration options for a `Scaler` trait.
```yaml
name: my-app-name
services:
my-service-name:
...
...
scaler:
replicas: 100
```
docs/en/helm/component.md
+1 -1
View File
@@ -8,7 +8,7 @@ In this section, it will introduce how to declare Helm charts as app components
## Prerequisite
* [fluxcd/flux2](../install#3-optional-install-flux2), make sure you have installed the flux2 in the [installation guide](/docs/install).
* Make sure you have enabled Helm support in the [installation guide](/docs/install).
## Declare `ComponentDefinition`
docs/en/install.mdx
+26 -156
View File
@@ -5,17 +5,17 @@ title: Installation
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
If you have installed the kubevale chart before, please read the [Upgrade](#upgrade) step directly.
> For upgrading existing KubeVela, please read the [upgrade guide](./advanced-install#upgrade).
## 1. Setup Kubernetes cluster
## 1. Choose Kubernetes Cluster
Requirements:
- Kubernetes cluster >= v1.15.0
- kubectl installed and configured
- `kubectl` installed and configured
If you don't have K8s cluster from Cloud Provider, you may pick either Minikube or KinD as local cluster testing option.
KubeVela is a simple custom controller that can be installed on any Kubernetes cluster including managed offerings or your own clusters. The only requirement is please ensure [ingress-nginx](https://kubernetes.github.io/ingress-nginx/deploy/) is installed and enabled.
> NOTE: If you are not using minikube or kind, please make sure to [install or enable ingress-nginx](https://kubernetes.github.io/ingress-nginx/deploy/) by yourself.
For for local deployment and test, you could use `minikube` or `kind`.
<Tabs
className="unique-tabs"
@@ -28,7 +28,7 @@ values={[
Follow the minikube [installation guide](https://minikube.sigs.k8s.io/docs/start/).
Once minikube is installed, create a cluster:
Then spins up a minikube cluster
```shell script
minikube start
@@ -80,8 +80,6 @@ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/mast
## 2. Install KubeVela Controller
These steps will install KubeVela controller and its dependency.
1. Add helm chart repo for KubeVela
```shell script
helm repo add kubevela https://kubevelacharts.oss-cn-hangzhou.aliyuncs.com/core
@@ -97,74 +95,10 @@ These steps will install KubeVela controller and its dependency.
helm install --create-namespace -n vela-system kubevela kubevela/vela-core
```
By default, it will enable the webhook with a self-signed certificate provided by [kube-webhook-certgen](https://github.com/jet/kube-webhook-certgen)
If you want to try the latest master branch, add flag `--devel` in command `helm search` to choose a pre-release
version in format `<next_version>-rc-master` which means the next release candidate version build on `master` branch,
like `0.4.0-rc-master`.
```shell script
helm search repo kubevela/vela-core -l --devel
```
```console
NAME CHART VERSION APP VERSION DESCRIPTION
kubevela/vela-core 0.4.0-rc-master 0.4.0-rc-master A Helm chart for KubeVela core
kubevela/vela-core 0.3.2 0.3.2 A Helm chart for KubeVela core
kubevela/vela-core 0.3.1 0.3.1 A Helm chart for KubeVela core
```
And try the following command to install it.
```shell script
helm install --create-namespace -n vela-system kubevela kubevela/vela-core --version <next_version>-rc-master
```
```console
NAME: kubevela
LAST DEPLOYED: Thu Apr 1 19:41:30 2021
NAMESPACE: vela-system
STATUS: deployed
REVISION: 1
NOTES:
Welcome to use the KubeVela! Enjoy your shipping application journey!
```
4. Install Kubevela with cert-manager (optional)
If cert-manager has been installed, it can be used to take care about generating certs.
## 3. Get KubeVela CLI
You need to install cert-manager before the kubevela chart.
```shell script
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager --namespace cert-manager --version v1.2.0 --create-namespace --set installCRDs=true
```
Install kubevela with enabled certmanager:
```shell script
helm install --create-namespace -n vela-system --set admissionWebhooks.certManager.enabled=true kubevela kubevela/vela-core
```
## 3. (Optional) Install flux2
This installation step is optional, it's required if you want to register [Helm Chart](https://helm.sh/) as KubeVela capabilities.
KubeVela relies on several CRDs and controllers from [fluxcd/flux2](https://github.com/fluxcd/flux2).
| CRD | Controller Image |
| ----------- | ----------- |
| helmrepositories.source.toolkit.fluxcd.io | fluxcd/source-controller:v0.9.0 |
| helmcharts.source.toolkit.fluxcd.io | - |
| buckets.source.toolkit.fluxcd.io | - |
| gitrepositories.source.toolkit.fluxcd.io | - |
| helmreleases.helm.toolkit.fluxcd.io | fluxcd/helm-controller:v0.8.0 |
You can install the whole flux2 from their [official website](https://github.com/fluxcd/flux2)
or install the chart with minimal parts provided by KubeVela:
```shell
$ helm install --create-namespace -n flux-system helm-flux http://oam.dev/catalog/helm-flux2-0.1.0.tgz
```
## 4. (Optional) Get KubeVela CLI
Using KubeVela CLI gives you a simplified workflow with optimized output comparing to using `kubectl`. It is not mandatory though.
Here are three ways to get KubeVela Cli:
@@ -222,9 +156,23 @@ sudo mv ./vela /usr/local/bin/vela
</TabItem>
</Tabs>
## 5. (Optional) Sync Capability from Cluster
If you want to run application from `vela` cli, then you should sync capabilities first like below:
## 4. Enable Helm Support
KubeVela leverages Helm controller from [Flux v2](https://github.com/fluxcd/flux2) to deploy [Helm](https://helm.sh/) based components.
You can enable this feature by installing a minimal Flux v2 chart as below:
```shell
$ helm install --create-namespace -n flux-system helm-flux http://oam.dev/catalog/helm-flux2-0.1.0.tgz
```
Or you could install full Flux v2 following its own guide of course.
## 5. Verify
Checking available application components and traits by `vela` CLI tool:
```shell script
vela components
@@ -240,84 +188,6 @@ worker vela-system deployments.apps Describes long-running, scalable, contai
to receive external network traffic.
```
## 6. (Optional) Clean Up
These capabilities are built-in so they are ready to use if showed up. KubeVela is designed to be programmable and fully self-service, so the assumption is more capabilities will be added later per your own needs.
<details>
Run:
```shell script
helm uninstall -n vela-system kubevela
rm -r ~/.vela
```
This will uninstall KubeVela server component and its dependency components.
This also cleans up local CLI cache.
Then clean up CRDs (CRDs are not removed via helm by default):
```shell script
kubectl delete crd \
appdeployments.core.oam.dev \
applicationconfigurations.core.oam.dev \
applicationcontexts.core.oam.dev \
applicationdeployments.core.oam.dev \
applicationrevisions.core.oam.dev \
applications.core.oam.dev \
approllouts.core.oam.dev \
componentdefinitions.core.oam.dev \
components.core.oam.dev \
containerizedworkloads.core.oam.dev \
healthscopes.core.oam.dev \
manualscalertraits.core.oam.dev \
podspecworkloads.standard.oam.dev \
scopedefinitions.core.oam.dev \
traitdefinitions.core.oam.dev \
workloaddefinitions.core.oam.dev
```
</details>
# Upgrade
If you have already installed KubeVela and wants to upgrade to the new version, you could follow below instructions.
## Step 1. Update helm repo
```shell
helm repo update
```
you can get the new version kubevela chart by run:
```shell
helm search repo kubevela/vela-core -l
```
## Step 2. Upgrade KubeVela CRDs
```shell
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_componentdefinitions.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_workloaddefinitions.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_traitdefinitions.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_applications.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_approllouts.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_applicationrevisions.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_scopedefinitions.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_appdeployments.yaml
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/charts/vela-core/crds/core.oam.dev_applicationcontexts.yaml
```
> Tips: If you meet errors like `* is invalid: spec.scope: Invalid value: "Namespaced": filed is immutable`. Please delete the crd with the error.
and re-apply the kubevela crds.
```shell
kubectl delete crd \
scopedefinitions.core.oam.dev \
traitdefinitions.core.oam.dev \
workloaddefinitions.core.oam.dev
```
## Step 3. Upgrade KubeVela helm chart
```shell
helm upgrade --install --create-namespace --namespace vela-system kubevela kubevela/vela-core --version <the_new_version>
```
Also, whenever new capabilities are added in the platform, you will immediately see them in above output.
docs/en/platform-engineers/cloud-services.md
+3 -3
View File
@@ -1,8 +1,8 @@
---
title: Define and Consume Cloud Resource
title: Crossplane
---
KubeVela provides unified abstraction even for cloud services.
Cloud services is also part of your application deployment.
## Should a Cloud Service be a Component or Trait?
@@ -17,7 +17,7 @@ In a single application, they are in form of Traits, and in multiple application
## Install and Configure Crossplane
KubeVela uses [Crossplane](https://crossplane.io/) as the cloud service operator. Please Refer to [Installation](https://github.com/crossplane/provider-alibaba/releases/tag/v0.5.0)
This guide will use [Crossplane](https://crossplane.io/) as the cloud service provider. Please Refer to [Installation](https://github.com/crossplane/provider-alibaba/releases/tag/v0.5.0)
to install Crossplane Alibaba provider v0.5.0.
If you'd like to configure any other Crossplane providers, please refer to [Crossplane Select a Getting Started Configuration](https://crossplane.io/docs/v1.1/getting-started/install-configure.html#select-a-getting-started-configuration).
docs/en/platform-engineers/definition-and-templates.md
+3 -5
View File
@@ -1,14 +1,12 @@
---
title: Definition CRD
title: Programmable Building Blocks
---
This documentation explains `ComponentDefinition` and `TraitDefinition` in detail.
> All definition objects are expected to be maintained and installed by platform team, think them as *capability providers* in your platform.
## Overview
Essentially, a definition object in KubeVela is consisted by three section:
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.
@@ -132,7 +130,7 @@ Please take care of this field, it's really important and useful for serious lar
### Capability Encapsulation and Abstraction
The templating and parameterizing of given capability are defined in `spec.schematic` field. For example, below is the full definition of *Web Service* type in KubeVela:
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>
docs/en/platform-engineers/openapi-v3-json-schema.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
title: Generate Forms from Definitions
title: Generating UI Forms
---
For any capabilities installed via [Definition Objects](./definition-and-templates),
docs/en/platform-engineers/overview.md
+155 -24
View File
@@ -1,20 +1,12 @@
---
title: Overview
title: Resource Model
---
This documentation will explain what is `Application` object and why you need it.
## Motivation
Encapsulation based abstraction is probably the mostly widely used approach to enable easier developer experience and allow users to deliver the whole application resources as one unit. For example, many tools today encapsulate Kubernetes *Deployment* and *Service* into a *Web Service* module, and then instantiate this module by simply providing parameters such as *image=foo* and *ports=80*. This pattern can be found in cdk8s (e.g. [`web-service.ts` ](https://github.com/awslabs/cdk8s/blob/master/examples/typescript/web-service/web-service.ts)), CUE (e.g. [`kube.cue`](https://github.com/cuelang/cue/blob/b8b489251a3f9ea318830788794c1b4a753031c0/doc/tutorial/kubernetes/quick/services/kube.cue#L70)), and many widely used Helm charts (e.g. [Web Service](https://docs.bitnami.com/tutorials/create-your-first-helm-chart/)).
Despite the efficiency and extensibility in defining abstractions, both DSL tools (e.g. cdk8s , CUE and Helm templating) are mostly used as client side tools and can be barely used as a platform level building block. This leaves platform builders either have to create restricted/inextensible abstractions, or re-invent the wheels of what DSL/templating has already been doing great.
KubeVela allows platform teams to create developer-centric abstractions with DSL/templating but maintain them with the battle tested [Kubernetes Control Loop](https://kubernetes.io/docs/concepts/architecture/controller/).
This documentation will explain the core resource model of KubeVela which is fully powered by Open Application Model (OAM).
## Application
First of all, KubeVela introduces an `Application` CRD as its main abstraction that could capture a full application deployment. To model the modern microservices, every application is composed by multiple components with attached traits (operational behaviors). For example:
KubeVela introduces an `Application` CRD as its main API that captures a full application deployment. Every application is composed by multiple components with attachable operational behaviors (traits). For example:
```yaml
apiVersion: core.oam.dev/v1beta1
@@ -43,29 +35,168 @@ spec:
bucket: "my-bucket"
```
The schema of *component* and *trait* specification in this application is actually enforced by another set of building block objects named *"definitions"*, for example, `ComponentDefinition` and `TraitDefinition`.
Though the application object doesn't have fixed schema, it is a composition object assembled by several *programmable building blocks* as shown below.
`XxxDefinition` resources are designed to leverage encapsulation solutions such as `CUE`, `Helm` and `Terraform modules` to template and parameterize Kubernetes resources as well as cloud services. This enables users to assemble templated capabilities into an `Application` by simply setting parameters. In the `application-sample` above, it models a Kubernetes Deployment (component `foo`) to run container and a Alibaba Cloud OSS bucket (component `bar`) alongside.
## Component
This abstraction mechanism is the key for KubeVela to provide *PaaS-like* experience (*i.e. app-centric, higher level abstractions, self-service operations etc*) to end users, with benefits highlighted as below.
The component model in KubeVela is designed to allow *component providers* to encapsulate deployable/provisionable entities by leveraging widely adopted tools such as CUE, Helm etc, and give a easier path to developers to deploy complicated microservices with ease.
### No "Juggling" Approach to Manage Kubernetes Objects
Templates based encapsulation is probably the mostly widely used approach to enable efficient application deployment and exposes easier interfaces to end users. For example, many tools today encapsulate Kubernetes *Deployment* and *Service* into a *Web Service* module, and then instantiate this module by simply providing parameters such as *image=foo* and *ports=80*. This pattern can be found in cdk8s (e.g. [`web-service.ts` ](https://github.com/awslabs/cdk8s/blob/master/examples/typescript/web-service/web-service.ts)), CUE (e.g. [`kube.cue`](https://github.com/cuelang/cue/blob/b8b489251a3f9ea318830788794c1b4a753031c0/doc/tutorial/kubernetes/quick/services/kube.cue#L70)), and many widely used Helm charts (e.g. [Web Service](https://docs.bitnami.com/tutorials/create-your-first-helm-chart/)).
For example, as the platform team we want to leverage Istio as the Service Mesh layer to control the traffic to certain `Deployment` instances. But this could be really painful today because we have to enforce end users to define and manage a set of Kubernetes resources in a "juggling" approach. For example, in a simple canary rollout case, the end users have to carefully manage a primary *Deployment*, a primary *Service*, a *root Service*, a canary *Deployment*, a canary *Service*, and have to probably rename the *Deployment* instance after canary promotion (this is actually unacceptable in production because renaming will lead to the app restart). What's worse, we have to expect the users properly set the labels and selectors on those objects carefully because they are the key to ensure proper accessibility of every app instance and the only revision mechanism our Istio controller could count on.
> Hence, a components provider could be anyone who packages software components in form of Helm chart of CUE modules. Think about 3rd-party software distributor, DevOps team, or even your CI pipeline.
The issue above could be even painful if the component instance is not *Deployment*, but *StatefulSet* or custom workload type. For example, normally it doesn't make sense to replicate a *StatefulSet* instance during rollout, this means the users have to maintain the name, revision, label, selector, app instances in a totally different approach from *Deployment*.
In above example, it describes an application composed with Kubernetes stateless workload (component `foo`) and a Alibaba Cloud OSS bucket (component `bar`) alongside.
#### Standard Contract Behind The Abstraction
### How it Works?
KubeVela is designed to relieve such burden of managing versionized Kubernetes resources manually. In nutshell, all the needed Kubernetes resources for an app are now encapsulated in a single abstraction, and KubeVela will maintain the instance name, revisions, labels and selector by the battle tested reconcile loop automation, not by human hand. At the meantime, the existence of definition objects allow the platform team to customize the details of all above metadata behind the abstraction, even control the behavior of how to do revision.
In above example, `type: worker` means the specification of this component (claimed in following `properties` section) will be enforced by a `ComponentDefinition` object named `worker` as below:
Thus, all those metadata now become a standard contract that any "day 2" operation controller such as Istio or rollout can rely on. This is the key to ensure our platform could provide user friendly experience but keep "transparent" to the operational behaviors.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: ComponentDefinition
metadata:
name: worker
annotations:
definition.oam.dev/description: "Describes long-running, scalable, containerized services that running at backend. They do NOT have network endpoint to receive external network traffic."
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
### No Configuration Drift
if parameter["cmd"] != _|_ {
command: parameter.cmd
}
}]
}
}
}
}
parameter: {
image: string
cmd?: [...string]
}
```
Light-weighted and flexible in defining abstractions, any of the existing encapsulation solutions today work at client side, for example, DSL/IaC (Infrastructure as Code) tools and Helm. This approach is easy to be adopted and has less invasion in the user cluster.
But client side abstractions always lead to an issue called *Infrastructure/Configuration Drift*, i.e. the generated component instances are not in line with the expected configuration. This could be caused by incomplete coverage, less-than-perfect processes or emergency changes.
Hence, the `properties` section of `backend` only exposes two parameters to fill: `image` and `cmd`, this is enforced by the `parameter` list of the `.spec.template` field of the definition.
Hence, all abstractions in KubeVela is designed to be maintained with [Kubernetes Control Loop](https://kubernetes.io/docs/concepts/architecture/controller/) and leverage Kubernetes control plane to eliminate the issue of configuration drifting, and still keeps the flexibly and velocity enabled by existing encapsulation solutions (e.g. DSL/IaC and templating).
## Traits
Traits are operational features that can be attached to component per needs. Traits are normally considered as platform features and maintained by platform team. In the above example, `type: autoscaler` in `frontend` means the specification (i.e. `properties` section)
of this trait will be enforced by a `TraitDefinition` object named `autoscaler` as below:
```yaml
apiVersion: core.oam.dev/v1beta1
kind: TraitDefinition
metadata:
annotations:
definition.oam.dev/description: "configure k8s HPA for Deployment"
name: hpa
spec:
appliesToWorkloads:
- webservice
- worker
schematic:
cue:
template: |
outputs: hpa: {
apiVersion: "autoscaling/v2beta2"
kind: "HorizontalPodAutoscaler"
metadata: name: context.name
spec: {
scaleTargetRef: {
apiVersion: "apps/v1"
kind: "Deployment"
name: context.name
}
minReplicas: parameter.min
maxReplicas: parameter.max
metrics: [{
type: "Resource"
resource: {
name: "cpu"
target: {
type: "Utilization"
averageUtilization: parameter.cpuUtil
}
}
}]
}
}
parameter: {
min: *1 | int
max: *10 | int
cpuUtil: *50 | int
}
```
The application also have a `sidecar` trait.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: TraitDefinition
metadata:
annotations:
definition.oam.dev/description: "add sidecar to the app"
name: sidecar
spec:
appliesToWorkloads:
- webservice
- worker
schematic:
cue:
template: |-
patch: {
// +patchKey=name
spec: template: spec: containers: [parameter]
}
parameter: {
name: string
image: string
command?: [...string]
}
```
Please note that the end users of KubeVela do NOT need to know about definition objects, they learn how to use a given capability with visualized forms (or the JSON schema of parameters if they prefer). Please check the [Generate Forms from Definitions](/docs/platform-engineers/openapi-v3-json-schema) section about how this is achieved.
## Standard Contract Behind The Abstractions
Once the application is deployed, KubeVela will index and manage the underlying instances with name, revisions, labels and selector etc in automatic approach. These metadata are shown as below.
| Label | Description |
| :--: | :---------: |
|`workload.oam.dev/type=<component definition name>` | The name of its corresponding `ComponentDefinition` |
|`trait.oam.dev/type=<trait definition name>` | The name of its corresponding `TraitDefinition` |
|`app.oam.dev/name=<app name>` | The name of the application it belongs to |
|`app.oam.dev/component=<component name>` | The name of the component it belongs to |
|`trait.oam.dev/resource=<name of trait resource instance>` | The name of trait resource instance |
|`app.oam.dev/appRevision=<name of app revision>` | The name of the application revision it belongs to |
Consider these metadata as a standard contract for any "day 2" operation controller such as rollout controller to work on KubeVela deployed applications. This is the key to ensure the interoperability for KubeVela based platform as well.
## No Configuration Drift
Despite the efficiency and extensibility in abstracting application deployment, IaC (Infrastructure-as-Code) tools may lead to an issue called *Infrastructure/Configuration Drift*, i.e. the generated component instances are not in line with the expected configuration. This could be caused by incomplete coverage, less-than-perfect processes or emergency changes. This makes them can be barely used as a platform level building block.
Hence, KubeVela is designed to maintain all these programmable capabilities with [Kubernetes Control Loop](https://kubernetes.io/docs/concepts/architecture/controller/) and leverage Kubernetes control plane to eliminate the issue of configuration drifting, while still keeps the flexibly and velocity enabled by IaC.
docs/en/rollout/appdeploy.md
+6 -6
View File
@@ -1,16 +1,16 @@
---
title: Multi-Cluster Application Deployment
title: Multi-Cluster Deployment
---
# Introduction
## Introduction
Modern application infrastructure involves multiple clusters to ensure high availability and maximize service throughput. In this section, we will introduce how to use KubeVela to achieve application deployment across multiple clusters with following features supported:
- Rolling Upgrade: To continuously deploy apps requires to rollout in a safe manner which usually involves step by step rollout batches and analysis.
- Traffic shifting: When rolling upgrade an app, it needs to split the traffic onto both the old and new revisions to verify the new version while preserving service availability.
## AppDeployment CRD
### AppDeployment
The `AppDeployment` CRD has been provided to satisfy such requirements. Here's an overview of the API:
The `AppDeployment` API in KubeVela is provided to satisfy such requirements. Here's an overview of the API:
```yaml
apiVersion: core.oam.dev/v1beta1
@@ -72,7 +72,7 @@ spec:
replicas: 5
```
## Cluster CRD
### Cluster
The clusters selected in the `placement` part from above is defined in Cluster CRD. Here's what it looks like:
@@ -99,7 +99,7 @@ data:
config: ... # kubeconfig data
```
# Quickstart
## Quickstart
Here's a step-by-step tutorial for you to try out. All of the yaml files are from [`docs/examples/appdeployment/`](https://github.com/oam-dev/kubevela/tree/master/docs/examples/appdeployment).
You must run all commands in that directory.
docs/en/rollout/rollout.md
+92 -197
View File
@@ -25,7 +25,7 @@ We design KubeVela rollout solutions with the following principles in mind
in a production environment including Blue/Green, Canary and A/B testing.
## AppRollout Example
## AppRollout
Here is a simple `AppRollout` that upgrade an application from v1 to v2 in three batches. The
first batch contains only 1 pod while the rest of the batches split the rest.
@@ -48,213 +48,108 @@ spec:
batchPartition: 1
```
## User Experience Workflow
## User Workflow
Here is the end to end user experience based on [CloneSet](https://openkruise.io/en-us/docs/cloneset.html)
1. Install CloneSet and create a `ComponentDefinition` for it.
```shell
helm install kruise https://github.com/openkruise/kruise/releases/download/v0.7.0/kruise-chart.tgz
```
```yaml
apiVersion: core.oam.dev/v1beta1
kind: ComponentDefinition
metadata:
name: clonesetservice
namespace: vela-system
annotations:
definition.oam.dev/description: "Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers.
If workload type is skipped for any service defined in Appfile, it will be defaulted to `webservice` type."
spec:
workload:
definition:
apiVersion: apps.kruise.io/v1alpha1
kind: CloneSet
schematic:
cue:
template: |
output: {
apiVersion: "apps.kruise.io/v1alpha1"
kind: "CloneSet"
metadata: labels: {
"app.oam.dev/component": context.name
}
spec: {
if parameter["replicas"] != _|_ {
replicas: parameter.replicas
}
selector: matchLabels: {
"app.oam.dev/component": context.name
}
1. Install CloneSet and its `ComponentDefinition`.
template: {
metadata: labels: {
"app.oam.dev/component": context.name
}
Since CloneSet is an customized workload for Kubernetes, we need to install its controller and component definition manually to KubeVela platform.
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
}
}
}]
}
}
if parameter["updateStrategyType"] != _|_ {
updateStrategy: {
type: parameter.updateStrategyType
}
}
}
}
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
// +usage=Cloneset updateStrategy, candidates are `ReCreate`/`InPlaceIfPossible`/`InPlaceOnly`
updateStrategyType?: string
// +usage=Number of pods in the cloneset
replicas?: int
}
```shell
helm install kruise https://github.com/openkruise/kruise/releases/download/v0.7.0/kruise-chart.tgz
```
2. Apply an application to the cluster
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: test-rolling
annotations:
"app.oam.dev/rolling-components": "metrics-provider"
"app.oam.dev/rollout-template": "true"
spec:
components:
- name: metrics-provider
type: clonesetservice
properties:
cmd:
- ./podinfo
- stress-cpu=1
image: stefanprodan/podinfo:4.0.6
port: 8080
updateStrategyType: InPlaceIfPossible
replicas: 5
```
```shell
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/docs/examples/cloneset-rollout/clonesetDefinition.yaml
```
3. Apply the following rollout to upgrade the application to v1
```yaml
apiVersion: core.oam.dev/v1beta1
kind: AppRollout
metadata:
name: rolling-example
spec:
# application (revision) reference
targetAppRevisionName: test-rolling-v1
componentList:
- metrics-provider
rolloutPlan:
rolloutStrategy: "IncreaseFirst"
rolloutBatches:
- replicas: 10%
- replicas: 40%
- replicas: 50%
```
Use can check the status of the ApplicationRollout and wait for the rollout to complete.
2. Deploy application to the cluster
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: test-rolling
annotations:
"app.oam.dev/rolling-components": "metrics-provider"
"app.oam.dev/rollout-template": "true"
spec:
components:
- name: metrics-provider
type: clonesetservice
properties:
cmd:
- ./podinfo
- stress-cpu=1
image: stefanprodan/podinfo:4.0.6
port: 8080
updateStrategyType: InPlaceIfPossible
replicas: 5
```
3. Attach the following rollout plan to upgrade the application to v1
```yaml
apiVersion: core.oam.dev/v1beta1
kind: AppRollout
metadata:
name: rolling-example
spec:
# application (revision) reference
targetAppRevisionName: test-rolling-v1
componentList:
- metrics-provider
rolloutPlan:
rolloutStrategy: "IncreaseFirst"
rolloutBatches:
- replicas: 10%
- replicas: 40%
- replicas: 50%
```
Use can check the status of the ApplicationRollout and wait for the rollout to complete.
4. User can continue to modify the application image tag and apply
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: test-rolling
annotations:
"app.oam.dev/rolling-components": "metrics-provider"
"app.oam.dev/rollout-template": "true"
spec:
components:
- name: metrics-provider
type: clonesetservice
properties:
cmd:
- ./podinfo
- stress-cpu=1
image: stefanprodan/podinfo:5.0.2
port: 8080
updateStrategyType: InPlaceIfPossible
replicas: 5
```
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: test-rolling
annotations:
"app.oam.dev/rolling-components": "metrics-provider"
"app.oam.dev/rollout-template": "true"
spec:
components:
- name: metrics-provider
type: clonesetservice
properties:
cmd:
- ./podinfo
- stress-cpu=1
image: stefanprodan/podinfo:5.0.2
port: 8080
updateStrategyType: InPlaceIfPossible
replicas: 5
```
5. Apply the application rollout that upgrade the application from v1 to v2
```yaml
apiVersion: core.oam.dev/v1beta1
kind: AppRollout
metadata:
name: rolling-example
spec:
# application (revision) reference
sourceAppRevisionName: test-rolling-v1
targetAppRevisionName: test-rolling-v2
componentList:
- metrics-provider
rolloutPlan:
rolloutStrategy: "IncreaseFirst"
rolloutBatches:
- replicas: 1
- replicas: 2
- replicas: 2
```
User can check the status of the ApplicationRollout and see the rollout completes, and the
ApplicationRollout's "Rolling State" becomes `rolloutSucceed`
```yaml
apiVersion: core.oam.dev/v1beta1
kind: AppRollout
metadata:
name: rolling-example
spec:
# application (revision) reference
sourceAppRevisionName: test-rolling-v1
targetAppRevisionName: test-rolling-v2
componentList:
- metrics-provider
rolloutPlan:
rolloutStrategy: "IncreaseFirst"
rolloutBatches:
- replicas: 1
- replicas: 2
- replicas: 2
```
User can check the status of the ApplicationRollout and see the rollout completes, and the
ApplicationRollout's "Rolling State" becomes `rolloutSucceed`
## State Transition
Here is the high level state transition graph
docs/sidebars.js
+51 -55
View File
@@ -18,30 +18,20 @@ module.exports = {
},
{
type: 'category',
label: 'Define Application',
label: 'Application Deployment',
items:[
'platform-engineers/overview',
'application',
]
},
{
type: 'category',
label: 'Rollout Application',
items:[
"rollout/rollout",
'rollout/appdeploy'
]
},
{
type: 'category',
label: 'Platform Builder Guide',
label: 'Platform Operation Guide',
items: [
'platform-engineers/overview',
'platform-engineers/definition-and-templates',
{
'Visualization': [
'platform-engineers/openapi-v3-json-schema'
]
},
'platform-engineers/openapi-v3-json-schema',
{
type: 'category',
label: 'Defining Components',
@@ -65,6 +55,13 @@ module.exports = {
'kube/trait',
]
},
{
type: 'category',
label: 'Defining Cloud Service',
items: [
'platform-engineers/cloud-services'
]
},
]
},
{
@@ -77,13 +74,6 @@ module.exports = {
'cue/advanced',
]
},
{
type: 'category',
label: 'Defining Cloud Service',
items: [
'platform-engineers/cloud-services'
]
},
{
type: 'category',
label: 'Hands-on Lab',
@@ -96,7 +86,7 @@ module.exports = {
},
{
type: 'category',
label: 'Developer Experience Guide',
label: 'Using KubeVela CLI',
items: [
{
'Appfile': [
@@ -105,7 +95,7 @@ module.exports = {
]
},
{
'Command Line Tool (CLI)': [
'Managing Applications': [
'developers/config-enviroments',
'developers/port-forward',
'developers/check-logs',
@@ -118,39 +108,45 @@ module.exports = {
},
{
type: 'category',
label: 'CLI References',
label: 'References',
items: [
'cli/vela_components',
'cli/vela_config',
'cli/vela_env',
'cli/vela_init',
'cli/vela_up',
'cli/vela_version',
'cli/vela_exec',
'cli/vela_logs',
'cli/vela_ls',
'cli/vela_port-forward',
'cli/vela_show',
'cli/vela_status',
'cli/vela_workloads',
'cli/vela_traits',
'cli/vela_system',
'cli/vela_template',
'cli/vela_cap',
],
},
{
type: 'category',
label: 'Capability References',
items: [
'developers/references/README',
'developers/references/component-types/webservice',
'developers/references/component-types/task',
'developers/references/component-types/worker',
'developers/references/traits/route',
'developers/references/traits/metrics',
'developers/references/traits/scaler',
'developers/references/restful-api/rest',
{
type: 'category',
label: 'CLI',
items: [
'cli/vela_components',
'cli/vela_config',
'cli/vela_env',
'cli/vela_init',
'cli/vela_up',
'cli/vela_version',
'cli/vela_exec',
'cli/vela_logs',
'cli/vela_ls',
'cli/vela_port-forward',
'cli/vela_show',
'cli/vela_status',
'cli/vela_workloads',
'cli/vela_traits',
'cli/vela_system',
'cli/vela_template',
'cli/vela_cap',
],
},
{
type: 'category',
label: 'Capabilities',
items: [
'developers/references/README',
'developers/references/component-types/webservice',
'developers/references/component-types/task',
'developers/references/component-types/worker',
'developers/references/traits/route',
'developers/references/traits/metrics',
'developers/references/traits/scaler',
'developers/references/restful-api/rest',
],
},
],
},
{