Deploying the Node.js Bookshelf using Deployment Manager

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

Deployment Manager provides a way of creating Google Cloud Platform 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:

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

Use the Pricing Calculator to generate a cost estimate based on your projected usage. New Cloud Platform 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 Cloud Platform project.

    Go to the Manage resources page

  3. Enable billing for your project.

    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 Node.js and npm using the official installer.

Creating a Cloud Storage bucket

The following instructions show how to create a Cloud Storage bucket.

To create a bucket:

  1. Invoke the following command in a terminal window:

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

  2. Set the bucket's default ACL to public-read, which enables users to see their uploaded images:

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

Cloning the sample app

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

  1. Clone the repository:

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

    cd nodejs-getting-started/7-gce
    

Configuring the app

In the 7-gce directory, create a file named config.json with the following contents.

{
    "GCLOUD_PROJECT": "[YOUR_PROJECT_ID]",
    "CLOUD_BUCKET": "[YOUR_BUCKET_NAME]",
    "DATA_BACKEND": "datastore",
    "OAUTH2_CLIENT_ID": "none",
    "OAUTH2_CLIENT_SECRET": "none",
    "OAUTH2_CALLBACK": "http://localhost:8080/auth/google/callback"
}

Replace [YOUR_PROJECT_ID] with your Google Cloud project ID and [YOUR_BUCKET_NAME] with the name of your Cloud Storage bucket.

Running the app on your local computer

Follow these steps to run the app locally.

  1. Install dependencies by running npm install.

  2. Start the application by running npm start.

  3. To view the locally running application, go to http://localhost:8080.

  4. To stop the local web server, press Control+C.

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.

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]/
git push cloud

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 nodejs-getting-started/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

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-8
    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 Adding Templates 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)}}

Also note that it's possible in a Deployment Manager Jinja template to 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 you created for the tutorial.

To delete the project:

  1. In the Cloud Platform 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 project. After selecting the checkbox next to the project name, click
      Delete project
  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

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...