diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml index 154c05648..bb9c601ea 100644 --- a/.github/workflows/go.yml +++ b/.github/workflows/go.yml @@ -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 diff --git a/docs/en/end-user/cloud-resources.md b/docs/en/end-user/cloud-resources.md index bfedd2939..d01b9d9f3 100644 --- a/docs/en/end-user/cloud-resources.md +++ b/docs/en/end-user/cloud-resources.md @@ -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 diff --git a/docs/en/end-user/diagnose.md b/docs/en/end-user/diagnose.md index 9a7e5951f..3d13e3878 100644 --- a/docs/en/end-user/diagnose.md +++ b/docs/en/end-user/diagnose.md @@ -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 -``` - -
Click to view diff result +
Click to view the details of diff result ```bash --- diff --git a/docs/en/end-user/explore.md b/docs/en/end-user/explore.md index 622348159..c25889580 100644 --- a/docs/en/end-user/explore.md +++ b/docs/en/end-user/explore.md @@ -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 diff --git a/docs/en/end-user/expose.md b/docs/en/end-user/expose.md index 8ec815a54..3ee3918d2 100644 --- a/docs/en/end-user/expose.md +++ b/docs/en/end-user/expose.md @@ -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 diff --git a/docs/en/end-user/kubectlplugin.md b/docs/en/end-user/kubectlplugin.md new file mode 100644 index 000000000..888a9bf77 --- /dev/null +++ b/docs/en/end-user/kubectlplugin.md @@ -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. +``` \ No newline at end of file diff --git a/docs/en/end-user/scale.md b/docs/en/end-user/scale.md index 6bf31ac38..8fd74ba24 100644 --- a/docs/en/end-user/scale.md +++ b/docs/en/end-user/scale.md @@ -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 diff --git a/docs/en/install.mdx b/docs/en/install.mdx index 0478eabe8..54645162c 100644 --- a/docs/en/install.mdx +++ b/docs/en/install.mdx @@ -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 + ``` + +
Click to see the expected output of helm test + + ```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! + ``` + +
+ ## 3. Get KubeVela CLI Using KubeVela CLI gives you a simplified workflow with optimized output comparing to using `kubectl`. It is not mandatory though. diff --git a/docs/en/platform-engineers/cloud-services.md b/docs/en/platform-engineers/cloud-services.md index c1a3dc2e9..cd9c5eb23 100644 --- a/docs/en/platform-engineers/cloud-services.md +++ b/docs/en/platform-engineers/cloud-services.md @@ -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. \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index e80d3645b..4c90a12cc 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -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',