Deploying the API Backend

This page explains how to deploy your API's backend code and the Extensible Service Proxy (ESP) to Kubernetes Engine and Compute Engine.

Although the deployment steps vary depending on the platform hosting your API, there is always a step where you provide ESP the service configuration ID and service name of your API. With this information, ESP can obtain your API's Endpoints configuration, which allows ESP to proxy requests and responses so that Cloud Endpoints can manage your API.

Prerequisites

As a starting point, this page assumes that you have:

Preparing for deployment

GCE with Docker

For Cloud Endpoints to manage your API, you must install and configure ESP as well as the backend server code for your API. We recommend that you install Docker on your Compute Engine VM instance so that you can run the ESP Docker image that is freely available in Google Container Registry.

Before you deploy:

The following outlines at a high-level the steps you must take before you can deploy your API and ESP to Compute Engine. In general, you do all the steps that you normally would to run your backend server code on Compute Engine.

  1. Create, configure, and start your VM instance. See the Compute Engine documentation.
  2. Install Docker Enterprise Edition (EE) or Docker Community Edition (CE) on your VM instance. See Install Docker.
  3. Create a Docker container for your backend server code. See Building a Docker Image.
  4. Push the container to Google Container Registry or another registry.
  5. Make sure that you can successfully:

GCE without Docker

Although we recommend that you run your API and ESP in Docker containers, you can install your API backend code and ESP directly on a Linux Compute Engine instance. Installing ESP on Windows is not supported.

Before you deploy:

The following outlines at a high-level the steps you must take before you can deploy your API with ESP to Compute Engine. In general, you do all the steps that you normally would to run your backend server code on Compute Engine.

  1. Create, configure, and start your VM instance. See the Compute Engine documentation.
  2. Copy the files for your backend code to your VM instance. See Transferring Files to Instances for details.
  3. Make sure that you can successfully:

Kubernetes Engine

With the addition of a small section to your Deployment manifest file, you can run the ESP Docker image on your container clusters along with your containerized application.

Before you deploy:

The following outlines at a high-level the steps you must take before you can deploy your API with ESP to Kubernetes Engine. In general, you do all the steps that you normally would to run your backend server code on Kubernetes Engine.

  1. Deploy your containerized application to the container clusters. The general steps as described in the Kubernetes Engine documentation are:

    1. Package your app into a Docker image.
    2. Upload the image to a registry.
    3. Create a container cluster.
    4. Deploy your app to the cluster.
    5. Expose your app to the Internet.
  2. Make sure that you can successfully:

    • Start your API's server.
    • Send requests to your API.

Deploying your API and ESP

GCE with Docker

To deploy your API with ESP to Compute Engine with Docker:

  1. Connect to your VM instance:

    gcloud compute ssh [INSTANCE_NAME]
    
  2. Create your own container network called esp_net:

    sudo docker network create --driver bridge esp_net
    
  3. Run an instance of the image of your backend server code and connect it to the esp_net container network:

    sudo docker run \
        --detach \
        --name=[YOUR_API_CONTAINER_NAME] \
        --net=esp_net \
        gcr.io/[YOUR_PROJECT_ID]/[YOUR_IMAGE]:1
    
    • Replace [YOUR_API_CONTAINER_NAME] with the name of your container.
    • Replace [YOUR_PROJECT_ID] with the GCP project ID that you used when you pushed the image.
    • Replace [YOUR_IMAGE] with the name of your image.
  4. Get the service configuration ID and service name of your API.

  5. Run an instance of the ESP Docker image:

    sudo docker run \
        --detach \
        --name=esp \
        --publish=80:9000 \
        --net=esp_net \
        gcr.io/endpoints-release/endpoints-runtime:1 \
        --service=[SERVICE_NAME] \
        --version=[SERVICE_CONFIG_ID] \
        --http2_port=9000 \
        --backend=grpc://[YOUR_API_CONTAINER_NAME]:8000
    
  6. Replace [SERVICE_NAME] and [SERVICE_CONFIG_ID] with the service name and service configuration ID that you obtained from the previous step.

  7. Replace [YOUR_API_CONTAINER_NAME] with the name of your API's container.

See ESP Startup Options for the full list of options that you can specify when starting ESP.

GCE without Docker

To deploy your API and ESP to Compute Engine without Docker:

  1. Get the service configuration ID and service name of your API.

  2. Follow the steps to update metadata on a running instance and create the following key-value pairs:

    KeyValue
    endpoints-service-nameThe service name of your API
    endpoints-service-versionThe service configuration ID of your API

    If you plan to create additional Linux Compute Engine instances, you can follow the steps to set metadata during instance creation and create the endpoints-service-name and endpoints-service-version key-value pairs.

  3. Connect to your VM instance:

    gcloud compute ssh [INSTANCE_NAME]
    
  4. Install ESP on your Linux VM. There are packages available from https://packages.cloud.google.com/apt/dists for the following Linux distributions:

    • Debian 6.0: google-cloud-endpoints-squeeze
    • Debian 7.7: google-cloud-endpoints-wheezy
    • Debian 8.0: google-cloud-endpoints-jessie
    • Ubuntu 10.04: google-cloud-endpoints-lucid
    • Ubuntu 12.04: google-cloud-endpoints-precise
    • Ubuntu 14.04: google-cloud-endpoints-trusty
    • Ubuntu 16.04: google-cloud-endpoints-xenial

    If you must run another Linux distribution, you will have to download the ESP source code and build ESP. See The Extensible Service Proxy README for details.

  5. Start your API's server.

  6. Edit /etc/default/nginx as root to set the port that ESP listens on. For example, to set 80 as the port:

    PORT=80
    
  7. Start ESP by running the command:

    sudo service nginx restart
    

See Running the Extensible Service Proxy as a guide for installing and starting ESP on a Debian 8 VM instance.

Kubernetes Engine

To deploy ESP to Kubernetes Engine:

  1. Get the service configuration ID and service name of your API.

  2. Open your Deployment manifest file (referred to as deployment.yaml below) and add the following to the containers section:

      containers:
      - name: esp
        image: gcr.io/endpoints-release/endpoints-runtime:1
        args: [
          "--http2_port=9000",
          "--service=[SERVICE_NAME]",
          "--version=[SERVICE_CONFIG_ID]",
          "--backend=grpc://127.0.0.1:8000"
        ]
        ports:
          - containerPort: 9000
    

    Replace [SERVICE_NAME] and [SERVICE_CONFIG_ID] with your API's service name and configuration ID. See ESP Startup Options for the full list of options that you can specify when starting ESP.

  3. Start the Kubernetes service using the kubectl create command:

        kubectl create -f deployment.yaml
    

Redeploying

Whenever you deploy a change to your Endpoints configuration using the command gcloud endpoints services deploy, a new service configuration ID is created and assigned to the updated configuration. ESP needs the new configuration ID to begin using the updated configuration. The following tabs show how to pass the new service configuration ID to ESP on each of the supported platforms.

GCE with Docker

To redeploy to Compute Engine with Docker:

  1. Connect to your VM instance:

    gcloud compute ssh [INSTANCE_NAME]
    
  2. Stop ESP:

    sudo docker stop esp
    
  3. Remove the ESP container:

    sudo docker rm esp
    
  4. Run an instance of the ESP Docker image:

    sudo docker run \
    --detach \
    --name=esp \
    --publish=80:9000 \
    --net=esp_net \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=[SERVICE_NAME] \
    --version=[SERVICE_CONFIG_ID] \
    --http2_port=9000 \
    --backend=grpc://[YOUR_API_CONTAINER_NAME]:8000
    
    • Replace [SERVICE_NAME] and [SERVICE_CONFIG_ID] with the service name and newest service configuration ID.
    • Replace [YOUR_API_CONTAINER_NAME] with the name of your API's container.

GCE without Docker

To redeploy to Compute Engine without Docker:

  1. Follow the steps to update metadata on a running instance and change the value of endpoints-service-version to the new service configuration ID.

  2. Connect to your VM instance:

    gcloud compute ssh [INSTANCE_NAME]
    
  3. Run the following command to restart ESP:

    sudo /etc/init.d/nginx restart
    

Kubernetes Engine

To redeploy to Kubernetes Engine:

  1. Update your Deployment manifest file (called deployment.yaml below). Change the value of --version to the latest service configuration ID using the kubectl edit command:

    kubectl edit -f deployment.yaml
    
  2. Save the file. The ESP container restarts automatically.

Tracking API activity

After you deploy ESP and your API backend, you can use tools such as curl or Postman to send requests to your API. After sending some requests, you can:

  • View the activity graphs for your API on the Endpoints dashboard.
    View Endpoints activity graphs
    It may take a few moments for the request to be reflected in the graphs.

  • Look at the request logs for your API on the Stackdriver Logging page.
    View Stackdriver logs

Send feedback about...

Cloud Endpoints with gRPC