Learning Appfile

A sample Appfile is as below:

name: testapp
services:
  frontend: # 1st service
    image: oamdev/testapp:v1
    build:
      docker:
        file: Dockerfile
        context: .
    cmd: ["node", "server.js"]
    port: 8080
    route: # trait
      domain: example.com
      rules:
        - path: /testapp
          rewriteTarget: /
  backend: # 2nd service
    type: task # workload type
    image: perl 
    cmd: ["perl",  "-Mbignum=bpi", "-wle", "print bpi(2000)"]

Under the hood, Appfile will build the image from source code, and then generate Application resource with the image name.

Schema

Before learning about Appfile’s detailed schema, we recommend you to get familiar with core concepts in KubeVela.

name: _app-name_
services:
  _service-name_:
    # If `build` section exists, this field will be used as the name to build image. Otherwise, KubeVela will try to pull the image with given name directly.
    image: oamdev/testapp:v1
    build:
      docker:
        file: _Dockerfile_path_ # relative path is supported, e.g. "./Dockerfile"
        context: _build_context_path_ # relative path is supported, e.g. "."
      push:
        local: kind # optionally push to local KinD cluster instead of remote registry
    type: webservice (default) | worker | task
    # detailed configurations of workload
    ... properties of the specified workload  ...
    _trait_1_:
      # properties of trait 1
    _trait_2_:
      # properties of trait 2
    ... more traits and their properties ...
  _another_service_name_: # more services can be defined
    ...

To learn about how to set the properties of specific workload type or trait, please use vela show <TYPE | TRAIT>.

Example Workflow

In the following workflow, we will build and deploy an example NodeJS app under examples/testapp/.

Prerequisites

Docker installed on the host
KubeVela installed and configured

1. Download test app code

git clone and go to the testapp directory:

$ git clone https://github.com/oam-dev/kubevela.git
$ cd kubevela/docs/examples/testapp

The example contains NodeJS app code, Dockerfile to build the app.

2. Deploy app in one command

In the directory there is a vela.yaml which follows Appfile format supported by Vela. We are going to use it to build and deploy the app.

NOTE: please change oamdev to your own registry account so you can push. Or, you could try the alternative approach in Local testing without pushing image remotely section.

    image: oamdev/testapp:v1 # change this to your image

Run the following command:

$ vela up
Parsing vela.yaml ...
Loading templates ...
Building service (express-server)...
Sending build context to Docker daemon  71.68kB
Step 1/10 : FROM mhart/alpine-node:12
 ---> 9d88359808c3
...
pushing image (oamdev/testapp:v1)...
...
Rendering configs for service (express-server)...
Writing deploy config to (.vela/deploy.yaml)
Applying deploy configs ...
Checking if app has been deployed...
App has not been deployed, creating a new deployment...
✅ App has been deployed 🚀🚀🚀
    Port forward: vela port-forward testapp
             SSH: vela exec testapp
         Logging: vela logs testapp
      App status: vela status testapp
  Service status: vela status testapp --svc express-server

Check the status of the service:

$ vela status testapp
  About:
    Name:       testapp
    Namespace:  default
    Created at: 2020-11-02 11:08:32.138484 +0800 CST
    Updated at: 2020-11-02 11:08:32.138485 +0800 CST
  Services:
    - Name: express-server
      Type: webservice
      HEALTHY Ready: 1/1
      Last Deployment:
        Created at: 2020-11-02 11:08:33 +0800 CST
        Updated at: 2020-11-02T11:08:32+08:00
      Routes:

Alternative: Local testing without pushing image remotely

If you have local kind cluster running, you may try the local push option. No remote container registry is needed in this case.

Add local option to build:

    build:
      # push image into local kind cluster without remote transfer
      push:
        local: kind
      docker:
        file: Dockerfile
        context: .

Then deploy the app to kind:

$ vela up

(Advanced) Check rendered manifests

By default, Vela renders the final manifests in .vela/deploy.yaml:

apiVersion: core.oam.dev/v1alpha2
kind: ApplicationConfiguration
metadata:
  name: testapp
  namespace: default
spec:
  components:
  - componentName: express-server
---
apiVersion: core.oam.dev/v1alpha2
kind: Component
metadata:
  name: express-server
  namespace: default
spec:
  workload:
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: express-server
    ...
---
apiVersion: core.oam.dev/v1alpha2
kind: HealthScope
metadata:
  name: testapp-default-health
  namespace: default
spec:
  ...

[Optional] Configure another workload type

By now we have deployed a Web Service, which is the default workload type in KubeVela. We can also add another service of Task type in the same app:

services:
  pi:
    type: task
    image: perl 
    cmd: ["perl",  "-Mbignum=bpi", "-wle", "print bpi(2000)"]
  express-server:
    ...

Then deploy Appfile again to update the application:

$ vela up

Congratulations! You have just deployed an app using Appfile.

What’s Next?

Play more with your app: