Preview environments

Limited vCluster Tenancy Configuration Support

This feature is only available when using the following worker node types:

Host Nodes

This guide shows how to use vCluster and GitHub Actions to deploy preview environments for an application on every pull request. This example creates a new virtual cluster for each pull request and deploy ArgoCD into it. It makes use of the sleep mode feature of the platform to make sure the environments are not using any resources if they are unused.

Prepare the platform

Install an IngressController

Make sure to install an IngressController into the Kubernetes cluster where the preview environments should get created. Loft recommends ingress-nginx, which can be installed through the platform under Cluster > Apps.

Configure preview environments domain

As a next step, make sure you have a wildcard domain configured under which the preview environments should be reachable, such as *.my-preview-environments.com. If you don't have access to a custom domain, the platform allows you to configure a *.CUSTOM.kubedev.sh domain in the Clusters > Cluster tab.

Create virtual cluster template

Next, create a new virtual cluster template for the preview environments. Navigate to Templates > Virtual Clusters and press on the button. Make sure to use the following Helm values:

# Reuse the host ingress controller for your ingresses
sync:
  ingresses:
    enabled: true

# Make sure pods don't break out of the virtual cluster
isolation:
  enabled: true
  networkPolicy:
    enabled: false

Next make sure sleep mode is configured to start after 30-60 minutes.

Optional: ingress authentication

In the Advanced Options tab, you can also enable 'Ingress Authentication' to only allow users that have access to your platform instance to access the preview environments.

Create preview environments project

Next create a new project preview to host the preview environments by pressing the plus button under the projects view. Make sure to only select the just created template as an allowed template and assign yourself and all other users or teams you want to have access to the preview environments in the members tab.

Create a GitHub deploy action

After having the vCluster project configured correctly, write the actual GitHub workflow that creates the preview environments. On every pull request this action creates a new virtual cluster that hosts the example application (ArgoCD in this case) and can be accessed through an Ingress.

The GitHub workflow looks like this:

name: Create Preview Environment

# Run for pull requests to the main branch
on:
  pull_request:
    branches:
      - main

# make sure the pipeline is only running once
concurrency:
  group: preview-${{ github.head_ref || github.ref_name }}
  cancel-in-progress: true

# define a job that deploys the preview environment
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: checkout
        uses: actions/checkout@v3

      - name: Install vCluster CLI
        uses: loft-sh/setup-loft@v2
        with:
          version: v3.0.0
          url: https://url-to-your-loft-instance.com
          # Specify your platform access key here
          access-key: ${{ secrets.LOFT_PREVIEW_ACCESS_KEY }}
          # Optional if your platform domain certificate is insecure
          #insecure: true

      - name: Deploy Preview Environment
        run: |
          INGRESS_HOST=loft-preview-${{ github.event.pull_request.number }}.my-preview-environments.com

          # Make sure to recreate if there is an already existing environment
          vcluster pro create loft-preview-${{ github.event.pull_request.number }} --project preview --recreate

          # Deploy the application here with an ingress
          helm repo add argo https://argoproj.github.io/argo-helm
          helm install argocd argo/argo-cd --version 5.16.3 \
                                            --create-namespace \
                                            -n argocd \
                                            --set server.ingress.enabled=true \
                                            --set server.ingress.hosts={$INGRESS_HOST}

      - uses: marocchino/sticky-pull-request-comment@v2
        with:
          number: ${{ github.event.pull_request.number }}
          header: release
          message: |
            Preview environment deployed at: http://loft-preview-${{ github.event.pull_request.number }}.my-preview-environments.com

Create a destroy action

Environments must be cleaned up if they are not needed anymore. In order to accomplish this, create a separate workflow to cleanup the virtual cluster created for the preview environment as soon as the pull request is closed or merged:

name: Destroy Preview Environment

on:
  pull_request:
    branches:
      - main
    types:
      - closed

jobs:
  destroy:
    runs-on: ubuntu-latest
    steps:
      - name: checkout
        uses: actions/checkout@v3

      - name: Install vCluster CLI
        uses: loft-sh/setup-loft@v2
        with:
          version: v3.0.0
          url: https://url-to-your-loft-instance.com
          # Specify your platform access key here
          access-key: ${{ secrets.LOFT_PREVIEW_ACCESS_KEY }}
          #insecure: true

      - name: Destroy Preview Environment
        run: |
          loft delete vcluster loft-preview-${{ github.event.pull_request.number }} --project preview

Conclusion

This guide showed how to build a complete flow for creating preview environments with the platform and GitHub Actions. After creation, the preview environments starts sleeping if it's not used and consumes no computing resources in the cluster. If you want to access a preview environment, just click the link in the pull request comment and the platform wakes up the environment automatically. This way you can build preview environments that are fast to create, flexible like separate Kubernetes clusters and with no costs at all for unused environments.