Merge pull request #916 from resouer/dev

Fix ref doc guide
This commit is contained in:
Jianbo Sun
2021-01-21 14:04:18 +08:00
committed by GitHub
10 changed files with 222 additions and 192 deletions
+1 -2
View File
@@ -14,7 +14,6 @@
- End User Guide
- Appfile
- [Learning Appfile](/en/developers/learn-appfile.md)
- [Writing-Appfile](./developers/writing-appfile.md)
- Operating
- [Setting Routes](/en/developers/set-route.md)
- [Setting Auto-scaling Policy](/en/developers/set-autoscale.md)
@@ -36,7 +35,7 @@
- References
- [Appfile](/en/developers/references/devex/appfile.md)
- [Capabilities](./developers/references/README.md)
- [Capabilities](/en/developers/references/README.md)
- Workload Types
- [Webservice](/en/developers/references/workload-types/webservice.md)
- [Task](/en/developers/references/workload-types/task.md)
+7 -3
View File
@@ -12,10 +12,12 @@ KubeVela follows a workflow with separate of concerns as below:
## Application
An *application* in KubeVela is an abstraction that allows developers to work with a single artifact to capture the complete application definition. It simplifies administrative tasks and serves as an anchor to avoid configuration drifts during operation, and also provides a much simpler path for on-boarding Kubernetes capabilities without relying on low level details. For example, a developer will be able to model the "web service" in Kubernetes without defining detailed Deployment + Service combo each time, or claim the auto-scaling requirements without referring to the underlying KEDA ScaleObject.
An *application* in KubeVela is an abstraction that allows developers to work with a single artifact to capture the complete application definition.
This is important to simplify administrative tasks and can serve as an anchor to avoid configuration drifts during operation. Also, as an abstraction object, `Application` provided a much simpler path for on-boarding Kubernetes capabilities without relying on low level details. For example, a developer will be able to model a "web service" without defining detailed Kubernetes Deployment + Service combo each time, or claim the auto-scaling requirements without referring to the underlying KEDA ScaleObject.
An application is composed of a collection of components. For instance, a `website` application with two components (i.e. `frontend` and `backend`) could be modeled as below:
An example of `website` application with two components (i.e. `frontend` and `backend`) could be modeled as below:
```yaml
apiVersion: core.oam.dev/v1alpha2
@@ -54,9 +56,11 @@ For each of the components, its `.type` field represents the runtime characteris
Optionally, each component has a `.traits` section that augments its workload instance with operational features such as load balancing policy, network ingress routing, auto-scaling policies, or upgrade strategies, etc. Its `.name` field references the specific trait definition, and `.properties` sets detailed configuration values of the given trait.
We also reference workload type and trait as "capabilities" in KubeVela.
## Definitions
Both the schemas of workload settings and trait properties in `Application` are enforced by modularized capability templates that are pre-defined separately by platform team. The platform team is responsible for registering and managing definitions in the cluster following [workload definition](https://github.com/oam-dev/spec/blob/master/4.workload_definitions.md) and [trait definition](https://github.com/oam-dev/spec/blob/master/6.traits.md) specifications in Open Application Model (OAM).
Both the schemas of workload settings and trait properties in `Application` are enforced by capability templates that are pre-defined separately by platform team in a set of definition objects. The platform team is responsible for registering and managing definitions in the cluster following [workload definition](https://github.com/oam-dev/spec/blob/master/4.workload_definitions.md) and [trait definition](https://github.com/oam-dev/spec/blob/master/6.traits.md) specifications in Open Application Model (OAM).
For example, a `worker` workload type could be defined by a `WorkloadDefinition` as below:
+101
View File
@@ -0,0 +1,101 @@
# The Reference Documentation Guide of Capabilities
In this documentation, we will show how to check the detailed schema of a given capability (i.e. workload type or trait).
This may sound challenging because every capability is a "plug-in" in KubeVela (even for the built-in ones), also, it's by design that KubeVela allows platform administrators to modify the capability templates at any time. In this case, do we need to manually write documentation for every newly installed capability? And how can we ensure those documentations for the system is up-to-date?
## Using Browser
Actually, as a important part of its "extensibility" design, KubeVela will always **automatically generate** reference documentation for every workload type or trait registered in your Kubernetes cluster, based on its template in definition of course. This feature works for any capability: either built-in ones or your own workload types/traits.
Thus, as an end user, the only thing you need to do is:
```console
$ vela show WORKLOAD_TYPE or TRAIT
```
This command will automatically open the reference documentation for given workload type or trait in your default browser.
### For Workload Types
Let's take `$ vela show webservice` as example. The detailed schema documentation for `Web Service` workload type will show up immediately as below:
![](../../resources/vela_show_webservice.jpg)
Note that there's in the section named `Specification`, it even provides you with a full sample for the usage of this workload type with a fake name `my-service-name`.
### For Traits
Similarly, we can also do `$ vela show autoscale`:
![](../../resources/vela_show_autoscale.jpg)
With these auto-generated reference documentations, we could easily complete the application description by simple copy-paste, for example:
```yaml
name: helloworld
services:
backend: # copy-paste from the webservice ref doc above
image: oamdev/testapp:v1
cmd: ["node", "server.js"]
port: 8080
cpu: "0.1"
autoscale: # copy-paste and modify from autoscaler ref doc above
min: 1
max: 8
cron:
startAt: "19:00"
duration: "2h"
days: "Friday"
replicas: 4
timezone: "America/Los_Angeles"
```
## Using Terminal
This reference doc feature also works for terminal-only case. For example:
```shell
$ vela show webservice --no-website
# Properties
+-------+----------------------------------------------------------------------------------+---------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+-------+----------------------------------------------------------------------------------+---------------+----------+---------+
| cmd | Commands to run in the container | []string | false | |
| env | Define arguments by using environment variables | [[]env](#env) | false | |
| image | Which image would you like to use for your service | string | true | |
| port | Which port do you want customer traffic sent to | int | true | 80 |
| cpu | Number of CPU units for the service, like `0.5` (0.5 CPU core), `1` (1 CPU core) | string | false | |
+-------+----------------------------------------------------------------------------------+---------------+----------+---------+
## env
+-----------+-----------------------------------------------------------+-------------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+-----------+-----------------------------------------------------------+-------------------------+----------+---------+
| name | Environment variable name | string | true | |
| value | The value of the environment variable | string | false | |
| valueFrom | Specifies a source the value of this var should come from | [valueFrom](#valueFrom) | false | |
+-----------+-----------------------------------------------------------+-------------------------+----------+---------+
### valueFrom
+--------------+--------------------------------------------------+-------------------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+--------------+--------------------------------------------------+-------------------------------+----------+---------+
| secretKeyRef | Selects a key of a secret in the pod's namespace | [secretKeyRef](#secretKeyRef) | true | |
+--------------+--------------------------------------------------+-------------------------------+----------+---------+
#### secretKeyRef
+------+------------------------------------------------------------------+--------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+------+------------------------------------------------------------------+--------+----------+---------+
| name | The name of the secret in the pod's namespace to select from | string | true | |
| key | The key of the secret to select from. Must be a valid secret key | string | true | |
+------+------------------------------------------------------------------+--------+----------+---------+
```
> Note that for all the built-in capabilities, we already published their reference docs [here](https://kubevela.io/#/en/developers/references/) based on the same doc generation mechanism.
+108 -12
View File
@@ -1,15 +1,111 @@
# Capability Documentation
# The Reference Documentation of Capabilities
Learning the detailed schema of every workload type and trait supported in KubeVela.
In this documentation, we will show how to check the detailed schema of a given capability (i.e. workload type or trait).
## Workload Types
- [webservice](workload-types/webservice.md)
- [task](workload-types/task.md)
- [worker](workload-types/worker.md)
This may sound challenging because every capability is a "plug-in" in KubeVela (even for the built-in ones), also, it's by design that KubeVela allows platform administrators to modify the capability templates at any time. In this case, do we need to manually write documentation for every newly installed capability? And how can we ensure those documentations for the system is up-to-date?
## Traits
- [route](traits/route.md)
- [autoscale](traits/autoscale.md)
- [rollout](traits/rollout.md)
- [metrics](traits/metrics.md)
- [scaler](traits/scaler.md)
## Using Browser
Actually, as a important part of its "extensibility" design, KubeVela will always **automatically generate** reference documentation for every workload type or trait registered in your Kubernetes cluster, based on the template in its definition of course. This feature works for any capability: either built-in ones or your own workload types/traits.
Thus, as an end user, the only thing you need to do is:
```console
$ vela show WORKLOAD_TYPE or TRAIT
```
This command will automatically open the reference documentation for given workload type or trait in your default browser.
Let's take `$ vela show webservice` as example. The detailed schema documentation for `Web Service` workload type will show up immediately as below:
![](../../../resources/vela_show_webservice.jpg)
Note that there's in the section named `Specification`, it even provides you with a full sample for the usage of this workload type with a fake name `my-service-name`.
Similarly, we can also do `$ vela show autoscale`:
![](../../../resources/vela_show_autoscale.jpg)
With these auto-generated reference documentations, we could easily complete the application description by simple copy-paste, for example:
```yaml
name: helloworld
services:
backend: # copy-paste from the webservice ref doc above
image: oamdev/testapp:v1
cmd: ["node", "server.js"]
port: 8080
cpu: "0.1"
autoscale: # copy-paste and modify from autoscaler ref doc above
min: 1
max: 8
cron:
startAt: "19:00"
duration: "2h"
days: "Friday"
replicas: 4
timezone: "America/Los_Angeles"
```
## Using Terminal
This reference doc feature also works for terminal-only case. For example:
```shell
$ vela show webservice --no-website
# Properties
+-------+----------------------------------------------------------------------------------+---------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+-------+----------------------------------------------------------------------------------+---------------+----------+---------+
| cmd | Commands to run in the container | []string | false | |
| env | Define arguments by using environment variables | [[]env](#env) | false | |
| image | Which image would you like to use for your service | string | true | |
| port | Which port do you want customer traffic sent to | int | true | 80 |
| cpu | Number of CPU units for the service, like `0.5` (0.5 CPU core), `1` (1 CPU core) | string | false | |
+-------+----------------------------------------------------------------------------------+---------------+----------+---------+
## env
+-----------+-----------------------------------------------------------+-------------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+-----------+-----------------------------------------------------------+-------------------------+----------+---------+
| name | Environment variable name | string | true | |
| value | The value of the environment variable | string | false | |
| valueFrom | Specifies a source the value of this var should come from | [valueFrom](#valueFrom) | false | |
+-----------+-----------------------------------------------------------+-------------------------+----------+---------+
### valueFrom
+--------------+--------------------------------------------------+-------------------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+--------------+--------------------------------------------------+-------------------------------+----------+---------+
| secretKeyRef | Selects a key of a secret in the pod's namespace | [secretKeyRef](#secretKeyRef) | true | |
+--------------+--------------------------------------------------+-------------------------------+----------+---------+
#### secretKeyRef
+------+------------------------------------------------------------------+--------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+------+------------------------------------------------------------------+--------+----------+---------+
| name | The name of the secret in the pod's namespace to select from | string | true | |
| key | The key of the secret to select from. Must be a valid secret key | string | true | |
+------+------------------------------------------------------------------+--------+----------+---------+
```
## For Built-in Capabilities
Note that for all the built-in capabilities, we already published their reference docs below based on the same doc generation mechanism.
- Workload Types
- [webservice](workload-types/webservice.md)
- [task](workload-types/task.md)
- [worker](workload-types/worker.md)
- Traits
- [route](traits/route.md)
- [autoscale](traits/autoscale.md)
- [rollout](traits/rollout.md)
- [metrics](traits/metrics.md)
- [scaler](traits/scaler.md)
@@ -44,4 +44,4 @@ services:
```
To set properties for the Workload types and Traits above, please refer to [Writing Appfile](../../writing-appfile.md).
> To learn about how to set the properties of specific workload type or trait, please check the [reference documentation guide](../../check-ref-doc.md).
+1 -1
View File
@@ -29,7 +29,7 @@ Introduce how to automatically scale workloads by cron.
timezone: "America/Los_Angeles"
```
> The full specification of `autoscale` could show up by `vela show autoscale` or be found on [kubevela.io](references/traits/autoscale.md)
> The full specification of `autoscale` could show up by `$ vela show autoscale` or be found on [its reference documentation](references/traits/autoscale.md)
2. Deploy an application
+1 -1
View File
@@ -26,7 +26,7 @@ The app will emit random latencies as metrics.
EOF
```
> The full specification of `metrics` could show up by `vela show metrics` or be found on [kubevela.io](references/traits/metrics.md)
> The full specification of `metrics` could show up by `$ vela show metrics` or be found on [its reference documentation](references/traits/metrics.md)
2. Deploy the application:
+1 -1
View File
@@ -21,7 +21,7 @@ services:
domain: "example.com"
```
> The full specification of `rollout` could show up by `vela show rollout` or be found on [kubevela.io](references/traits/rollout.md)
> The full specification of `rollout` could show up by `$ vela show rollout` or be found on [its reference documentation](references/traits/rollout.md)
Apply this `appfile.yaml`:
+1 -1
View File
@@ -16,7 +16,7 @@ services:
rewriteTarget: /
```
> The full specification of `route` could show up by `vela show route` or be found on [kubevela.io](references/traits/route.md)
> The full specification of `route` could show up by `$ vela show route` or be found on [its reference documentation](references/traits/route.md)
Apply again:
-170
View File
@@ -1,170 +0,0 @@
# Writing Appfile
If you have successfully deployed an application with the Appfile in [Learning Appfile Guide](./learn-appfile.md), you may
wonder how to set properties for Workload types and Traits from scratch on your own.
Let's imagine we'd like to write an Appfile to deploy an application `helloworld` with a service `backend` whose Workload type is `webservice` and
automatically scale it to 4 replicas from 19:00 to 21:00 every Friday. Here are several ways to get going.
## Look up the reference doc in a locally hosted website
Just run `vela show ${workloadType}/${trait}` to start up the properties reference doc for the Workload type or Trait in
a locally hosted website. Let's run `vela show webservice`. Your default web browser is invoked, and a new tab [http://127.0.0.1:18081/#/workload-types/webservice](http://127.0.0.1:18081/#/workload-types/webservice) is automatically created.
![](../../resources/vela_show_webservice.jpg)
In section `Specification`, here is a sample Appfile.
```yaml
name: my-app-name
services:
my-service-name:
type: webservice # could be skipped
image: oamdev/testapp:v1
cmd: ["node", "server.js"]
port: 8080
cpu: "0.1"
env:
- name: FOO
value: bar
- name: FOO
valueFrom:
secretKeyRef:
name: bar
key: bar
```
- Set application name
In the first line, we can set the name to `helloworld` as our application name.
- Set Workload type's properties
For `services`, we change `my-service-name` to `backend` as the service name, and set `services.backend.type` to `webservice`
to mark the Workload type. As the default Workload type in KubeVela is `service`, we can also skip `services.backend.type`.
```yaml
name: helloworld
services:
backend:
```
Now let's set the properties and values for service `backend` in field `services.backend`. Look up section `Properties` in
the website above, which clearly lists all properties for `webservice` and each property contains name, description, type,
required or optional, and default value.
For example, property `cmd` can set the commands to run in the container, and it's in list format, while optional; property `port`
has a default value `80`, which means we can skip setting it if the target port is the same; the format type of property
`env` is complicated, and the struct consists of three sub-property `name`, `value` and `valueFrom`.
Now let's complete field `services.backend`.
```yaml
name: helloworld
services:
backend:
image: oamdev/testapp:v1
cmd: ["node", "server.js"]
port: 8080
cpu: "0.1"
```
- Set Trait's properties
Trait `autoscale` can automatically scale a service. Let load its reference doc by `vela show autoscale`.
![](../../resources/vela_show_autoscale.jpg)
Add a new field `services.backend.autoscale` to set its properties. By checking section `Perperties`, we get to know we can set
`min` to `1` and `max` to `8`. We should also add `service.backend.autoscale.cron` field to set `startAt` to `19:00`,
`duration` to `2h`, `days` to `Friday`, and `timezone` to your expected timezone, like `America/Los_Angeles`.
Now let's finish the Appfile.
```yaml
name: helloworld
services:
backend:
image: oamdev/testapp:v1
cmd: ["node", "server.js"]
port: 8080
cpu: "0.1"
autoscale:
min: 1
max: 8
cron:
startAt: "19:00"
duration: "2h"
days: "Friday"
replicas: 4
timezone: "America/Los_Angeles"
```
## Show up the properties reference on the Cli console
If you can't invoke a browser and just want to see the properties reference on the terminal console, just add flag `--no-website` to command `vela show`.
```shell
$ vela show webservice --no-website
# Properties
+-------+----------------------------------------------------------------------------------+---------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+-------+----------------------------------------------------------------------------------+---------------+----------+---------+
| cmd | Commands to run in the container | []string | false | |
| env | Define arguments by using environment variables | [[]env](#env) | false | |
| image | Which image would you like to use for your service | string | true | |
| port | Which port do you want customer traffic sent to | int | true | 80 |
| cpu | Number of CPU units for the service, like `0.5` (0.5 CPU core), `1` (1 CPU core) | string | false | |
+-------+----------------------------------------------------------------------------------+---------------+----------+---------+
## env
+-----------+-----------------------------------------------------------+-------------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+-----------+-----------------------------------------------------------+-------------------------+----------+---------+
| name | Environment variable name | string | true | |
| value | The value of the environment variable | string | false | |
| valueFrom | Specifies a source the value of this var should come from | [valueFrom](#valueFrom) | false | |
+-----------+-----------------------------------------------------------+-------------------------+----------+---------+
### valueFrom
+--------------+--------------------------------------------------+-------------------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+--------------+--------------------------------------------------+-------------------------------+----------+---------+
| secretKeyRef | Selects a key of a secret in the pod's namespace | [secretKeyRef](#secretKeyRef) | true | |
+--------------+--------------------------------------------------+-------------------------------+----------+---------+
#### secretKeyRef
+------+------------------------------------------------------------------+--------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+------+------------------------------------------------------------------+--------+----------+---------+
| name | The name of the secret in the pod's namespace to select from | string | true | |
| key | The key of the secret to select from. Must be a valid secret key | string | true | |
+------+------------------------------------------------------------------+--------+----------+---------+
```
## Look up the reference doc in a [kubevela.io](https://kubevela.io/#/en/developers/references/)
> Platform team extended Workload type or Trait currently could not display in KubeVela official site.
If you just want to look up KubeVela built-in Workload types and Traits, directly visiting the official site [https://kubevela.io/#/en/developers/references/](./references/README.md)
is also recommended.
# Comparation
Properties reference | Access | Support built-in capability? | Support extended capability? | Include Appfile sample
------------ | ------------- | ------------- | ------------- | ------------- |
Locally hosted website | `vela show ${workloadType}/${trait}` | Yes | Yes | Yes
Cli console | `vela show ${workloadType}/${trait} --no-website` | Yes | Yes | No
Official site | [https://kubevela.io/#/en/developers/references/](https://kubevela.io/#/en/developers/references/) | Yes | No | Yes