Update stateful workloads

To decide how to handle updates, StatefulSet objects use an update strategy defined in the .spec.updateStrategy section of its manifest. There are two strategies, OnDelete and RollingUpdate:

  • OnDelete does not delete and recreate Pod objects when the object's configuration changes. Instead, you must manually delete the old Pod objects for the controller to create updated Pod objects.
  • RollingUpdate deletes and recreates Pod objects when the object's configuration changes. New Pod objects must be in Running and Ready states before their predecessors are deleted. With this strategy, changing the Pod specification triggers a rollout. This is the default update strategy for StatefulSet objects.

There are multiple ways of updating StatefulSet objects. The common, declarative method is kubectl apply. To update a StatefulSet directly from your shell or in a preferred editor, use kubectl edit. You can roll out updates to the Pod's specification for a StatefulSet resource, such as its image, resource usage, resource requests, or configuration.

StatefulSet objects use an ordinal index for the identity and ordering of their Pod objects. By default, the pods of a StatefulSet are deployed in sequential order and are terminated in the reverse ordinal order. For example, a StatefulSet named web has its Pod objects named web-0, web-1, and web-2. When the StatefulSet specification is changed, its Pod objects are gracefully stopped and recreated in an ordered way. In this example, the pod named web-2 is terminated first, then web-1, and so on.

Alternatively, you can specify the podManagementPolicy: Parallel field to have a StatefulSet resource launch or terminate all of its Pod objects in parallel, rather than waiting for Pod objects to become running and ready or to be terminated prior to launching or terminating another pod.

Before you begin

To run commands against a user cluster, use the gdcloud CLI to access its kubeconfig file.

  1. Ensure that you have downloaded, installed, and configured the gdcloud CLI.

  2. Run gdcloud auth login to log in to the org admin cluster.

  3. Locate the user cluster name, or ask your Platform Administrator what the cluster name is.

  4. To generate the kubeconfig file of the user cluster, run:

    gdcloud clusters get-credentials USER_CLUSTER_NAME
    
  5. Record the path to the generated file, such as /tmp/user-cluster-kubeconfig-with-user-identity.yaml.

  6. Use the path to replace USER_CLUSTER_KUBECONFIG in these instructions.

To get the required permissions to update stateful workloads, ask your Organization IAM Admin to grant you the Namespace Admin role.

Update a StatefulSet resource

To update the StatefulSet, apply a new or updated manifest file. This is useful for making various changes to your StatefulSet when scaling or for specifying a new version of your application.

To update a StatefulSet object, run:

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    apply -f STATEFULSET_FILE

Replace the following:

  • USER_CLUSTER_KUBECONFIG: the kubeconfig file for the user cluster running the stateful workloads.

  • STATEFULSET_FILE: the name of the updated StatefulSet manifest file.

The kubectl apply command applies a manifest file to a resource. If the specified resource does not exist, it is created by the command.

Inspect a StatefulSet resource update rollout

You can view detailed information regarding the update rollout status and history of a StatefulSet object. You can also undo a rollout of a StatefulSet object.

Inspect the rollout

To inspect the rollout of the StatefulSet resource, run:

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    rollout status statefulset STATEFULSET_NAME
  • USER_CLUSTER_KUBECONFIG: the kubeconfig file for the user cluster running the stateful workloads.

  • STATEFULSET_NAME: the name of the updated StatefulSet object.

Get the rollout history

To see the StatefulSet resource's rollout history, run:

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    rollout history statefulset STATEFULSET_NAME
  • USER_CLUSTER_KUBECONFIG: the kubeconfig file for the user cluster running the stateful workloads.

  • STATEFULSET_NAME: the name of the updated StatefulSet object.

Undo a rollout

To undo a rollout, run:

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    rollout undo statefulset STATEFULSET_NAME

Replace the following:

  • USER_CLUSTER_KUBECONFIG: the kubeconfig file for the user cluster running the stateful workloads.

  • STATEFULSET_NAME: the name of the StatefulSet object.