kubevela
/
kubevela.github.io
mirror of https://github.com/kubevela/kubevela.github.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

sync commit 9c70edeb7704cfb2c24a54f9a3d130c6f6c440ae from kubevela-refs/heads/master

This commit is contained in:
kubevela-bot 2021-06-30 09:45:54 +00:00
parent 62c1aeca2f
commit 63624509c3
5 changed files with 1 additions and 552 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

306
docs/end-user/scopes/advanced-rollout.md
View File

@ -1,306 +0,0 @@
---
title: Advanced Rollout Plan
---
The rollout plan feature in KubeVela is essentially provided by `AppRollout` API.
## AppRollout Specification
The following describes all the available fields of a AppRollout:
```yaml
apiVersion: core.oam.dev/v1beta1
kind: AppRollout
metadata:
name: rolling-example
spec:
# SourceAppRevisionName contains the name of the appRevisionName that we need to upgrade from.
# it can be empty only when you want to scale an application. +optional
sourceAppRevisionName: test-rolling-v1
# TargetAppRevisionName contains the name of the appRevisionName that we need to upgrade to.
targetAppRevisionName: test-rolling-v2
# The list of component to upgrade in the application.
# We only support single component application so far. +optional
componentList:
- metrics-provider
# RolloutPlan is the details on how to rollout the resources
rolloutPlan:
# RolloutStrategy defines strategies for the rollout plan
# the value can be IncreaseFirst or DecreaseFirst
# Defaults to IncreaseFirst. +optional
rolloutStrategy: "IncreaseFirst"
# The exact distribution among batches.
# its size has to be exactly the same as the NumBatches (if set)
# The total number cannot exceed the targetSize or the size of the source resource
# We will IGNORE the last batch's replica field if it's a percentage since round errors can lead to inaccurate sum
# We highly recommend to leave the last batch's replica field empty
rolloutBatches:
# Replicas is the number of pods to upgrade in this batch
# it can be an absolute number (ex: 5) or a percentage of total pods
# we will ignore the percentage of the last batch to just fill the gap
# Below is an example the first batch contains only 1 pod while the rest of the batches split the rest.
- replicas: 1
- replicas: 50%
- replicas: 50%
# All pods in the batches up to the batchPartition (included) will have
# the target resource specification while the rest still have the source resource
# This is designed for the operators to manually rollout
# Default is the the number of batches which will rollout all the batches. +optional
batchPartition: 1
# Paused the rollout
# defaults to false. +optional
paused: false
# The size of the target resource. In rollout operation it's the same as the size of the source resource.
# when use rollout to scale an application targetSize is the target source you want scale to. +optional
targetSize: 4
```
## Basic Usage
1. Deploy application
```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: worker
properties:
cmd:
- ./podinfo
- stress-cpu=1
image: stefanprodan/podinfo:4.0.6
port: 8080
replicas: 5
```
Verify AppRevision `test-rolling-v1` have generated
```shell
$ kubectl get apprev test-rolling-v1
NAME AGE
test-rolling-v1 9s
```
2. 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%
targetSize: 5
```
User can check the status of the ApplicationRollout and wait for the rollout to complete.
3. User can continue to modify the application image tag and apply.This will generate new AppRevision `test-rolling-v2`
```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: worker
properties:
cmd:
- ./podinfo
- stress-cpu=1
image: stefanprodan/podinfo:5.0.2
port: 8080
replicas: 5
```
Verify AppRevision `test-rolling-v2` have generated
```shell
$ kubectl get apprev test-rolling-v2
NAME AGE
test-rolling-v2 7s
```
4. 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`
## Advanced Usage
Using `AppRollout` separately can enable some advanced use case.
### Revert
5. Apply the application rollout that revert the application from v2 to v1
```yaml
apiVersion: core.oam.dev/v1beta1
kind: AppRollout
metadata:
name: rolling-example
spec:
# application (revision) reference
sourceAppRevisionName: test-rolling-v2
targetAppRevisionName: test-rolling-v1
componentList:
- metrics-provider
rolloutPlan:
rolloutStrategy: "IncreaseFirst"
rolloutBatches:
- replicas: 1
- replicas: 2
- replicas: 2
```
### Skip Revision Rollout
6. User can apply this yaml continue to modify the application image tag.This will generate new AppRevision `test-rolling-v3`
```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: worker
properties:
cmd:
- ./podinfo
- stress-cpu=1
image: stefanprodan/podinfo:5.2.0
port: 8080
replicas: 5
```
Verify AppRevision `test-rolling-v3` have generated
```shell
$ kubectl get apprev test-rolling-v3
NAME AGE
test-rolling-v3 7s
```
7. Apply the application rollout that rollout the application from v1 to v3
```yaml
apiVersion: core.oam.dev/v1beta1
kind: AppRollout
metadata:
name: rolling-example
spec:
# application (revision) reference
sourceAppRevisionName: test-rolling-v1
targetAppRevisionName: test-rolling-v3
componentList:
- metrics-provider
rolloutPlan:
rolloutStrategy: "IncreaseFirst"
rolloutBatches:
- replicas: 1
- replicas: 2
- replicas: 2
```
### Scale the application
Before using AppRollout to scale an application, we must be aware of the real status of workload now. Check the workload status.
```shell
$ kubectl get deploy metrics-provider-v3
NAME READY UP-TO-DATE AVAILABLE AGE
metrics-provider-v3 5/5 5 5 10m
```
Last target appRevision is `test-rolling-v3` and the workload have 5 replicas currently.
8. Apply the appRollout increase the replicas nums of workload to 7.
```yaml
apiVersion: core.oam.dev/v1beta1
kind: AppRollout
metadata:
name: rolling-example
spec:
# sourceAppRevisionName is empty means this is a scale operation
targetAppRevisionName: test-rolling-v3
componentList:
- metrics-provider
rolloutPlan:
rolloutStrategy: "IncreaseFirst"
rolloutBatches:
# split two batches to scale. First batch increase 1 pod and second increase 1.
- replicas: 1
- replicas: 1
# targetSize means that final total size of workload is 7
targetSize: 7
```
## More Details About `AppRollout`
### Design Principles and Goals
There are several attempts at solving rollout problem in the cloud native community. However, none
of them provide a true rolling style upgrade. For example, flagger supports Blue/Green, Canary
and A/B testing. Therefore, we decide to add support for batch based rolling upgrade as
our first style to support in KubeVela.
We design KubeVela rollout solutions with the following principles in mind
- First, we want all flavors of rollout controllers share the same core rollout
related logic. The trait and application related logic can be easily encapsulated into its own
package.
- Second, the core rollout related logic is easily extensible to support different type of
workloads, i.e. Deployment, CloneSet, Statefulset, DaemonSet or even customized workloads.
- Thirdly, the core rollout related logic has a well documented state machine that
does state transition explicitly.
- Finally, the controllers can support all the rollout/upgrade needs of an application running
in a production environment including Blue/Green, Canary and A/B testing.
### State Transition
Here is the high level state transition graph
![](../../resources/approllout-status-transition.jpg)
### Roadmap
Our recent roadmap for rollout plan is [here](./roadmap).

240
docs/end-user/scopes/appdeploy.md
View File

@ -1,240 +0,0 @@
---
title: Placement
---
## Introduction
In this section, we will introduce how to use KubeVela to place application across multiple clusters with traffic management enabled. For traffic management, KubeVela currently allows you to split the traffic onto both the old and new revisions during rolling update and verify the new version while preserving service availability.
### AppDeployment
The `AppDeployment` API in KubeVela is provided to satisfy such requirements. Here's an overview of the API:
```yaml
apiVersion: core.oam.dev/v1beta1
kind: AppDeployment
metadata:
name: sample-appdeploy
spec:
traffic:
hosts:
- example.com
http:
- match:
# match any requests to 'example.com/example-app'
- uri:
prefix: "/example-app"
# split traffic 50/50 on v1/v2 versions of the app
weightedTargets:
- revisionName: example-app-v1
componentName: testsvc
port: 80
weight: 50
- revisionName: example-app-v2
componentName: testsvc
port: 80
weight: 50
appRevisions:
- # Name of the AppRevision.
# Each modification to Application would generate a new AppRevision.
revisionName: example-app-v1
# Cluster specific workload placement config
placement:
- clusterSelector:
# You can select Clusters by name or labels.
# If multiple clusters is selected, one will be picked via a unique hashing algorithm.
labels:
tier: production
name: prod-cluster-1
distribution:
replicas: 5
- # If no clusterSelector is given, it will use the host cluster in which this CR exists
distribution:
replicas: 5
- revisionName: example-app-v2
placement:
- clusterSelector:
labels:
tier: production
name: prod-cluster-1
distribution:
replicas: 5
- distribution:
replicas: 5
```
### Cluster
The clusters selected in the `placement` part from above is defined in Cluster CRD. Here's what it looks like:
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Cluster
metadata:
name: prod-cluster-1
labels:
tier: production
spec:
kubeconfigSecretRef:
name: kubeconfig-cluster-1 # the secret name
```
The secret must contain the kubeconfig credentials in `config` field:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: kubeconfig-cluster-1
data:
config: ... # kubeconfig data
```
## 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.
1. Create an Application
```bash
cat <<EOF | kubectl apply -f -
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: example-app
annotations:
app.oam.dev/revision-only: "true"
spec:
components:
- name: testsvc
type: webservice
properties:
addRevisionLabel: true
image: crccheck/hello-world
port: 8000
EOF
```
This will create `example-app-v1` AppRevision. Check it:
```bash
kubectl get applicationrevisions.core.oam.dev
```
```console
NAME AGE
example-app-v1 116s
```
> Note: with `app.oam.dev/revision-only: "true"` annotation, above `Application` resource won't create any pod instances and leave the real deployment process to `AppDeployment`.
1. Then use the above AppRevision to create an AppDeployment.
```bash
kubectl apply -f appdeployment-1.yaml
```
> Note: in order to AppDeployment to work, your workload object must have a `spec.replicas` field for scaling.
1. Now you can check that there will 1 deployment and 2 pod instances deployed
```bash
kubectl get deploy
```
```console
NAME READY UP-TO-DATE AVAILABLE AGE
testsvc-v1 2/2 2 0 27s
```
1. Update Application properties:
```bash
cat <<EOF | kubectl apply -f -
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: example-app
annotations:
app.oam.dev/revision-only: "true"
spec:
components:
- name: testsvc
type: webservice
properties:
addRevisionLabel: true
image: nginx
port: 80
EOF
```
This will create a new `example-app-v2` AppRevision. Check it:
```bash
kubectl get applicationrevisions.core.oam.dev
```
```console
NAME
example-app-v1
example-app-v2
```
1. Then use the two AppRevisions to update the AppDeployment:
```bash
kubectl apply -f appdeployment-2.yaml
```
(Optional) If you have Istio installed, you can apply the AppDeployment with traffic split:
```bash
# set up gateway if not yet
kubectl apply -f gateway.yaml
kubectl apply -f appdeployment-2-traffic.yaml
```
Note that for traffic split to work, your must set the following pod labels in workload cue templates (see [webservice.cue](https://github.com/oam-dev/kubevela/blob/master/hack/vela-templates/cue/webservice.cue)):
```shell
"app.oam.dev/component": context.name
"app.oam.dev/appRevision": context.appRevision
```
1. Now you can check that there will 1 deployment and 1 pod per revision.
```bash
kubectl get deploy
```
```console
NAME READY UP-TO-DATE AVAILABLE AGE
testsvc-v1 1/1 1 1 2m14s
testsvc-v2 1/1 1 1 8s
```
(Optional) To verify traffic split:
```bash
# run this in another terminal
kubectl -n istio-system port-forward service/istio-ingressgateway 8080:80
```
```console
Forwarding from 127.0.0.1:8080 -> 8080
Forwarding from [::1]:8080 -> 8080
# The command should return pages of either docker whale or nginx in 50/50
$ curl -H "Host: example-app.example.com" http://localhost:8080/
```
1. Cleanup:
```bash
kubectl delete appdeployments.core.oam.dev --all
kubectl delete applications.core.oam.dev --all
```

4
docs/end-user/scopes/rollout-plan.md
View File

@ -62,10 +62,6 @@ spec:
User can check the status of the application and see the rollout completes, and the
application's `status.rollout.rollingState` becomes `rolloutSucceed`.
## Advanced Usage
If you want to control and rollout the specific application revisions, or do revert, please refer to [Advanced Usage](advanced-rollout) to learn more details.

2
docs/quick-start.md
View File

@ -68,4 +68,4 @@ Here are some recommended next steps:
- Learn KubeVela's [core concepts](./concepts)
- Learn more details about [`Application`](end-user/application) and what it can do for you.
- Learn how to attach [rollout plan](end-user/scopes/rollout-plan) to this application, or [place it to multiple runtime clusters](end-user/scopes/appdeploy).
- Learn how to attach [rollout plan](end-user/scopes/rollout-plan) to this application.

1
sidebars.js
View File

@ -44,7 +44,6 @@ module.exports = {
'end-user/traits/more',
]
},
'end-user/scopes/appdeploy',
'end-user/scopes/rollout-plan',
{
'Observability': [