Skip to main content
Version: main 🚧

Deploy vCluster on AKS

This guide provides step-by-step instructions for deploying vCluster on Azure Kubernetes Service (AKS).

Prerequisites​

Before starting, ensure you have the following tools installed:

  • kubectl installed: Kubernetes command-line tool for interacting with the cluster. See Install and Set Up kubectl for installation instructions.
  • vCluster CLI 
    brew install loft-sh/tap/vcluster

    The binaries in the tap are signed using the Sigstore framework for enhanced security.

    Confirm that you've installed the correct version of the vCluster CLI.

    vcluster --version
  • Azure CLI (az)
    note

    Ensure you have the necessary permissions to create and manage AKS clusters in your Azure subscription.

Create AKS cluster​

Right subscription

Ensure you are using the correct Azure subscription by running az account show.

Start by creating an AKS cluster using the Azure CLI. First, set up your environment variables:

Modify the following with your specific values to generate a copyable command:
export RESOURCE_GROUP=vcluster-demo-rg
export CLUSTER_NAME=vcluster-demo
export LOCATION=eastus
export NODE_SIZE=Standard_D4s_v3
export NODE_COUNT=2

Create a resource group:

Create resource group
az group create --name $RESOURCE_GROUP --location $LOCATION

Create the AKS cluster:

Create AKS cluster
az aks create \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME \
    --location $LOCATION \
    --node-count $NODE_COUNT \
    --node-vm-size $NODE_SIZE \
    --generate-ssh-keys

This command creates an AKS cluster with managed identity enabled and Azure Monitor for containers.

Configure kubectl​

After the cluster is created, get credentials to access the cluster:

Get cluster credentials
az aks get-credentials --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME

Verify the host cluster creation​

Verify the cluster by listing the nodes:

List cluster nodes
kubectl get nodes

You should see output similar to:

NAME                                STATUS   ROLES    AGE   VERSION
aks-nodepool1-34960941-vmss000000   Ready    <none>   67m   v1.29.9
aks-nodepool1-34960941-vmss000001   Ready    <none>   67m   v1.29.9

Predeployment configuration options​

Before deploying, it's recommended to review the set of configuration options that cannot be updated post deployment. These options require deploying a new vCluster instead of upgrading your vCluster with new options.

Control Plane Options​

Decide the various options of how you want your control plane deployed:

  • High availability - Run multiple copies of vCluster components.
  • Rootless mode - Deploy the vCluster pod without root access to the host cluster.
  • Backing Store - Decide how the data of your cluster is stored.
    Backing store options

    vCluster supports etcd or a relational database (using KINE) as the backend.This feature provides flexibility to vCluster operators. The available data store options allow you to select a data store that fits your use case.

    vCluster supports the following datastore options:

    warning

    After deploying your vCluster, there are limited migration paths to change your backing store. Review the backing store migration options before deploying.

    Backing store options

    This is the default, so you don't need to configure anything. If you want to explicitly set this option, you can use:

    controlPlane:
      backingStore:
        database:
          embedded:
            enabled: true

Worker Nodes​

Decide where you want your worker nodes to come from:

  • Nodes from the host cluster - (Default) All worker nodes of the shared host cluster are used by the virtual cluster and all resources are synced to the single namespace that the vCluster is deployed on.
  • Private Nodes - Enable adding individual nodes to the virtual cluster.

Deploy vCluster on AKS​

YAML configuration

If you're not sure which options to configure, you can update most settings later by upgrading your vCluster with an updated vcluster.yaml. However, some settings — such as what type of worker nodes or the backing store — can only be set during the initial deployment and cannot be changed during an upgrade.

All of the deployment options below have the following assumptions:

  • A vcluster.yaml is provided. Refer to the vcluster.yaml reference docs to explore all configuration options. This file is optional and can be removed from the examples.
  • The vCluster is called my-vcluster.
  • The vCluster is be deployed into the team-x namespace.

The vCluster CLI provides the most straightforward way to deploy and manage virtual clusters.

  1. Install the vCluster CLI:

     brew install loft-sh/tap/vcluster-experimental

    If you installed the CLI using brew install vcluster, you should brew uninstall vcluster and then install the experimental version. The binaries in the tap are signed using the Sigstore framework for enhanced security.

    Confirm that you've installed the correct version of the vCluster CLI.

    vcluster --version

  2. Deploy vCluster:

    Modify the following with your specific values to generate a copyable command:
    vcluster create my-vcluster --namespace team-x --values vcluster.yaml
    note

    After installation, vCluster automatically switches your Kubernetes context to the new virtual cluster. You can now run kubectl commands against the virtual cluster.

Next steps​

Now that you have vCluster running on AKS, consider exploring the platform UI to manage your virtual clusters.

Cleanup​

If you deployed the AKS cluster with this tutorial, and want to clean up the resources, run the following command:

Clean up resources
az group delete --name $RESOURCE_GROUP --yes --no-wait