Simplify Edge Deployments with OpenYurt UnitedDeployment and Patch Customization

UnitedDeployment Overview

In edge‑computing environments workloads are often spread across geographically distributed node pools. Traditional per‑region Deployments require separate objects with distinct nodeSelector labels, leading to high management overhead as the number of regions grows.

OpenYurt’s yurt‑app‑manager introduces the UnitedDeployment custom resource, which abstracts a set of child Deployments (or StatefulSets) into a single higher‑level object. A UnitedDeployment defines a workloadTemplate (a Deployment or StatefulSet) and a list of Pools . Each pool specifies a name, replica count, and a nodeSelectorTerm that targets a specific edge node pool (e.g., apps.openyurt.io/nodepool=beijing).

Component repository: https://github.com/openyurtio/yurt-app-manager

UnitedDeployment Structure

WorkloadTemplate : the base workload specification (e.g., image: nginx:1.18.0).

Pools : a list where each entry defines name, replicas, and nodeSelectorTerm to bind the child workload to a node pool.

apiVersion: apps.openyurt.io/v1alpha1
kind: UnitedDeployment
metadata:
  name: test
  namespace: default
spec:
  selector:
    matchLabels:
      app: test
  workloadTemplate:
    deploymentTemplate:
      metadata:
        labels:
          app: test
      spec:
        selector:
          matchLabels:
            app: test
        template:
          metadata:
            labels:
              app: test
          spec:
            containers:
            - name: nginx
              image: nginx:1.18.0
              imagePullPolicy: Always
  topology:
    pools:
    - name: beijing
      nodeSelectorTerm:
        matchExpressions:
        - key: apps.openyurt.io/nodepool
          operator: In
          values:
          - beijing
      replicas: 1
    - name: hangzhou
      nodeSelectorTerm:
        matchExpressions:
        - key: apps.openyurt.io/nodepool
          operator: In
          values:
          - hangzhou
      replicas: 2

When the UnitedDeployment is created, the controller generates child Deployments named test-beijing-* and test-hangzhou-*. Each child inherits the template configuration while applying its pool’s specific nodeSelector and replicas.

Patch Extension for Per‑Pool Customization

Real‑world usage revealed scenarios where the basic UnitedDeployment is insufficient, such as:

Rolling out a new image to a single pool for validation before a full rollout.

Using different private image registries per pool, requiring distinct image names.

Varying CPU/memory requirements across pools.

Different ConfigMaps per pool.

To address these, a patch field was added to each pool. The field accepts a Kubernetes strategic‑merge‑patch that can modify any part of the child workload (e.g., container image, resource requests).

pools:
- name: beijing
  nodeSelectorTerm:
    matchExpressions:
    - key: apps.openyurt.io/nodepool
      operator: In
      values:
      - beijing
  replicas: 1
  patch:
    spec:
      template:
        spec:
          containers:
          - name: nginx
            image: nginx:1.19.3

The patch must follow the standard Kubernetes strategic‑merge‑patch syntax, identical to the format used by kubectl patch.

Feature Demonstration

Environment preparation : Deploy a Kubernetes or OpenYurt cluster with at least two nodes labeled apps.openyurt.io/nodepool=beijing and apps.openyurt.io/nodepool=hangzhou. Install the yurt‑app‑manager component.

Create the UnitedDeployment using the YAML manifest shown above (apply with kubectl apply -f).

Verify child Deployments : Run kubectl get deployments and confirm two Deployments exist with the expected replica counts and node selectors.

Inspect Pods : Use kubectl get pod to see one pod for the Beijing pool and two for the Hangzhou pool.

Apply a per‑pool patch : Edit the UnitedDeployment ( kubectl edit ud test) and add the patch section to the Beijing pool to change the container image to nginx:1.19.3.

Validate the update : Retrieve the specific child Deployment ( kubectl get deployment test-beijing-... -o yaml) and verify that the image field reflects the new version.

Conclusion

The UnitedDeployment model ( workloadTemplate + pools) enables operators to distribute workloads across edge regions efficiently while maintaining a concise configuration. The added patch capability provides granular control for image versioning, private registries, resource tuning, and ConfigMap variations, covering the majority of edge‑deployment requirements.