github/kubevela
1
0
Fork 0
mirror of https://github.com/kubevela/kubevela.git synced 2026-08-19 04:26:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add More End User Docs (#1511)

Browse Source 
* update docs

* update docs

* refine cloud resource docs

* update install guidegst
This commit is contained in:
Jianbo Sun
2021-04-16 21:46:44 +08:00
committed by GitHub
parent fb6d505e6e
commit 75f081f248
10 changed files with 147 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/go.yml
+1 -1
View File
@@ -29,7 +29,7 @@ jobs:
uses: fkirc/skip-duplicate-actions@v3.3.0
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
paths_ignore: '["**.md", "**.png", "**.jpg"]'
paths_ignore: '["**.md", "**.mdx", "**.png", "**.jpg"]'
do_not_skip: '["workflow_dispatch", "schedule", "push"]'
concurrent_skipping: false
docs/en/end-user/cloud-resources.md
+13 -2
View File
@@ -2,11 +2,22 @@
title: Provision and Consume Cloud Resources
---
We assure that Crossplane controllers, ProviderConfig, ComponentDefinition and TraitDefinition are ready. If not, please
refer to [section: Cloud Service for Platform Engineers](../platform-engineers/cloud-services.md)
> ⚠️ This section requires your platform builder has already installed the [cloud resources related capabilities](../platform-engineers/cloud-services).
## Provision and consume cloud resource in a single application v1 (one cloud resource)
Check the parameters of cloud resource component:
```shell
kubectl vela show alibaba-rds
```
Use the service binding trait to bind cloud resources into workload as ENV.
```shell
kubectl vela show service-binding
```
Create an application with a cloud resource provisioning component and a consuming component as below.
```yaml
docs/en/end-user/diagnose.md
+24 -43
View File
@@ -2,29 +2,15 @@
title: Debug and Test
---
Now you can use the debug and test feature of vela through the kubectl plugin.
You can make further debug and test for your application by using [vela kubectl plugin](./kubectlplugin).
## Installation
## Dry-Run the `Application`
You can install kubectl plugin `kubectl vela` by:
Dry run will help you to understand what are the real resources which will to be expanded and deployed
to the Kubernetes cluster. In other words, it will mock to run the same logic as KubeVela's controller
and output the results locally.
**macOS/Linux**
```shell script
curl -fsSl https://kubevela.io/script/install-kubectl-vela.sh | bash
```
## Debug and Test
`kubectl vela` supports several killer debug features, you can view and compare the
rendering results of the Application through kubectl.
### Dry-Run the `Application`
You can use `kubectl vela` to dry run and check the rendered resources in real Kubernetes cluster.
This command will exactly execute the same render logic in KubeVela's Application Controller
and output the result for you.
Suppose we have the following Application
For example, let's dry-run the following application:
```yaml
# app.yaml
@@ -47,8 +33,6 @@ spec:
"/": 8000
```
Through `kubectl vela dry-run`, you can see the k8s resources that the application will generate in the cluster.
```shell
kubectl vela dry-run -f app.yaml
---
@@ -121,35 +105,31 @@ spec:
```
In this example, the definitions(`webservice` and `ingress`) which `vela-app` depends on is the built-in
definitions of KubeVela. You can also use `-d `or `--definitions` to specify the local definition files.
components and traits of KubeVela. You can also use `-d `or `--definitions` to specify your local definition files.
`-d `or `--definitions` permitting user to provide capability definitions used in the application from local files.
`dry-run` cmd will prioritize the provided capabilities than the living ones in the cluster.
### Live-Diff the `Application`
## Live-Diff the `Application`
`kubectl vela live-diff` allows users to have a preview of what would change if upgrade an application.
It basically generates a diff between the specific revision of an application and the result of `kubectl vela dry-run`
Live-diff helps you to have a preview of what would change if you're going to upgrade an application without making any changes
to the living cluster.
This feature is extremely useful for serious production deployment, and make the upgrade under control
It basically generates a diff between the specific revision of running instance and the local candidate application.
The result shows the changes (added/modified/removed/no_change) of the application as well as its sub-resources,
such as components and traits. `live-diff` will not make any changes to the living cluster,
so it's very helpful if you want to update an application but worry about the unknown results that may be produced.
such as components and traits.
Let's deploy the application `vela-app` mentioned [here](#dry-run-the-application).
Assume you have just deployed the application in dry-run section.
Then you can list the revisions of the Application.
```shell
kubectl apply -f app.yaml
```
Then you can see that the v1 version of Application is generated.
```shell
$ kubectl get applicationrevisions.core.oam.dev
$ kubectl get apprev -l app.oam.dev/name=vela-app
NAME AGE
vela-app-v1 50s
```
Then, assume we want to update the application with below configuration. To preview changes brought by updating
while not really apply updated configuration into the cluster, we can use `live-diff` here.
Assume we're going to upgrade the application like below.
```yaml
# new-app.yaml
@@ -178,6 +158,11 @@ spec:
"/": 8080 # change port
```
Run live-diff like this:
```shell
kubectl vela live-diff -f new-app.yaml -r vela-app-v1
```
`-r` or `--revision` is a flag that specifies the name of a living ApplicationRevision with which you want to compare the updated application.
@@ -185,11 +170,7 @@ spec:
which are out of the context of a change will be omitted. It's useful if the diff result contains a lot of unchanged content
while you just want to focus on the changed ones.
```shell
kubectl vela live-diff -f new-app.yaml -r vela-app-v1
```
<details><summary> Click to view diff result </summary>
<details><summary> Click to view the details of diff result </summary>
```bash
---
docs/en/end-user/explore.md
+1 -1
View File
@@ -98,7 +98,7 @@ worker Deployment Describes long-running, scalable, containerize
The component definition objects are namespace isolated align with application, while the `vela-system` is a common system namespace of KubeVela,
definitions laid here can be used by every application.
You can use `kubectl vela show` to see the usage of specific component definition.
You can use [vela kubectl plugin](./kubectlplugin) to view the detail usage of specific component definition.
```shell
$ kubectl vela show webservice
docs/en/end-user/expose.md
+15 -2
View File
@@ -6,6 +6,21 @@ title: Expose Application
To expose your application publicly, you just need to add an `ingress` trait.
View ingress schema by [vela kubectl plugin](./kubectlplugin).
```shell
$ kubectl vela show ingress
# Properties
+--------+------------------------------------------------------------------------------+----------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+--------+------------------------------------------------------------------------------+----------------+----------+---------+
| http | Specify the mapping relationship between the http path and the workload port | map[string]int | true | |
| domain | Specify the domain you want to expose | string | true | |
+--------+------------------------------------------------------------------------------+----------------+----------+---------+
```
Then modify and deploy this application.
```yaml
# vela-app.yaml
apiVersion: core.oam.dev/v1beta1
@@ -27,8 +42,6 @@ spec:
"/": 8000
```
Apply this application:
```bash
$ kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/docs/examples/vela-app.yaml
application.core.oam.dev/first-vela-app created
docs/en/end-user/kubectlplugin.md
+46
View File
@@ -0,0 +1,46 @@
---
title: Install kubectl plugin
---
Install vela kubectl plugin can help you to ship applications more easily!
## Installation
You can install kubectl plugin `kubectl vela` by:
**macOS/Linux**
```shell script
curl -fsSl https://kubevela.io/script/install-kubectl-vela.sh | bash
```
You can also download the binary from [release pages ( >= v1.0.3)](https://github.com/oam-dev/kubevela/releases) manually.
Kubectl will discover it from your system path automatically.
## Usage
```shell
$ kubectl vela -h
A Highly Extensible Platform Engine based on Kubernetes and Open Application Model.
Usage:
kubectl vela [flags]
kubectl vela [command]
Available Commands:
Flags:
-h, --help help for vela
dry-run Dry Run an application, and output the K8s resources as
result to stdout, only CUE template supported for now
live-diff Dry-run an application, and do diff on a specific app
revison. The provided capability definitions will be used
during Dry-run. If any capabilities used in the app are not
found in the provided ones, it will try to find from
cluster.
show Show the reference doc for a workload type or trait
version Prints out build version information
Use "kubectl vela [command] --help" for more information about a command.
```
docs/en/end-user/scale.md
+12
View File
@@ -8,6 +8,18 @@ In the [Deploy Application](../application) section, we use `cpuscaler` trait as
You can use scale your application manually by using `scaler` trait.
```shell
$ kubectl vela show scaler
# Properties
+----------+--------------------------------+------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+----------+--------------------------------+------+----------+---------+
| replicas | Specify replicas of workload | int | true | 1 |
+----------+--------------------------------+------+----------+---------+
```
Deploy the application.
```yaml
# sample-manual.yaml
apiVersion: core.oam.dev/v1beta1
docs/en/install.mdx
+31
View File
@@ -97,6 +97,37 @@ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/mast
By default, it will enable the webhook with a self-signed certificate provided by [kube-webhook-certgen](https://github.com/jet/kube-webhook-certgen).
You can also [install it with `cert-manager`](./advanced-install#install-kubevela-with-cert-manager).
4. Verify chart installed successfully
```shell script
helm test kubevela -n vela-system
```
<details> <summary> Click to see the expected output of helm test </summary>
```shell
Pod kubevela-application-test pending
Pod kubevela-application-test pending
Pod kubevela-application-test running
Pod kubevela-application-test succeeded
NAME: kubevela
LAST DEPLOYED: Tue Apr 13 18:42:20 2021
NAMESPACE: vela-system
STATUS: deployed
REVISION: 1
TEST SUITE: kubevela-application-test
Last Started: Fri Apr 16 20:49:10 2021
Last Completed: Fri Apr 16 20:50:04 2021
Phase: Succeeded
TEST SUITE: first-vela-app
Last Started: Fri Apr 16 20:49:10 2021
Last Completed: Fri Apr 16 20:49:10 2021
Phase: Succeeded
NOTES:
Welcome to use the KubeVela! Enjoy your shipping application journey!
```
</details>
## 3. Get KubeVela CLI
Using KubeVela CLI gives you a simplified workflow with optimized output comparing to using `kubectl`. It is not mandatory though.
docs/en/platform-engineers/cloud-services.md
+2
View File
@@ -338,3 +338,5 @@ environment names with secret key. Here is an example.
key: Bucket
...
```
You can see [the end user usage workflow](../end-user/cloud-resources) to know how it used.
docs/sidebars.js
+2
View File
@@ -28,7 +28,9 @@ module.exports = {
'rollout/appdeploy',
{
'More Operations': [
'end-user/kubectlplugin',
'end-user/explore',
'end-user/diagnose',
'end-user/expose',
'end-user/scale',
'end-user/labels',