This tutorial shows how to run the Java Bookshelf sample app on Google Kubernetes Engine (GKE). Follow this tutorial to containerize and deploy an existing Java web app to GKE. We recommend that you work through the Bookshelf app documentation as part of the tutorial for the App Engine standard environment.
- Create a GKE cluster.
- Containerize a Java app.
- Create a replicated frontend for the Bookshelf app.
- Create a load-balanced service to route HTTP traffic to the Bookshelf app frontend.
This tutorial uses the following billable components of Google Cloud:
When you finish this tutorial, you can avoid continued billing by deleting the resources you created. For more information, see Cleaning up.
Before you begin
Sign in to your Google Account.
If you don't already have one, sign up for a new account.
In the Cloud Console, on the project selector page, select or create a Cloud project.
Make sure that billing is enabled for your Google Cloud project. Learn how to confirm billing is enabled for your project.
- Enable the Datastore, GKE, Cloud Storage, and Pub/Sub APIs.
- Install and initialize the Cloud SDK.
- Install Docker. Docker builds container images locally.
gcloud components install kubectl
Creating a GKE cluster
A GKE cluster is a managed set of Compute Engine virtual machines (VMs) that operate as a single GKE cluster. This tutorial needs a cluster with a minimum of two nodes, and these nodes need access to all Google APIs.
Create the cluster. Replace
[YOUR_GCP_ZONE]with the Google Cloud zone where you want to host your cluster.
gcloud container clusters create bookshelf \ --scopes "cloud-platform" \ --num-nodes 2 \ --enable-basic-auth \ --issue-client-certificate \ --enable-ip-alias \ --zone [YOUR_GCP_ZONE]
Verify that you have access to the cluster. The following command lists the nodes in your container cluster and indicates that your container cluster is running and that you have access to it.
kubectl get nodes
You use the
kubectl command to create resources in a GKE
cluster. To learn more about
GKE cluster operations.
In general, you use
gcloud to manage resources in your Google Cloud
project, and you use
kubectl to manage resources in your
GKE cluster. A single project can have multiple clusters,
which lets you have clusters made up of different machine types to satisfy
When you create a cluster with
gcloud, authentication is set up automatically
kubectl. If you use the
Google Cloud Console
to create clusters, you can set up authentication by using the
gcloud container clusters get-credentials command.
Cloning the sample app
The sample app is available on GitHub at
Clone the repository:
git clone https://github.com/GoogleCloudPlatform/getting-started-java.git
Go to the sample directory:
Check out the
git checkout 787a8e6345b6585d2e132672f17914b7020be482
The Bookshelf app uses Datastore to store book data. To initialize Datastore in your project for the first time, complete the following steps:
In the Cloud Console, open the Datastore page.
Select a region for your datastore.
Click Continue until you reach the Create an Entity page, and then close the window. The Bookshelf app is ready to create entities in Datastore.
Creating a Cloud Storage bucket
The Bookshelf app uses Cloud Storage to store image files.
The following instructions detail how to create a Cloud Storage bucket. Buckets are the basic containers that hold your data in Cloud Storage.
Cloud Storage cuckets are the basic containers that hold your data in Cloud Storage. Name your bucket the same as your Google Cloud project ID.
Create the bucket:
gsutil mb gs://YOUR_PROJECT_ID
Replace YOUR_PROJECT_ID with your Google Cloud project ID.
To let users see their uploaded images, set the bucket's default access control list (ACL) to
gsutil defacl set public-read gs://YOUR_PROJECT_ID
Containerizing the app
The sample app includes a Dockerfile, which is used to create the app's Docker image. This Docker image runs the app on GKE.
# The Google App Engine python runtime is Debian Jessie with Python installed # and various os-level packages to allow installation of popular Python # libraries. The source is on github at: # https://github.com/GoogleCloudPlatform/python-docker FROM gcr.io/google_appengine/jetty9 # Add application code. ADD target/bookshelf-gke-1.0-SNAPSHOT/ /app
Package the Bookshelf app:
mvn clean -DprojectID=[YOUR_PROJECT_ID] package
Build the app's Docker image:
docker build -t gcr.io/[YOUR_PROJECT_ID]/bookshelf .
Push the image to Container Registry so that your cluster can access the image:
gcloud docker -- push gcr.io/[YOUR_PROJECT_ID]/bookshelf
Deploying the Bookshelf frontendThe Bookshelf app has a set of frontend servers that handles and processes the web requests.
The cluster resources needed to run the frontend are defined in the
bookshelf-frontend.yaml file. These resources are described as a
You can use deployments to create and update a replica set and its associated
# Copyright 2017 Google Inc. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License # This file configures the bookshelf application frontend. The frontend serves # public web traffic. apiVersion: extensions/v1beta1 kind: Deployment metadata: name: bookshelf-frontend labels: app: bookshelf # The bookshelf frontend replica set ensures that at least 3 # instances of the bookshelf app are running on the cluster. # For more info about Pods see: # https://cloud.google.com/kubernetes-engine/docs/pods/ spec: replicas: 3 template: metadata: labels: app: bookshelf tier: frontend spec: containers: - name: bookshelf-app # Replace [GCLOUD_PROJECT] with your project ID. image: gcr.io/[GCLOUD_PROJECT]/bookshelf # This setting makes nodes pull the docker image every time before # starting the pod. This is useful when debugging, but should be turned # off in production. imagePullPolicy: Always # The bookshelf process listens on port 8080 for web traffic by default. ports: - name: http-server containerPort: 8080
[GCLOUD_PROJECT]with your project ID. Save and close the
Deploy the resources to the cluster:
kubectl create -f bookshelf-frontend.yaml
Track the status of the deployment:
kubectl get deployments
After the deployment has the number of available pods that you want, the deployment is complete.
If you run into issues with the deployment, you can delete it and start over:
kubectl delete deployments bookshelf-frontend
After the deployment is complete, you can see the pods that the deployment created:
kubectl get pods
Creating the Bookshelf service
provide a single point of access to a set of pods. While it's possible to access
a single pod, pods are ephemeral, and it's more convenient to address a set of
pods with a single endpoint. In the Bookshelf app, the Bookshelf service lets
you access the Bookshelf frontend pods from a single IP address. This service is
defined in the
# Copyright 2017 Google Inc. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License # The bookshelf service provides a load-balancing proxy over the bookshelf # frontend pods. By specifying the type as a 'LoadBalancer', Kubernetes Engine # will create an external HTTP load balancer. # For more information about Services see: # https://cloud.google.com/kubernetes-engine/docs/services/ # For more information about external HTTP load balancing see: # https://cloud.google.com/kubernetes-engine/docs/load-balancer apiVersion: v1 kind: Service metadata: name: bookshelf-frontend labels: app: bookshelf tier: frontend spec: type: LoadBalancer ports: - port: 80 targetPort: http-server selector: app: bookshelf tier: frontend
Notice that the pods and the service that uses the pods are separate. Kubernetes uses labels to select the pods that a service addresses. By using labels, you can have a service that addresses pods from different replica sets and have multiple services that point to an individual pod.
Create the Bookshelf service:
kubectl create -f bookshelf-service.yaml
Get the service's external IP address:
kubectl describe service bookshelf
It might take up to a minute to allocate the IP address. The external IP address is listed under
Accessing the Bookshelf app
You've now deployed all the resources needed to run the Bookshelf app on GKE. To load the app in your browser and create books, use the external IP address from the previous step.
To avoid incurring charges to your Google Cloud Platform account for the resources used in this tutorial:
Delete the project
The easiest way to eliminate billing is to delete the project that you created for the tutorial.
To delete the project:
- In the Cloud Console, go to the Manage resources page.
- In the project list, select the project you want to delete and click Delete delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Delete the cluster
Deleting the cluster removes all GKE and Compute Engine resources, but you need to manually remove any resources in Cloud Storage, Datastore, and Pub/Sub.
Delete the cluster by using the following command. Replace
[YOUR_GCP_ZONE] with the project and zone you used when
creating the cluster.
gcloud container clusters delete bookshelf --project [YOUR_PROJECT_ID] --zone [YOUR_GCP_ZONE]