Virtual Kubelet: Running Kubernetes Pods on ACI, Fargate and Other Backends

The gap Virtual Kubelet fills between the scheduler and a non-Kubernetes backend

Kubernetes schedules pods onto nodes, and a node is whatever answers the kubelet API. Virtual Kubelet takes that position. It registers itself as a node in a cluster and speaks the kubelet interface, so the control plane treats it like any other worker while the actual containers run somewhere else. The README puts it plainly: it "masquerades as a kubelet for the purposes of connecting Kubernetes to other APIs."

The intended audience is narrow. The README says the primary scenario is extending the Kubernetes API into serverless container platforms such as ACI and Fargate, and that the project is focused on providing a library you consume in your own project to build a custom node agent. That means the person who gets value here is a platform engineer with a backend that already runs containers and an API to start them. If you have that, Virtual Kubelet saves you from reimplementing pod lifecycle bookkeeping against the API server. If you do not, there is nothing to plug in.

One boundary is stated outright: Virtual Kubelet is explicitly not intended to be an alternative to Kubernetes federation. Multi-cluster scheduling is a different problem with different tools.

How the provider interface, node registration and pod lifecycle fit together

The architecture is a library plus an interface. Virtual Kubelet handles the Kubernetes side: it watches pods assigned to its node, maintains node status, and exposes the operations the API server expects. A provider implements the backend side. The README lists what the current features cover on the Kubernetes-facing side: create, delete and update pods; container logs, exec and metrics; get pod, pods and pod status; capacity; node addresses, node capacity and node daemon endpoints; operating system; and bring your own virtual network.

The provider contract has three rules in the README. A provider must supply the back-end plumbing for lifecycle management of pods, containers and supporting resources; it must conform to the current API Virtual Kubelet exposes; and it does not have access to the Kubernetes API Server, with a well-defined callback mechanism for data such as secrets or configmaps. That third rule shapes the design. Your provider does not hold a kubeconfig and does not watch the cluster. It receives what it needs through callbacks, which keeps the credential boundary in one place but also means anything you need from the cluster has to be requested through that mechanism.

Node capacity is another thing the provider declares. Because the virtual node advertises capacity and node addresses, the scheduler treats it as a real target. What you advertise determines what lands on it. A provider that reports generous capacity will attract pods that the backend may not be able to run.

Building a provider: install steps and a first run

Virtual Kubelet is a Go module, not a standalone installer. The README points to godoc for consumption instructions, and the module path is in go.mod. A provider project starts by requiring it:

go get github.com/virtual-kubelet/virtual-kubelet

The repository builds a binary named virtual-kubelet from ./cmd/virtual-kubelet. The Makefile shows the build target with CGO disabled and static linking, and the Dockerfile runs that same target and copies the result into a scratch image whose entrypoint is /usr/bin/virtual-kubelet with a default CMD of --help.

make build

For a container build, the Makefile defines a safebuild target that passes BUILD_TAGS through to docker build and tags the image as virtual-kubelet with the current VERSION. The Dockerfile accepts the same idea as a build argument:

ARG BUILD_TAGS=""
RUN make VK_BUILD_TAGS="${BUILD_TAGS}" build

Because the README says there are implementations available for several providers and directs you to those repos for deployment details, the practical first run is to pick one of them rather than start from scratch. The Azure Container Instances provider is documented in its own repository, and it reads a configuration file passed with the --provider-config flag. That flag is the same one the Alibaba Cloud ECI provider uses. The Azure connector's config file is TOML, with an example at providers/azure/example.toml according to the README.

Once a provider is running and registered, you exercise it with ordinary pod manifests. The examples directory holds files such as nginx-pod.yaml, pause.yaml and nginx-pod-probes-named-ports.yaml, which are the kind of workload you would apply to confirm that scheduling, status and probes behave as expected against the virtual node.

Where Virtual Kubelet is the wrong choice

The clearest failure mode is treating it as a finished product. The README describes it as a library, and the deployment instructions live in each provider repository, not here. If no provider exists for your backend, the work is yours: lifecycle plumbing, conformance with the current provider API, and a callback path for secrets and configmaps. That is a project, not a configuration change.

The second limitation follows from the node model. A virtual node is a single scheduling target with whatever capacity the provider advertises. Pods that need host-level features assume a real machine. The examples directory includes nanoserver.yaml and iis-pod.yaml, which suggests Windows workloads are contemplated, but the README does not document how operating system selection interacts with scheduling, so a provider author has to work that out.

Third, the README names one thing Virtual Kubelet is not: an alternative to Kubernetes federation. If your goal is to spread workloads across clusters with a shared control plane, this is the wrong layer.

Finally, the provider list is a set of links to other repositories. Their maintenance is not this repository's maintenance. A provider that has not been touched in a while is a risk you take on independently of Virtual Kubelet itself.

Virtual Kubelet compared with running a real node pool

The obvious alternative is a managed node pool: real VMs that join the cluster and run a real kubelet. The difference is where the container runtime lives. With a node pool, the kubelet and the container runtime are on the same machine, and every Kubernetes feature that depends on the host (hostPath volumes, privileged containers, node-level daemonsets) has somewhere to run. With Virtual Kubelet, the container runs in a backend that knows nothing about the node abstraction, and the provider translates.

That translation is the cost and the benefit. You lose host-level semantics and gain the ability to schedule onto a serverless platform without managing VMs, which is the trade the README frames as "on-demand and nearly instantaneous container compute, orchestrated by Kubernetes, without having VM infrastructure to manage." A node pool gives you fidelity; Virtual Kubelet gives you reach into an API that was never a node.

Within the Virtual Kubelet ecosystem, the choice is which provider. Admiralty Multi-Cluster Scheduler takes a different route from the cloud providers: it mutates annotated pods into proxy pods on a virtual-kubelet node and creates delegate pods in remote clusters, then runs a feedback loop to copy status and annotations back. That is a scheduling and federation-shaped approach built on the same node abstraction, and it is worth reading before assuming a cloud provider is the right fit.

Maintenance, versioning and the Apache-2.0 licence

The repository is not archived. The last push was on 2026-09-18, and releases are frequent: v1.14.0 on 2026-09-07, v1.13.0 on 2026-07-08, and v1.12.0 on 2026-01-27. The module declares go 1.26.0 with a toolchain of go1.26.8, and it tracks Kubernetes libraries at v0.36.4 across k8s.io/api, apimachinery, apiserver, client-go and kubelet. That pinning matters: a provider built against an older k8s.io/kubelet will need attention when it upgrades, because the provider API must conform to the current API Virtual Kubelet exposes.

The upgrade cost sits mostly in your provider, not in the library. The README's requirement that a provider conform to the current API is the contract that will break. The Dockerfile pins a golangci-lint version as ARG GOLANG_CI_LINT_VERSION with a default of v2.13.2, which tells you lint runs in CI and that a provider vendored into a build like this will be held to it.

The licence is Apache-2.0, stated in the repository and in the LICENSE file. Apache-2.0 permits commercial use and modification and includes a patent grant. It also requires that you preserve notices and state changes. Whether that fits a product you ship is a question for your own counsel; nothing in the repository changes the terms.

Editorial conclusion

Adopt Virtual Kubelet if you control a backend API and want Kubernetes scheduling to reach it, and you accept owning the provider code, its callbacks for secrets and configmaps, and the node object it registers. Do not adopt it if you want a finished node agent for a cloud someone else already integrated, or if you need federation between clusters, which the README states it is explicitly not. Before writing code, read the provider interface in the node package, check whether an existing provider already covers your backend, and confirm which node labels and taints your provider must set so the scheduler sends only the pods you intend.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. virtual-kubelet/virtual-kubelet on GitHub