Run StatefulSet

This page shows how to leverage Kueue’s scheduling and resource management capabilities when running StatefulSets.

We demonstrate how to support scheduling StatefulSets in Kueue based on the Plain Pod Group integration, where StatefulSet is represented as a single independent workload.

This guide is for serving users that have a basic understanding of Kueue. For more information, see Kueue’s overview.

Before you begin

1. Learn how to install Kueue with a custom manager configuration.

2. Ensure that you have the v1/statefulset integration enabled, for example:

   apiVersion: config.kueue.x-k8s.io/v1beta1
   kind: Configuration
   integrations:
     frameworks:
      - "pod" # required by statefulset
      - "statefulset"
   

   Also, follow steps in Run Plain Pods to learn how to enable and configure the v1/pod integration.

3. Check Administer cluster quotas for details on the initial Kueue setup.

Running a StatefulSet admitted by Kueue

When running a StatefulSet on Kueue, take into consideration the following aspects:

a. Queue selection

The target local queue should be specified in the metadata.labels section of the StatefulSet configuration.

metadata:
   labels:
      kueue.x-k8s.io/queue-name: user-queue

b. Configure the resource needs

The resource needs of the workload can be configured in the spec.template.spec.containers.

spec:
  template:
     spec:
      containers:
       - resources:
           requests:
             cpu: 3

c. Scaling

Currently, scaling operations on StatefulSets are not supported. This means you cannot perform scale up or scale down operations directly through Kueue.

Example

Here is a sample StatefulSet:

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: nginx-statefulset
  labels:
    app: nginx
    kueue.x-k8s.io/queue-name: user-queue
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: registry.k8s.io/nginx-slim:0.27
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: "100m"
  serviceName: "nginx"

You can create the StatefulSet using the following command:

kubectl create -f sample-statefulset.yaml