Deploying the Python Bookshelf app using Cloud Deployment Manager

This tutorial shows how to deploy the Python Bookshelf sample using Google Cloud Deployment Manager.

Deployment Manager provides a way of creating Google Cloud Platform (GCP) resources in a declarative and repeatable way, so it is easy to create all the necessary resources for a deployment in a single step. With Deployment Manager, you can update your deployments and track your modifications over time. You can create templates using Jinja or Python and parameterize them, so that similar deployments can share a template.

Objectives

  • Clone and configure the Bookshelf sample app.
  • Create Deployment Manager configurations and templates.
  • Create Deployment Manager deployments.
  • Deploy the Bookshelf sample app using Deployment Manager.

Costs

This tutorial uses billable components of Cloud Platform, including:

  • Compute Engine
  • Cloud Storage
  • Cloud Datastore
  • Cloud Logging
  • Cloud Pub/Sub

Use the Pricing Calculator to generate a cost estimate based on your projected usage. New GCP users might be eligible for a free trial.

Before you begin

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. Select or create a Google Cloud Platform project.

    Go to the Manage resources page

  3. Make sure that billing is enabled for your Google Cloud Platform project.

    Learn how to enable billing

  4. Enable the Cloud Datastore, Cloud Storage, and Cloud Pub/Sub APIs.

    Enable the APIs

  5. Install and initialize the Cloud SDK.
  6. Install Python, pip, and virtualenv on your system. For instructions, refer to Setting Up a Python Development Environment for Google Cloud Platform.

Creating a Cloud Storage bucket

The following instructions show how to create a Cloud Storage bucket. Buckets are the basic containers that hold your data in Cloud Storage.

  1. In a terminal window, enter the following command:

    gsutil mb gs://[YOUR-BUCKET-NAME]

    [YOUR-BUCKET-NAME] represents the name of your Cloud Storage bucket.

  2. To view uploaded images in the bookshelf app, set the bucket's default access control list (ACL) to public-read.

    gsutil defacl set public-read gs://[YOUR-BUCKET-NAME]

Cloning the sample app

The sample application is available on GitHub at GoogleCloudPlatform/getting-started-python.

  1. Clone the repository:

    git clone https://github.com/GoogleCloudPlatform/getting-started-python.git
    
  2. Go to the sample directory:

    cd getting-started-python/7-gce
    

Configuring the app

  1. Open config.py for editing.

  2. Set the value of PROJECT_ID to your project ID.

  3. Set the value CLOUD_STORAGE_BUCKET to the name of the bucket you created in the previous step.

  4. Save and close config.py.

Running the app on your local computer

  1. Create an isolated Python environment, and install dependencies:

    Linux/macOS

    virtualenv -p python3 env
    source env/bin/activate
    pip install -r requirements.txt
    

    Windows

    virtualenv -p python3 env
    env\scripts\activate
    pip install -r requirements.txt
    

  2. Run the application:

    python main.py
    
  3. In your web browser, enter this address:

    http://localhost:8080

To stop the local web server, press Control+C. If you want to exit the virtual environment, enter deactivate.

Deploying the sample app

Pushing your code to a repository

There are several ways to get your code onto a running Compute Engine instance. One way is to use Cloud Source Repositories. Every project includes a Git repository that can easily be made available to Compute Engine instances. Your instances can then pull the latest version of your application code during startup. This is convenient because updating your application does not require configuring new images or instances; all you need to do is restart an existing instance or create a new one.

If this is your first time using Git, use git config --global to set up your identity.

First, create a repository here on your GCP Console. Or create a repository using gcloud:

gcloud source repos create [YOUR_REPO]

where [YOUR_PROJECT_ID] is your project ID and [YOUR_REPO] is the name of the repository just created. Then push your application code to your project's repository:

git commit -am "Updating configuration"
git config credential.helper gcloud.sh
git remote add cloud https://source.developers.google.com/p/[YOUR_PROJECT_ID]/r/[YOUR_REPO]
git push cloud master

where [YOUR_PROJECT_ID] is your project ID.

Creating the deployment

After your configuration is committed and your code is uploaded to Cloud Source repository, you can use the Deployment Manager configuration to create the deployment.

Go to the deployment_manager directory:

cd getting-started-python/7-gce/gce/deployment_manager

Create the deployment:

gcloud deployment-manager deployments create my-deployment --config config.yaml

View a list of all the deployments:

gcloud deployment-manager deployments list

Get a description of the deployment and the resources it created:

gcloud deployment-manager deployments describe my-deployment

Viewing your application

After you create the forwarding rule, it can take several minutes for your configuration to propagate and for traffic to be routed to your instances. To check the progress, enter this command:

gcloud compute backend-services get-health bookshelf-my-deployment-frontend --global

When at least one of your instances reports HEALTHY, get the forwarding IP address for the load balancer by entering this command:

gcloud compute forwarding-rules list --global

Your forwarding-rules IP address is in the IP_ADDRESS column. In your browser, enter the IP address from the list.

Your app is now running on the load-balanced, autoscaled, Google Cloud Platform!

Understanding the code

Configuring the deployment

You can see how the deployment is configured in config.yaml:

imports:
- name: bookshelf.jinja
  path: ./bookshelf.jinja

resources:
- name: bookshelf
  type: bookshelf.jinja
  properties:
    zone: us-central1-f
    machine-type: n1-standard-1
    machine-image: https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/family/debian-9
    min-instances: 1
    max-instances: 10
    target-utilization: 0.6
    scopes:
    - https://www.googleapis.com/auth/cloud-platform

The config file imports the template file as a resource and uses it to define a resource named bookshelf. The template takes several properties as parameters. For more information about creating Deployment Manager configuration files, see Creating a Configuration.

Configuring the deployment template's schema

Next, look at the schema file, bookshelf.jinja.schema, which defines and documents the parameters that the deployment is expected to provide in its configuration file. For more information about configuration schemas, see Using Schemas:

info:
  title: Bookshelf GCE Deploy
  author: Google Inc.
  description: Creates a GCE Deployment

imports:
- name: startup-script
  path: ../startup-script.sh

required:
- zone
- machine-type
- min-instances
- max-instances
- scopes

properties:
  zone:
    description: Zone to create the resources in.
    type: string
  machine-type:
    description: Type of machine to use
    type: string
  machine-image:
    description: The OS image to use on the machines
    type: string
  min-instances:
    description: The minimum number of VMs the autoscaler will create
    type: integer
  max-instances:
    description: The maximum number of VMs the autoscaler will create
    type: integer
  target-utilization:
    description: The target CPU usage for the autoscaler to base its scaling on
    type: number
  scopes:
    description: A list of scopes to create the VM with
    type: array
    minItems: 1
    items:
      type: string

Configuring the deployment template

The template defines several resources to create an autoscaled, load-balanced, managed instance group. See the comments in the template for a full description of the resources created, and review the Bookshelf on Compute Engine tutorial for a more thorough explanation of the resources being created.

Keep in mind that Deployment Manager provides a way to declaratively define cloud resources, but most of the configuration for a given resource is defined by its API. For example, most of the configuration options for the Instance Template resource can be found in the Instance Template resource definition in the reference documentation for the Compute Engine API.

The template is written using the Jinja templating language. When writing Deployment Manager templates, you can either use Jinja or Python. Jinja has the advantage of being more declarative, which is often more readable and easier to understand. For some complex deployments, the full expressiveness of Python might make things simpler. In this case, Jinja is sufficient to create the resources necessary.

In a template, certain environment variables are automatically set that can be accessed via the env dictionary. In this case, the name of the deployment is referenced as a name to be reused when assigning names to the resources that are created. For more information about available environment variables, see Using environment variables in the Deployment Manager documentation:

{% set NAME = "bookshelf-" + env["deployment"] %}
{% set SERVICE = "bookshelf-" + env["deployment"] + "-frontend" %}

Note that the template uses the same startup script that is used in the Compute Engine tutorial. The value is imported via config.yaml and then inserted here. It's important that whitespace in the script is properly maintained in the template. The Jinja indent directive is used to accomplish this:

            value: |
{{imports['startup-script']|indent(14, true)}}

In a Deployment Manager Jinja template you can also refer to resources created elsewhere in the template. In this example, the backend service uses the reference of the managed instance group to obtain the instance group it should point to:

- group: $(ref.{{ NAME }}-frontend-group.instanceGroup)
  zone: {{ properties['zone'] }}

Properties specified in config.yaml can be used in the template:

minNumReplicas: {{ properties['min-instances'] }}
maxNumReplicas: {{ properties['max-instances'] }}
loadBalancingUtilization:
  utilizationTarget: {{ properties['target-utilization'] }}

Cleaning up

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 that you created for the tutorial.

To delete the project:

  1. In the GCP Console, go to the Projects page.

    Go to the Projects page

  2. In the project list, select the project you want to delete and click Delete delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

Deleting your deployment

Enter this command to delete your deployment. This deletes the load balancer and any Compute Engine instances associated with your deployment:

gcloud deployment-manager deployments delete my-deployment

What's next

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

Send feedback about...