Deploying a Stateless Application

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

Overview

Stateless applications are applications which do not store data or application state to the cluster or to persistent storage. Instead, data and application state stay with the client, which makes stateless applications more scalable. For example, a frontend application is stateless: you deploy multiple replicas to increase its availability and scale down when demand is low, and the replicas have no need for unique identities.

Kubernetes uses the Deployment controller to deploy stateless applications as uniform, non-unique Pods. Deployments manage the desired state of your application: how many Pods should run your application, what version of the container image should run, what the Pods should be labelled, and so on. The desired state can be changed dynamically through updates to the Deployment's Pod specification.

Stateless applications are in contrast to stateful applications, which use persistent storage to save data and which use StatefulSets to deploy Pods with unique identities.

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.

Anatomy of a Deployment

The following is an example of a simple Deployment manifest file. This Deployment creates three replicated Pods labelled app: my-app that run the hello-app image stored in Container Registry:

apiVersion: apps/v1beta2
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: hello-app
        image: gcr.io/google-samples/hello-app:1.0
        ports:
        - containerPort: 80

where:

  • kind: specifies that a Deployment is created with the defined specifications
  • metadata: name: is the name of the Deployment
  • spec: replicas: is the number of replicated Pods that the Deployment manages
  • spec: template: metadata: labels: is the label given to each Pod, which the Deployment uses to manage the Pods
  • spec: template: spec: is the Pod specification, which defines how each Pod should run. spec: containers includes the name of the container to run in each Pod, the container image that should run, and which port should be exposed from the container

For more information about the Deployment specification, refer to the Deployment API reference.

Creating a Deployment

You create a Deployment using one of the following methods:

  • You can use the Deploy feature in Google Cloud Platform Console's Workloads dashboard to create a simple Deployment from a container image you've stored in Container Registry
  • You can create a Deployment from the command-line using kubectl run
  • You can write a Deployment manifest and run kubectl apply to create the resource

Console

To create a Deployment, perform the following steps:

  1. Visit the Kubernetes Engine Workloads dashboard in GCP Console.

    Visit the Workloads dashboard

  2. Click Deploy.

  3. Fill Container Image with the container image and its version (such as nginx:latest), or click Select existing Google Container Registry image and choose the image.
  4. Configure the container as desired: add environmental variables, initial commands, application name, namespace, and labels.
  5. From the Cluster drop-down menu, choose the desired cluster.
  6. Click Deploy.

kubectl run

You can imperatively create a Deployment from the command-line using kubectl run.

The following command creates a Deployment using a container image you specify. This example Deployment produces three replicated Pods that run the container, and exposes port 80 from the container:

kubectl run [DEPLOYMENT_NAME] --image [IMAGE]:[TAG] --replicas 3 \
--labels [KEY]:[VALUE] --port 80 --generator deployment/apps.v1beta1 \
--save-config

where:

  • [DEPLOYMENT_NAME] is the name you choose for the Deployment
  • [IMAGE] is the image to run in the container
  • [TAG] is the version of the image to run (default is latest for the latest version)
  • [KEY]:[VALUE] is the label you choose for the Pods, such as app: my-app

--generator specifies the API generator to use.

--save-config causes the configuration of the Deployment to be saved in its annotation, which allows it to be updated in the future by kubectl apply. Alternatively, you can use kubectl apply to create the Deployment, then use kubectl apply to update the Deployment in the future.

kubectl apply

You can declaratively create and update Deployments from manifest files using kubectl apply. This method also retains updates made to live resources without merging the changes back into the manifest files.

To create a Deployment from its manifest file, run the following command:

kubectl apply -f [DEPLOYMENT_FILE]

where [DEPLOYMENT_FILE] is the manifest file, such as config.yaml.

You can also use kubectl apply -f [DIRECTORY]/ to create all objects (except existing ones) defined in manifest files stored a directory.

Inspecting the Deployment

After you create a Deployment, you can use one of the following methods to inspect it:

Console

To inspect a Deployment, perform the following steps:

  1. Visit the Kubernetes Engine Workloads dashboard in GCP Console.

    Visit the Workloads dashboard

  2. To get more information about a workload, select the desired workload from the menu.

The Workloads dashboard offers several menus:

  • To see the Deployment's live configuration, click YAML.
  • To see all events related to the Deployment, click Events.
  • To see the Deployment's revision history, click Revision history.

kubectl

To get detailed information about the Deployment, run the following command:

kubectl describe deployment [DEPLOYMENT_NAME]

where [DEPLOYMENT_NAME] is the name of the Deployment.

To list the Pods created by the Deployment, run the following command:

kubectl get pods -l [KEY]=[VALUE]

In this command, the -l flag instructs kubectl to get all Pods with a key-value label. For example, if you labelled the Deployment app: my-app, you'd run kubectl get pods -l app=my-app to see Pods with that label.

To get information about a specific Pod:

kubectl describe pod [POD_NAME]

To view a Deployment's manifest, run the following command:

kubectl get deployments [DEPLOYMENT_NAME] -o yaml

This command displays the Deployment's live configuration in YAML format.

Updating the Deployment

You can roll out updates to a Deployment's Pod specification, such as their image, resource usage/requests, or configuration.

You can update a Deployment using the following methods:

  • You can use the Rolling update menu and YAML editor from the GCP Console Workloads dashboard
  • You can make changes to a manifest file and apply them with kubectl apply
  • You can update the Pod specification's image, resources, or selector fields using kubectl set
  • You can update a Deployment directly from your shell or in a preferred editor using kubectl edit

Console

The Rolling update menu, available in the Workloads dashboard,

To access the Deployment's Rolling update menu, perform the following steps:

  1. Visit the Kubernetes Engine Workloads dashboard in GCP Console.

    Visit the Workloads dashboard

  2. Select the desired workload from the menu.

  3. Click Actions, then Rolling update.

You can make the following changes to the Deployment's update strategy:

  • Minimum seconds ready: Specifies the minimum number of seconds for which newly-created Pods should be ready for it to be considered available.
  • Maximum surge: Optional field which specifies the maximum number of Pods that can be created over the desired number of Pods. Value can be an absolute number or a percentage.
  • Maximum unavailable: Optional field which specifies the maximum number of Pods that can be unavailable during the update process. Value can be an absolute number or a percentage.

To edit an existing container:

  1. From the Rolling update menu, select the container to expand its menu.
  2. To change the container name, edit the Container name field.
  3. To change the container image or version, edit the Image name field.
  4. Click Done to save the changes.
  5. To delete the container, click the Trash icon.

To add a new container:

  1. From the Rolling update menu, click Add container.
  2. Fill the Image name field with the image and version, using the following format: [IMAGE_NAME]:[IMAGE_VERSION]. For example, nginx:1.7.9.
  3. Optionally, fill the Container name field with a name for the container.
  4. Click Done.
  5. Click Update.

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

  1. Visit the Kubernetes Engine Workloads dashboard in GCP Console.

    Visit the Workloads dashboard

  2. Select the desired workload.

  3. Click Edit.
  4. Use the editor to make the desired changes to the object.
  5. Click Save.

kubectl apply

You can update the Deployment by applying a new or updated manifest file. This is useful for making various changes to your Deployment, such as for scaling or for specifying a new version of your application.

To update a Deployment, run the following command:

kubectl apply -f [DEPLOYMENT_FILE]

where [DEPLOYMENT_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.

kubectl set

You can use kubectl set to change a Deployment's image, resources (requests or limits), or selector fields.

To change a Deployment's image, run the following command:

kubectl set image deployment [DEPLOYMENT_NAME] [IMAGE] [IMAGE]:[TAG]

For example, to update a Deployment from nginx version 1.7.9 to 1.9.1, run the following command:

kubectl set image deployment nginx nginx=nginx:1.9.1

kubectl edit

kubectl edit allows you to edit the Deployment 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 deployment [DEPLOYMENT_NAME]

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

To see its rollout status, run the following command:

kubectl rollout status deployment [DEPLOYMENT_NAME]

Rolling back an update

You can roll back an update using kubectl rollout undo.

You can roll back an in-progress or completed update to its previous revision:

kubectl rollout undo deployment my-deployment

You can also roll back to a specific revision:

kubectl rollout undo deployment my-deployment --to-revision=3

Scaling a Deployment

You can manually scale a Deployment using GCP Console or kubectl scale.

To learn how to autoscale deployments, refer to Autoscaling Deployments.

Console

To scale a Deployment, perform the following steps:

  1. Visit the Kubernetes Engine Workloads dashboard in GCP Console.

    Visit the Workloads dashboard

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

To manually scale a Deployment, run the following command:

kubectl scale deployment [DEPLOYMENT_NAME] --replicas [NUMBER_OF_REPLICAS]

where [NUMBER_OF_REPLICAS] is the desired number of replicated Pods.

Deleting a Deployment

You can delete a Deployment using GCP Console or kubectl delete.

Console

To delete a Deployment, perform the following steps:

  1. Visit the Kubernetes Engine Workloads dashboard in GCP Console.

    Visit the Workloads dashboard

  2. From the menu, select the desired workload.

  3. Click Delete.
  4. From the confirmation dialog menu, click Delete.

kubectl

To delete a Deployment, run the following command:

kubectl delete deployment [DEPLOYMENT_NAME]

What's next

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

Send feedback about...

Kubernetes Engine