Deploying the API Backend

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

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

App Engine

With the addition of a small configuration step (described below), deploying your API is the same as deploying any application to the App Engine flexible environment. Follow the App Engine documentation to:

You deploy your API to App Engine using the gcloud app deploy command. This command automatically builds a container image by using the Container Builder service and then deploys that image to your App Engine flexible environment.

Before you deploy:

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:
  3. Start your API's server.
  4. Send requests to your API.

Deploying your API and ESP

App Engine

To deploy the API and ESP to App Engine:

  1. Get the service name and service configuration ID of your API.
  2. Edit app.yaml, and add a section called endpoints_api_service that contains the service name and service configuration ID that you obtained from the previous step. You can use the app.yaml from the tutorial as a model:
    Python
    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      config_id: ENDPOINTS-CONFIG-ID
    Go
    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      config_id: ENDPOINTS-CONFIG-ID
    PHP
    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
      # previously run the deploy command, you can list your existing configuration
      # ids using the 'configs list' command as follows:
      #
      #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
      #
      name: ENDPOINTS-SERVICE-NAME
      config_id: ENDPOINTS-CONFIG-ID
    Ruby
    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      config_id: ENDPOINTS-CONFIG-ID
    NodeJS
    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      config_id: ENDPOINTS-CONFIG-ID
    • Replace ENDPOINTS-SERVICE-NAME with your API's service name.
    • Replace ENDPOINTS-CONFIG-ID with the service configuration ID. For example:
    endpoints_api_service:
      name: "example-project-12345.appspot.com"
      config_id: "2017-02-13-r0"
    
  3. Save the app.yaml file.
  4. Deploy your backend code and ESP to App Engine:
    gcloud app deploy
    

    Because you added the endpoints_api_service section to app.yaml, the gcloud app deploy command deploys and configures ESP in a separate container to your App Engine flexible environment. All request traffic is routed through ESP, and it proxies requests and responses to and from the container running your backend server code.

When you deploy your API to the App Engine flexible environment for the first time, there might be a delay as your virtual machine (VM) and other infrastructure are set up. For additional information, see the "Ensuring successful deployment" section on the Testing and Deploying your Application page in the App Engine documentation.

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.0
    • 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 \
        --name=esp \
        --detach \
        --publish=80:8080 \
        --net=esp_net \
        gcr.io/endpoints-release/endpoints-runtime:1 \
        --service=[SERVICE_NAME] \
        --version=[SERVICE_CONFIG_ID] \
        --backend=[YOUR_API_CONTAINER_NAME]:8080
    • Replace [SERVICE_NAME] and [SERVICE_CONFIG_ID] with the service name and service configuration ID that you obtained from the previous step.
    • 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 in the Compute Engine documentation to update metadata on a running instance and create the following key-value pairs:
    Key Value
    endpoints-service-name The service name of your API
    endpoints-service-version The service configuration ID of your API

    If you plan to create additional Linux Compute Engine instances, you can follow the steps in the Compute Engine documentation 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: [
        "--http_port=8081",
        "--backend=127.0.0.1:8080",
        "--service=[SERVICE_NAME]",
        "--version=[SERVICE_CONFIG_ID]",
      ]

    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 createcommand:
    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.

App Engine

To redeploy to App Engine:

  1. Open the app.yaml file. In the endpoints_api_service section, change the value of the config_id field to the new service configuration ID, and save the file.
  2. Redeploy your application and ESP:
    gcloud app deploy

    This command deploys new ESP instances which will have your new service configuration.

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 \
        --name=esp \
        --detach \
        --publish=80:8080 \
        --net=esp_net \
        gcr.io/endpoints-release/endpoints-runtime:1 \
        --service=[SERVICE_NAME] \
        --version=[SERVICE_CONFIG_ID] \
        --backend=[YOUR_API_CONTAINER_NAME]:8080
    
    • 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 in the Compute Engine documentation 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 OpenAPI