Example of basic operations#

Your Kubernetes cluster supports basic Kubernetes resources, such as Deployments and Services. This section provides an example of basic operations with an nginx Kubernetes Deployment with LoadBalancer Service.

For more information about the Kubernetes objects, see the Kubernetes documentation.

Launch a new Deployment#

Create a Deployment called nginx using the official nginx image with five replicas.

  1. Create a Deployment:

    $ kubectl run nginx --image nginx --replicas 5
      deployment "nginx" created
    
  2. Verify by displaying the list of Pods:

    $ kubectl get pods
      NAME                     READY     STATUS    RESTARTS   AGE
      nginx-2371676037-9ktzl   1/1       Running   0          27s
      nginx-2371676037-kdm13   1/1       Running   0          27s
      nginx-2371676037-l2x0c   1/1       Running   0          27s
      nginx-2371676037-tl21g   1/1       Running   0          27s
      nginx-2371676037-vwpr0   1/1       Running   0          27s
    
    $ kubectl get deployments nginx
    $ kubectl describe deployments nginx
    

Expose your Deployment with a LoadBalancer#

Expose the nginx Deployment using a Kubernetes LoadBalancer Service.

  1. Create a LoadBalancer Service object:

    $ kubectl expose deployment/nginx --port=80 --type=LoadBalancer
      service "nginx" exposed
    

    Kubernetes creates a load balancer that directs all traffic on port 80 to one of the five nginx replicas.

  2. Verify that the Service is created:

    $ kubectl get service nginx
      NAME         CLUSTER-IP    EXTERNAL-IP   PORT(S)        AGE
      nginx        10.3.108.11   148.62.x.x    80:32350/TCP   49s
    

Access your Deployment#

Use the EXTERNAL-IP from the nginx Service above in a web browser or use curl for the EXTERNAL-IP and port:

$ curl http://<external-ip>:<port>

Add persistent storage to your Deployment#

Rackspace KaaS enables you to add persistent storage to your Pods to run stateful applications. You can add a PersistentVolume by using a StorageClass and mounting the volume to storage server, or by creating a hostPath PersistentVolume and mounting it to your Kubernetes master node storage. Although the latter is supported, we do not recommend that you create hostPath PersistentVolumes because Kubernetes cannot remount the data volume and recover from node failures which might trigger applications outages. However, if you use distributed, replicated, or ephemeral systems, such as Kafka or Redis, you might be able to use host local storage because the data is replicated by within these systems and does not require Kubernetes to remount or recover the failed nodes. In other cases, use the default StorageClass for the OpenStack Block Storage service (cinder) that is backed by Ceph.

To add a persistent volume to a Pod, you need to create a PersistentVolumeClaim (PVC). Because your Kubernetes cluster already has a default StorageClass, you do not need to specify it in the PersistentVolumeClaim. The default StorageClass is already used by default.

Rackspace KaaS supports the following access modes to persistent volumes:

  • ReadWriteOnce (RWO): You can mount a volume with read and write access to a single node.
  • ReadOnlyMany (ROM): You can mount a volume with read only permissions to many nodes.

Note

Automated volume expansion using the allowVolumeExpansion parameter and PersistentVolumeClaimResize are not supported.

To add persistent storage to your cluster, complete the following steps:

  1. Create a configuration file for the PVC:

    kind: PersistentVolumeClaim
    apiVersion: v1
    metadata:
      name: pvc-test
    spec:
      accessModes:
        - ReadWriteOnce
      resources:
        requests:
          storage: 32Gi
    

    Note

    You cannot specify a volumeName in the PVC. Rackspace KaaS assigns a name to the PersistentVolume (PV).

  2. Create the PersistentVolumeClaim:

    kubectl create -f deployments/stable/storage/pvc-test1.yaml
    
  3. Verify that the claim was created by displaying the list of PVCs in the cluster:

    kubectl get pvc
    

    Example of system response:

    NAME        STATUS    VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
    pvc-test    Bound     pvc-02a20856-6f39-11e8-b07f-fa163e9c3664   32Gi       RWO            openstack      3
    

    The status must be Bound. If you see the status set to Pending, your configuration file might be incorrect.

  4. Create a Deployment configuration file for your stateful application or open an existing Pod file for editing:

    Example:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: mysql
    spec:
      selector:
        matchLabels:
          app: mysql
      strategy:
        type: Recreate
      template:
        metadata:
          labels:
            app: mysql
        spec:
          containers:
          - image: mysql:5.6
            name: mysql
            env:
              # Use secret in real usage
            - name: MYSQL_ROOT_PASSWORD
              value: password
            ports:
            - containerPort: 3306
              name: mysql
            volumeMounts:
            - name: mysql-persistent-storage
              mountPath: /var/lib/mysql
          volumes:
          - name: mysql-persistent-storage
            persistentVolumeClaim:
              claimName: pvc-test
    
  5. Verify that claimName is set to the claim that you created in previous steps.

  6. Create the Pod or apply the changes to the existing Pod by running one of the following commands:

    kubectl apply -f deployments/mysql-test.yaml
    

    System response:

    deployment "mysql" created
    
  7. Verify that the mysql Pod was created:

    kubectl get pods
    

    Example of system response:

    NAME                     READY     STATUS              RESTARTS   AGE
    mysql-5f7dcd7b68-2rfx2   1/1       Running             0          1m
    
  8. Verify that the Deployment uses the created persistent volume:

    kubectl describe pod mysql-5f7dcd7b68-m97s9
    

    Example of system response:

    Name:           mysql-5f7dcd7b68-m97s9
    Namespace:      default
    Node:           kubernetes-test-worker-1/10.0.0.13
    Start Time:     Wed, 13 Jun 2018 13:59:18 -0700
    Labels:         app=mysql
                 pod-template-hash=1938783624
    Annotations:    <none>
    Status:         Running
    IP:             10.2.0.44
    Controlled By:  ReplicaSet/mysql-5f7dcd7b68
    Containers:
    mysql:
     Container ID:   docker://4e22406c32cb2004ec32ffef1f2ca82630d4028027a21324460317afb440f857
     Image:          mysql:5.6
     Image ID:       docker-pullable://mysql@sha256:7e3575b7949a4f8712a47b0fc875022dcea5d84f4672b1532587b6933502f757
     Port:           3306/TCP
     State:          Running
       Started:      Wed, 13 Jun 2018 13:59:33 -0700
     Ready:          True
     Restart Count:  0
     Environment:
       MYSQL_ROOT_PASSWORD:  password
     Mounts:
       /var/lib/mysql from mysql-persistent-storage (rw)
       /var/run/secrets/kubernetes.io/serviceaccount from default-token-szjzp (ro)
    Conditions:
    Type           Status
    Initialized    True
    Ready          True
    PodScheduled   True
    Volumes:
    mysql-persistent-storage:
     Type:       PersistentVolumeClaim (a reference to a PersistentVolumeClaim in the same namespace)
     ClaimName:  pvc-test1
     ReadOnly:   false
    default-token-szjzp:
     Type:        Secret (a volume populated by a Secret)
     SecretName:  default-token-szjzp
     Optional:    false
    
     ...
    

Using local storage#

While Kubernetes supports adding a persistent volume that uses storage space from a Kubernetes node, we do not recommend to that you use such volumes in production environments. Instead create a PersistentVolumeClaim by using the default StorageClass as described in Add persistent storage to your Deployment. If you still decide to use storage on a Kubernetes worker node by creating a hostPath volume, you must verify that the node has sufficient disk space. You will not be able to resize this volume.

To verify storage space that is used by a Pod on a Kubernetes node, run the following commands:

  1. Get the location of the storage by obtaining the information about the Pod mountpoint:

    kubectl describe pod <pod-name>
    

    Example of system response:

    ...
    
    Mounts:
      /usr/share/nginx/html from pv-volume (rw)
    
    ...
    
  2. Get the information about available disk space:

    kubectl exec -it <pod-name> -- /bin/bash -c 'df /usr/share/nginx/html'
    

    Example of system response:

    Filesystem     1K-blocks    Used Available Use% Mounted on
    /dev/vda9       99171716 9720480  85276368  11% /usr/share/nginx/html
    
  3. Create a hostPath persistent volume as described in the Kubernetes documentation.

Scale replicas for your Deployment#

You can scale your nginx Deployment by increasing the number of replicas in the Deployment. To do that, run the following commands:

  1. Increase the number of replicas:

    $ kubectl scale deployment/nginx --replicas=10
      deployment "nginx" scaled
    
  2. View the status of the Deployment update:

    $ kubectl rollout status deployment/nginx
    

    System response:

    deployment "nginx" successfully rolled out
    
  3. Verify by displaying the list of Pods:

    $ kubectl get pods
      NAME                     READY     STATUS    RESTARTS   AGE
      nginx-2371676037-9ktzl   1/1       Running   0          11m
      nginx-2371676037-k22cm   1/1       Running   0          2m
      nginx-2371676037-kdm13   1/1       Running   0          11m
      nginx-2371676037-l2x0c   1/1       Running   0          11m
      nginx-2371676037-qzqh9   1/1       Running   0          2m
      nginx-2371676037-tl21g   1/1       Running   0          11m
      nginx-2371676037-tvkgz   1/1       Running   0          2m
      nginx-2371676037-vwpr0   1/1       Running   0          11m
      nginx-2371676037-ww7f7   1/1       Running   0          2m
      nginx-2371676037-xjkq9   1/1       Running   0          2m
    

Clean up the Deployment#

When you finish the nginx example, you can delete the Deployment and Service objects by running the following commands:

$ kubectl delete service nginx
$ kubectl delete deployment nginx