Deploying a containerized web application

Create a repository

In this tutorial, you store an image in Artifact Registry and deploy it from the registry. For this quickstart, you'll create a repository named hello-repo.

1. Set the PROJECT_ID environment variable to your Google Cloud project ID (PROJECT_ID). You'll use this environment variable when you build the container image and push it to your repository.

   export PROJECT_ID=PROJECT_ID
   

2. Confirm that the PROJECT_ID environment variable has the correct value:

   echo $PROJECT_ID
   

3. Set your project ID for the Google Cloud CLI:

   gcloud config set project $PROJECT_ID
   

   Output:

   Updated property [core/project].
   

4. Create the hello-repo repository with the following command:

   gcloud artifacts repositories create hello-repo \
      --repository-format=docker \
      --location=REGION \
      --description="Docker repository"
   

   Replace REGION with the a region for the repository, such as us-west1. To see a list of available locations, run the command:

    gcloud artifacts locations list
   

Building the container image

In this tutorial, you deploy a sample web application called hello-app, a web server written in Go that responds to all requests with the message Hello, World! on port 8080.

GKE accepts Docker images as the application deployment format. Before deploying hello-app to GKE, you must package the hello-app source code as a Docker image.

To build a Docker image, you need source code and a Dockerfile. A Dockerfile contains instructions on how the image is built.

1. Download the hello-app source code and Dockerfile by running the following commands:

   git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples
   cd kubernetes-engine-samples/quickstarts/hello-app
   

2. Build and tag the Docker image for hello-app:

   docker build -t REGION-docker.pkg.dev/${PROJECT_ID}/hello-repo/hello-app:v1 .
   

   This command instructs Docker to build the image using the Dockerfile in the current directory, save it to your local environment, and tag it with a name, such as us-west1-docker.pkg.dev/my-project/hello-repo/hello-app:v1. The image is pushed to Artifact Registry in the next section.

   • The PROJECT_ID variable associates the container image with the hello-repo repository in your Google Cloud project.
   • The us-west1-docker.pkg.dev prefix refers to Artifact Registry, regional host for your repository.

3. Run the docker images command to verify that the build was successful:

   docker images
   

   Output:

   REPOSITORY                                                 TAG     IMAGE ID       CREATED          SIZE
   us-west1-docker.pkg.dev/my-project/hello-repo/hello-app    v1      25cfadb1bf28   10 seconds ago   54 MB
   

4. Add IAM policy bindings to your service account:

   gcloud artifacts repositories add-iam-policy-binding hello-repo \
       --location=REGION \
       --member=serviceAccount:PROJECT_NUMBER[email protected] \
       --role="roles/artifactregistry.reader"
   

   Replace PROJECT_NUMBER with the project number of your project.

Running your container locally (optional)

1. Test your container image using your local Docker engine:

   docker run --rm -p 8080:8080 REGION-docker.pkg.dev/${PROJECT_ID}/hello-repo/hello-app:v1
   

2. Click the Web Preview button and then select the 8080 port number. GKE opens the preview URL on its proxy service in a new browser window.

Pushing the Docker image to Artifact Registry

You must upload the container image to a registry so that your GKE cluster can download and run the container image. In this tutorial, you will store your container in Artifact Registry.

1. Configure the Docker command-line tool to authenticate to Artifact Registry:

   gcloud auth configure-docker REGION-docker.pkg.dev
   

2. Push the Docker image that you just built to the repository:

   docker push REGION-docker.pkg.dev/${PROJECT_ID}/hello-repo/hello-app:v1
   

Creating a GKE cluster

Now that the Docker image is stored in Artifact Registry, create a GKE cluster to run hello-app. A GKE cluster consists of a pool of Compute Engine VM instances running Kubernetes, the open source cluster orchestration system that powers GKE.

Deploying the sample app to GKE

You are now ready to deploy the Docker image you built to your GKE cluster.

Kubernetes represents applications as Pods, which are scalable units holding one or more containers. The Pod is the smallest deployable unit in Kubernetes. Usually, you deploy Pods as a set of replicas that can be scaled and distributed together across your cluster. One way to deploy a set of replicas is through a Kubernetes Deployment.

In this section, you create a Kubernetes Deployment to run hello-app on your cluster. This Deployment has replicas (Pods). One Deployment Pod contains only one container: the hello-app Docker image. You also create a HorizontalPodAutoscaler resource that scales the number of Pods from 3 to a number between 1 and 5, based on CPU load.

Exposing the sample app to the internet

While Pods do have individually-assigned IP addresses, those IPs can only be reached from inside your cluster. Also, GKE Pods are designed to be ephemeral, starting or stopping based on scaling needs. And when a Pod crashes due to an error, GKE automatically redeploys that Pod, assigning a new Pod IP address each time.

What this means is that for any Deployment, the set of IP addresses corresponding to the active set of Pods is dynamic. We need a way to 1) group Pods together into one static hostname, and 2) expose a group of Pods outside the cluster, to the internet.

Kubernetes Services solve for both of these problems. Services group Pods into one static IP address, reachable from any Pod inside the cluster. GKE also assigns a DNS hostname to that static IP. For example, hello-app.default.svc.cluster.local.

The default Service type in GKE is called ClusterIP, where the Service gets an IP address reachable only from inside the cluster. To expose a Kubernetes Service outside the cluster, create a Service of type LoadBalancer. This type of Service spawns an External Load Balancer IP for a set of Pods, reachable through the internet.

In this section, you expose the hello-app Deployment to the internet using a Service of type LoadBalancer.

Now that the hello-app Pods are exposed to the internet through a Kubernetes Service, you can open a new browser tab, and navigate to the Service IP address you copied to the clipboard. A Hello, World! message appears, along with a Hostname field. The Hostname corresponds to one of the three hello-app Pods serving your HTTP request to your browser.

Deploying a new version of the sample app

In this section, you upgrade hello-app to a new version by building and deploying a new Docker image to your GKE cluster.

Kubernetes rolling update lets you update your Deployments without downtime. During a rolling update, your GKE cluster incrementally replaces the existing hello-app Pods with Pods containing the Docker image for the new version. During the update, your load balancer service routes traffic only into available Pods.

1. Return to Cloud Shell, where you have cloned the hello app source code and Dockerfile. Update the function hello() in the main.go file to report the new version 2.0.0.

2. Build and tag a new hello-app Docker image.

   docker build -t REGION-docker.pkg.dev/${PROJECT_ID}/hello-repo/hello-app:v2 .
   

3. Push the image to Artifact Registry.

   docker push REGION-docker.pkg.dev/${PROJECT_ID}/hello-repo/hello-app:v2
   

Now you're ready to update your hello-app Kubernetes Deployment to use a new Docker image.