This page explains how to deploy a stateful application using Google Kubernetes Engine.
Overview
Stateful applications save data to persistent disk storage for use by the server, by clients, and by other applications. An example of a stateful application is a database or key-value store to which data is saved and retrieved by other applications.
Persistent storage can be dynamically provisioned, so that the underlying volumes are created on demand. In Kubernetes, you configure dynamic provisioning by creating a StorageClass. In GKE, a default StorageClass allows you to dynamically provision Compute Engine persistent disks.
Kubernetes uses the StatefulSet controller to deploy stateful applications as StatefulSet objects. Pods in StatefulSets are not interchangeable: each Pod has a unique identifier that is maintained no matter where it is scheduled.
Stateful applications are different from stateless applications, in which client data is not saved to the server between sessions.
You can learn more about persistent storage in multi-zonal and regional clusters.
Before you begin
To prepare for this task, perform the following steps:
- Ensure that you have enabled the Google Kubernetes Engine API. Enable Google Kubernetes Engine API
- Ensure that you have installed the Cloud SDK.
- Set your default project ID:
gcloud config set project [PROJECT_ID]
- If you are working with zonal clusters, set your default compute zone:
gcloud config set compute/zone [COMPUTE_ZONE]
- If you are working with regional clusters, set your default compute region:
gcloud config set compute/region [COMPUTE_REGION]
- Update
gcloud
to the latest version:gcloud components update
- Ensure your containerized application is stored in an image registry, such as Container Registry.
You can follow the quickstart, to enable the GKE API, create a cluster, and learn more about GKE.
Requesting persistent storage in a StatefulSet
Applications can request persistent storage with a [PersistentVolumeClaim]persistent disk storage.
Normally, PersistentVolumeClaim objects have to be created by the user in
addition to the Pod. However, StatefulSets include a volumeClaimTemplates
array, which automatically generates the PersistentVolumeClaim objects. Each
StatefulSet replica gets its own PersistentVolumeClaim object.
Creating a StatefulSet
You use kubectl apply
to create a StatefulSet.
kubectl apply
uses manifest files to create, update, and delete resources
in your cluster. This is a
declarative method
of object configuration. This method retains writes made to live objects without
merging the changes back into the object configuration files.
The following is a simple example of a StatefulSet governed by a Service that has been created separately:
apiVersion: apps/v1 kind: StatefulSet metadata: name: [STATEFULSET_NAME] spec: 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
where:
- [STATEFULSET_NAME] is the name you choose for the StatefulSet
- [SERVICE_NAME] is the name you choose for the Service
- [APP_NAME] is the name you choose for the application run in the Pods
- [CONTAINER_NAME] is name you choose for the containers in the Pods
- [PORT_NAME] is the name you choose for the port opened by the StatefulSet
- [PVC_NAME] is the name you choose for the PersistentVolumeClaim
In this file, the kind
field specifies that a StatefulSet object should be
created with the specifications defined in the file. This example StatefulSet
produces three replicated Pods, and opens port 80 for exposing the
StatefulSet to the Internet.
To create a StatefulSet, run the following command:
kubectl apply -f [STATEFULSET_FILE]
You can also use kubectl apply -f [DIRECTORY]/
to create
all objects (except existing ones) defined in configuration files stored a
directory.
For more information about kubectl apply
, see the
kubectl
reference documentation.
Inspecting a StatefulSet
kubectl
To inspect the StatefulSet, run the following command:
kubectl get statefulset [STATEFULSET_NAME] -o yaml
This command displays the StatefulSet's live configuration in YAML 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 labelled
for the app [APP_NAME].
The output is similar to the following:
NAME READY STATUS RESTARTS AGE [POD_NAME] 1/1 Running 0 1m [POD_NAME] 1/1 Running 0 1m
To get detailed information about the StatefulSet, run the following command:
kubectl describe statefulset [STATEFULSET_NAME]
where [STATEFULSET_NAME] is the name of the StatefulSet.
To get information about a specific Pod:
kubectl describe pod [POD_NAME]
To list the PersistentVolumeClaims that were created:
kubectl get pvc
The output is similar to the following:
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE [STATEFULSET_NAME]-[PVC_NAME]-0 Bound pvc-bdff4e1e-183e-11e8-bf6d-42010a800002 1G RWO standard 9s [STATEFULSET_NAME]-[PVC_NAME]-1 Bound pvc-bdff4e1e-183e-11e8-bf6d-42010a800003 1G RWO standard 9s [STATEFULSET_NAME]-[PVC_NAME]-2 Bound pvc-bdff4e1e-183e-11e8-bf6d-42010a800004 1G RWO standard 9s
To get information about a specific PersistentVolumeClaim:
kubectl describe pvc [STATEFULSET_NAME]-[PVC_NAME]-0
To get information about a specific PersistentVolume:
kubectl describe pv [PV_NAME]
Console
To inspect a StatefulSet, perform the following steps:
Visit the Google Kubernetes Engine Workloads menu in Cloud Console.
Select the desired workload from the menu.
The Workloads menu offers several menus:
- To see the StatefulSet's live configuration, click YAML.
- To see all events related to the StatefulSet, click Events.
- To see the StatefulSet's revision history, click Revision history.
Updating a StatefulSet
There are multiple ways of updating StatefulSets. The common, declarative method
is kubectl apply
. To update the StatefulSet directly from your shell or in a
preferred editor, you can use kubectl edit
. You can also use the YAML editor
from the GKE Workloads menu in the Cloud Console.
You can roll out updates to a StatefulSet's Pods specification 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 when scaling or for specifying a new version of your application.
To update a StatefulSet, run the following command:
kubectl apply -f [STATEFULSET_FILE]
where [STATEFULSET_FILE] is the updated 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.
For more information about kubectl apply
, see the
kubectl
reference documentation.
Console
To edit the live configuration of a StatefulSet, perform the following steps:
Visit the Google Kubernetes Engine Workloads menu in Cloud Console.
Select the desired workload.
Click Edit.
Use the editor to make the desired changes to the object.
Click Save.
Inspecting update rollout
kubectl
To inspect the StatefulSet's rollout, run the following command:
kubectl rollout status statefulset [STATEFULSET_NAME]
To see the StatefulSet's rollout history:
kubectl rollout history statefulset [STATEFULSET_NAME]
To undo a rollout:
kubectl rollout undo statefulset [STATEFULSET_NAME]
Console
To see the revision history of a StatefulSet, perform the following steps:
Visit the Google Kubernetes Engine Workloads menu in Cloud Console.
Select the desired workload from the menu.
Click Revision history.
Select the desired revision.
Update strategies
StatefulSet’s updateStrategy
field allows you to configure and disable
automated rolling updates for containers, labels, resource request/limits, and
annotations for the Pods in a StatefulSet.
You can learn more about Update Strategies for StatefulSets in the Kubernetes documentation.
Scaling a StatefulSet
kubectl
kubectl scale
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]
where [NUMBER_OF_REPLICAS]
is the desired number of replicated Pods.
Console
To scale a StatefulSet, perform the following steps:
Visit the Google Kubernetes Engine Workloads menu in Cloud Console.
Select the desired workload from the menu.
Click Actions, then Scale.
From the Replicas field, enter the desired number of replicas.
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:
Visit the Google Kubernetes Engine Workloads menu in Cloud Console.
From the menu, select the desired workload.
Click Delete.
From the confirmation dialog menu, click Delete.