---
title: Installation
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

> For upgrading existing KubeVela, please read the [upgrade guide](./platform-engineers/advanced-install/#upgrade).

## 1. Choose Control Plane Cluster

Requirements:

- Kubernetes cluster >= v1.19 && <= v1.22
- [Kubectl](https://kubernetes.io/docs/tasks/tools/)

KubeVela relies on Kubernetes as a control plane. The control plane could be any managed Kubernetes offering or your cluster.

For local deployment and test, you could use `kind` or `minikube`.

> For production usage, you could use your Kubernetes cluster or Kubernetes services provided by cloud providers.
> For offline installation, please refer to [KubeVela Offline Installation Guide](./platform-engineers/system-operation/offline-installation).

<Tabs
className="unique-tabs"
defaultValue="kind"
values={[
{label: 'Kind', value: 'kind'},
{label: 'Minikube', value: 'minikube'},
{label: 'K3s', value: 'k3s'},
{label: 'RKE', value: 'rke'},
{label: 'Cloud Provider', value: 'cloudprovider'},
]}>

<TabItem value="minikube">

> Minikube is **NOT RECOMMENDED** for production.

Follow the minikube [installation guide](https://minikube.sigs.k8s.io/docs/start/).

Then spins up a minikube cluster

```shell script
minikube start
```

Install ingress to enable service route:

```shell script
minikube addons enable ingress
```

</TabItem>

<TabItem value="k3s">

> The k3s is great for: Edge、IoT、Development.

1. Install k3s

> K3s provides an installation script that is a convenient way to install it as a service on systemd or openrc based systems.

Follow [this guide](https://rancher.com/docs/k3s/latest/en/quick-start/) to get more support.

```shell
curl -sfL https://get.k3s.io | sh -
```

2. Copy kubeconfig

```shell
make ~/.kube
cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
```

</TabItem>

<TabItem value="rke">

> This installation applies to the production environment. Please prepare 1~N servers or VMs.

This section guides to install a RKE Kubernetes cluster, you can refer to their installation guides for [more details](https://rancher.com/docs/rancher/v2.5/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-ha/).

<b>（1） Docker </b>

The RKE depends on docker, Please install Docker on all servers or virtual machines, if not installed follow the docker [installation guide](https://docs.docker.com/engine/install/).

<b>（2）Install RKE:</b>

Download RKE binary from [RKE release page](https://github.com/rancher/rke/releases).

If your internet access was limited, try using the binary cached by KubeVela team:

```
wget https://static.kubevela.net/binary/rke/rke_linux-amd64 -O /usr/bin/rke
chmod +x /usr/bin/rke
```

<b>（3）Install RKE cluster</b>

> Please switch to a non-root user who has permission to operate docker and execute the following commands.

```shell script
  mkdir ~/rkeinit && cd ~/rkeinit
  # Wizard-style configuration
  rke config
  # Kubernetes Cluster Installation
  rke up
  # Install kubectl Command
  mkdir ~/.kube
  cp kube_config_cluster.yml ~/.kube/config
  docker cp kubelet:/usr/local/bin/kubectl /usr/local/bin/kubectl
```

</TabItem>

<TabItem value="kind">

> Kind is **NOT RECOMMENDED** for production.

Follow [this guide](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) to install kind.

Then spins up a kind cluster:

```shell script
cat <<EOF | kind create cluster --image=kindest/node:v1.20.7 --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  kubeadmConfigPatches:
  - |
    kind: InitConfiguration
    nodeRegistration:
      kubeletExtraArgs:
        node-labels: "ingress-ready=true"
  extraPortMappings:
  - containerPort: 80
    hostPort: 80
    protocol: TCP
  - containerPort: 443
    hostPort: 443
    protocol: TCP
EOF
```

Install ingress controller to enable service route：

```shell script
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/kind/deploy.yaml
```

</TabItem>

<TabItem value="cloudprovider">

> Using for production environment

- Alibaba Cloud [ACK Service](https://www.aliyun.com/product/kubernetes)
- AWS [EKS Service](https://aws.amazon.com/cn/eks)
- Azure [AKS Service](https://azure.microsoft.com/en-us/services/kubernetes-service)
- Google [GKE Service](https://cloud.google.com/kubernetes-engine)

> Please make sure one of the [ingress controllers](https://kubernetes.github.io/ingress-nginx/deploy/) is available.

</TabItem>  
</Tabs>

## 2. Install KubeVela CLI

KubeVela CLI provides an easy to engage and manage your application delivery in command lines.

<Tabs
    className="unique-tabs"
    defaultValue="script"
    values={[
        {label: 'Script', value: 'script'},
        {label: 'Homebrew', value: 'homebrew'},
        {label: 'Download directly from releases', value: 'download'},
    ]}>
<TabItem value="script">

** MacOS/Linux **

```shell script
curl -fsSl https://kubevela.io/script/install.sh | bash -s 1.3.3
```

**Windows**

> Only the official release version is supported.

```shell script
powershell -Command "iwr -useb https://kubevela.io/script/install.ps1 | iex"
```

</TabItem>
<TabItem value="homebrew">

**macOS/Linux**

Update your brew first. Please note that the brew method only supports the installation of the official release version.

```shell script
brew update
```

Then install KubeVela CLI

```shell script
brew install kubevela
```

</TabItem>
<TabItem value="download">

- Download the latest `vela` binary file via [release log](https://github.com/kubevela/kubevela/releases).
- Unzip the binary file, and configure the environment variables in `$PATH`, and you're done.

```shell script
sudo mv ./vela /usr/local/bin/vela
```

> [Installation Tips](https://github.com/kubevela/kubevela/issues/625):
> If you are using a Mac system, it will pop up a warning that "vela" cannot be opened because the package from the developer cannot be verified.
>
> MacOS imposes stricter restrictions on the software that can run in the system. You can temporarily solve this problem by opening `System Preference ->Security & Privacy -> General` and clicking on `Allow Anyway`.

</TabItem>
</Tabs>

## 3. Install KubeVela Core

<Tabs
    className="unique-tabs"
    defaultValue="vela"
    values={[
        {label: 'Default', value: 'vela'},
        {label: 'Helm', value: 'helm'},
    ]}>
<TabItem value="vela">

> The version of vela CLI >= 1.2.3.

```shell script
vela install
```

<details> <summary> check out the outcome </summary>

```shell
...
Watching for changes to Job kubevela-vela-core-cluster-gateway-tls-secret-patch with timeout of 18m0s
Add/Modify event for kubevela-vela-core-cluster-gateway-tls-secret-patch: ADDED
kubevela-vela-core-cluster-gateway-tls-secret-patch: Jobs active: 0, jobs failed: 0, jobs succeeded: 0
Add/Modify event for kubevela-vela-core-cluster-gateway-tls-secret-patch: MODIFIED
kubevela-vela-core-cluster-gateway-tls-secret-patch: Jobs active: 1, jobs failed: 0, jobs succeeded: 0
Add/Modify event for kubevela-vela-core-cluster-gateway-tls-secret-patch: MODIFIED
kubevela-vela-core-cluster-gateway-tls-secret-patch: Jobs active: 1, jobs failed: 0, jobs succeeded: 0
Add/Modify event for kubevela-vela-core-cluster-gateway-tls-secret-patch: MODIFIED
Starting delete for "kubevela-vela-core-admission" ServiceAccount
Starting delete for "kubevela-vela-core-admission" ClusterRole
Starting delete for "kubevela-vela-core-admission" ClusterRoleBinding
Starting delete for "kubevela-vela-core-admission" Role
Starting delete for "kubevela-vela-core-admission" RoleBinding
Starting delete for "kubevela-vela-core-admission-patch" Job
Starting delete for "kubevela-vela-core-cluster-gateway-admission" ServiceAccount
Starting delete for "kubevela-vela-core-cluster-gateway-admission" Role
Starting delete for "kubevela-vela-core-cluster-gateway-admission" RoleBinding
Starting delete for "kubevela-vela-core-cluster-gateway-tls-secret-patch" Job

KubeVela control plane has been successfully set up on your cluster.
If you want to enable dashboard, please run "vela addon enable velaux"
```

</details>

</TabItem>

<TabItem value="helm">

If you are helm user, you can also use helm to install kubevela core:

> helm v3.2.0+ required

```
helm repo add kubevela https://charts.kubevela.net/core
helm repo update
helm install --create-namespace -n vela-system kubevela kubevela/vela-core --version 1.3.3 --wait
```

</TabItem>
</Tabs>

## 4. Install VelaUX

> This is optional if you don't use UI console of KubeVela.

VelaUX is a dashboard including UI+API services, it enables you to do everything around application delivery and management.

```shell script
vela addon enable velaux --version v1.3.3
```

expected output:

```
Addon: velaux enabled Successfully.
```

By default, velaux didn't have any exposed port, you can view it by:

```
vela port-forward addon-velaux -n vela-system
```

Choose `> Cluster: local | Namespace: vela-system | Component: velaux | Kind: Service` for visit.

If you have loadbalaner or ingress, please refer to [VelaUX addon docs](./reference/addons/velaux) for more advanced installation ways.

VelaUX need authentication. Default username is admin and get default password as below

```shell
vela logs -n vela-system --name apiserver addon-velaux | grep "initialized admin username"
```

If there is no password in logs, you can get it from secret with the name `admin` in the `vela-system` namespace.

## 5. Uninstall

Before uninstalling kubevela, you must delete all applications and disable all addons.

1. Uninstall VelaUX

```
vela addon disable velaux
```

2. Uninstall KubeVela Core

```
vela uninstall
```

3. Uninstall CRD

Before deleting, you must delete all CR resources.

```
kubectl get crd |grep oam | awk '{print $1}' | xargs kubectl delete crd
```

## Next Step

- [Deploy your first application](./quick-start).