Deploying a Stateful Application

This page explains how to deploy a stateful application using Kubernetes Engine.

Before you begin

To prepare for this task, perform the following steps:

  • Ensure that you have installed the Cloud SDK.
  • Set your default project ID:
    gcloud config set project [PROJECT_ID]
  • Set your default compute zone:
    gcloud config set compute/zone [COMPUTE_ZONE]
  • Update all gcloud commands to the latest version:
    gcloud components update
  • Ensure your containerized application is stored in an image registry, such as Container Registry.

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

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 create beforehand. In Kubernetes, dynamic provisioning is configured by creating a StorageClass. In Kubernetes Engine, 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.

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/v1beta2
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

Console

To inspect a StatefulSet, perform the following steps:

  1. Visit the 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.

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 deployment [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]

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 Kubernetes Engine Workloads menu in the GCP Console.

You can rollout updates to StatefulSets' Pods specification such as their image, resource usage/requests, or configuration.

Console

To edit the live configuration of a StatefulSet, perform the following steps:

  1. Visit the 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.

kubectl edit

kubectl edit allows you to edit the StatefulSet directly from your shell or terminal window. It will open the editor defined by your KUBE_EDITOR or EDITOR environment variables, or, if these aren't set, fall back to the vi command-line in Linux or notepad in Windows. The command accepts filenames as well as command line arguments, although the files you point to must be previously saved versions of resources.

Run the following command:

kubectl edit statefulset [STATEFULSET_NAME]

This command causes the defined or default editor to open the StatefulSet's configuration file. Edit the value of the file's replicas field, then save the file.

For more information about kubectl edit, see the kubectl reference documentation .

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.

Inspecting update rollout

Console

To see the revision history of a StatefulSet, perform the following steps:

  1. Visit the 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.

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]

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

Console

To scale a StatefulSet, perform the following steps:

  1. Visit the 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.

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.

Deleting a StatefulSet

Console

To delete a StatefulSet, perform the following steps:

  1. Visit the 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.

kubectl

To delete a StatefulSet, run the following command:

kubectl delete statefulset [STATEFULSET_NAME]

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Kubernetes Engine