DevOps Dictionary

Kubernetes PriorityClass is a cluster-level Kubernetes object that assigns scheduling priority to pods. In practical terms, it tells the Kubernetes scheduler which workloads matter most when the cluster does not have enough CPU, memory, or other resources to run everything at once.

What Kubernetes PriorityClass does

A PriorityClass gives pods a numeric priority value. Pods with higher values are scheduled before pods with lower values. If the cluster is short on resources, Kubernetes can also preempt lower-priority pods so a higher-priority pod can run.

This is useful when some workloads should stay available even during resource pressure. For example, you may want CoreDNS, an ingress controller, monitoring agents, or a production API to take priority over batch jobs, preview environments, or test workloads.

How it works

A PriorityClass is created once at the cluster level. Pods use it by setting priorityClassName in their pod spec.

apiVersion: scheduling.k8s.io/v1
kind: PriorityClass
metadata:
  name: production-critical
value: 100000
globalDefault: false
description: "Priority class for production workloads that should run before lower-priority workloads."

apiVersion: apps/v1
kind: Deployment
metadata:
  name: payments-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: payments-api
  template:
    metadata:
      labels:
        app: payments-api
    spec:
      priorityClassName: production-critical
      containers:
        - name: app
          image: example/payments-api:1.0.0
          resources:
            requests:
              cpu: "500m"
              memory: "512Mi"

When the pod is admitted, Kubernetes converts the named PriorityClass into an integer priority on the pod. The scheduler then uses that value when deciding which pending pods to place first.

Preemption behavior

Preemption is the behavior most engineers associate with PriorityClass. If a high-priority pod cannot be scheduled because no node has enough free resources, the scheduler may choose lower-priority pods as victims. Kubernetes terminates those lower-priority pods, then schedules the higher-priority pod when enough capacity is available.

Preemption is powerful, but it can cause real disruption. A preempted pod receives normal termination handling, including its termination grace period. If the workload has a PodDisruptionBudget, the scheduler tries to respect it, but Kubernetes may still violate a budget if no better option exists.

You can also create a non-preempting PriorityClass by setting preemptionPolicy: Never. Pods using that class move ahead in the scheduling queue, but they do not evict lower-priority pods.

apiVersion: scheduling.k8s.io/v1
kind: PriorityClass
metadata:
  name: high-priority-non-preempting
value: 50000
preemptionPolicy: Never
globalDefault: false
description: "High scheduling priority without evicting lower-priority pods."

Common use cases

• Cluster services: Protect DNS, CNI components, log collectors, metrics agents, and other platform services that many applications depend on.
• Production workloads: Give customer-facing services priority over development, staging, or temporary workloads.
• Batch and data jobs: Assign lower priority to jobs that can wait or restart, such as report generation, ML training, or queue consumers.
• Platform controllers: Keep controllers such as ingress, certificate management, autoscaling, or infrastructure controllers available during resource pressure.
• Multi-tenant clusters: Use different priority levels to separate critical shared services from less urgent team workloads.

For example, if you run data workflows such as Apache Airflow on AWS EKS, you may give the Airflow scheduler a higher priority than worker pods. The scheduler keeps coordinating work, while workers can restart if the cluster needs room for more urgent services.

Key fields

• metadata.name: The name pods reference through priorityClassName.
• value: The priority number. Higher values mean higher priority. Kubernetes reserves very high values for system-critical workloads.
• globalDefault: If true, pods without a priorityClassName receive this class by default. Only one PriorityClass in a cluster can be the global default.
• description: A human-readable explanation of when to use the class.
• preemptionPolicy: Controls whether pods using the class can preempt lower-priority pods. The common values are PreemptLowerPriority and Never.

PriorityClass vs QoS class

PriorityClass and Kubernetes QoS classes solve different problems.

• PriorityClass controls scheduling order and preemption when Kubernetes decides which pods should run first.
• QoS class is derived from CPU and memory requests and limits. It affects how the kubelet handles pods during node-level resource pressure.

A pod can be high priority and still have poor resource settings. For critical workloads, set both a sensible PriorityClass and accurate resource requests.

PriorityClass vs resource requests and limits

PriorityClass does not create capacity. If every node is full and all lower-priority pods have already been removed, a high-priority pod can still remain pending. You still need proper node sizing, autoscaling, and resource requests.

For example, a pod with priority 100000 and a memory request of 64Gi will not schedule on nodes that cannot provide that memory. Priority helps decide order. It does not bypass physical or configured capacity limits.

Operational guidance

• Keep the number of classes small: Start with 3 to 5 levels, such as system-critical, production-critical, standard, and batch-low.
• Reserve high values: Do not let every team mark its workload as critical. Require review for high-priority classes.
• Use clear descriptions: Make it obvious which workloads should use each class.
• Pair with PodDisruptionBudgets: PDBs reduce accidental disruption, especially for replicated services.
• Watch for preemption loops: If high-priority pods repeatedly evict lower-priority pods, the cluster may need more capacity or better requests.
• Manage as code: Store PriorityClass manifests with your cluster configuration. If you manage Kubernetes resources with Terraform, keep these policies near other scheduling and namespace controls. This guide on deploying Kubernetes resources using Terraform shows a related workflow.

Real-world example

Assume a startup runs one shared Kubernetes cluster for production APIs, internal tools, and nightly batch jobs. During a traffic spike, the cluster runs out of available CPU.

With PriorityClass configured:

• The payments API uses production-critical with value 100000.
• The internal admin UI uses standard with value 1000.
• Nightly report jobs use batch-low with value 100.

If new payments API pods need to start and no node has room, Kubernetes can terminate lower-priority report pods first. The reports may restart later, while the customer-facing API gets capacity sooner.

Limitations and risks

• It can disrupt workloads: Preempted pods are terminated and rescheduled later if capacity becomes available.
• It is not a replacement for autoscaling: PriorityClass helps allocate scarce capacity, but it does not add nodes or replicas.
• It can hide poor capacity planning: Frequent preemption usually means the cluster is undersized or requests are inaccurate.
• It requires governance: If teams assign high priority too freely, the priority model loses value.
• It affects upgrade planning: During node drains and version upgrades, high-priority workloads still need enough safe capacity. Review scheduling policies as part of Kubernetes upgrade planning.

How platform teams commonly use it

Platform teams often define a small set of approved PriorityClasses and expose them through workload templates, Helm charts, GitOps repositories, or internal developer platforms. Application teams choose from approved options instead of creating arbitrary priority values.

If your platform provisions cloud infrastructure through Kubernetes controllers, such as Crossplane, you may assign higher priority to the controllers that reconcile infrastructure state. For related infrastructure-as-code patterns, see this guide on deploying AWS resources using Crossplane on Kubernetes.

Summary

Kubernetes PriorityClass helps you control which pods get scheduled first and which workloads can preempt others when resources are scarce. Use it for clear workload tiers, protect truly critical services, and combine it with accurate resource requests, autoscaling, PodDisruptionBudgets, and capacity planning.