Run a Virtual Kubelet either on or external to a Kubernetes cluster

You can Virtual Kubelet either on or external to a Kubernetes cluster using the virtual-kubelet command-line tool. If you run Virtual Kubelet on a Kubernetes cluster, you can also deploy it using Helm.

For virtual-kubelet installation instructions, see the Setup guide.

External to a Kubernetes cluster

To run Virtual Kubelet external to a Kubernetes cluster (not on the Kubernetes cluster you are connecting it to), run the virtual-kubelet binary with your chosen provider. Here’s an example:

virtual-kubelet --provider aws

Once Virtual Kubelet is deployed, run kubectl get nodes and you should see a virtual-kubelet node (unless you’ve named it something else using the --nodename flag).


The command-line tool for running Virtual Kubelets

$ virtual-kubelet flags


--cluster-domain stringKubernetes cluster domaincluster.local
--disable-taint boolDisable the Virtual Kubelet Node taintfalse
--enable-node-lease boolUse node leases (1.13) for node heartbeatsfalse
--full-resync-period durationHow often to perform a full resync of Pods between Kubernetes and the provider1m0s
--kubeconfig stringkubectl config file$HOME/.kube/config
--log-level stringThe log level, e.g. trace debug, info, warn, or errorinfo
--metrics-addr stringThe address to listen on for metrics and stats:10255
--namespace stringThe Kubernetes namespaceall
--nodename stringThe Kubernetes Node namevirtual-kubelet
--os stringThe operating system (must be linux or windows)Linux
--pod-sync-workers intThe number of Pod synchronization workers10
--provider stringThe Virtual Kubelet provider
--provider-config stringThe Virtual Kubelet provider configuration file
--startup-timeout durationHow long to wait for the virtual-kubelet to start
--trace-exporter stringsThe tracing exporter to use. Available exporters are jaeger and ocagent
--trace-sample-rate stringThe probability of tracing samples
--trace-service-name stringThe name of the services used to register with the trace exportervirtual-kubelet
--trace-tag mapTags to include with traces, in key=value form

On a Kubernetes cluster

It’s possible to run the Virtual Kubelet as a Kubernetes Pod in a Minikube or Docker for Desktop Kubernetes cluster.

At this time, automation of this deployment is supported only for the mock provider.

In order to deploy the Virtual Kubelet, you need to install Skaffold, a Kubernetes development tool. You also need to make sure that your current kubectl context is either minikube or docker-for-desktop (depending on which Kubernetes platform you’re using).

First, clone the Virtual Kubelet repository:

git clone
cd virtual-kubelet


make skaffold

By default, this will run Skaffold in development mode, which will make Skaffold watch hack/skaffold/virtual-kubelet/Dockerfile and its dependencies for changes and re-deploy the Virtual Kubelet when changes happen. It will also make Skaffold stream logs from the Virtual Kubelet Pod.

Alternative, you can run Skaffold outside of development mode—if you aren’t concerned about continuous deployment and log streaming—by running:

make skaffold MODE=run

This will build and deploy the Virtual Kubelet and return.


Helm is a package manager that enables you to easily deploy complex systems on Kubernetes using configuration bundles called Charts.

You can use the Virtual Kubelet Helm chart to deploy Virtual Kubelet on Kubernetes.

First, add the Chart repository (the Chart is currently hosted on GitHub):

helm repo add virtual-kubelet \
You can check to make sure that the repo is listed amongst your current repos using helm repo list.

Now you can install Virtual Kubelet using helm install. Here’s an example command:

helm install virtual-kubelet/virtual-kubelet \
  --name virtual-kubelet-azure \
  --namespace virtual-kubelet \
  --set provider=azure

This would install the Azure Container Instances Virtual Kubelet in the virtual-kubelet namespace.

To verify that Virtual Kubelet has been installed, run this command, which will list the available nodes and watch for changes:

kubectl get nodes \
  --namespace virtual-kubelet \

© 2023 The Virtual Kubelet authors