Skip to main content

Deploy vCluster Platform on Google Cloud

This guide provides step-by-step instructions for deploying the platform on Google Kubernetes Engine (GKE).

Prerequisites​

Before starting, ensure you have the following tools installed:

  • 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 
    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
  • Google Cloud SDK (gcloud CLI)
    note

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

Create GKE cluster​

  1. Prepare the environment.

    Start by creating a zonal GKE cluster using the gcloud CLI. First, set up your environment variables:

    tip

    Project ID can be found in the Google Cloud Console under the project name. Alternatively use gcloud project list to list all projects and their IDs. To check which project is active, use gcloud config get-value project.

    Set environment variables
    export PROJECT_ID=development
    export CLUSTER_NAME=vcluster-demo
    export ZONE=europe-west1-b
    export MACHINE_TYPE=e2-standard-4

    Configure gcloud and enable the required APIs and set default project:

    Configure gcloud
    gcloud config set project $PROJECT_ID
    gcloud services enable container.googleapis.com

  2. Create the cluster.

    Create GKE cluster
    gcloud container clusters create $CLUSTER_NAME \
        --zone $ZONE \
        --machine-type $MACHINE_TYPE \
        --num-nodes 2
    info

    This process typically takes about 10-15 minutes.

    This command creates a GKE cluster named vcluster-demo in the europe-west1-b zone with two nodes of type e2-standard-4.

    kubeconfig update

    This command automatically updates your kubeconfig file with the new cluster configuration.

  3. Verify the cluster creation.

    Verify that the GKE was created successfully by listing the nodes:

    List cluster nodes
    kubectl get nodes

    You should see output similar to:

    NAME           LOCATION        MASTER_VERSION      MASTER_IP      MACHINE_TYPE   NODE_VERSION        NUM_NODES  STATUS
    vcluster-demo  europe-west1-b  1.30.5-gke.1443001  35.187.66.218  e2-standard-4  1.30.5-gke.1443001  2          RUNNING

Platform setup​

With the GKE cluster up and running, you can now deploy the platform in a few easy steps.

    Install the platform​

  1. Deploy platform using the vCluster CLI.

    Now that you have vCluster running on GKE, set up the platform and configure GPC in the following steps.

    Easiest way to deploy a platform is using the vcluster CLI

    idempotency

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

    vcluster platform start

    The command asks you for providing email address for the admin user

    deployment expected 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
    retry

    If the command takes to long to execute, for example due to other cluster operations, simply run the command one more time

  2. Connect to the platform.

    Once the platform is deployed, default browser with the platform UI opens and you should see the output similar to this:

    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 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 via UI, provide: First Name, Last Name, Email (should default to the one supplied earlier) and Organization.

    To login via CLI, simply copy/pasted the Login via CLI command.

    This is the basic platform deployment, from there you can refer to the Next steps seciton to learn about platform features.

    There are a few additional optional configuration steps that can be done.

    [Optional] expose platform UI via load balancer​

  1. Create a LoadBalancer service to expose the platform UI.

    note

    Please note that 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. Once the service is active, obtain the external IP address:

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

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

    certificate

    Note that the platform uses a self-signed certificate, so you need to accept the warning in your browser. For production use, you should replace the certificate with a valid one.

    [Optional] setup custom domain and configure DNS​

  1. Configure DNS in Google Cloud DNS. To use a custom domain, you need to configure the DNS to point to the LoadBalancer IP address.

    Configure DNS
    EXTERNAL_IP="provide the load balancer external IP"

    gcloud dns managed-zones create vcluster-platform --dns-name="yourdomain.tld."

    gcloud dns record-sets transaction start --zone=vcluster-platform

    gcloud dns record-sets transaction add "${EXTERNAL_IP}" \
        --name="vcluster-platform.yourdomain.tld." \
        --ttl=300 \
        --type=A \
        --zone=vcluster-platform

    gcloud dns record-sets transaction execute --zone=vcluster-platform

  2. Connect the platform to the custom domain.

    Once the DNS is setup, the platform can be started with the command vcluster platform start --host=vcluster-platform.yourdomain.tld

    info

    Read more about how to configure a custom domain.

    If you do not have a custom domain setup, follow this tutorial.

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 on "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 & Wakeup - How to temporarily scale down unused virtual clusters and bring them back up

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

Cleanup​

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

Clean up resources
gcloud container clusters delete $CLUSTER_NAME --zone $ZONE --quiet