Deploy Edge Applications with OpenYurt and KubeVela: A Step‑by‑Step Guide

Background

Edge devices are gaining compute capacity, creating a need to combine cloud advantages with edge resources. "Cloud‑edge collaboration" is a key focus, and the CNCF projects OpenYurt and KubeVela together provide a unified solution.

OpenYurt Overview

OpenYurt extends native Kubernetes to edge environments without invasive changes. Edge nodes are treated as regular Kubernetes nodes and gain capabilities such as autonomous edge operation, efficient management channels, node‑pool abstraction, traffic topology, secure containers, edge‑native Serverless/FaaS, and heterogeneous resource support.

KubeVela Overview

KubeVela, built on the OAM model, simplifies application delivery and management. It abstracts infrastructure complexity, supports micro‑service containers, cloud resource management, versioned and gray releases, autoscaling, observability, multi‑cluster, CI integration, and GitOps.

Core Requirements for Edge Deployment

Unified configuration : Avoid manual per‑resource edits; enable batch management, security, and audit integration.

Differential deployment : Deploy the same workload to multiple node pools with slight configuration differences, using NodeSelector to steer scheduling.

Scalability : Leverage the growing cloud‑native ecosystem to accommodate new workloads and operational features.

Demo Environment

A three‑node Kubernetes cluster simulates the edge scenario:

Node 1 – master (cloud node)

Node 2 – worker in node pool beijing Node 3 – worker in node pool

shanghai

Preparation Steps

Install YurtAppManager (core OpenYurt component providing the NodePool CRD):

git clone https://github.com/openyurtio/yurt-app-manager.git && \
helm install yurt-app-manager -n kube-system ./charts/yurt-app-manager/

Install KubeVela and enable the FluxCD addon :

curl -fsSl https://kubevela.net/script/install.sh | bash
vela install
vela addon enable fluxcd

Create node pools for Beijing and Shanghai:

apiVersion: apps.openyurt.io/v1beta1
kind: NodePool
metadata:
  name: beijing
spec:
  type: Edge
  annotations:
    apps.openyurt.io/example: test-beijing
  taints:
  - key: apps.openyurt.io/example
    value: beijing
    effect: NoSchedule
---
apiVersion: apps.openyurt.io/v1beta1
kind: NodePool
metadata:
  name: shanghai
spec:
  type: Edge
  annotations:
    apps.openyurt.io/example: test-shanghai
  taints:
  - key: apps.openyurt.io/example
    value: shanghai
    effect: NoSchedule

Label edge nodes to join the pools (replace node1 and node2 with the actual node names):

kubectl label node <code>node1</code> apps.openyurt.io/desired-nodepool=beijing
kubectl label node <code>node2</code> apps.openyurt.io/desired-nodepool=shanghai

Deploying an Ingress Controller to Edge Nodes

The example uses an Nginx Ingress controller deployed via a KubeVela Application that references a Helm chart. The component is replicated to both node pools with different configuration values.

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: edge-ingress
spec:
  components:
  - name: ingress-nginx
    type: helm
    properties:
      chart: ingress-nginx
      url: https://kubernetes.github.io/ingress-nginx
      repoType: helm
      version: 4.3.0
      values:
        controller:
          service:
            type: NodePort
          admissionWebhooks:
            enabled: false
    traits:
    - type: edge-nginx
  policies:
  - name: replication
    type: replication
    properties:
      selector: ["ingress-nginx"]
      keys: ["beijing", "shanghai"]
  workflow:
    steps:
    - name: deploy
      type: deploy
      properties:
        policies: ["replication"]

Application Structure

helm

component – describes the Helm chart to install. replication policy – splits the component into two instances, one per node pool, using the keys field. deploy workflow step – triggers the replication policy.

Custom Edge‑Nginx Trait

The trait patches Helm values to set node selectors, tolerations, and a unique ingressClass for each replica.

"edge-nginx": {
  "type": "trait",
  "attributes": {
    "podDisruptive": true,
    "appliesToWorkloads": ["helm"]
  },
  "template": {
    "patch": {
      // +patchStrategy=retainKeys
      "metadata": {"name": "$(context.name)-$(context.replicaKey)"},
      // +patchStrategy=jsonMergePatch
      "spec": {
        "values": {
          "ingressClassByName": true,
          "controller": {
            "ingressClassResource": {
              "name": "nginx-$(context.replicaKey)",
              "controllerValue": "openyurt.io/$(context.replicaKey)"
            }
          },
          "_selector": {
            "tolerations": [{"key": "apps.openyurt.io/example", "operator": "Equal", "value": "$(context.replicaKey)"}],
            "nodeSelector": {"apps.openyurt.io/nodepool": "$(context.replicaKey)"}
          }
        }
      }
    }
  }
}

The trait uses two patch strategies: retainKeys to overwrite existing values and jsonMergePatch to merge maps.

Deploy and Verify

vela up -f app.yaml
vela status edge-ingress --tree --detail

Expected output shows two HelmRelease resources, one per node pool. Verify pods on each pool with:

kubectl get node -l apps.openyurt.io/nodepool=beijing
kubectl get pod -l app.kubernetes.io/name=ingress-nginx -n default -o wide

Extending to New Edge Applications

By defining a new trait (e.g., gateway-nginx) that patches a Gateway API Helm chart, the same pattern can deploy other workloads to edge pools without additional code.

"gateway-nginx": {
  "type": "trait",
  "attributes": {"podDisruptive": true, "appliesToWorkloads": ["helm"]},
  "template": {
    "patch": {
      // +patchStrategy=retainKeys
      "metadata": {"name": "$(context.name)-$(context.replicaKey)"},
      // +patchStrategy=jsonMergePatch
      "spec": {
        "values": {
          "fullnameOverride": "nginx-gateway-nginx-$(context.replicaKey)",
          "gatewayClass": {"name": "nginx$(context.replicaKey)", "controllerName": "k8s-gateway-nginx.nginx.org/nginx-gateway-nginx-controller-$(context.replicaKey)"},
          "_selector": {
            "tolerations": [{"key": "apps.openyurt.io/example", "operator": "Equal", "value": "$(context.replicaKey)"}],
            "nodeSelector": {"apps.openyurt.io/nodepool": "$(context.replicaKey)"}
          }
        }
      }
    }
  }
}

The full example, including the trait definition and application YAML, is available in the GitHub repository:

https://github.com/chivalryq/yurt-vela-example/tree/main/gateway-nginx

Conclusion

OpenYurt turns edge nodes into native Kubernetes nodes, while KubeVela provides a declarative, extensible delivery model. Together they enable unified configuration, differential deployment, and easy scalability for edge workloads, and the approach can be reused for future edge scenarios such as Gateway API.