Skip to content

Commit 948cbb3

Browse files
[v0.32] doc: add setup-vind github action documentation (#1783) (#1791)
* Backport: Copy vcluster/configure/vcluster-yaml/experimental/docker.mdx to vcluster_versioned_docs/version-0.32.0/configure/vcluster-yaml/experimental/docker.mdx * Backport: Copy vcluster/integrations/setup-vind.mdx to vcluster_versioned_docs/version-0.32.0/integrations/setup-vind.mdx * Backport: Copy vcluster/third-party-integrations/github-actions/pull-requests.mdx to vcluster_versioned_docs/version-0.32.0/third-party-integrations/github-actions/pull-requests.mdx --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
1 parent 2fa2037 commit 948cbb3

3 files changed

Lines changed: 101 additions & 0 deletions

File tree

vcluster_versioned_docs/version-0.32.0/configure/vcluster-yaml/experimental/docker.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ vind creates a complete Kubernetes cluster that runs entirely within Docker cont
2424
- **External nodes**: Use [vCluster VPN](../private-nodes/vpn.mdx) and the vCluster Platform to join external nodes into the vCluster
2525
- **Isolation**: Complete separation between different vCluster instances
2626
- **Portability**: Works consistently across different Docker environments
27+
- **CI/CD**: Use the [`setup-vind` GitHub Action](../../../integrations/setup-vind.mdx) to provision clusters in GitHub Actions workflows
2728

2829
## How to use
2930

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
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.

vcluster_versioned_docs/version-0.32.0/third-party-integrations/github-actions/pull-requests.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ GitHub Actions can be created for the following workflows:
2424
<!-- vale on -->
2525
- [Setup vCluster](https://github.com/loft-sh/setup-vcluster): Installs the `vCluster` CLI
2626
- [Setup DevSpace](https://github.com/loft-sh/setup-devspace): Installs the `DevSpace` CLI
27+
- [Setup vind](https://github.com/loft-sh/setup-vind): Provisions a Kubernetes cluster via the [Docker driver (vind)](../../configure/vcluster-yaml/experimental/docker.mdx) for [CI testing](../../integrations/setup-vind.mdx)
2728

2829
## Deploy virtual clusters on pull requests
2930

0 commit comments

Comments
 (0)