Virtual Kubelet: a kubelet that hands the node back end to a provider
Virtual Kubelet is an open source Kubernetes kubelet implementation.
At a glance
- What is it?
- The project is a library for building Kubernetes node agents that present the kubelet API while the actual compute lives somewhere else, and its provider contract is deliberately narrow about what a provider may touch.
- Who is it for?
- Use it when you want pods to land on a platform that is not a cluster you operate, and only if you can write a provider that satisfies the callback contract for secrets and config maps. It is not a federation layer, so cross cluster scheduling stays outside its scope, and check which Kubernetes version the module pins before you build against it, since the dependency set here tracks k8s.io libraries at 0.37.1 and the toolchain at Go 1.26.8.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 5 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- virtual-kubelet/virtual-kubelet4,582 ★ · +10
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| virtual-kubelet/virtual-kubelet | 4.6k | 4.6k |
10 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
It masquerades as a kubelet, and that is the whole trick
Virtual Kubelet is an open source kubelet implementation that presents itself as a kubelet for the purpose of connecting Kubernetes to other APIs. The node it registers looks ordinary to the control plane, and the compute behind it is supplied by whichever service the provider wraps, with ACI, AWS Fargate, IoT Edge and Tensile Kube named as examples. The primary scenario stated is extending the Kubernetes API into serverless container platforms, and the project is open to other targets. One exclusion is stated as plainly as the goals: it is explicitly not intended as an alternative to Kubernetes federation, which keeps expectations honest about what scheduling it does and does not attempt. Its own description is Kubernetes API on top, programmable back, and the architecture is described as pluggable and built directly on Kubernetes primitives so providers can be layered on top.
The provider contract forbids API server access outright
Three conditions define a supported integration, and the third one is a prohibition rather than a feature. A provider must supply the back end plumbing for the lifecycle of pods, containers and supporting resources in the context of Kubernetes. It must conform to the current API offered by the project. And it must not have access to the Kubernetes API server, instead exposing a well defined callback mechanism for obtaining data such as secrets and config maps. That single constraint is what keeps providers thin: anything a provider needs from the cluster has to arrive through a callback the library controls, so credentials and configuration are passed in rather than fetched. Each provider may still bring its own configuration file and its own required environment variables, so the split is between configuration, which the provider owns, and cluster data, which it may not read.
What the node reports back is a short, specific list
The advertised surface is enumerated rather than implied: create, delete and update pods; container logs, exec and metrics; getting a pod, a pod list and pod status; capacity; node addresses, node capacity and node daemon endpoints; the operating system; and bringing your own virtual network. Read as a kubelet contract, that is a node that reports itself accurately and forwards the pod verbs, with no container runtime of its own anywhere in the description. Two entries are worth isolating. Capacity is what lets the scheduler place work, so a provider that reports it has to report it truthfully. Bring your own virtual network is listed as a feature in its own right.
Provider configuration arrives through a --provider-config file
Configuration is per provider rather than global, and the mechanism is a flag. The Alibaba Cloud ECI provider reads the file named by the --provider-config flag, with the example file kept in the ECI provider repository as eci.toml. The Azure connector works the same way, in TOML format, with an example the README places at providers/azure/example.toml. Each provider may also require its own environment variables, so provider wiring is read from the provider's own documentation.
Fargate pods keep VPC networking and share the cluster with nodes
The AWS Fargate section is the longest provider description, and it is really a list of what the platform hands to the pod rather than of what the provider does. Pods get VPC networking with dedicated ENIs in your subnets, public IP addresses for internet access, private IP addresses to reach the Kubernetes cluster, security groups, IAM roles and CloudWatch Logs, plus access to other AWS services. The line that matters for scheduling is the last one: pods on Fargate can coexist with pods on regular worker nodes in the same Kubernetes cluster. That is what turns the provider into an extension of the cluster instead of a separate destination, since the scheduler does not have to choose between two disjoint worlds. It also means node capacity and node addresses, which the library reports, have to be synthesized from an API that does not expose ordinary nodes.
Admiralty splits one pod into a proxy and a delegate
The Admiralty Multi-Cluster Scheduler provider works by mutating annotated pods into proxy pods scheduled on a virtual-kubelet node, then creating corresponding delegate pods in remote clusters, which are the ones that actually run the containers. A feedback loop then updates the statuses and annotations of the proxy pods to reflect the statuses and annotations of the delegate pods. This is the clearest example in the provider list of why the library is a set of Kubernetes primitives: status propagation is a loop the provider implements itself rather than a feature it inherits. It also shows the cost of the model, since pod status becomes a mirror of a remote object and every update crosses that loop, so a slow remote cluster shows up as a slow status on the proxy.
ACI mixes instances with VMs, and Cisco provisions over RESTCONF
Two providers describe how far from a serverless platform this can go. The Azure Container Instances provider lets a cluster run typical pods on virtual machines and Azure Container Instances simultaneously in the same Kubernetes cluster, so one node type is real hardware and another is an API call, chosen by the scheduler like any other node. Cisco Virtual Kubelet targets infrastructure devices instead of a cloud: it uses the application hosting functionality supported on Cisco devices and performs provisioning over RESTCONF, which the README presents as a simplified entry point for application owners deploying containers at the edge. Between them, the two cases bracket the design: the node interface stays identical while the back end ranges from managed instances to a device with its own management protocol.
Go 1.26 toolchain, a scratch image and a lint stage in one Dockerfile
The build surface is pinned hard enough to read. The module declares go 1.26.0 with toolchain go1.26.8, and the Kubernetes libraries it builds against are all at 0.37.1, including api, apimachinery, apiserver, client-go and kubelet itself, alongside controller-runtime at 0.25.2 and OpenTelemetry at 1.47.0. The Makefile builds a static binary with CGO disabled, netgo and osusergo tags, and a release target that runs goreleaser through gobin_tool. The Dockerfile has three stages: a builder on golang:1.26.8 that runs the Makefile with optional build tags, a lint stage on golangci-lint v2.13.2 that copies go.mod and go.sum and runs go mod download first so the module cache is warm, and a final stage on scratch that copies the binary and the certificate directory, which is why the image contains nothing else.
.PHONY: build
build: build_tags := netgo osusergo
build: OUTPUT_DIR ?= bin
build: authors
@echo "Building..."
CGO_ENABLED=0 go build -ldflags '-extldflags "-static"' -o $(OUTPUT_DIR)/$(binary) $(if $V,-v) $(VERSION_FLAGS) ./cmd/$(binary)FROM scratch
COPY --from=builder /usr/bin/virtual-kubelet /usr/bin/virtual-kubelet
COPY --from=builder /etc/ssl/certs/ /etc/ssl/certs
ENTRYPOINT [ "/usr/bin/virtual-kubelet" ]
CMD [ "--help" ]Editorial conclusion
Use it when you want pods to land on a platform that is not a cluster you operate, and only if you can write a provider that satisfies the callback contract for secrets and config maps. It is not a federation layer, so cross cluster scheduling stays outside its scope, and check which Kubernetes version the module pins before you build against it, since the dependency set here tracks k8s.io libraries at 0.37.1 and the toolchain at Go 1.26.8.
Frequently asked questions
What is the purpose of a kubelet, and where does Virtual Kubelet fit?
Virtual Kubelet is a kubelet implementation that presents itself as a kubelet so Kubernetes can connect to other APIs, with the compute supplied by a provider such as ACI or AWS Fargate. It reports pods, logs, exec, metrics, capacity, node addresses and node daemon endpoints, and it is explicitly not meant as an alternative to Kubernetes federation.
what is virtual kubelet
It is a Go library for building custom Kubernetes node agents, with a pluggable provider interface and a pluggable architecture built on Kubernetes primitives. Its stated description is Kubernetes API on top, programmable back, and the primary scenario is extending the Kubernetes API into serverless container platforms.
What is a virtual cluster, in relation to this project?
That is not what this project builds: it registers a single node whose back end is a provider, not a cluster of its own. The documentation rules out the neighbouring concept explicitly, stating that Virtual Kubelet is not intended to be an alternative to Kubernetes federation.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/virtual-kubelet-virtual-kubelet)Star history chart for your README
[](https://hysenlabs.com/projects/virtual-kubelet-virtual-kubelet)Was this useful?