Deploying a stateful application

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 on demand, so that the underlying volumes don't need to be manually created beforehand. In Kubernetes, dynamic provisioning is configured by creating a StorageClass. In GKE, a default StorageClass is installed so you can dynamically provision Google 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 in contrast to stateless applications, in which client data is not saved to the server between sessions.

Note: If you are working with multi-zone or regional clusters, refer to Persistent storage in multi-zone 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

Note: You can override these default settings in gcloud commands using the --project, --zone, and --region operational flags.

• Ensure your containerized application is stored in an image registry, such as Container Registry.

If you are new to GKE, you should complete the quickstart, in which you'll enable the GKE API and learn how the product works.

Requesting persistent storage in a StatefulSet

Applications can request persistent storage with a PersistentVolumeClaim object.

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.

Note: kubectl apply fails if you do not have an active cluster.

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:

1. Visit the Google Kubernetes Engine Workloads menu in GCP Console.

   Visit the Workloads menu

2. 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 GCP Console.

You can rollout updates to StatefulSets' Pods specification such as their 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.

Note: To update a resource with kubectl apply, the resource would need to have been created using either kubectl apply or kubectl create --save-config.

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:

1. Visit the Google Kubernetes Engine Workloads menu in GCP Console.

   Visit the Workloads menu

2. Select the desired workload.

3. Click Edit.

4. Use the editor to make the desired changes to the object.

5. Click Save.

Note: While it is possible to specify a different PersistentVolume, it is not possible to update existing PersistentVolumes.

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:

1. Visit the Google Kubernetes Engine Workloads menu in GCP Console.

   Visit the Workloads menu

2. Select the desired workload from the menu.

3. Click Revision history.

4. 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.

To learn about StatefulSet update strategies, refer to Update Strategies 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:

1. Visit the Google Kubernetes Engine Workloads menu in GCP Console.

   Visit the Workloads menu

2. Select the desired workload from the menu.

3. Click Actions, then Scale.

4. From the Replicas field, enter the desired number of replicas.

5. 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:

1. Visit the Google Kubernetes Engine Workloads menu in GCP Console.

   Visit the Workloads menu

2. From the menu, select the desired workload.

3. Click Delete.

4. From the confirmation dialog menu, click Delete.

What's next

• Learn about deploying stateless applications.