Run a Single-Instance Stateful Application

This page shows you how to run a single-instance stateful application in Kubernetes using a PersistentVolume and a Deployment. The application is MySQL.

Objectives

  • Create a PersistentVolume referencing a disk in your environment.
  • Create a MySQL Deployment.
  • Expose MySQL to other pods in the cluster at a known DNS name.

Before you begin

Deploy MySQL

You can run a stateful application by creating a Kubernetes Deployment and connecting it to an existing PersistentVolume using a PersistentVolumeClaim. For example, this YAML file describes a Deployment that runs MySQL and references the PersistentVolumeClaim. The file defines a volume mount for /var/lib/mysql, and then creates a PersistentVolumeClaim that looks for a 20G volume. This claim is satisfied by any existing volume that meets the requirements, or by a dynamic provisioner.

Note: The password is defined in the config yaml, and this is insecure. See Kubernetes Secrets for a secure solution.

application/mysql/mysql-deployment.yaml Run a Single-Instance Stateful Application - 图1

  1. apiVersion: v1
  2. kind: Service
  3. metadata:
  4.   name: mysql
  5. spec:
  6.   ports:
  7.   - port: 3306
  8.   selector:
  9.     app: mysql
  10.   clusterIP: None
  11. ---
  12. apiVersion: apps/v1 # for versions before 1.9.0 use apps/v1beta2
  13. kind: Deployment
  14. metadata:
  15.   name: mysql
  16. spec:
  17.   selector:
  18.     matchLabels:
  19.       app: mysql
  20.   strategy:
  21.     type: Recreate
  22.   template:
  23.     metadata:
  24.       labels:
  25.         app: mysql
  26.     spec:
  27.       containers:
  28.       - image: mysql:5.6
  29.         name: mysql
  30.         env:
  31.           # Use secret in real usage
  32.         - name: MYSQL_ROOT_PASSWORD
  33.           value: password
  34.         ports:
  35.         - containerPort: 3306
  36.           name: mysql
  37.         volumeMounts:
  38.         - name: mysql-persistent-storage
  39.           mountPath: /var/lib/mysql
  40.       volumes:
  41.       - name: mysql-persistent-storage
  42.         persistentVolumeClaim:
  43.           claimName: mysql-pv-claim

application/mysql/mysql-pv.yaml Run a Single-Instance Stateful Application - 图2

  1. apiVersion: v1
  2. kind: PersistentVolume
  3. metadata:
  4.   name: mysql-pv-volume
  5.   labels:
  6.     type: local
  7. spec:
  8.   storageClassName: manual
  9.   capacity:
  10.     storage: 20Gi
  11.   accessModes:
  12.     - ReadWriteOnce
  13.   hostPath:
  14.     path: "/mnt/data"
  15. ---
  16. apiVersion: v1
  17. kind: PersistentVolumeClaim
  18. metadata:
  19.   name: mysql-pv-claim
  20. spec:
  21.   storageClassName: manual
  22.   accessModes:
  23.     - ReadWriteOnce
  24.   resources:
  25.     requests:
  26.       storage: 20Gi

  1. Deploy the PV and PVC of the YAML file:

    1.  kubectl apply -f https://k8s.io/examples/application/mysql/mysql-pv.yaml

  2. Deploy the contents of the YAML file:

    1.  kubectl apply -f https://k8s.io/examples/application/mysql/mysql-deployment.yaml

  3. Display information about the Deployment:

    1.  kubectl describe deployment mysql
    3.  Name:                 mysql
    4.  Namespace:            default
    5.  CreationTimestamp:    Tue, 01 Nov 2016 11:18:45 -0700
    6.  Labels:               app=mysql
    7.  Annotations:          deployment.kubernetes.io/revision=1
    8.  Selector:             app=mysql
    9.  Replicas:             1 desired | 1 updated | 1 total | 0 available | 1 unavailable
    10.  StrategyType:         Recreate
    11.  MinReadySeconds:      0
    12.  Pod Template:
    13.    Labels:       app=mysql
    14.    Containers:
    15.     mysql:
    16.      Image:      mysql:5.6
    17.      Port:       3306/TCP
    18.      Environment:
    19.        MYSQL_ROOT_PASSWORD:      password
    20.      Mounts:
    21.        /var/lib/mysql from mysql-persistent-storage (rw)
    22.    Volumes:
    23.     mysql-persistent-storage:
    24.      Type:       PersistentVolumeClaim (a reference to a PersistentVolumeClaim in the same namespace)
    25.      ClaimName:  mysql-pv-claim
    26.      ReadOnly:   false
    27.  Conditions:
    28.    Type          Status  Reason
    29.    ----          ------  ------
    30.    Available     False   MinimumReplicasUnavailable
    31.    Progressing   True    ReplicaSetUpdated
    32.  OldReplicaSets:       <none>
    33.  NewReplicaSet:        mysql-63082529 (1/1 replicas created)
    34.  Events:
    35.    FirstSeen    LastSeen    Count    From                SubobjectPath    Type        Reason            Message
    36.    ---------    --------    -----    ----                -------------    --------    ------            -------
    37.    33s          33s         1        {deployment-controller }             Normal      ScalingReplicaSet Scaled up replica set mysql-63082529 to 1

  4. List the pods created by the Deployment:

    1.  kubectl get pods -l app=mysql
    3.  NAME                   READY     STATUS    RESTARTS   AGE
    4.  mysql-63082529-2z3ki   1/1       Running   0          3m

  5. Inspect the PersistentVolumeClaim:

    1.  kubectl describe pvc mysql-pv-claim
    3.  Name:         mysql-pv-claim
    4.  Namespace:    default
    5.  StorageClass:
    6.  Status:       Bound
    7.  Volume:       mysql-pv-volume
    8.  Labels:       <none>
    9.  Annotations:    pv.kubernetes.io/bind-completed=yes
    10.                  pv.kubernetes.io/bound-by-controller=yes
    11.  Capacity:     20Gi
    12.  Access Modes: RWO
    13.  Events:       <none>

Accessing the MySQL instance

The preceding YAML file creates a service that allows other Pods in the cluster to access the database. The Service option clusterIP: None lets the Service DNS name resolve directly to the Pod’s IP address. This is optimal when you have only one Pod behind a Service and you don’t intend to increase the number of Pods.

Run a MySQL client to connect to the server:

  1. kubectl run -it --rm --image=mysql:5.6 --restart=Never mysql-client -- mysql -h mysql -ppassword

This command creates a new Pod in the cluster running a MySQL client and connects it to the server through the Service. If it connects, you know your stateful MySQL database is up and running.

  1. Waiting for pod default/mysql-client-274442439-zyp6i to be running, status is Pending, pod ready: false
  2. If you don't see a command prompt, try pressing enter.
  4. mysql>

Updating

The image or any other part of the Deployment can be updated as usual with the kubectl apply command. Here are some precautions that are specific to stateful apps:

  • Don’t scale the app. This setup is for single-instance apps only. The underlying PersistentVolume can only be mounted to one Pod. For clustered stateful apps, see the StatefulSet documentation.
  • Use strategy: type: Recreate in the Deployment configuration YAML file. This instructs Kubernetes to not use rolling updates. Rolling updates will not work, as you cannot have more than one Pod running at a time. The Recreate strategy will stop the first pod before creating a new one with the updated configuration.

Deleting a deployment

Delete the deployed objects by name:

  1. kubectl delete deployment,svc mysql
  2. kubectl delete pvc mysql-pv-claim
  3. kubectl delete pv mysql-pv-volume

If you manually provisioned a PersistentVolume, you also need to manually delete it, as well as release the underlying resource. If you used a dynamic provisioner, it automatically deletes the PersistentVolume when it sees that you deleted the PersistentVolumeClaim. Some dynamic provisioners (such as those for EBS and PD) also release the underlying resource upon deleting the PersistentVolume.

What’s next