Update stateful workloads

Shared Standard

This document explains how to update existing stateful workloads running in a Google Distributed Cloud (GDC) air-gapped Kubernetes cluster. As your application evolves based on resource usage and configuration optimizations, you must update your underlying pod specification in the Kubernetes cluster to reflect those workload changes. For more information on planning updates for stateful workloads, see the Kubernetes documentation for Update strategies.

This document is for developers within the application operator group, who are responsible for updating application workloads for their organization. For more information, see Audiences for GDC air-gapped documentation.

Before you begin

To complete the tasks in this document, you must request the necessary permissions and prepare your environment.

Request IAM roles

You must have specific roles to get the permissions you need to update stateful workloads. The roles you require depend on whether you are working within an organization-scoped shared cluster or project-scoped standard cluster. For more information, see Kubernetes cluster configurations.

Shared cluster roles

To create, delete, edit, or view workloads in a shared cluster, ask your Project IAM Admin to grant you the Namespace Admin (namespace-admin) role. This role is bound to your project namespace.

Standard cluster roles

To create, delete, edit, or view workloads in a standard cluster, ask your Project IAM Admin to grant you the Cluster Developer (cluster-developer) role. This role is bound to your project namespace.

Prepare your environment

To run commands against a Kubernetes cluster using the API, make sure you have the following resources:

Locate the Kubernetes cluster name, or ask a member of the platform administrator group what the cluster name is.
Sign in and generate the kubeconfig file for the Kubernetes cluster.
Use the kubeconfig path of the Kubernetes cluster to replace KUBERNETES_CLUSTER_KUBECONFIG in these instructions.

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 KUBERNETES_CLUSTER_KUBECONFIG -n NAMESPACE \
    apply -f STATEFULSET_FILE

Replace the following:

KUBERNETES_CLUSTER_KUBECONFIG: the kubeconfig file for the cluster running the stateful workloads.
NAMESPACE: the namespace. For shared clusters, this must be a project namespace. For standard clusters, it can be any namespace.
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 KUBERNETES_CLUSTER_KUBECONFIG -n NAMESPACE \
    rollout status statefulset STATEFULSET_NAME

KUBERNETES_CLUSTER_KUBECONFIG: the kubeconfig file for the cluster running the stateful workloads.
NAMESPACE: the namespace. For shared clusters, this must be a project namespace. For standard clusters, it can be any namespace.
STATEFULSET_NAME: the name of the updated StatefulSet object.

Get the rollout history

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

kubectl --kubeconfig KUBERNETES_CLUSTER_KUBECONFIG -n NAMESPACE \
    rollout history statefulset STATEFULSET_NAME

KUBERNETES_CLUSTER_KUBECONFIG: the kubeconfig file for the cluster running the stateful workloads.
NAMESPACE: the namespace. For shared clusters, this must be a project namespace. For standard clusters, it can be any namespace.
STATEFULSET_NAME: the name of the updated StatefulSet object.

Undo a rollout

To undo a rollout, run:

kubectl --kubeconfig KUBERNETES_CLUSTER_KUBECONFIG -n NAMESPACE \
    rollout undo statefulset STATEFULSET_NAME