GitHub actions on pull requests

Supported Configurations

Running the control plane as a container with:

• Shared Nodes
• Private Nodes

GitHub Actions can be created for the following workflows:

• Setup vCluster: Installs the vCluster CLI
• Setup DevSpace: Installs the DevSpace CLI
• Setup vind: Provisions a Kubernetes cluster via the Docker driver (vind) for CI testing

Deploy tenant clusters on pull requests

Tenant clusters provide isolated Kubernetes environments for each pull request, enabling:

• Parallel testing without resource conflicts between PRs
• Clean environments that don't accumulate state from previous test runs
• Fast creation and deletion compared to provisioning full clusters
• Cost efficiency by sharing underlying infrastructure while maintaining isolation

Deploy with host nodes

When using host nodes, tenant cluster workloads run on the existing control plane cluster nodes. This is the simplest setup for CI/CD pipelines.

Basic

This example shows how to create and delete a virtual cluster for testing an application named the-app on pull requests.

# .github/workflows/vclusters.yaml
name: Pull Request Checks
on:
  pull_request:
    branches:
      - "main"
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - name: Install vCluster CLI
        uses: loft-sh/setup-vcluster@main
      - name: Login to vCluster Platform instance
        env:
          PLATFORM_URL: ${{ secrets.PLATFORM_URL }}
          ACCESS_KEY: ${{ secrets.ACCESS_KEY }}
        run: vcluster platform login $PLATFORM_URL --access-key $ACCESS_KEY
      - name: Create PR Virtual Cluster
        env:
          NAME: repo-${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}
        run: vcluster create $NAME --project default
      - name: Deploy Application
        run: kubectl apply -Rf ./kubernetes
      - name: Wait for Deployment
        run: kubectl rollout status deployments/the-app
      - name: Run Tests
        run: make e2e
      - name: Delete PR Virtual Cluster
        env:
          NAME: repo-${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}
        run: vcluster delete $NAME --project default

Explanation:

1. The Setup vCluster action is used to install the vCluster CLI.
2. The vcluster platform login command is used to log in to the organization's platform instance. Environment variables PLATFORM_URL and ACCESS_KEY are populated using GitHub secrets. See Access Keys for help generating a platform access key.
3. The vcluster create command is used to create a unique virtual cluster using information about the pull request in the default project. This automatically configures the kube context for the next steps.
4. The next step deploys the application using the runner provided kubectl and manifests located under ./kubernetes.
5. Before running tests, use kubectl to wait for the the-app deployment to become ready.
6. Now, run the end-to-end tests. The example uses make to run tests, but the command should be customized for your testing framework.
7. Finally, the vcluster delete command is used to delete the virtual cluster.

Automatic Cleanup

This example shows how to create and reuse a virtual cluster for testing an application named the-app on pull requests.

# .github/workflows/vclusters.yaml
name: Pull Request Checks
on:
  pull_request:
    branches:
      - "main"
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - name: Install vCluster CLI
        uses: loft-sh/setup-vcluster@main
      - name: Login to vCluster Platform instance
        env:
          PLATFORM_URL: ${{ secrets.PLATFORM_URL }}
          ACCESS_KEY: ${{ secrets.ACCESS_KEY }}
        run: vcluster platform login $PLATFORM_URL --access-key $ACCESS_KEY
      - name: Create PR Virtual Cluster
        env:
          NAME: repo-${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}
        run: vcluster create $NAME --project default --upgrade
      - name: Deploy Application
        run: kubectl apply -Rf ./kubernetes
      - name: Wait for Deployment
        run: kubectl rollout status deployments/the-app
      - name: Run Tests
        run: make e2e

Explanation:

1. The Setup vCluster action is used to install the vCluster CLI.
2. The vcluster platform login command is used to log in to the organization's platform instance. Environment variables PLATFORM_URL and ACCESS_KEY are populated using GitHub secrets.
3. The vcluster create command is used to create a unique virtual cluster using information about the pull request in the default project. This automatically configures the kube context for the next steps. The --upgrade flag has been added to reuse the existing virtual cluster and upgrade it to the latest version. Additional flags may be used to control the desired virtual cluster version.
4. The next step deploys the application using the runner provided kubectl and manifests located under ./kubernetes.
5. Before running tests, use kubectl to wait for the the-app deployment to become ready.
6. Now, run the end-to-end tests. The example uses make to run tests, but the command should be customized for your testing framework.

Reuse

This example shows how to automatically delete a Virtual Cluster after testing an application named the-app for pull requests.

# .github/workflows/vclusters.yaml
name: Pull Request Checks
on:
  pull_request:
    branches:
      - 'main'
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - name: Install vCluster CLI
        uses: loft-sh/setup-loft@main
        with:
          url: ${{ secrets.PLATFORM_URL }}
          access-key: ${{ secrets.PLATFORM_ACCESS_KEY }}
      - name: Create Virtual Cluster for PR
        uses: loft-sh/create-vcluster@main
        with:
          name: repo-${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}
          auto-cleanup: true
      - name: Deploy Application
        run: kubectl apply -Rf ./kubernetes
      - name: Wait for Deployment
        run: kubectl rollout status deployments/the-app
      - name: Run Tests
        run: make e2e

Explanation:

1. The Setup Loft action is used to install the vCluster CLI and login using the provided url and access-key.
2. The Create Virtual Cluster action is used to create a unique virtual cluster using information about the pull request. This automatically configures the kube context for the following steps. Additionally, the auto-cleanup option is enabled, which deletes the virtual cluster after the job completes.
3. The next step deploys the application using the runner provided kubectl and manifests located under ./kubernetes.
4. Before running tests, use kubectl to wait for the the-app deployment to become ready.
5. Finally, run the end-to-end tests. This example uses make to run tests, but the command should be customized for your testing framework. There's no need to delete the virtual cluster since the auto-cleanup option was used when creating the virtual cluster.

Deploy with private nodes

When using private nodes, virtual clusters have dedicated worker nodes that are separate from the host cluster. For CI/CD workflows, combine private nodes with auto-nodes so that worker nodes are automatically provisioned when the virtual cluster is created and cleaned up when deleted.

Prerequisites

Before using private nodes in your GitHub Actions workflow:

1. vCluster Platform must be installed and running
2. A node provider must be configured in vCluster Platform
3. A virtual cluster template with private nodes and auto-nodes enabled must be created

Create a template with private nodes

In vCluster Platform, create a virtual cluster template with private nodes configuration:

Private nodes template configuration

# Enable private nodes with auto-provisioning
privateNodes:
  enabled: true
  autoNodes:
    # Reference the node provider configured in vCluster Platform
    - provider: my-node-provider
      dynamic:
        - name: ci-node-pool
          # Limit the number of nodes for CI workloads
          limits:
            nodes: "3"

# Control plane configuration
controlPlane:
  distro:
    k8s:
      image:
        tag: v1.31.2
  service:
    spec:
      # LoadBalancer required for private nodes connectivity
      type: LoadBalancer

# Network configuration required for private nodes
networking:
  podCIDR: 10.64.0.0/16
  serviceCIDR: 10.128.0.0/16

Configure GitHub Actions workflow

This example creates a virtual cluster with private nodes using a Platform template:

# .github/workflows/vclusters-private-nodes.yaml
name: Pull Request Checks (Private Nodes)
on:
  pull_request:
    branches:
      - "main"
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - name: Install vCluster CLI
        uses: loft-sh/setup-vcluster@main
      - name: Login to vCluster Platform instance
        env:
          PLATFORM_URL: ${{ secrets.PLATFORM_URL }}
          ACCESS_KEY: ${{ secrets.ACCESS_KEY }}
        run: vcluster platform login $PLATFORM_URL --access-key $ACCESS_KEY
      - name: Create PR Virtual Cluster with Private Nodes
        env:
          NAME: repo-${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}
        # Use --template to reference the private nodes template
        run: vcluster create $NAME --project default --template private-nodes-ci
      - name: Wait for nodes to be ready
        # Auto-nodes provisions worker nodes; wait for them to join
        run: |
          echo "Waiting for private nodes to join the cluster..."
          kubectl wait --for=condition=Ready nodes --all --timeout=300s
      - name: Deploy Application
        run: kubectl apply -Rf ./kubernetes
      - name: Wait for Deployment
        run: kubectl rollout status deployments/the-app
      - name: Run Tests
        run: make e2e
      - name: Delete PR Virtual Cluster
        env:
          NAME: repo-${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}
        # Deleting the vCluster also cleans up the auto-provisioned nodes
        run: vcluster delete $NAME --project default

Explanation:

1. The Setup vCluster action installs the vCluster CLI.
2. The vcluster platform login command authenticates to vCluster Platform using GitHub secrets.
3. The vcluster create command with --template private-nodes-ci creates a virtual cluster using the private nodes template. This triggers auto-nodes to provision dedicated worker nodes.
4. Wait for the auto-provisioned nodes to join and become ready before deploying applications.
5. Deploy and test the application on the dedicated private nodes.
6. The vcluster delete command removes the virtual cluster and auto-nodes automatically cleans up the provisioned worker nodes.

Node provisioning time

Auto-nodes provisioning typically takes 1-3 minutes depending on your cloud provider. Factor this into your CI/CD pipeline timeouts.

DevSpace for running tests on pull requests

This example shows how use the Setup DevSpace GitHub Action to install the DevSpace CLI and DevSpace commands to run tests.

# .github/workflows/vclusters.yaml
name: Pull Request Checks
on:
  pull_request:
    branches:
      - "main"
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - name: Install DevSpace CLI
        uses: loft-sh/setup-devspace@main
      - name: Install vCluster CLI
        uses: loft-sh/setup-vcluster@main
      - name: Login to platform instance
        env:
          PLATFORM_URL: ${{ secrets.PLATFORM_URL }}
          ACCESS_KEY: ${{ secrets.ACCESS_KEY }}
        run: vcluster platform login $PLATFORM_URL --access-key $ACCESS_KEY
      - name: Create PR Virtual Cluster
        env:
          NAME: repo-${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}
        run: vcluster create $NAME --project default
      - name: Run Tests
        run: devspace run e2e

Explanation:

1. The Setup DevSpace action installs the DevSpace CLI.
2. The Setup vCluster action is used to install the vCluster CLI.
3. The vcluster platform login command is used to log in to the organization's platform instance. Environment variables PLATFORM_URL and ACCESS_KEY are populated using GitHub secrets.
4. The vcluster create command is used to create a unique virtual cluster using information about the pull request in the default project. This automatically configures the kube context for the next steps.
5. Finally, use devspace run e2e to perform the needed steps to deploy and test my-app.