This tutorial shows how to run the Java Bookshelf Application on Kubernetes Engine. Follow this tutorial to containerize and deploy an existing Java web application to Kubernetes Engine. It is highly recommended that you work through the Bookshelf app documentation as part of the tutorial for the App Engine flexible environment.
- Create a Kubernetes Engine cluster.
- Containerize a Java application.
- Create a replicated frontend for the Bookshelf application.
- Create a load-balanced service to route HTTP traffic to the Bookshelf frontend.
This tutorial uses billable components of Cloud Platform, including:
- Kubernetes Engine
- Compute Engine
- Cloud Storage
- Cloud Datastore
- Cloud Pub/Sub
Before you begin
Sign in to your Google Account.
If you don't already have one, sign up for a new account.
Select or create a GCP project.
Make sure that billing is enabled for your project.
- Enable the Cloud Datastore, Cloud Storage, Cloud Pub/Sub, and Google+ APIs.
- Install and initialize the Cloud SDK.
- Install Docker. Docker is used to build container images locally.
gcloud components install kubectl
Creating a Kubernetes Engine cluster
A Kubernetes Engine cluster is a managed set of Compute Engine virtual machines
that operate as a single Kubernetes cluster. This tutorial needs a cluster with
a minimum of two nodes, and these nodes need access to all Google APIs.
[YOUR_GCP_ZONE] with the
Cloud Platform zone where you want
your cluster to be hosted.
Create the 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:
kubectl get nodes
Running this command lists the nodes in your container cluster and indicates that your container cluster is up and running and you have access to it.
You use the
kubectl command to create resources in a Kubernetes
Engine Cluster. To learn more about
Kubernetes Engine Cluster Operations.
In general, you use
gcloud to manage resources in your GCP project
and you use
kubectl to manage resources within your Kubernetes Engine cluster.
A single project can have multiple clusters, which makes it easy to have
clusters that are made up of different machine types to satisfy different needs.
When you create a cluster with
gcloud, it automatically sets up
kubectl. Clusters created by using the
Cloud Console can set up authentication using the
gcloud container clusters get-credentials command.
Cloning the sample application
The sample application is available on GitHub at GoogleCloudPlatform/getting-started-java.
Clone the repository:
git clone https://github.com/GoogleCloudPlatform/getting-started-java.git
Navigate to the sample directory:
The Bookshelf application uses Cloud Datastore to store the books. To initialize Datastore in your project for the first time:
Open the Datastore on GCP Console.
Select a region for your datastore and click Continue. When you reach the “Create an Entity” page, close the window as the Bookshelf application is ready to create entities on Datastore.
Creating a Cloud Storage bucket
The Bookshelf application uses Google Cloud Storage to store image files.
The following instructions show how to create a Cloud Storage bucket. Buckets are the basic containers that hold your data in Cloud Storage.
Name your bucket the same as your project ID.
To create a bucket:
Invoke the following command:
gsutil mb gs://[YOUR-PROJECT-ID]
[YOUR-PROJECT-ID]with your project ID.
Set the bucket's default ACL to
public-readto enable users to see their uploaded images:
gsutil defacl set public-read gs://[YOUR-PROJECT-ID]
[YOUR-PROJECT-ID]with your project ID.
Containerizing the application
The sample application includes a Dockerfile, which is used create the application's Docker image. This Docker image runs the application on Kubernetes Engine.
# 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
mvn clean -DprojectID=[YOUR_PROJECT_ID] package
Build the application's Docker image:
docker build -t gcr.io/[YOUR_PROJECT_ID]/bookshelf .
Push the image to Google Container Registry so that your cluster can access the image:
gcloud docker -- push gcr.io/[YOUR_PROJECT_ID]/bookshelf
Deploying the Bookshelf front endThe Bookshelf application is comprised of a set of frontend servers that handles and processes the web requests.
The cluster resources needed to run the frontend are defined in
bookshelf-frontend.yaml. These resources are described as a
Deployments make it easy 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.
kubectlto deploy the resources to the cluster:
kubectl create -f bookshelf-frontend.yaml
Track the status of the deployment:
kubectl get deployments
Once the deployment has the same number of available pods as desired pods, the deployment is complete. If you run into issues with the deployment, you can delete it and start over:
kubectl delete deployments bookshelf-frontend
Once 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 usually more convenient to
address a set of pods with a single endpoint. In the Bookshelf application,
The Bookshelf service allows you to access the Bookshelf frontend pods from a
single IP address. This service is defined in
# 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. With 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
Note that it may take up to 60 seconds for the IP address to be allocated. The external IP address will be listed under
Accessing the Bookshelf application
You have now deployed all the resources needed to run the Bookshelf application on Kubernetes Engine. Use the external IP address from the previous step to load the application in your web browser and create books.
To avoid incurring charges to your Google Cloud Platform account for the resources used in this tutorial:
Deleting the project
The easiest way to eliminate billing is to delete the project you created for the tutorial.
To delete the project:
- In the GCP Console, go to the Projects page.
- In the project list, select the project you want to delete and click Delete project.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Deleting the cluster
Deleting the cluster removes all Kubernetes Engine and Compute Engine resources, but you need to manually remove any resources in Cloud Storage, Cloud Datastore, and Cloud Pub/Sub.
Delete the cluster using the following command. Replace
the zone you used when
creating the cluster.
gcloud container clusters delete bookshelf --zone [YOUR_GCP_ZONE]