{"id":37088890,"url":"https://github.com/spectrocloud/cluster-api-provider-vcluster","last_synced_at":"2026-01-14T10:54:43.531Z","repository":{"id":41124507,"uuid":"495916820","full_name":"spectrocloud/cluster-api-provider-vcluster","owner":"spectrocloud","description":null,"archived":false,"fork":true,"pushed_at":"2025-09-04T06:07:35.000Z","size":28487,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"spectrocloud","last_synced_at":"2025-09-04T08:26:46.324Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"loft-sh/cluster-api-provider-vcluster","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spectrocloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-05-24T17:07:08.000Z","updated_at":"2025-03-06T17:35:23.000Z","dependencies_parsed_at":"2023-01-30T17:15:33.259Z","dependency_job_id":"49c8b047-83a3-482b-bb1b-ee60ba7c5b27","html_url":"https://github.com/spectrocloud/cluster-api-provider-vcluster","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/spectrocloud/cluster-api-provider-vcluster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spectrocloud%2Fcluster-api-provider-vcluster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spectrocloud%2Fcluster-api-provider-vcluster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spectrocloud%2Fcluster-api-provider-vcluster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spectrocloud%2Fcluster-api-provider-vcluster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spectrocloud","download_url":"https://codeload.github.com/spectrocloud/cluster-api-provider-vcluster/tar.gz/refs/heads/spectrocloud","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spectrocloud%2Fcluster-api-provider-vcluster/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28417731,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:47:48.104Z","status":"ssl_error","status_checked_at":"2026-01-14T10:46:19.031Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T10:54:42.658Z","updated_at":"2026-01-14T10:54:43.526Z","avatar_url":"https://github.com/spectrocloud.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# About\n\nThis is a [Cluster API](https://cluster-api.sigs.k8s.io/introduction.html) provider for the [vcluster project](https://www.vcluster.com/) - create fully functional virtual Kubernetes clusters.\n\n# Quick Start - Deploying Nginx in a Kind cluster\n Can be found [here](./docs/quick-start.md)\n\n# Installation instructions\n\nPrerequisites:\n- [clusterctl](https://cluster-api.sigs.k8s.io/user/quick-start.html#install-clusterctl) (v1.1.5+)\n- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)\n- A Kubernetes cluster where you will have cluster-admin permissions\n- Optional, depending on how you expose the vcluster instance - [vcluster CLI](https://www.vcluster.com/docs/getting-started/setup)\n\nInstall the vcluster provider\n\n```shell\nclusterctl init --infrastructure vcluster\n```\n\nNext you will generate a manifest file for a vcluster instance and create it in the management cluster.\nCluster instance is configured using clusterctl parameters and environment variables - CHART_NAME, CHART_REPO, CHART_VERSION, VCLUSTER_HOST and VCLUSTER_PORT.\nIn the example commands below, the HELM_VALUES variable will be populated with the contents of the `values.yaml` file.\n```shell\nexport CLUSTER_NAME=vcluster\nexport CLUSTER_NAMESPACE=vcluster\nexport KUBERNETES_VERSION=1.23.0\nexport HELM_VALUES=\"\"\n# Uncomment if you want to use vcluster values\n# export HELM_VALUES=$(cat devvalues.yaml | sed -z 's/\\n/\\\\n/g')\nkubectl create namespace ${CLUSTER_NAMESPACE}\nclusterctl generate cluster ${CLUSTER_NAME} \\\n    --infrastructure vcluster \\\n    --kubernetes-version ${KUBERNETES_VERSION} \\\n    --target-namespace ${CLUSTER_NAMESPACE} | kubectl apply -f -\n```\n\nNow we just need to wait until vcluster custom resource reports ready status:\n```shell\nkubectl wait --for=condition=ready vcluster -n $CLUSTER_NAMESPACE $CLUSTER_NAME --timeout=300s\n```\nAt this point the cluster is ready to be used. Please refer to the next chapter to get the credentials.\n\n**Note**: at the moment, the provider is able to host vclusters only in the cluster where the vcluter provider is running([management cluster](https://cluster-api.sigs.k8s.io/user/concepts.html#management-cluster)). Support for the remote host clusters is on our roadmap - [spectrocloud/cluster-api-provider-vcluster#6](https://github.com/loft-sh/cluster-api-provider-vcluster/issues/6).\n\n# How to connect to your vcluster\nThere are multiple methods for exposing your vcluster instance, and they are described in the [vcluster docs](https://www.vcluster.com/docs/operator/external-access). If you follow the docs exactly, you will need to use the vcluster CLI to retrieve kubeconfig. When using this CAPI provider you have an alternative - `clusterctl get kubeconfig ${CLUSTER_NAME} --namespace ${CLUSTER_NAMESPACE} \u003e ./kubeconfig.yaml`, more details about this are in the [CAPI docs](https://cluster-api.sigs.k8s.io/clusterctl/commands/get-kubeconfig.html). Virtual cluster kube config will be written to: ./kubeconfig.yaml. You can access the cluster via `kubectl --kubeconfig ./kubeconfig.yaml get namespaces`.\n\nHowever, if you are not exposing the vcluster instance with an external hostname, but you want to connect to it from outside the cluster, you will need to use the [vcluster CLI](https://www.vcluster.com/docs/getting-started/setup):\n```shell\nvcluster connect ${CLUSTER_NAME} -n ${CLUSTER_NAMESPACE}\n```\n\n# vcluster custom resource example\nWith the `clusterctl generate cluster` command we are producing a manifest with two Kubernetes custom resources - Cluster (cluster.x-k8s.io/v1beta1) and VCluster (infrastructure.cluster.x-k8s.io/v1alpha1).  \nBelow you may find an example of these two CRs with the comments explaining important fields.\n\n``` yaml\napiVersion: cluster.x-k8s.io/v1beta1\nkind: Cluster\nmetadata:\n  name: ${CLUSTER_NAME}\nspec:\n  # Two *Ref fields below must reference VCluster CR by name\n  # in order to conform to the CAPI contract   \n  infrastructureRef:\n    apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1\n    kind: VCluster\n    # name field must match .metadata.name of the VCluster CR\n    name: ${CLUSTER_NAME}\n  controlPlaneRef:\n    apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1\n    kind: VCluster\n    # name field must match .metadata.name of the VCluster CR\n    name: ${CLUSTER_NAME}\n---\napiVersion: infrastructure.cluster.x-k8s.io/v1alpha1\nkind: VCluster\nmetadata:\n  name: ${CLUSTER_NAME}\nspec:\n  # Kubernetes version that should be used in this vcluster instance, e.g. \"1.23\".\n  # The patch number from the version will be ignored, and the latest supported one\n  # by the used chart will be installed.\n  # Versions out of the supported range will be ignored, and earliest/latest supported\n  # version will be used instead.\n  kubernetesVersion: \"1.24\"\n\n  # We are using vcluster Helm charts for the installation and upgrade.\n  # The helmRelease sub-fields allow you to set Helm values and chart repo, name and version.\n  # Sources of the charts can be found here - https://github.com/loft-sh/vcluster/tree/main/charts \n  #\n  # This field, and all it's sub-fields, are optional.\n  helmRelease:\n\n    # The values field must contain a string with contents that would make a valid YAML file.\n    # Please refer to vcluster documentation for the extensive explanation of the features,\n    # and the appropriate Helm values that need to be set for your use case - https://www.vcluster.com/docs\n    values: |-\n      # example:\n      # syncer:\n      #   extraArgs:\n      #   - --tls-san=myvcluster.mydns.abc\n\n    chart: \n      # By default, the \"https://charts.loft.sh\" repo is used\n      repo: ${CHART_REPO:=null}\n      # By default, the \"vcluster\" chart is used. This coresponds to the \"k3s\" distro of the\n      # vcluster, and the \"/charts/k3s\" folder in the vcluster GitHub repo.\n      # Other available options currently are: \"vcluster-k8s\", \"vcluster-k0s\" and \"vcluster-eks\".\n      name: ${CHART_NAME:=null}\n      # By default, a particular vcluster version is used in a given CAPVC release. You may find\n      # it out from the source code, e.g.: \n      # https://github.com/loft-sh/cluster-api-provider-vcluster/blob/v0.1.3/pkg/constants/constants.go#L7\n      #\n      # Please refer to the vcluster Releases page for the list of the available versions:\n      # https://github.com/loft-sh/vcluster/releases\n      version: ${CHART_VERSION:=null}\n\n  # controlPlaneEndpoint represents the endpoint used to communicate with the control plane.\n  # You may leave this field empty, and then CAPVC will try to fill in this information based\n  # on the network resources created by the chart (Service, Ingress).\n  # The vcluster chart provides options to create a service of LoadBalancer type by setting\n  # Helm value - `.service.type: \"LoadBalancer\"`, or creating an Ingress by setting Helm value\n  # `.ingress.enabled: true` and `.ingress.host`. You can explore all options in the charts\n  # folder of our vcluster repo - https://github.com/loft-sh/vcluster/tree/main/charts\n  #\n  # We also recommend reading official vcluster documentation page on this topic:\n  # https://www.vcluster.com/docs/operator/external-access\n  # this page outlines additional Helm values that you will need to set in certain cases, e.g.\n  # `.syncer.extraArgs: [\"--tls-san=myvcluster.mydns.abc\"]`\n  #\n  # This field, and all it's sub-fields, are optional.\n  controlPlaneEndpoint:\n    host: \"myvcluster.mydns.abc\"\n    port: \"443\"\n```\n\n# Development instructions\n\nPrerequisites:\n- [Devspace](https://devspace.sh/cli/docs/getting-started/installation)\n- [clusterctl](https://cluster-api.sigs.k8s.io/user/quick-start.html#install-clusterctl)\n- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)\n- [envsubst](https://github.com/drone/envsubst) - which you can easily install into a local bin directory - `GOBIN=\"$(pwd)/bin\" go install -tags tools github.com/drone/envsubst/v2/cmd/envsubst@v2.0.0-20210730161058-179042472c46`\n- A Kubernetes cluster where you will have cluster-admin permissions\n\nFirst, we install core components of the Cluster API:\n```shell\nclusterctl init\n```\n\nNext we will start a development container for the vcluster provider.\nDevspace will continuosly sync local source code into the container, and you will be able to easily and quickly restart the provider with the newest code via the shell that is opened by the following command:\n\n```shell\ndevspace dev\n```\n\nOnce the shell is opened, you should see some basic instructions printed.\nYou can then run the provider with the following command:\n```shell\ngo run -mod vendor main.go\n```\n\nNext, in a separate terminal you will generate a manifest file for a vcluster instance.\nCluster instance is configured from a template file using environment variables - CLUSTER_NAME, KUBERNETES_VERSION, CHART_NAME, CHART_REPO, CHART_VERSION, VCLUSTER_HOST and VCLUSTER_PORT. Only the CLUSTER_NAME variable is mandatory.\nIn the example commands below, the HELM_VALUES variable will be populated with the contents of the `devvalues.yaml` file, don't forget to re-run the `export HELM_VALUES...` command when the `devvalues.yaml` changes.\n```shell\nexport CLUSTER_NAME=test\nexport CLUSTER_NAMESPACE=test\nexport KUBERNETES_VERSION=1.24.0\nexport HELM_VALUES=$(cat devvalues.yaml | sed -z 's/\\n/\\\\n/g')\nkubectl create namespace ${CLUSTER_NAMESPACE}\ncat templates/cluster-template.yaml | ./bin/envsubst | kubectl apply -n ${CLUSTER_NAMESPACE} -f -\n```\n\nNow we just need to wait until VCluster custom resource reports ready status:\n```shell\nkubectl wait --for=condition=ready vcluster -n $CLUSTER_NAMESPACE $CLUSTER_NAME --timeout=300s\n```\nAt this point the cluster is ready to be used. Please refer to \"How to connect to your vcluster\" chapter above to get the credentials.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspectrocloud%2Fcluster-api-provider-vcluster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspectrocloud%2Fcluster-api-provider-vcluster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspectrocloud%2Fcluster-api-provider-vcluster/lists"}