Contributing
Thank you for contributing to vcluster! Here you can find common questions around developing vcluster.
There are a number of areas where contributions can be accepted:
- Write code to fix bugs or implement features
- Review pull requests
- Try out our alphas and betas and give us feedback in our community Slack channel
- Help respond to Github issues to help our community
- Create docs or guides
We recommend developing vCluster directly on a local Kubernetes cluster as it provides faster feedback. There are two ways that we recommend developing.
- DevSpace
- Locally
- Docker needs to be installed (e.g. docker-desktop, orbstack, rancher desktop etc.)
- kubectl
- Helm v3.10.0+
- Local Kubernetes v1.26+ cluster (i.e. Docker Desktop, minikube, KinD or similar)
Click Fork button (top right) to establish a cloud-based fork.
git clone YOUR_PERSONAL_FORK_URL
One of the primary containers of vCluster is the syncer but you can also work on other components like hostpath-mapper. The guide focuses on the syncer container.
The vCluster repo is enabled to develop using DevSpace. Devspace will automatically set up a vcluster and sync your code changes from the repository to a running container. So, you can easily develop and test.
Follow the guide on how to install DevSpace
Ensure your kubectl is connected to the local Kubernetes cluster.
$ kubectl get namespaces
In your Github vcluster directory, run:
$ devspace dev
Which uses the devspace.yaml file in the vcluster directory to deploy a vCluster and launch DevSpace:
info Using namespace 'vcluster'
info Using kube context 'minikube'
info Created namespace: vcluster
build:vcluster Rebuild image ghcr.io/loft-sh/loft-enterprise/dev-vcluster because tag is missing
build:vcluster Building image 'ghcr.io/loft-sh/loft-enterprise/dev-vcluster:YwXtFIF' with engine 'buildkit'
build:vcluster Execute BuildKit command with: docker buildx build --tag ghcr.io/loft-sh/loft-enterprise/dev-vcluster:YwXtFIF --file Dockerfile --target builder -
#0 building with "default" instance using docker driver557.1kB
build:vcluster
build:vcluster #1 [internal] load remote build context
Sending build context to Docker daemon 99.17MBdaemon 17.83MB
...
...
build:vcluster #21 exporting to image
build:vcluster #21 exporting layers
build:vcluster #21 exporting layers 3.9s done
build:vcluster #21 writing image sha256:35a71edf70fe3be275cfd42a775e15621a9067880b5f397e957daedb0ed7b73b
build:vcluster #21 writing image sha256:35a71edf70fe3be275cfd42a775e15621a9067880b5f397e957daedb0ed7b73b done
build:vcluster #21 naming to ghcr.io/loft-sh/loft-enterprise/dev-vcluster:YwXtFIF done
build:vcluster #21 DONE 3.9s
build:vcluster
build:vcluster View build details: docker-desktop://dashboard/build/default/default/q7vc4iv3ip8v24qxnybv4eo5p
build:vcluster Done processing image 'ghcr.io/loft-sh/loft-enterprise/dev-vcluster'
deploy:vcluster-k8s Deploying chart ./chart (vcluster) with helm...
deploy:vcluster-k8s Deployed helm chart (Release revision: 1)
deploy:vcluster-k8s Successfully deployed vcluster-k8s with helm
dev:vcluster Waiting for pod to become ready...
dev:vcluster DevSpace is waiting, because Pod vcluster-devspace-7b467dc9cd-hbtbz has status: Init:1/3
dev:vcluster Selected pod vcluster-devspace-7b467dc9cd-hbtbz
dev:vcluster ports Port forwarding started on: 2346 -> 2345
dev:vcluster sync Sync started on: . <-> .
dev:vcluster sync Waiting for initial sync to complete
dev:vcluster sync Initial sync completed
dev:vcluster term Opening shell to syncer:vcluster-devspace-7b467dc9cd-hbtbz (pod:container)
____ ____
| _ \ _____ __/ ___| _ __ __ _ ___ ___
| | | |/ _ \ \ / /\___ \| '_ \ / _` |/ __/ _ \
| |_| | __/\ V / ___) | |_) | (_| | (_| __/
|____/ \___| \_/ |____/| .__/ \__,_|\___\___|
|_|
Welcome to your development container!
This is how you can work with it:
- Run `go run -mod vendor cmd/vcluster/main.go start` to start vcluster
- Run `devspace enter -n vcluster --pod vcluster-devspace-7b467dc9cd-hbtbz -c syncer` to create another shell into this container
- Run `kubectl ...` from within the container to access the vcluster if its started
- Files will be synchronized between your local machine and this container
NOTE: you may need to provide additional flags through the command line, because the flags set from the chart are ignored in the dev mode.
If you wish to run vcluster in the debug mode with delve, run:
`dlv debug ./cmd/vcluster/main.go --listen=0.0.0.0:2345 --api-version=2 --output /tmp/__debug_bin --headless --build-flags="-mod=vendor" -- start`
Wait until the `API server listening at: [::]:2345` message appears
Start the "Debug vcluster (localhost:2346)" configuration in VSCode to connect your debugger session.
Note: vcluster won't start until you connect with the debugger.
Note: vcluster will be stopped once you detach your debugger session.
TIP: hit an up arrow on your keyboard to find the commands mentioned above :)
vcluster-0:vcluster-dev$
Now, your terminal is running in DevSpace, and you can develop and test with DevSpace.
Start vcluster in DevSpace via go run
vcluster-0:vcluster-dev$ go run -mod vendor cmd/vcluster/main.go start
Now, you can start to work with the virtual cluster based on the source code. This vCluster is running on your local Kubernetes cluster.
If you change a file locally, DevSpace will automatically sync the file into the Devspace container. After any changes, re-run the same command in the DevSpace terminal to apply the changes.
You can either debug with Delve within DevSpace or locally. Devspace is more convenient as no port forwarding is required.
Run vCluster in the debug mode with Delve in the vcluster directory. Note: Other sessions of DevSpace will need to be terminated before starting another
$ devspace dev -n vcluster
Once DevSpace launches and you are in the vcluster pod, run the following delve command.
vcluster-0:vcluster-dev$ dlv debug ./cmd/vcluster/main.go --listen=0.0.0.0:2345 --api-version=2 --output /tmp/__debug_bin --headless --build-flags="-mod=vendor" -- start
Wait until the API server listening at: [::]:2345 message appears.
Start the Debug vcluster (localhost:2346) configuration in Visual Studio Code to connect your debugger session.
If you are not using Visual Studio Code, configure your IDE to connect to localhost:2346 for the "remote" delve debugging.
Note: vCluster won't start until you connect with the debugger. Note: vCluster will be stopped once you detach your debugger session.
Download the vCluster CLI and use it to connect to your virtual cluster.
By connecting to the vCluster using the CLI, you set your local KubeConfig to the virtual cluster
$ vcluster connect vcluster
Build the CLI tool
$ go generate ./... && go build -o vcluster cmd/vclusterctl/main.go # build vcluster cli
Test the built CLI tool
./vcluster create v1 # create vcluster
If you already have vCluster CLI installed, please make sure to uninstall it first.
$ just build-snapshot
• starting build...
[...]
• running before hooks
• running hook=go mod tidy
• running hook=just embed-charts 0.20.0-next
• running hook=just clean-release
• running hook=just copy-assets
• running hook=just generate-vcluster-images 0.20.0-next
[...]
• building binaries
• partial build match=target=darwin_arm64
• partial build match=target=darwin_arm64
• building binary=dist/<ARCH>/vcluster
[...]
• build succeeded after 11s
$ ./dist/<ARCH>/vcluster version
vcluster version 0.20.0-next
kind create cluster
Creating cluster "kind" ...
✓ Ensuring node image (kindest/node:v1.29.2) 🖼
✓ Preparing nodes 📦
✓ Writing configuration 📜
✓ Starting control-plane 🕹️
✓ Installing CNI 🔌
✓ Installing StorageClass 💾
Set kubectl context to "kind-kind"
You can now use your cluster with:
kubectl cluster-info --context kind-kind
docker build . -t my-vcluster:0.0.1
Note: Feel free to push this image into your own registry.
If using kind as your local Kubernetes cluster, you need to import the image into kind.
$ kind load docker-image my-vcluster:0.0.1
For vCluster v0.20+:
Create a vcluster.yaml that sets the image to be your locally built Docker image.
controlPlane:
statefulSet:
imagePullPolicy: Never
image:
registry: ""
repository: my-vcluster
tag: 0.0.1Launch your vCluster using your vcluster.yaml
$ ./dist/<ARCH>/vcluster create my-vcluster -n my-vcluster -f ./vcluster.yaml --local-chart-dir chart
By connecting to the vCluster using the CLI, you set your local KubeConfig to the virtual cluster
$ ./dist/<ARCH>/vcluster connect my-vcluster
All of the tests are located in the vcluster directory.
Run the entire unit test suite.
$ ./hack/test.sh
Run the e2e tests, that are located in the e2e folder.
$ just delete-kind
$ just e2e
If Ginkgo is already installed, run ginkgo -v.
For running conformance tests, please take a look at conformance tests
This project is licensed under the Apache 2.0 License.
It is important to state that you retain copyright for your contributions, but agree to license them for usage by the project and author(s) under the Apache 2.0 license. Git retains history of authorship, but we use a catch-all statement rather than individual names.