Skip to main content
Version: main 🚧

Deploy vCluster Platform on Azure using AKS

This guide provides instructions for deploying the platform on Azure using Azure Kubernetes Service (AKS).

Prerequisites​

Ensure you have the following:

  • Administrator access to a Kubernetes cluster: See Accessing Clusters with kubectl for more information. Your current kube-context must have administrative privileges, which you can verify with kubectl auth can-i create clusterrole -A

    info

    To obtain a kube-context with admin access, ensure you have the necessary credentials and permissions for your Kubernetes cluster. This typically involves using kubectl config commands or authenticating through your cloud provider's CLI tools.

  • helm installed: Helm v3.10 is required for deploying the platform. Refer to the Helm Installation Guide if you need to install it.

  • kubectl installed: Kubernetes command-line tool for interacting with the cluster. See Install and Set Up kubectl for installation instructions.

  • vCluster CLI installed: 
    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) installed.
note

Ensure you have the necessary permissions to create clusters and manage Azure services.

Create an AKS cluster​

  1. Prepare the environment.

    Create an AKS cluster using the az CLI. Set up your environment variables:

    Modify the following with your specific values to generate a copyable command:
    Set environment variables
    export RESOURCE_GROUP_NAME=vcluster-demo-ResourceGroup
    export REGION=westeurope
    export CLUSTER_NAME=vcluster-demo
    export DNS_LABEL=vcluster-demo-dns

  2. (Optional) Create a resource group if the specified resource group name does not exist:

    Create a resource group
    az group create --name $RESOURCE_GROUP_NAME --location $REGION

  3. Create the cluster:

    Create an AKS cluster
    az aks create --resource-group $RESOURCE_GROUP_NAME --name $CLUSTER_NAME --node-count 2
    info

    This process typically takes about 10-15 minutes.

    Using the default values, this command creates a AKS cluster named vcluster-demo in the westeurope region with two nodes.

  4. Download the kubeconfig file for the new cluster:

    Get Kubeconfig
    az aks get-credentials --resource-group $RESOURCE_GROUP_NAME --name $CLUSTER_NAME

  5. Verify the cluster creation.

    Verify that AKS was created successfully by listing the nodes:

    List cluster nodes
    kubectl get nodes

    You should see an output similar to the following:

    Example output
    NAME                                STATUS   ROLES    AGE     VERSION
    aks-nodepool1-41068841-vmss000000   Ready    <none>   6m4s    v1.31.8
    aks-nodepool1-41068841-vmss000001   Ready    <none>   6m11s   v1.31.8

Set up the platform​

After the AKS cluster is running, deploy the platform.

Install the platform​

  1. Deploy the platform using the vCluster CLI.

    idempotency

    The following command is idempotent, meaning that running it again does not result in creating another cluster with the same name.

    vcluster platform start

    The command prompts you to enter the email address for the admin user:

    Expected deployment output
    By providing your email, you accept our Terms of Service and Privacy Statement:
    Terms of Service: https://www.loft.sh/legal/terms
    Privacy Statement: https://www.loft.sh/legal/privacy
    ? Please specify an email address for the admin user
    tip

    If the command takes too long to execute—such as when other cluster operations are in progress—rerun the command.

  2. Connect to the platform.

    After the platform is deployed, your default browser opens with the platform UI, and you should see output similar to the following:

    platform deployment output
    ##########################   LOGIN   ############################

    Username: admin
    Password: 9758c908-b931-4edd-b3cb-3f034e50651a  # Change via UI or via: vcluster platform reset password

    Login via UI:  https://hyx4907.loft.host
    Login via CLI: vcluster platform login https://hyx4907.loft.host

    #################################################################

    vCluster Platform was successfully installed and can now be reached at: https://hyx4907.loft.host

    Thanks for using vCluster Platform!
    19:34:46 done You are successfully logged into vCluster Platform!
    - Use `vcluster platform create vcluster` to create a new virtual cluster
    - Use `vcluster platform add vcluster` to add an existing virtual cluster to a vCluster platform instance

    When logging in using the UI, provide the following details:

    • First Name
    • Last Name
    • Email (pre-filled with the address you supplied earlier)
    • Organization

    To log in using the CLI, run the Login via CLI command provided above.

    This completes the basic platform deployment. For additional configuration and available features, see the Next steps section.

    You can optionally perform additional configuration steps:

Expose the platform UI using LoadBalancer​

  1. Optionally, you can expose the platform UI using a LoadBalancer service to make it accessible outside the cluster.

    note

    This assumes the platform is deployed in the vcluster-platform namespace which is a default deployment namespace.

    cat <<EOF | kubectl apply -f -
    apiVersion: v1
    kind: Service
    metadata:
      name: vcluster-platform-loadbalancer
      namespace: vcluster-platform
    spec:
      type: LoadBalancer
      externalTrafficPolicy: Cluster
      selector:
        app: loft
      ports:
      - name: https
        protocol: TCP
        port: 443
        targetPort: 10443
    EOF

  2. After the service is active, obtain the external IP address:

    kubectl get svc vcluster-platform-loadbalancer -n vcluster-platform

    Navigate to the IP address in your browser https://<EXTERNAL_IP>.

    tip

    The platform uses a self-signed certificate, so you should accept the warning in your browser. For production use, replace the default self-signed certificate with a valid TLS certificate.

Set up custom domain and configure DNS​

Optionally, you can set up a custom domain, SSL certificate, and configure DNS to provide a secure URL for accessing the platform. Official Azure guide

  1. All necessary steps for configuring DNS and SSL for Azure Kubernetes Service (AKS) App Routing are thoroughly described in the official Azure documentation. Please refer to the guide here: Configure DNS and SSL for AKS App Routing.

  2. Connect the platform to the custom domain.

    After DNS is set up, you can start the platform using the following command:

    vcluster platform start --host=vcluster-platform.yourdomain.tld
    info

    For more information on how to configure a custom domain, see the Configure external access and TLS documentation.

Control pod scheduling on AKS node pools​

Azure Kubernetes Service (AKS) uses two types of node pools with different purposes:

  • System node pools: Host critical infrastructure pods such as CoreDNS and metrics-server. These pools use the label kubernetes.azure.com/mode: system.
  • User node pools: Run application workloads and can scale to zero when not needed.

By default, the platform pods can be scheduled on any available node. For production environments, you may want to ensure platform pods run on user node pools to keep system node pools reserved for critical infrastructure.

Available scheduling options​

You can control where platform pods are scheduled using Helm values during installation or upgrade. Three main approaches are available:

  • nodeSelector: Simplest approach using node labels
  • Node affinity: More flexible with soft and hard scheduling rules
  • Tolerations: Works with node taints to allow pods on specific nodes

Use nodeSelector for basic scheduling​

The nodeSelector field is the simplest way to constrain platform pods to specific nodes using labels. This example schedules platform pods only on user node pools (labeled with kubernetes.azure.com/mode: user), keeping system node pools reserved for critical infrastructure.

Modify the following with your specific values to generate a copyable command:
values.yaml - Using nodeSelector to target user node pools
# Deploy platform pods only on user node pools
nodeSelector:
  kubernetes.azure.com/mode: user

Apply this configuration during platform installation:

Install platform with nodeSelector
helm upgrade loft vcluster-platform \
  --install \
  --repo https://charts.loft.sh/ \
  --namespace vcluster-platform \
  --create-namespace \
  --values values.yaml
info

The nodeSelector requires nodes to have the exact label specified. If no matching nodes exist, pods will remain in a pending state.

Use node affinity for flexible scheduling​

Node affinity provides more control than nodeSelector, allowing you to specify both required and preferred scheduling rules.

Modify the following with your specific values to generate a copyable command:
values.yaml - Using node affinity with preference rules
affinity:
  nodeAffinity:
    # Hard requirement: pods must be scheduled on nodes matching this rule
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: kubernetes.azure.com/mode
              operator: In
              values:
                - user
    # Soft preference: prefer nodes that are not spot instances
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        preference:
          matchExpressions:
            - key: kubernetes.azure.com/scalesetpriority
              operator: NotIn
              values:
                - spot

The example above:

  1. Requires pods to be scheduled only on user node pools
  2. Prefers non-spot instances when available
tip

Use preferredDuringSchedulingIgnoredDuringExecution for soft preferences that won't block pod scheduling if the preference can't be satisfied.

Use tolerations with tainted system pools​

Microsoft recommends applying the CriticalAddonsOnly=true:NoSchedule taint to system node pools. This prevents application pods from being scheduled there unless they have a matching toleration. If your system node pools use this taint, configure platform pods to run on user node pools without requiring tolerations.

note

By default, platform pods don't include the CriticalAddonsOnly toleration, so they won't be scheduled on tainted system node pools. You only need to configure tolerations if you want platform pods to run on tainted nodes.

If your user node pools also have custom taints, add the appropriate tolerations:

Modify the following with your specific values to generate a copyable command:
values.yaml - Using tolerations for custom tainted nodes
# Allow scheduling on user node pools with custom taints
tolerations:
  - key: workload-type
    operator: Equal
    value: platform
    effect: NoSchedule

Combine scheduling mechanisms​

For precise control, combine multiple scheduling mechanisms:

Modify the following with your specific values to generate a copyable command:
values.yaml - Combining nodeSelector and tolerations
# Target specific node pool by label
nodeSelector:
  workload-type: platform

# Allow scheduling on nodes with this taint
tolerations:
  - key: workload-type
    operator: Equal
    value: platform
    effect: NoSchedule

This configuration:

  1. Selects only nodes labeled with workload-type: platform
  2. Tolerates the matching taint on those nodes
info

For more information about platform configuration options, see platform configuration.

Next steps​

After logging into the UI, you'll be able to start creating virtual clusters immediately. You're automatically part of a project called Default Project.

Click New Virtual Cluster and Create to spin one up to try out.

tip

Find more information about creating virtual clusters in the create virtual clusters section.

Otherwise, read more about some primary concepts:

  • Projects - How resources can be grouped together into different projects.
  • Virtual clusters - How to create and manage virtual clusters.
  • Templates - How to use templates to control what type of resources that can be made.
  • Host clusters - How to add more host clusters to the platform.
  • Sleep and wakeup - How to temporarily scale down unused virtual clusters and bring them back up.

You can also use Google as an identity provider and configure SSO to enable user authentication to the platform.

Clean up resources​

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

Clean up resources
az aks delete --resource-group $RESOURCE_GROUP_NAME --name $CLUSTER_NAME