Version: v1.0

Application

This documentation will walk through how to use KubeVela to design a simple application without any polices or placement rule defined.

Note: since you didn’t declare placement rule, KubeVela will deploy this application directly to the control plane cluster (i.e. the cluster your kubectl is talking to). This is also the same case if you are using local cluster such as KinD or MiniKube to play KubeVela.

Step 1: Check Available Components

Components are deployable or provisionable entities that compose your application. It could be a Helm chart, a simple Kubernetes workload, a CUE or Terraform module, or a cloud database etc.

Let’s check the available components in fresh new KubeVela.

  1. kubectl get comp -n vela-system
  2. NAME WORKLOAD-KIND DESCRIPTION
  3. task Job Describes jobs that run code or a script to completion.
  4. webservice Deployment Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers.
  5. worker Deployment Describes long-running, scalable, containerized services that running at backend. They do NOT have network endpoint to receive external network traffic.

To show the specification for given component, you could use vela show.

  1. $ kubectl vela show webservice
  2. # Properties
  3. +------------------+----------------------------------------------------------------------------------+-----------------------+----------+---------+
  4. | NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
  5. +------------------+----------------------------------------------------------------------------------+-----------------------+----------+---------+
  6. | cmd | Commands to run in the container | []string | false | |
  7. | env | Define arguments by using environment variables | [[]env](#env) | false | |
  8. | addRevisionLabel | | bool | true | false |
  9. | image | Which image would you like to use for your service | string | true | |
  10. | port | Which port do you want customer traffic sent to | int | true | 80 |
  11. | cpu | Number of CPU units for the service, like `0.5` (0.5 CPU core), `1` (1 CPU core) | string | false | |
  12. | volumes | Declare volumes and volumeMounts | [[]volumes](#volumes) | false | |
  13. +------------------+----------------------------------------------------------------------------------+-----------------------+----------+---------+
  14. ... // skip other fields

Tips: vela show xxx --web will open its capability reference documentation in your default browser.

You could always add more components to the platform at any time.

Step 2: Declare an Application

Application is the full description of a deployment. Let’s define an application that deploys a Web Service and a Worker components.

  1. # sample.yaml
  2. apiVersion: core.oam.dev/v1beta1
  3. kind: Application
  4. metadata:
  5. name: website
  6. spec:
  7. components:
  8. - name: frontend
  9. type: webservice
  10. properties:
  11. image: nginx
  12. - name: backend
  13. type: worker
  14. properties:
  15. image: busybox
  16. cmd:
  17. - sleep
  18. - '1000'

Step 3: Attach Traits

Traits are platform provided features that could overlay a given component with extra operational behaviors.

  1. $ kubectl get trait -n vela-system
  2. NAME APPLIES-TO DESCRIPTION
  3. cpuscaler [webservice worker] Automatically scale the component based on CPU usage.
  4. ingress [webservice worker] Enable public web traffic for the component.
  5. scaler [webservice worker] Manually scale the component.
  6. sidecar [webservice worker] Inject a sidecar container to the component.

Let’s check the specification of sidecar trait.

  1. $ kubectl vela show sidecar
  2. # Properties
  3. +---------+-----------------------------------------+----------+----------+---------+
  4. | NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
  5. +---------+-----------------------------------------+----------+----------+---------+
  6. | name | Specify the name of sidecar container | string | true | |
  7. | image | Specify the image of sidecar container | string | true | |
  8. | command | Specify the commands run in the sidecar | []string | false | |
  9. +---------+-----------------------------------------+----------+----------+---------+

Note that traits are designed to be overlays.

This means for sidecar trait, your frontend component doesn’t need to have a sidecar template or bring a webhook to enable sidecar injection. Instead, KubeVela is able to patch a sidecar to its workload instance after it is generated by the component (no matter it’s a Helm chart or CUE module) but before it is applied to runtime cluster.

Similarly, the system will assign a HPA instance based on the properties you set and “link” it to the target workload instance, the component itself is untouched.

Now let’s attach sidecar and cpuscaler traits to the frontend component.

  1. # sample.yaml
  2. apiVersion: core.oam.dev/v1beta1
  3. kind: Application
  4. metadata:
  5. name: website
  6. spec:
  7. components:
  8. - name: frontend # This is the component I want to deploy
  9. type: webservice
  10. properties:
  11. image: nginx
  12. traits:
  13. - type: cpuscaler # Automatically scale the component by CPU usage after deployed
  14. properties:
  15. min: 1
  16. max: 10
  17. cpuPercent: 60
  18. - type: sidecar # Inject a fluentd sidecar before applying the component to runtime cluster
  19. properties:
  20. name: "sidecar-test"
  21. image: "fluentd"
  22. - name: backend
  23. type: worker
  24. properties:
  25. image: busybox
  26. cmd:
  27. - sleep
  28. - '1000'

Step 4: Deploy the Application

  1. $ kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/docs/examples/enduser/sample.yaml
  2. application.core.oam.dev/website created

You’ll get the application becomes running.

  1. $ kubectl get application
  2. NAME COMPONENT TYPE PHASE HEALTHY STATUS AGE
  3. website frontend webservice running true 4m54s

Check the details of the application.

  1. $ kubectl get app website -o yaml
  2. apiVersion: core.oam.dev/v1beta1
  3. kind: Application
  4. metadata:
  5. generation: 1
  6. name: website
  7. namespace: default
  8. spec:
  9. components:
  10. - name: frontend
  11. properties:
  12. image: nginx
  13. traits:
  14. - properties:
  15. cpuPercent: 60
  16. max: 10
  17. min: 1
  18. type: cpuscaler
  19. - properties:
  20. image: fluentd
  21. name: sidecar-test
  22. type: sidecar
  23. type: webservice
  24. - name: backend
  25. properties:
  26. cmd:
  27. - sleep
  28. - "1000"
  29. image: busybox
  30. type: worker
  31. status:
  32. ...
  33. latestRevision:
  34. name: website-v1
  35. revision: 1
  36. revisionHash: e9e062e2cddfe5fb
  37. services:
  38. - healthy: true
  39. name: frontend
  40. traits:
  41. - healthy: true
  42. type: cpuscaler
  43. - healthy: true
  44. type: sidecar
  45. - healthy: true
  46. name: backend
  47. status: running

Specifically:

  1. status.latestRevision declares current revision of this deployment.
  2. status.services declares the component created by this deployment and the healthy state.
  3. status.status declares the global state of this deployment.

List Revisions

When updating an application entity, KubeVela will create a new revision for this change.

  1. $ kubectl get apprev -l app.oam.dev/name=website
  2. NAME AGE
  3. website-v1 35m

Furthermore, the system will decide how to/whether to rollout the application based on the attached rollout plan.