How to Transform a Native Kubernetes Cluster into an OpenYurt Edge‑Native Cluster

Introduction

With the rapid growth of edge computing, increasing amounts of data must be stored, processed, and analyzed at the network edge, creating a need for efficient resource and application management. The cloud‑native approach of extending cloud capabilities to the edge, exemplified by OpenYurt, addresses this challenge.

Environment Preparation

In the cloud, an ENS node (public IP) runs Ubuntu 18.04 with Docker 19.03.5 and hosts the Kubernetes control plane (master‑node). At the edge, a Raspberry Pi 4 (Ubuntu 18.04, Docker 19.03.5, hostname edge-node) connects to a local router that accesses the internet via a 4G dongle.

Native Kubernetes Cluster Setup

The cloud control plane is created with kubeadm (v1.16.6) using Alibaba Cloud mirrors that support both amd64 and arm64 architectures. The following commands install the Kubernetes components on both cloud and edge nodes:

curl -s https://mirrors.aliyun.com/kubernetes/apt/doc/apt-key.gpg | sudo apt-key add -
echo "deb https://mirrors.aliyun.com/kubernetes/apt/ kubernetes-xenial main" > /etc/apt/sources.list.d/kubernetes.list
sudo apt-get update
sudo apt install -y kubelet=1.16.6-00 kubeadm=1.16.6-00 kubectl=1.16.6-00

Initialize the master node:

kubeadm init --image-repository=registry.cn-hangzhou.aliyuncs.com/edge-kubernetes --kubernetes-version=v1.16.6 --pod-network-cidr=10.244.0.0/16

Copy the admin config to $HOME/.kube/config and join the edge node with the token provided by kubeadm init:

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
kubeadm join 183.195.233.42:6443 --token XXXX --discovery-token-ca-cert-hash XXXX

Configure a loopback CNI on both nodes:

{
  "cniVersion": "0.3.0",
  "name": "lo",
  "type": "loopback"
}

Remove CoreDNS and taint the master node to simplify later OpenYurt installation:

kubectl delete deployment coredns -n kube-system
kubectl taint node master-node node-role.kubernetes.io/master-

Limitations of Native Kubernetes in Edge Scenarios

Deploy a test nginx pod with nodeSelector targeting the edge node, host networking enabled, and a short pod‑toleration (5 seconds) to observe eviction behavior during network loss.

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  tolerations:
  - key: "node.kubernetes.io/unreachable"
    operator: "Exists"
    effect: "NoExecute"
    tolerationSeconds: 5
  - key: "node.kubernetes.io/not-ready"
    operator: "Exists"
    effect: "NoExecute"
    tolerationSeconds: 5
  nodeSelector:
    kubernetes.io/hostname: edge-node
  containers:
  - name: nginx
    image: nginx
    hostNetwork: true

When the edge node loses connectivity, the pod cannot be accessed from the cloud (logs, exec, port‑forward all fail), and after ~40 seconds the node becomes NotReady. After the configured 5‑second toleration, the pod is evicted and later removed when the network is restored, showing that native Kubernetes cannot manage edge workloads reliably under intermittent connectivity.

Converting to an OpenYurt Cluster

Use the OpenYurt conversion tool yurtctl to add edge‑specific components and a cloud‑edge tunnel:

yurtctl convert \
  --yurt-controller-manager-image=registry.cn-hangzhou.aliyuncs.com/openyurt/yurt-controller-manager:v0.2.1 \
  --yurt-tunnel-agent-image=registry.cn-hangzhou.aliyuncs.com/openyurt/yurt-tunnel-agent:v0.2.1 \
  --yurt-tunnel-server-image=registry.cn-hangzhou.aliyuncs.com/openyurt/yurt-tunnel-server:v0.2.1 \
  --yurtctl-servant-image=registry.cn-hangzhou.aliyuncs.com/openyurt/yurtctl-servant:v0.2.1 \
  --yurthub-image=registry.cn-hangzhou.aliyuncs.com/openyurt/yurthub:v0.2.1 \
  --cloud-nodes=master-node \
  --deploy-yurttunnel

The conversion takes about two minutes and does not disrupt the running nginx pod.

After conversion, the following OpenYurt components appear:

# Cloud‑side
kubectl get pods -A -owide | grep master | grep yurt
# Edge‑side
kubectl get pods -A -owide | grep edge | grep yurt

Testing OpenYurt Operations

Standard kubectl commands (logs, exec, port‑forward) now succeed against the edge pod, confirming that OpenYurt restores cloud‑side operability.

# logs
kubectl logs nginx
# exec
kubectl exec -it nginx -- sh
# port‑forward
kubectl port-forward pod/nginx 8888:80

Accessing http://127.0.0.1:8888 from the master node returns the nginx page.

Edge Network‑Disruption Tests with OpenYurt

Enable node autonomy:

kubectl annotate node edge-node node.beta.alibabacloud.com/autonomy=true

Test 1: Network loss → recovery – After cutting the router’s public link for one minute, the edge node becomes NotReady but the pod remains Running. Restoring the network returns the node to Ready while the pod stays running, demonstrating resilience.

Test 2: Network loss → edge node reboot → recovery – After the same one‑minute outage, the edge node is rebooted. Post‑reboot, the OpenYurt daemon ( yurthub) and tunnel agent automatically restart, and the previously running pod is recreated, confirming that OpenYurt’s autonomous mode preserves workload continuity even after a node restart during a network outage.

Reverting to Native Kubernetes

When needed, the cluster can be reverted with:

yurtctl revert --yurtctl-servant-image=registry.cn-hangzhou.aliyuncs.com/openyurt/yurtctl-servant:v0.2.1

The revert process also leaves the business workload unaffected.

Conclusion

OpenYurt extends native Kubernetes with edge‑node autonomy and a cloud‑edge tunnel, enabling reliable management of edge workloads under unstable network conditions. It retains full compatibility with existing Kubernetes tooling while adding essential edge capabilities, making it a practical solution for cloud‑edge integrated deployments.