|
| 1 | +--- |
| 2 | +title: CI testing with setup-vind |
| 3 | +sidebar_label: CI Testing (setup-vind) |
| 4 | +sidebar_position: 7 |
| 5 | +description: Use the setup-vind GitHub Action to provision Kubernetes clusters via vCluster's Docker driver for CI/CD testing. |
| 6 | +--- |
| 7 | + |
| 8 | +import InterpolatedCodeBlock from '@site/src/components/InterpolatedCodeBlock'; |
| 9 | + |
| 10 | +The [`setup-vind`](https://github.com/loft-sh/setup-vind) GitHub Action provisions Kubernetes clusters via [vCluster's Docker driver (vind)](../configure/vcluster-yaml/experimental/docker.mdx) for CI/CD testing. It replaces `setup-kind` with a full virtual cluster running in Docker, usable for end-to-end (e2e) tests, multi-cluster setups, and more. |
| 11 | + |
| 12 | +Compared to KinD, vind provides: |
| 13 | + |
| 14 | +- **No image loading** - vind uses the host Docker daemon directly, so there's no need to run `kind load docker-image` before tests. |
| 15 | +- **LoadBalancer support** - Kubernetes Services of type `LoadBalancer` work out of the box and are reachable within the CI runner. |
| 16 | +- **Full vCluster configuration** - the cluster supports any [vCluster configuration](../configure/vcluster-yaml/README.mdx), including multi-node setups and VPN-based private nodes. |
| 17 | + |
| 18 | +The action handles the full lifecycle automatically: |
| 19 | + |
| 20 | +- **Main step**: installs the vCluster CLI, sets the Docker driver, creates the cluster, and waits for nodes to become ready. |
| 21 | +- **Post step**: exports container logs as a GitHub artifact and deletes the cluster. |
| 22 | + |
| 23 | +## Basic usage |
| 24 | + |
| 25 | +```yaml |
| 26 | +# .github/workflows/e2e.yaml |
| 27 | +name: E2E Tests |
| 28 | +on: |
| 29 | + pull_request: |
| 30 | + branches: [main] |
| 31 | +jobs: |
| 32 | + e2e: |
| 33 | + runs-on: ubuntu-latest |
| 34 | + steps: |
| 35 | + - uses: actions/checkout@v4 |
| 36 | + - uses: loft-sh/setup-vind@v1 |
| 37 | + - run: kubectl get nodes |
| 38 | + - run: make e2e |
| 39 | +``` |
| 40 | +
|
| 41 | +:::tip |
| 42 | +After the `setup-vind` step completes, `kubectl` is configured and the cluster is ready to use. The action waits up to 5 minutes for nodes to register before proceeding. |
| 43 | +::: |
| 44 | + |
| 45 | +## Inputs |
| 46 | + |
| 47 | +| Input | Default | Description | |
| 48 | +|-------|---------|-------------| |
| 49 | +| `version` | `latest` | vCluster CLI version to install | |
| 50 | +| `name` | `vind` | Cluster name | |
| 51 | +| `config` | | Path to `vcluster.yaml` values file (repo-relative) | |
| 52 | +| `kubernetes-version` | | Kubernetes version for the cluster | |
| 53 | +| `skipClusterDeletion` | `false` | Skip cluster deletion in post step | |
| 54 | +| `skipClusterLogsExport` | `false` | Skip log export in post step | |
| 55 | + |
| 56 | +## Examples |
| 57 | + |
| 58 | +### Specify a Kubernetes version |
| 59 | + |
| 60 | +<InterpolatedCodeBlock |
| 61 | + code={'- uses: loft-sh/setup-vind@v1\n with:\n kubernetes-version: "[[VAR:KUBERNETES_VERSION:1.35.0]]"'} |
| 62 | + language="yaml" |
| 63 | +/> |
| 64 | + |
| 65 | +### Use a config file |
| 66 | + |
| 67 | +<InterpolatedCodeBlock |
| 68 | + code={'- uses: loft-sh/setup-vind@v1\n with:\n config: [[VAR:CONFIG_PATH:hack/vcluster.yaml]]'} |
| 69 | + language="yaml" |
| 70 | +/> |
| 71 | + |
| 72 | +### Multi-cluster setup |
| 73 | + |
| 74 | +Create multiple clusters in the same job by giving each a unique name: |
| 75 | + |
| 76 | +<InterpolatedCodeBlock |
| 77 | + code={'- uses: loft-sh/setup-vind@v1\n with:\n name: [[VAR:CLUSTER_NAME_1:platform]]\n- uses: loft-sh/setup-vind@v1\n with:\n name: [[VAR:CLUSTER_NAME_2:agent]]'} |
| 78 | + language="yaml" |
| 79 | +/> |
| 80 | + |
| 81 | +## Migrate from setup-kind |
| 82 | + |
| 83 | +The following table shows how `setup-kind` inputs map to `setup-vind`. Version numbers are illustrative. |
| 84 | + |
| 85 | +| `setup-kind` | `setup-vind` | Notes | |
| 86 | +|------------|------------|-------| |
| 87 | +| `version: v0.30.0` | `version: v0.32.0` | vCluster CLI version, not KinD | |
| 88 | +| `image: kindest/node:v1.35.0` | `kubernetes-version: "1.35.0"` | No node image needed | |
| 89 | +| `config: kind.yaml` | `config: vcluster.yaml` | Different config format (vCluster values) | |
| 90 | +| `kind load docker-image` | *(not needed)* | vind runs in Docker directly | |
| 91 | + |
| 92 | +## Requirements and limitations |
| 93 | + |
| 94 | +:::warning Linux runners only |
| 95 | +The action supports `linux/amd64` and `linux/arm64` runners. It does not run on Windows or macOS GitHub-hosted runners. |
| 96 | +::: |
| 97 | + |
| 98 | +- **Docker required** - the runner must have Docker installed (standard on `ubuntu-latest`). |
| 99 | +- **Kernel modules** - the action pre-loads `br_netfilter`, `overlay`, and `bridge` modules automatically. No user action needed. |
0 commit comments