github/kubevela
1
0
Fork 0
mirror of https://github.com/kubevela/kubevela.git synced 2026-02-14 10:00:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Focus on appfile in docs part 3 (w/ ref docs)

Browse Source
This commit is contained in:
Harry Zhang
2020-11-11 16:59:04 -08:00
parent 16ddba80b3
commit 3af42feb02
19 changed files with 252 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
CONTRIBUTING.md
View File

@@ -14,6 +14,8 @@ contributing to `kubevela` or build a PoC (Proof of Concept).
3. ginkgo 1.14.0+ (just for [E2E test](https://github.com/oam-dev/kubevela/blob/master/DEVELOPMENT.md#e2e-test))
4. golangci-lint 1.31.0+, it will install automatically if you run `make`, you can [install it manually](https://golangci-lint.run/usage/install/#local-installation) if the installation is too slow.
We also recommend you to learn about KubeVela's [design](docs/en/design.md) before dive into its code.
## Build
* Clone this project

18
docs/_sidebar.md
View File

@@ -4,16 +4,16 @@
- Using KubeVela
- Appfile
- [Learning Appfile](/en/developers/devex/appfile.md)
- [Learning Appfile](/en/developers/learn-appfile.md)
- Operating
- [Setting Routes](/en/developers/set-route.md)
- [Setting Auto-scaling Policy](/en/developers/set-autoscale.md)
- [Setting Rollout Strategy](/en/developers/set-rollout.md)
- [Setting Monitoring Policy](/en/developers/set-metrics.md)
- Debugging
- [Port Forwarding](/en/developers/port-forward.md)
- [Check Application Logs](/en/developers/check-logs.md)
- [Execute Commands in Container](/en/developers/exec-cmd.md)
- [Port Forwarding](/en/developers/port-forward.md)
- Extensibility
- [Managing Capabilities](/en/developers/cap-center.md)
- Configuring
@@ -28,9 +28,19 @@
- Roadmap
- [KubeVela Roadmap](/en/roadmap.md)
- Reference
- References
- [Concepts and Glossaries](/en/concepts.md)
- [Capability Documentation](/en/developers/references/README.md)
- [Appfile](/en/developers/references/devex/appfile.md)
- Capabilities
- Workload Types
- [Web Service](/en/developers/references/workload-types/web-service.md)
- [Task](/en/developers/references/workload-types/task.md)
- [Worker](/en/developers/references/workload-types/backend-worker.md)
- Traits
- [Route](/en/developers/references/traits/route.md)
- [Autoscale](/en/developers/references/traits/autoscale.md)
- [Rollout](en/developers/references/traits/rollout.md)
- [Metrics](en/developers/references/traits/metrics.md)
- CLI
- General
- [vela config](/en/cli/vela_config.md)

2
docs/en/concepts.md
View File

@@ -22,7 +22,7 @@ A service represents the runtime configurations (i.e., workload type and traits)
## Application
An application in KubeVela is a collection of services which describes what a developer tries to build and ship from high level. An example could be an "website" application which is composed of two services "frontend" and "backend", or a "wordpress" application which is composed of "php-server" and "database".
An application is defined by an `Appfile` (named `vela.yaml` by default) in KubeVela.
An application is defined by an `Appfile` (named `vela.yaml` by default) in KubeVela. Please check its full schema in the [Appfile reference documentation](developers/references/devex/appfile.md).
## Environment
Before releasing an application to production, it's important to test the code in testing/staging workspaces. In KubeVela, we describe these workspaces as "deployment environments" or "environments" for short. Each environment has its own configuration (e.g., domain, Kubernetes namespace, configuration data, access control policy etc.) to allow user to create different deployment environments such as "test" and "production".

37
docs/en/developers/devex/appfile.md → docs/en/developers/learn-appfile.md
View File

@@ -6,7 +6,8 @@ In this tutorial, we will build and deploy an example NodeJS app under [examples
## Prerequisites
- [docker](https://docs.docker.com/get-docker/) installed on the host
- [Docker](https://docs.docker.com/get-docker/) installed on the host
- [KubeVela](../install.md) installed and configured
## 1. Download test app code
@@ -24,7 +25,7 @@ The example contains NodeJS app code, Dockerfile to build the app.
In the directory there is a [vela.yaml](https://github.com/oam-dev/kubevela/tree/master/docs/examples/testapp/vela.yaml) which follows Appfile format supported by Vela.
We are going to use it to build and deploy the app.
**ATTENTION**: change the image field in vela.yaml to something you can push to:
> 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.
```yaml
image: oamdev/testapp:v1 # change this to your image
@@ -67,10 +68,10 @@ 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
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:
@@ -86,7 +87,7 @@ $ vela status testapp
### Alternative: Local testing without pushing image remotely
If you have local [kind](../../install.md#kind) cluster running, you may try the local push option without pushing image remotely.
If you have local [kind](../install.md) cluster running, you may try the local push option. No remote container registry is needed in this case.
Add local option to `build`:
@@ -146,13 +147,12 @@ spec:
## [Optional] Configure another workload type
By now we have deployed a *webservice* workload. We can also add a *task* workload in appfile:
> Below is a simplified [k8s job example](https://kubernetes.io/docs/concepts/workloads/controllers/job/#running-an-example-job) using Vela:
By now we have deployed a *[Web Service](references/workload-types/webservice.md)*. We can also add another service of *[Task](references/workload-types/task.md)* type in the same app:
```yaml
services:
pi:
type: task
image: perl
cmd: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
@@ -160,25 +160,20 @@ services:
...
```
Then deploy appfile again to update the application:
Then deploy Appfile again to update the application:
```bash
$ vela up
```
> Interested in the design of Appfile? A detailed design doc could be found [here](https://github.com/oam-dev/kubevela/blob/master/design/vela-core/appfile-design.md).
> Interested in the more details of Appfile? [Learn Full Schema of Appfile](references/devex/appfile.md)
## What's Next?
Congratulations! You have just deployed an app using Vela.
Here are some next steps that you can have more play with your app:
Some tips that you can have more play with your app:
- [Check Application Logs](./check-logs.md)
- [Execute Commands in Application Container](./exec-cmd.md)
- [Access Application via Route](./port-forward.md)
- [Check Application Logs](../check-logs.md)
- [Execute Commands in Container](../exec-cmd.md)
- [Port Forward to Container](../port-forward.md)
## References
For more configuration options of built-in capabilities, check [references](../references/README.md)

45
docs/en/developers/references/devex/appfile.md Normal file
View File

@@ -0,0 +1,45 @@
# Appfile
## Description
Appfile is the single source-of-truth of the application description in KubeVela. It captures the application architecture and behaviors of its components following Open Application Model.
Before learning about Appfile's detailed schema, we recommend you to get familiar with core [concepts and glossaries](../../../concepts.md) in KubeVela.
## Schema
List of all available sections for Appfile.
```yaml
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
...
```

2
docs/en/developers/devex/cli.md → docs/en/developers/references/devex/cli.md
View File

@@ -1,7 +1,5 @@
# KubeVela CLI
Learn about general configurations for `vela` command line tool. For the usage of the CLI, please check the KubeVela's [user documentation](../../README.md) instead.
### Auto-completion
#### bash

0
docs/en/developers/devex/dashboard.md → docs/en/developers/references/devex/dashboard.md
View File

0
docs/en/developers/references/traits/autoscale.md Normal file
View File

22
docs/en/developers/references/traits/metrics.md
View File

@@ -1,5 +1,27 @@
# Metrics
## Description
`Metrics` is used to configure monitoring metrics to your service.
## Specification
List of all available properties for a `Route` trait.
```yaml
name: my-app-name
services:
my-service-name:
...
metrics:
format: "prometheus"
port: 8080
path: "/metrics"
scheme: "http"
enabled: true
```
## Properties
Name | Type | Description | Notes

20
docs/en/developers/references/traits/rollout.md
View File

@@ -1,5 +1,24 @@
# Rollout
## Description
`Rollout` is used to configure Canary rollout strategy to your application.
## Specification
List of all available properties for a `Rollout` trait.
```yaml
servcies:
express-server:
...
rollout:
replica: 5
stepWeight: 20
interval: "30s"
```
## Properties
Name | Type | Description | Notes
@@ -7,4 +26,3 @@ Name | Type | Description | Notes
**replica**** | **string** | total replica for your app | [ default to 5 ]
**stepWeight** | **string** | weight percent of every step for this update | [default to 20 ]
**interval** | **string** | wait interval for every rolling update step | [default to '30s']

22
docs/en/developers/references/traits/route.md
View File

@@ -1,5 +1,27 @@
# Route
## Description
`Route` is used to configure external access to your service.
## Specification
List of all available properties for a `Route` trait.
```yaml
name: my-app-name
services:
my-service-name:
...
route:
domain: example.com
issuer: tls
rules:
- path: /testapp
rewriteTarget: /
```
## Properties
Name | Type | Description | Notes

18
docs/en/developers/references/traits/scale.md
View File

@@ -1,5 +1,23 @@
# Scaler
## Description
`Scaler` is used to configure replicas to your service.
## Specification
List of all available properties for a `Scaler` trait.
```yaml
name: my-app-name
services:
my-service-name:
...
scaler:
replica: 100
```
## Properties
Name | Type | Description | Notes

20
docs/en/developers/references/workload-types/backend-worker.md
View File

@@ -1,6 +1,24 @@
# Worker
## Properties
## Description
`Worker` is a workload type to describe long-running, scalable, containerized services that running at backend. They do NOT have network endpoint to receive external network traffic.
## Specification
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"]
```
## Parameters
Name | Type | Description | Notes
------------ | ------------- | ------------- | -------------

20
docs/en/developers/references/workload-types/task.md
View File

@@ -1,5 +1,25 @@
# Task
## Description
`Task` is a workload type to describe jobs that run code or a script to completion.
## Specification
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)"]
```
## Properties
Name | Type | Description | Notes

33
docs/en/developers/references/workload-types/web-service.md
View File

@@ -1,6 +1,35 @@
# Webservice
# Web Service
## Properties
## Description
`Web Service` is a workload type to describe 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 `Web Service` type.
## Specification
List of all configuration options for a `Web Service` 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
env:
- name: FOO
value: bar
- name: FOO
valueFrom:
secretKeyRef:
name: bar
key: bar
```
## Parameters
Name | Type | Description | Notes
------------ | ------------- | ------------- | -------------

15
docs/en/developers/set-metrics.md
View File

@@ -1,7 +1,6 @@
# Monitoring Application
If your application has exposed metrics, you can easily setup monitoring system
with the help of `metric` capability.
If your application has exposed metrics, you can easily tell the platform how to collect the metrics data from your app with `metric` capability.
Let's run [`christianhxc/gorandom:1.0`](https://github.com/christianhxc/prometheus-tutorial) as an example app.
The app will emit random latencies as metrics.
@@ -60,12 +59,18 @@ The metrics trait will automatically discover port and label to monitor if no pa
If more than one ports found, it will choose the first one by default.
## Verify that the metrics are collected on prometheus
**(Optional) Verify that the metrics are collected on Prometheus**
<details>
Expose the port of Prometheus dashboard:
```bash
kubectl --namespace monitoring port-forward `kubectl -n monitoring get pods -l prometheus=oam -o name` 9090
```
Then access the prometheus dashboard via http://localhost:9090/targets
Then access the Prometheus dashboard via http://localhost:9090/targets
![Image of Prometheus Dashboard](../../resources/metrics.jpg)
![Prometheus Dashboard](../../resources/metrics.jpg)
</details>

44
docs/en/developers/set-rollout.md
View File

@@ -2,9 +2,7 @@
The `rollout` section is used to configure rolling update policy for your app.
Add rollout config under `express-server` along with the [`route` config](./set-rollout.md).
As for convenience， the complete example would like as below:
Add rollout config under `express-server` along with a `route`.
```yaml
name: testapp
@@ -13,32 +11,24 @@ services:
type: webservice
image: oamdev/testapp:v1
port: 8080
rollout:
replica: 5
stepWeight: 20
interval: "30s"
route:
domain: example.com
```
> The full specification of `rollout` could be found [here](references/traits/rollout.md)
Apply this `appfile.yaml`:
```bash
$ vela up
```
You could use rollout capability to
The workflow will like below:
Firstly, deploy your app by:
```bash
$ vela svc deploy testapp -t webservice --image oamdev/testapp:v1 --port 8080
App testapp deployed
```
You could check the status by:
```bash
@@ -99,7 +89,7 @@ Apply this `appfile.yaml` again:
$ vela up
```
Then it will rolling update your instance, you could try `curl` your app multiple times:
You could then try to `curl` your app multiple times and and see how the new instances being promoted following Canary rollout strategy:
```bash
$ curl -H "Host:example.com" http://<your-ingress-ip-address>/
@@ -114,23 +104,7 @@ $ curl -H "Host:example.com" http://<your-ingress-ip-address>/
Hello World%
$ curl -H "Host:example.com" http://<your-ingress-ip-address>/
Hello World -- Updated Version Two!%
```
It will return both version of output info as both instances are all existing.
<details>
<summary>Under the hood, it was flagger canary running.</summary>
```bash
$ kubectl get canaries.flagger.app testapp-trait-76fc76fddc -w
NAME STATUS WEIGHT LASTTRANSITIONTIME
testapp-trait-76fc76fddc Progressing 0 2020-11-10T09:06:10Z
testapp-trait-76fc76fddc Progressing 20 2020-11-10T09:06:30Z
testapp-trait-76fc76fddc Progressing 40 2020-11-10T09:06:40Z
testapp-trait-76fc76fddc Progressing 60 2020-11-10T09:07:31Z
testapp-trait-76fc76fddc Promoting 0 2020-11-10T09:08:00Z
testapp-trait-76fc76fddc Promoting 100 2020-11-10T09:08:10Z
testapp-trait-76fc76fddc Finalising 0 2020-11-10T09:08:20Z
testapp-trait-76fc76fddc Succeeded 0 2020-11-10T09:08:30Z
```
</details>
For every 30 second, 20% more traffic will be shifted to the new instance from the old instance as we configured in Appfile.

4
docs/en/developers/set-route.md
View File

@@ -16,13 +16,15 @@ servcies:
rewriteTarget: /
```
> The full specification of `route` could be found [here](references/traits/route.md)
Apply again:
```bash
$ vela up
```
Check the status until we see route trait ready:
Check the status until we see route is ready:
```bash
$ vela status testapp
About:

3
docs/en/quick-start.md
View File

@@ -73,8 +73,7 @@ Hello World
Congratulations! You have just deployed an app using KubeVela. Here are some recommended next steps:
- Learn about the project's [motivation](./introduction.md) and [architecture](./design.md)
- Try out more [tutorials](./developers/devex/appfile.md)
- Try out more [tutorials](developers/learn-appfile.md)
- Join our community [Slack](https://cloud-native.slack.com/archives/C01BLQ3HTJA) and/or [Gitter](https://gitter.im/oam-dev/community)
Welcome onboard and sail Vela!