diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 6ecc711cd..ee6032272 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,8 +1,10 @@ - Overview - [Introduction](/en/introduction.md) - - [Getting Started](/en/quick-start.md) + - [Installation](/en/install.md) + - [Quick Start](/en/quick-start.md) + - [Concepts](/en/concepts.md) -- Using KubeVela +- For Developers - [Setting Up Deployment Environment](/en/developers/config-enviroments.md) - [Initializing Application](/en/developers/app-init.md) - [Setting Routes](/en/developers/set-route.md) @@ -18,46 +20,45 @@ - [Managing Capabilities](/en/developers/cap-center.md) - [Capability References](/en/developers/references/README.md) -- Extending KubeVela - - [Add Trait](/en/platform-engineers/trait.md) - - [Add Workload Type](/en/platform-engineers/workload-type.md) - - [Add Cloud Resource](/en/platform-engineers/cloud-resource.md) +- For Platform Engineers + - [Extending KubeVela](/en/platform-engineers/extending-kubevela.md) + +- Internals + - [Design and Architecture](/en/design.md) - Roadmap - [KubeVela Roadmap](/en/roadmap.md) -- Reference - - [Concepts and Glossaries](/en/concepts.md) - - CLI - - General - - [vela config](/en/cli/vela_config.md) - - [vela env](/en/cli/vela_env.md) - - [vela init](/en/cli/vela_init.md) - - [vela install](/en/cli/vela_install.md) - - [vela up](/en/cli/vela_up.md) - - [vela version](/en/cli/vela_version.md) - - Applications - - [vela delete](/en/cli/vela_delete.md) - - [vela exec](/en/cli/vela_exec.md) - - [vela logs](/en/cli/vela_logs.md) - - [vela ls](/en/cli/vela_ls.md) - - [vela port-forward](/en/cli/vela_port-forward.md) - - [vela show](/en/cli/vela_show.md) - - [vela status](/en/cli/vela_status.md) - - [vela svc](/en/cli/vela_svc.md) - - Workload Types - - [vela workloads](/en/cli/vela_workloads.md) - - Traits - - [vela traits](/en/cli/vela_traits.md) - - [vela scaler](/en/cli/vela_scaler.md) - - [vela route](/en/cli/vela_route.md) - - [vela autoscale](/en/cli/vela_autoscale.md) - - [vela rollout](/en/cli/vela_rollout.md) - - [vela metric](/en/cli/vela_metric.md) - - System - - [vela completion](/en/cli/vela_completion.md) - - [vela dashboard](/en/cli/vela_dashboard.md) - - [vela system](/en/cli/vela_system.md) - - [vela template](/en/cli/vela_template.md) - - Extensibility - - [vela cap](/en/cli/vela_cap.md) +- CLI Reference + - General + - [vela config](/en/cli/vela_config.md) + - [vela env](/en/cli/vela_env.md) + - [vela init](/en/cli/vela_init.md) + - [vela install](/en/cli/vela_install.md) + - [vela up](/en/cli/vela_up.md) + - [vela version](/en/cli/vela_version.md) + - Applications + - [vela delete](/en/cli/vela_delete.md) + - [vela exec](/en/cli/vela_exec.md) + - [vela logs](/en/cli/vela_logs.md) + - [vela ls](/en/cli/vela_ls.md) + - [vela port-forward](/en/cli/vela_port-forward.md) + - [vela show](/en/cli/vela_show.md) + - [vela status](/en/cli/vela_status.md) + - [vela svc](/en/cli/vela_svc.md) + - Workload Types + - [vela workloads](/en/cli/vela_workloads.md) + - Traits + - [vela traits](/en/cli/vela_traits.md) + - [vela scaler](/en/cli/vela_scaler.md) + - [vela route](/en/cli/vela_route.md) + - [vela autoscale](/en/cli/vela_autoscale.md) + - [vela rollout](/en/cli/vela_rollout.md) + - [vela metric](/en/cli/vela_metric.md) + - System + - [vela completion](/en/cli/vela_completion.md) + - [vela dashboard](/en/cli/vela_dashboard.md) + - [vela system](/en/cli/vela_system.md) + - [vela template](/en/cli/vela_template.md) + - Extensibility + - [vela cap](/en/cli/vela_cap.md) diff --git a/docs/en/platform-engineers/extending-kubevela.md b/docs/en/platform-engineers/extending-kubevela.md new file mode 100644 index 000000000..e5f8963cd --- /dev/null +++ b/docs/en/platform-engineers/extending-kubevela.md @@ -0,0 +1,142 @@ +# Extending Capabilities in KubeVela + +## How Capabilities Work + +A Capability is a functionality provided by the infrastructure that users can configure to run and operate applications. +Vela has [an extensible capability system](../design.md#2-capability-oriented-architecture) that allows platform builders to bring bespoke infrastructure capabilities into Vela by writing YAML definitions and CUE templates. + +In the following tutorial, you will learn how to add a new capability and expose it to users via CLI/Appfile. +The new capability is a type of trait but the same process applies to workload as well. + +## Add A New Capability + +Prerequisites: + +- [helm v3](https://helm.sh/docs/intro/install/) +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) + +### Step 1: Install KubeWatch + +```bash +$ helm repo add vela-demo https://wonderflow.info/kubewatch/archives/ +$ helm install kubewatch vela-demo/kubewatch --version 0.1.0 +``` + +### Step 2: Add Trait Definition with CUE template + +```bash +$ cat << EOF | kubectl apply -f - +apiVersion: core.oam.dev/v1alpha2 +kind: TraitDefinition +metadata: + name: kubewatch + annotations: + definition.oam.dev/apiVersion: labs.bitnami.com/v1alpha1 + definition.oam.dev/kind: KubeWatch + definition.oam.dev/description: "Add a watch for resource" +spec: + appliesToWorkloads: + - "*" + workloadRefPath: spec.workloadRef + definitionRef: + name: kubewatches.labs.bitnami.com + extension: + template: | + output: { + apiVersion: "labs.bitnami.com/v1alpha1" + kind: "KubeWatch" + spec: handler: webhook: url: parameter.webhook + } + parameter: { + webhook: string + } +EOF +``` + +That's it! Once you have applied the definition file the feature will be automatically registered in Vela Server and exposed to users. + +### Step 3: Verify Kubewatch Trait Installed + +```bash +$ vela traits +Synchronizing capabilities from clusterβŒ› ... +Sync capabilities successfully βœ… Add(1) Update(0) Delete(0) +TYPE CATEGORY DESCRIPTION ++kubewatch trait Add a watch for resource + +Listing trait capabilities ... + +NAME DESCRIPTION APPLIES TO +kubewatch Add a watch for resource +... +``` + +### Step 4: Adding Kubewatch Trait to The App + +Write an Appfile: + +```bash +$ cat << EOF > vela.yaml +name: testapp +services: + testsvc: + type: webservice + image: crccheck/hello-world + port: 8000 + route: + domain: testsvc.example.com +EOF +``` + +Deploy it: + +```bash +$ vela up +... +βœ… 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 testsvc +``` + +You can use either of the following options to attach the newly added kubewatch trait to the App: + +#### Option 1: Testing in CLI + +Add kubewatch trait to the application: + +```bash +$ vela kubewatch testapp --svc testsvc --webhook https://hooks.slack.com/ +Adding kubewatch for app testsvc +β ‹ Checking Status ... +βœ… Application Deployed Successfully! + - Name: testsvc + Type: webservice + HEALTHY Ready: 1/1 + Traits: + - βœ… kubewatch: webhook=https://hooks.slack.com/... + ... +``` + +Check your Slack channel to verify the nofitications: + +![Image of Kubewatch](../../resources/kubewatch-notif.jpg) + +#### Option 2: Testing in Appfile + +Instead of using CLI, you can add `kubewatch` config to Appfile: + +```bash +$ cat << EOF >> vela.yaml + kubewatch: + webhook: https://hooks.slack.com/ +EOF +``` + +Deploy it: + +``` +$ vela up +``` diff --git a/docs/en/quick-start.md b/docs/en/quick-start.md index 489617ee6..be4aa9e7c 100644 --- a/docs/en/quick-start.md +++ b/docs/en/quick-start.md @@ -1,155 +1,12 @@ # Quick Start -Welcome to KubeVela! In this guide, we'll walk you through how to install KubeVela, and deploy your first simple application. +Welcome to KubeVela! In this guide, we'll walk you through how to deploy a simple service application using KubeVela CLI/Appfile. -## Step 1: Install +## Setup -#### 1. Setup Kubernetes cluster +Make sure you have finished and verified the installation following [this guide](./install.md). -- Kubernetes cluster >= v1.15.0 -- kubectl installed and configured - -You may pick either Minikube or KinD as local cluster testing option. - -> NOTE: If you are not using minikube or kind, please make sure to [install or enable ingress-nginx](https://kubernetes.github.io/ingress-nginx/deploy/) by yourself. - -##### Minikube - -
-Follow the minikube [installation guide](https://minikube.sigs.k8s.io/docs/start/). - -Once minikube is installed, create a cluster: - -```bash -$ minikube start -``` - -Install ingress: - -```bash -$ minikube addons enable ingress -``` -
- -##### KinD - -
-Follow [this guide](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) to install kind. - -Then spins up a kind cluster: - -```bash -cat < - -#### 2. Get KubeVela - -1. Download the latest `vela` binary from the [releases page](https://github.com/oam-dev/kubevela/releases). -2. Unpack the `vela` binary and add it to `$PATH` to get started. - -```bash -$ sudo mv ./vela /usr/local/bin/vela -``` - -#### 3. Initialize KubeVela - -Run: - -```bash -$ vela install -``` - -This will install KubeVela server component and its dependency components. - -**Verify Installation Manually (Advanced)** - -
-Check Vela Helm Chart has been installed: -``` -$ helm list -n vela-system -NAME NAMESPACE REVISION ... -kubevela vela-system 1 ... -``` - -Later on, check that the dependency components has been installed (they will need 5-10 minutes to complete): -``` -$ helm list --all-namespaces -NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION -flagger vela-system 1 2020-11-10 18:47:14.0829416 +0000 UTC deployed flagger-1.1.0 1.1.0 -keda keda 1 2020-11-10 18:45:15.6981827 +0000 UTC deployed keda-2.0.0-rc3 2.0.0-rc2 -kube-prometheus-stack monitoring 1 2020-11-10 18:45:37.9608079 +0000 UTC deployed kube-prometheus-stack-9.4.4 0.38.1 -kubevela vela-system 1 2020-11-10 10:44:20.663582 -0800 PST deployed -``` - -> We will introduce a `vela system health` command to check the dependencies in the future. -
- -**Customize Your Installation (Advanced)** - -
-We have installed the following dependency components along with Vela server component: - -- [Prometheus Stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) -- [Cert-manager](https://cert-manager.io/) -- [Flagger](https://flagger.app/) - -The config has been saved in a ConfigMap in "vela-system/vela-config": - -``` -$ kubectl -n vela-system get cm vela-config -o yaml -apiVersion: v1 -data: - certificates.cert-manager.io: | - { - "repo": "jetstack", - "urL": "https://charts.jetstack.io", - "name": "cert-manager", - "namespace": "cert-manager", - "version": "1.0.3" - } - flagger.app: | - ... -kind: ConfigMap -``` - -User can specify their own dependencies by editing the `vela-config` ConfigMap. -Currently adding new chart or updating existing chart requires redeploying Vela: -``` -$ kubectl -n vela-system edit cm vela-config -... - -$ helm uninstall -n vela-system kubevela -$ helm install -n vela-system kubevela -``` -
- -## Step 2: Deploy Your First Application - -**vela init** +## 1. Initialize Application ```bash $ vela init --render-only @@ -184,7 +41,7 @@ services: domain: testsvc.example.com ``` -**vela up** +## 2. Deploy Application ```bash $ vela up @@ -210,10 +67,10 @@ Check the status until we see route trait ready: $ vela status testapp About: - Name: testapp - Namespace: default - Created at: ... - Updated at: ... + Name: testapp + Namespace: default + Created at: ... + Updated at: ... Services: @@ -224,7 +81,7 @@ Services: Created at: ... Updated at: ... Routes: - - route: Visiting URL: http://testsvc.example.com IP: localhost + - route: Visiting URL: http://testsvc.example.com IP: localhost ``` **In [kind cluster setup](./install.md#kind)**, you can visit the service via localhost. In other setups, replace localhost with ingress address accordingly. @@ -245,47 +102,6 @@ Hello World `'--.._\..--'' ``` -**Voila!** You are all set to go. - -## Step 3: (Optional) Clean Up - -
-Run: - -```bash -$ helm uninstall -n vela-system kubevela -$ rm -r ~/.vela -``` - -This will uninstall KubeVela server component and its dependency components. -This also cleans up local CLI cache. - -Then clean up CRDs (CRDs are not removed via helm by default): - -``` -$ kubectl delete crd \ - applicationconfigurations.core.oam.dev \ - applicationdeployments.core.oam.dev \ - autoscalers.standard.oam.dev \ - certificaterequests.cert-manager.io \ - certificates.cert-manager.io \ - challenges.acme.cert-manager.io \ - clusterissuers.cert-manager.io \ - components.core.oam.dev \ - containerizedworkloads.core.oam.dev \ - healthscopes.core.oam.dev \ - issuers.cert-manager.io \ - manualscalertraits.core.oam.dev \ - metricstraits.standard.oam.dev \ - orders.acme.cert-manager.io \ - podspecworkloads.standard.oam.dev \ - routes.standard.oam.dev \ - scopedefinitions.core.oam.dev \ - servicemonitors.monitoring.coreos.com \ - traitdefinitions.core.oam.dev \ - workloaddefinitions.core.oam.dev -``` -
## What's Next