Schedule applications to a specific node pool using node labels - Container Service for Kubernetes

Choose a scheduling method

Method	How it works	Use when
`nodeSelector`	Exact label match	Simple, single-condition scheduling
`nodeAffinity`	Label expressions with hard and soft rules	Multi-condition scheduling, or when you need fallback behavior

How it works

ACK uses the native Kubernetes scheduling mechanism to match pods to nodes based on labels. The process works as follows:

Set node pool labels. A node pool manages a group of nodes with the same configuration. When you configure Node Labels for a node pool, ACK syncs those labels to all nodes in the pool, including new nodes added during scale-out.

After you open Node Pool Configuration and select Update Labels and Taints of Existing Nodes, ACK also syncs the labels to existing nodes.
Define a scheduling rule. In the pod spec, use nodeSelector or nodeAffinity to specify the labels that target nodes must have.
(Optional) Configure exclusive access. Add a taint to the node pool so that only pods with a matching toleration are scheduled there.
Automatic scheduling. The Kubernetes scheduler places pods on nodes that satisfy the rules above.

ACK automatically creates a globally unique label alibabacloud.com/nodepool-id for each node pool. Use this label to target a specific node pool with an exact match.

Prerequisites

Before you begin, ensure that you have:

An ACK cluster with at least one node pool
kubectl configured to connect to your cluster

Step 1: Set labels on a node pool

Log on to the ACK console. In the left navigation pane, click ACK consoleClusters.
On the Clusters page, click the name of your cluster. In the left navigation pane, click Nodes > Node Pools.

In the Actions column of the target node pool, click Edit. Expand the advanced options section and configure Node Labels:

Field	Requirement	Details
Key (name part)	Required	1–63 characters; starts and ends with `[a-z0-9A-Z]`; allows letters, digits, hyphens (`-`), underscores (`_`), and periods (`.`)
Key (prefix part)	Optional	A DNS subdomain up to 253 characters, ending with `/`. The `kubernetes.io/` prefix is reserved — use `kubelet.kubernetes.io/` or `node.kubernetes.io/` instead.
Value	Optional	Up to 63 characters; starts and ends with `[a-z0-9A-Z]`; allows letters, digits, hyphens, underscores, and periods

If required, select Update Labels and Taints of Existing Nodes to sync the labels to nodes already in the pool.
In the left navigation pane, choose Nodes > Nodes. Click Manage Labels and Taints and verify the labels on the Labels tab.

Step 2: Configure a scheduling rule

After the node pool labels are in place, configure nodeSelector or nodeAffinity in your Deployment's pod spec.

Option 1: nodeSelector

nodeSelector schedules pods to nodes that have an exact label match. It is the simpler of the two options.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment-basic
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      nodeSelector:
        pod: nginx      # The node must have this label for the pod to be scheduled there.
      containers:
      - name: nginx
        image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
        ports:
        - containerPort: 80
        # Declare resource requests and limits in production to guarantee Quality of Service (QoS).
        resources:
          requests:
            cpu: "100m"
            memory: "128Mi"
          limits:
            cpu: "200m"
            memory: "256Mi"

Option 2: nodeAffinity

nodeAffinity supports label expressions (such as In, NotIn, and Exists) and two scheduling modes:

Hard affinity (requiredDuringSchedulingIgnoredDuringExecution): The pod must be placed on a matching node. If no match exists, the pod stays in Pending.
Soft affinity (preferredDuringSchedulingIgnoredDuringExecution): The scheduler prioritizes matching nodes but falls back to any available node if no match is found.

The following example uses hard affinity to ensure the pod runs on a node with the label pod: nginx:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-with-affinity
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      affinity:
        nodeAffinity:
          # Hard affinity: the pod is not scheduled if no node matches.
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
            - matchExpressions:
              - key: pod         # The node label key
                operator: In
                values:
                - nginx          # The node label value
      containers:
      - name: nginx-with-affinity
        image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
        ports:
        - containerPort: 80
        # Declare resource requests and limits in production to guarantee Quality of Service (QoS).
        resources:
          requests:
            cpu: "100m"
            memory: "128Mi"
          limits:
            cpu: "200m"
            memory: "256Mi"

Step 3: Deploy and verify

Apply the Deployment:
```
kubectl apply -f deployment.yaml
```
Check pod status and scheduling result. The -o wide flag shows which node each pod was scheduled to:
```
kubectl get pods -l app=nginx -o wide
```
You can check whether the pod is scheduled to the destination node in the output.

What's next

To set labels on individual nodes for finer-grained scheduling, see Manage node labels.
If a pod stays in Pending after you apply the scheduling rule, see Troubleshoot pod exceptions.
For advanced scheduling options — including sequential scale-out and payload-aware scheduling — see Scheduling policies provided by ACK.
If hard affinity finds no matching nodes, ACK can automatically scale out nodes from a node pool that has the matching labels and auto scaling enabled.
For clusters created before node pools were introduced, see Migrate unmanaged nodes to a node pool.