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:
    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:

    az group create --name $RESOURCE_GROUP_NAME --location $REGION

  3. Create the 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:

    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.

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