Autopilot Standard
This page explains how to deploy a stateful application usingGoogle Kubernetes Engine (GKE).
Overview
Stateful applications save data topersistent disk storagefor use by the server, by clients, and by other applications. An example of astateful application is a database or key-value store to which data is saved andretrieved by other applications.
Persistent storage can bedynamically provisioned,so that the underlying volumes are created on demand. In Kubernetes, youconfigure dynamic provisioning by creating aStorageClass.In GKE, a default StorageClass allows you to dynamicallyprovision Compute Engine persistent disks.
Kubernetes uses the StatefulSetcontroller to deploy stateful applications as StatefulSet objects. Pods inStatefulSets are not interchangeable: each Pod has a unique identifier that ismaintained no matter where it is scheduled.
Stateful applications are different fromstateless applications, in whichclient data is not saved to the server between sessions.
You can learn more aboutpersistent storage in multi-zonal and regional clusters.
Before you begin
Before you start, make sure you have performed the following tasks:
- Enable the Google Kubernetes Engine API. Enable Google Kubernetes Engine API
- If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running
gcloud components update
.
- Ensure your containerized application is stored in an image registry, such asArtifact Registry.
You can follow thequickstart,to enable the GKE API, create a cluster, and learn more aboutGKE.
Requesting persistent storage in a StatefulSet
Applications can request persistent storage with aPersistentVolumeClaim.
Typically, you must create PersistentVolumeClaim objects in addition to creatingthe Pod. However, StatefulSet objects include a volumeClaimTemplates
array,which automatically generates the PersistentVolumeClaim objects. EachStatefulSet replica gets its own PersistentVolumeClaim object.
You can also use a preexisting disk in a StatefulSet.
Creating a StatefulSet
To create a StatefulSet resource, use the kubectl apply
command.
The kubectl apply
command uses manifest files to create, update, and deleteresources in your cluster. This is a declarativemethod of object configuration. This method retains writes made to live objects withoutmerging the changes back into the object configuration files.
Linux
The following manifest file is a simple example of a StatefulSet governed by aService that has been created separately:
apiVersion: apps/v1kind: StatefulSetmetadata: name: STATEFULSET_NAMEspec: selector: matchLabels: app: APP_NAME serviceName: "SERVICE_NAME" replicas: 3 updateStrategy: type: RollingUpdate template: metadata: labels: app: APP_NAME spec: containers: - name: CONTAINER_NAME image: ... ports: - containerPort: 80 name: PORT_NAME volumeMounts: - name: PVC_NAME mountPath: ... volumeClaimTemplates: - metadata: name: PVC_NAME annotations: ... spec: accessModes: [ "ReadWriteOnce" ] resources: requests: storage: 1Gi
Replace the following:
STATEFULSET_NAME
: the name of the StatefulSet.SERVICE_NAME
: the name of the Service.APP_NAME
: the name of the application run in the Pods.CONTAINER_NAME
: the name of the containers in the Pods.PORT_NAME
: the name of the port opened by the StatefulSet.PVC_NAME
: the name of the PersistentVolumeClaim.
In this file, the kind
field specifies that a StatefulSet object should becreated with the specifications defined in the file. This example StatefulSetproduces three replicated Pods, and opens port 80 for exposing theStatefulSet to the internet.
Windows
When using clusters with Windows Server node pools,you must create a StorageClass because the default StorageClass uses ext4
asthe file system type, which only works for Linux containers. If you are using aCompute Engine persistent disk, you must use NTFS
as the file storage typeas shown in the following example:
apiVersion: storage.k8s.io/v1kind: StorageClassmetadata: name: STORAGECLASS_NAMEparameters: type: pd-standard fstype: NTFSprovisioner: kubernetes.io/gce-pdreclaimPolicy: DeletevolumeBindingMode: WaitForFirstConsumer
The following StatefulSet manifest uses the StorageClass defined above. Itcreates four PersistentVolume and PersistentVolumeClaim pairs to representfour Compute Engine persistent disks. Each Pod in the StatefulSet consumesone persistent disk.
To ensure your Pods are correctly scheduled onto Windows Server nodes, youmust add a node selector to your Pod specification.
apiVersion: apps/v1kind: StatefulSetmetadata: name: STATEFULSET_NAMEspec: replicas: 4 selector: matchLabels: app: APP_NAME template: metadata: labels: app: APP_NAME name: CONTAINER_NAME spec: nodeSelector: kubernetes.io/os: windows containers: - name: CONTAINER_NAME image: ... ports: - containerPort: 80 name: PORT_NAME volumeMounts: - name: PVC_NAME mountPath: C:\mnt\state volumeClaimTemplates: - metadata: name: PVC_NAME spec: storageClassName: STORAGECLASS_NAME accessModes: [ "ReadWriteOnce" ] resources: requests: storage: 1Gi
Replace the following:
APP_NAME
: the name of the application run in the Pods.STATEFULSET_NAME
: the name of the StatefulSet.CONTAINER_NAME
: the name of the containers in the Pods.PORT_NAME
: the name of the port opened by the StatefulSet.PVC_NAME
: the name of the PersistentVolumeClaim.STORAGECLASS_NAME
: the name of the StorageClass.
To create a StatefulSet resource, run the following command replacingSTATEFULSET_FILE
with the manifest file name:
kubectl apply -f STATEFULSET_FILE
You can also use kubectl apply -f DIRECTORY/
to createall objects (except existing ones) defined in configuration files stored in adirectory.
Inspecting a StatefulSet
kubectl
To inspect the StatefulSet, run the following command:
kubectl get statefulset STATEFULSET_NAME -o yaml
This command displays the live configuration of the StatefulSet resource inYAML format.
To list the Pods created by the StatefulSet, run the following command:
kubectl get pods -l app=APP_NAME
In this command, the -l
flag instructs kubectl
to get all Pods labeledfor the APP_NAME
.
The output is similar to the following:
NAME READY STATUS RESTARTS AGEpod-name 1/1 Running 0 1mpod-name 1/1 Running 0 1m
To get detailed information about the StatefulSet, run the following command:
kubectl describe statefulset STATEFULSET_NAME
To get information about a specific Pod, run the following command:
kubectl describe pod POD_NAME
To list the PersistentVolumeClaim objects that were created, run thefollowing command:
kubectl get pvc
The output is similar to the following:
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGESTATEFULSET_NAME-PVC_NAME-0 Bound pvc-bdff4e1e-183e-11e8-bf6d-42010a800002 1G RWO standard 9sSTATEFULSET_NAME-PVC_NAME-1 Bound pvc-bdff4e1e-183e-11e8-bf6d-42010a800003 1G RWO standard 9sSTATEFULSET_NAME-PVC_NAME-2 Bound pvc-bdff4e1e-183e-11e8-bf6d-42010a800004 1G RWO standard 9s
To get information about a specific PersistentVolumeClaim, run the following command:
kubectl describe pvc STATEFULSET_NAME-PVC_NAME-0
To get information about a specific PersistentVolume, run the following command:
kubectl describe pv PV_NAME
Console
To inspect a StatefulSet, perform the following steps:
Go to the Workloads page in the Google Cloud console.
Go to Workloads
In the workloads list, click the name of the StatefulSet you want to inspect.
On the Stateful Set details page, do any of the following:
- Click the Revision History tab to see the StatefulSet's revision history.
- Click the Events tab to see all events related to the StatefulSet.
- Click the Logs tab to see container logs for the StatefulSet.
- Click the YAML tab to see, copy, or download the configurationYAML for the StatefulSet.
Updating a StatefulSet
There are multiple ways of updating StatefulSets. The common, declarative methodis kubectl apply
. To update the StatefulSet directly from your shell or in apreferred editor, you can use kubectl edit
. You can also use the YAML editorfrom the GKE Workloads menu in the Google Cloud console.
You can roll out updates to thePods specification for a StatefulSet resource, such as its image, resource usage/requests, or configuration.
kubectl apply
You can update the StatefulSet by applying a new or updated manifest file.This is useful for making various changes to your StatefulSet, such as whenscaling or for specifying a new version of your application.
To update a StatefulSet, run the following command:
kubectl apply -f STATEFULSET_FILE
Replace STATEFULSET_FILE
with the updated manifest file.
The kubectl apply
command applies a manifest file to a resource. If thespecified resource does not exist, it is created by the command.
For more information about kubectl apply
, see thekubectl
reference documentation.
Console
To edit the live configuration of a StatefulSet, perform the followingsteps:
Go to the Workloads page in the Google Cloud console.
Go to Workloads
In the workloads list, click the name of the StatefulSet you want to modify.
Click edit Edit.
Change the configuration YAML as desired.
Click Save.
Inspecting update rollout
kubectl
To inspect the rollout of the StatefulSet, run the following command:
kubectl rollout status statefulset STATEFULSET_NAME
To see the StatefulSet's rollout history, run the following command:
kubectl rollout history statefulset STATEFULSET_NAME
To undo a rollout, run the following command:
kubectl rollout undo statefulset STATEFULSET_NAME
Console
To see the revision history of a StatefulSet, perform the following steps:
Go to the Workloads page in the Google Cloud console.
Go to Workloads
In the workloads list, click the name of the StatefulSet you want to inspect.
Click the Revision History tab.
Select the desired revision.
Update strategies
StatefulSet’s updateStrategy
field allows you to configure and disableautomated rolling updates for containers, labels, resource requests, limits, andannotations for the Pods in a StatefulSet.
You can learn more aboutUpdate Strategies for StatefulSets in the Kubernetes documentation.
Scaling a StatefulSet
kubectl
The kubectl scale
command can be used at any time to scale your StatefulSet.
To manually scale a StatefulSet, run the following command:
kubectl scale statefulset STATEFULSET_NAME --replicas NUMBER_OF_REPLICAS
Replace NUMBER_OF_REPLICAS
with the desired number ofreplicated Pods.
Console
To scale a StatefulSet, perform the following steps:
Go to the Workloads page in the Google Cloud console.
Go to Workloads
In the workloads list, click the name of the StatefulSet you want to modify.
Click listActions > Scale > Edit replicas.
Enter the new number of Replicas for the StatefulSet.
Click Scale.
Deleting a StatefulSet
kubectl
To delete a StatefulSet, run the following command:
kubectl delete statefulset STATEFULSET_NAME
Console
To delete a StatefulSet, perform the following steps:
Go to the Workloads page in the Google Cloud console.
Go to Workloads
In the workloads list, select one or more StatefulSets you want to delete.
Click delete Delete.
When prompted to confirm, click Delete.
What's next
- Learn how to deploy a MySQL cluster on GKE for high availability
- Learn about deploying stateless applications.
- Take a tutorial about upgrading a cluster running a stateful workload.