# OpenYurt puts a node sidecar between every edge worker and the API server

> OpenYurt keeps a stock Kubernetes API and wraps it in four components, so worker nodes can sit in distant physical regions behind a link that drops. It targets fleets that genuinely lose connectivity, and its verified Kubernetes ceiling is 1.34.

**openyurtio/openyurt** — OpenYurt - Extending your native Kubernetes to edge(project under CNCF)

- Repository: https://github.com/openyurtio/openyurt
- Website: https://openyurt.io
- Stars: 2,009 · Forks: 491
- Language: Go
- License: Apache-2.0
- Published: 2026-10-13 · Updated: 2026-10-13 · Language: en
- Canonical page: https://hysenlabs.com/projects/openyurtio-openyurt

## YurtHub sits between kubelet and the API server on every worker

A Kubernetes cluster whose workers sit in factories, shops or cell sites runs into a problem the cloud control plane was not built for: the link between them drops. OpenYurt's answer is a process on the node rather than a new API. YurtHub runs on worker nodes as a static pod and handles requests that components such as Kubelet and Kubeproxy send to kube-apiserver, so a node's API traffic terminates locally instead of leaving the node on a link that may not be there.

Regions are first class in this design. Edge nodes in a cluster can span multiple physical regions, which OpenYurt calls `Pools`, and one centralized Kubernetes control plane in the cloud manages all of them. Each node holds enough compute to run its own workloads plus the OpenYurt components that have to live beside them. Everything cluster-wide sits in Yurt-Manager, described as all controllers and webhooks for edge. The README names the problems it targets: unreliable or disconnected cloud-edge networking, edge autonomy, edge device management, and region-aware deployment.

## A vanilla cluster is the real alternative, and its weak spot is named

The honest alternative is the cluster you already know: upstream Kubernetes with no sidecar, every worker dialing the control plane directly, and no region concept at all. In a single data centre that arrangement has one fewer pod per node and one fewer thing to operate. It also breaks in a specific way, the one OpenYurt names in its opening paragraph: a node that cannot reach the API server stops reporting and stops executing work handed to it.

What OpenYurt changes is who terminates that traffic, not what the API looks like, and it claims intact Kubernetes API compatibility while doing it. Where the alternative loses is geography at scale. OpenYurt makes distance a modelled property through `Pools` and Raven-Agent rather than an incident discovered during a WAN outage. If your nodes are all in one region over a reliable link, none of this earns its cost, and no per-node overhead figure for a YurtHub deployment appears anywhere in the repository.

## Raven replaced Yurt-Tunnel with a Layer 7 reverse proxy

Running `kubectl exec` or `kubectl logs` against a pod in another physical region means pushing an interactive stream across the same link that keeps dropping. Raven-Agent handles edge-edge and edge-cloud communication and works at two layers. Layer 3 provides network connectivity among pods in different physical regions, the shape a single vanilla cluster has. Layer 7 reverse proxies the native Kubernetes O&M commands `kubectl exec` and `kubectl logs`.

The component's own description carries its history in one clause: Raven-Agent replaces Yurt-Tunnel. Any dashboard, runbook or install manifest still naming Yurt-Tunnel is out of date, and the repository's top-level listing has no Yurt-Tunnel entry to inspect, so there is no fallback to the older name. The RPC substrate underneath is shared rather than per component, with google.golang.org/grpc pinned at v1.83.1 in the module file.

## One YurtIoTDock per NodePool, and devices only through EdgeX

Edge hardware is where the Kubernetes abstraction gets thin, and OpenYurt's answer is a dedicated bridge. One instance of YurtIoTDock is deployed in every edge NodePool, it bridges the EdgeX Foundry platform, and it uses Kubernetes CRD to manage edge devices. Holding device state in custom resources puts the inventory in the same API server as the workloads, which is convenient, and it also ties your device model to whatever custom resources you have applied.

This repository is the core, not the whole edge feature set. Alongside the four main components the README lists auxiliary controllers for integration and customization, and the first of those is not here: a node resource manager handles additional edge node resources such as LVM, QuotaPath and Persistent Memory, with details kept in the openyurtio/node-resource-manager repository. Anyone sizing a production edge platform has to follow that link, because the top-level listing holds charts, cmd, config, hack, pkg and test and says nothing about edge storage.

## The README splits installation in two and prints no command

This is the thinnest corner of the README, and it is thin on purpose. Installation is divided into two parts: installing the OpenYurt control plane components, and joining nodes. Both steps are links into the hosted documentation at `openyurt.io`, and the repository README contains no command to copy. Want the sequence? The docs site is where it lives.

What the repository does hand you are build knobs in the `Makefile`, and they tell you what a build host is expected to have:

```bash
KUBERNETESVERSION ?=v1.34
GOLANGCILINT_VERSION ?= v2.11.4
TARGET_PLATFORMS ?= linux/amd64
BUILD_KUSTOMIZE ?= _output/manifest
```

Kubernetes v1.34 is the version the build targets by default, the linter is pinned at v2.11.4, and rendered manifests land under `_output/manifest`. Watch the first line's spacing: `KUBERNETESVERSION ?=v1.34` has no space between the variable and its assignment operator, while the other three have one. Copy that line wrong and the default silently stops applying.

A second block exposes the regional build switch:

```bash
ifeq (${REGION}, cn)
	GOPROXY=https://goproxy.cn
	DOCKER_BUILD_ARGS += --build-arg GOPROXY=$(GOPROXY) --build-arg MIRROR_REPO=mirrors.aliyun.com
endif
```

Setting REGION=cn rewrites the Go module proxy and appends two build args that point the image build at mirrors.aliyun.com. On any other value none of that applies, which is the closest thing to a documented regional build path the source tree contains.

## Kubernetes 1.34 is a ceiling, and go.mod pins every library to it

OpenYurt is certified to support up to Kubernetes version 1.34, and the README is careful about what sits above that line: compatibility with subsequent versions is expected, but has not yet been verified. The module file agrees with the sentence.

```go
module github.com/openyurtio/openyurt

go 1.25.0
```

Every Kubernetes library sits at v0.34.0, from k8s.io/api and k8s.io/client-go through k8s.io/kubectl and k8s.io/kubelet, and the Go directive reads go 1.25.0. That makes the cost of a Kubernetes upgrade concrete. Moving to a newer cluster is not a cluster-side change for this project; it is a coordinated bump across every k8s.io module in the require block, plus the verification the README already flags as outstanding. Test libraries are pinned just as tightly, with github.com/onsi/ginkgo/v2 at v2.28.1 and github.com/onsi/gomega at v1.42.1 in the same block.

The last push on this repository landed on 2026-10-05, and the newest version tag, v1.7.0, is dated 2026-05-06, so the code moves while the Kubernetes ceiling has not moved with it. Licensing raises no adoption question for most teams: the project ships under Apache-2.0, and the README credits the original Kubernetes authors for the implementations it reuses.

## Intact API compatibility, with a sidecar in the request path

Two claims in the same README paragraph pull in opposite directions. OpenYurt preserves intact Kubernetes API compatibility, and it also runs YurtHub on worker nodes as a static pod to handle the requests those components send to the API server. A node sidecar in front of kube-apiserver is by definition inside the request path for that node, and Yurt-Manager, described as all controllers and webhooks, sits in the admission path for the whole cluster. Neither sentence is false. One describes the surface you program against, the other describes what sits underneath it.

```go
require (
	github.com/aliyun/alibaba-cloud-sdk-go v1.62.156
	github.com/edgexfoundry/go-mod-core-contracts/v3 v3.1.0
	github.com/projectcalico/api v0.0.0-20240708202104-e3f70b269c2c
)
```

The vendor agnostic claim has a smaller wrinkle in the same file. The root module requires github.com/aliyun/alibaba-cloud-sdk-go v1.62.156 alongside the EdgeX and Calico contracts, and the Makefile swaps the Go proxy for goproxy.cn and the image mirror for mirrors.aliyun.com under one regional branch. None of that stops OpenYurt being vendor agnostic in deployment. It does mean a specific cloud SDK sits in the main require block of a CNCF incubating project.

A smaller tell sits in the component links. Four of the five point into a moving documentation path, `openyurt.io/docs/next/core-concepts/`, while the Yurt-Manager link goes to `openyurt.io/docs/core-concepts/yurt-manager/` with no version segment at all. Follow the first four and you are reading unreleased documentation for a project whose verified Kubernetes ceiling is 1.34.

## Four cases where OpenYurt adds cost without benefit

Single region clusters are the clearest case against it. YurtHub, Raven-Agent and the `Pools` model exist for distance and link loss, and a fleet in one data centre pays for a static pod on every node without a documented return. Device fleets are the second case: YurtIoTDock is described as a bridge to the EdgeX Foundry platform, not a general purpose device agent, so Hardware inventory living outside that platform stays outside this project. Operations carried over from Yurt-Tunnel are the third, since Raven-Agent replaces it and the top-level listing has no entry for the older name.

The fourth case is anyone who needs a documented way back. The README does not describe a rollback or revert procedure for a control plane that mediates traffic on every node, and the install steps live off-repository at `openyurt.io`, where the sequence cannot be read from the source tree at all. That gap is small for a pilot and expensive during an incident, because the people restoring service will be reading a web page rather than a file in the version you deployed.

## Conclusion

OpenYurt earns a place in fleets spread across physical regions with real link loss, because YurtHub, Raven-Agent and the region aware Pools model address failures a plain upstream cluster leaves open. It does not earn one in a single region cluster, nor where device inventory lives outside EdgeX Foundry, nor where the install sequence has to live inside your own runbooks. Before adopting, read the two part install path on openyurt.io, confirm your cluster sits at or below Kubernetes 1.34, and check that the devices you care about are modelled as EdgeX custom resources.

## FAQ

### Which Kubernetes versions does OpenYurt support?

OpenYurt is certified to support up to Kubernetes version 1.34. Compatibility with subsequent versions is described as expected, but it has not yet been verified.

### What replaced Yurt-Tunnel in OpenYurt?

Raven-Agent replaces Yurt-Tunnel. It provides Layer 3 network connectivity among pods in different physical regions and Layer 7 reverse proxying for native Kubernetes commands such as kubectl exec and kubectl logs.

### How does OpenYurt manage edge devices?

One instance of YurtIoTDock is deployed in every edge NodePool. It bridges the EdgeX Foundry platform and uses Kubernetes CRD to manage edge devices.

### Does the OpenYurt README include the installation commands?

No. It splits installation into two parts, installing the OpenYurt control plane components and joining nodes, and links both steps to the hosted documentation at openyurt.io.

### Does OpenYurt require Alibaba Cloud to run?

The README describes OpenYurt as vendor agnostic, and its components are deployed on a stock Kubernetes control plane. The module file still requires github.com/aliyun/alibaba-cloud-sdk-go v1.62.156, and the Makefile switches the Go proxy and image mirror when REGION is set to cn.

### What is a Pool in OpenYurt?

A Pool is a physical region. Edge nodes in a cluster can span multiple physical regions, and one centralized Kubernetes control plane in the cloud manages all of them.

## Sources

- [License: Apache-2.0](https://github.com/openyurtio/openyurt/blob/master/LICENSE)
- [openyurtio/openyurt on GitHub](https://github.com/openyurtio/openyurt)
- [Project website](https://openyurt.io)
- [README](https://github.com/openyurtio/openyurt/blob/master/README.md)
- [Releases](https://github.com/openyurtio/openyurt/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openyurtio-openyurt