Skip to main content
Version: v4.2

Deploy vCluster Platform on Google Cloud using GKE

This guide provides instructions for deploying the platform on Google Cloud using Google Kubernetes Engine (GKE).

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

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

Create a GKE cluster​

  1. Prepare the environment.

    Start by creating a zonal GKE cluster using the gcloud CLI. 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.

    Modify the following with your specific values to generate a copyable command:
    export PROJECT_ID=development
    export CLUSTER_NAME=vcluster-demo
    export ZONE=europe-west1-b
    export MACHINE_TYPE=e2-standard-4

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

    Modify the following with your specific values to generate a copyable command:
    gcloud config set project=your-project-id
    gcloud services enable container.googleapis.com

  2. Create the cluster.

    Modify the following with your specific values to generate a copyable command:
    gcloud container clusters create=vcluster-demo \
      --zone=europe-west1-b \
      --machine-type=e2-standard-4 \
      --num-nodes=2
    info

    This process typically takes about 10-15 minutes.

    Using the default values, 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 GKE 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           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

Set up the platform​

After the GKE 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 it 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 load balancer​

  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 and configure DNS to provide a secure URL for accessing the platform.

  1. Configure DNS in Google Cloud DNS.

    To use a custom domain, you must configure the DNS to point to the LoadBalancer IP address.

    Modify the following with your specific values to generate a copyable command:
    EXTERNAL_IP=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.

    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 acess and TLS documentation.

    If you do not have a custom domain setup, follow the Set up a domain by using Cloud DNS 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 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.

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