Deploying the API Backend

This page explains how to deploy your API's backend code and the Extensible Service Proxy (ESP) to Google 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 name and an option that configures ESP to use the latest deployed Endpoints service configuration. 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

Compute Engine

For Cloud Endpoints to manage your API, you must install and configure ESP as well as the backend server code for your API. You need to 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 Google Cloud Build Documentation.
  4. Push the container to Google Container Registry or another registry.
  5. Make sure that you can successfully:

GKE

When you create a cluster in the GCP Console, by default, the OAuth scopes that are granted to the cluster's service account include the scopes that Cloud Endpoints requires:

  • Service Control: Enabled
  • Service Management: Read Only

When you create a cluster using the gcloud container clusters create command or using a third-party configuration file, make sure you specify the following scopes:

  • "https://www.googleapis.com/auth/servicecontrol"
  • "https://www.googleapis.com/auth/service.management.readonly"

For more information, see What are access scopes?.

Before you deploy:

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. The following outlines at a high-level the steps you must take before you can deploy your API with ESP to GKE. In general, you do all the steps that you normally would to run your backend server code on GKE.

  1. Deploy your containerized application to the container clusters. The general steps as described in the GKE 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

Compute Engine

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 name of your API. This is the name that you specified in the name field of your service configuration YAML file.

  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] \
        --rollout_strategy=managed \
        --http2_port=9000 \
        --backend=grpc://[YOUR_API_CONTAINER_NAME]:8000
    
    • Replace [SERVICE_NAME] with the name of your service.
    • Replace [YOUR_API_CONTAINER_NAME] with the name of your API's container.

The --rollout_strategy=managed option configures ESP to use the latest deployed service configuration. When you specify this option, within a minute after you deploy a new service configuration, ESP detects the change and automatically begins using it. We recommend that you specify this option instead of a specific configuration ID for ESP to use.

If you need to configure ESP to use a specific configuration ID:

  1. Include the --version option and set it to a specific configuration ID.

  2. Either remove the --rollout_strategy=managed option or set --rollout_strategy to fixed. The fixed option configures ESP to use the service configuration that you specified in --version.

  3. Issue the docker run command again.

If you specify both --rollout_strategy=managed and the --version option, ESP starts with the configuration that you specified in --version, but then runs in managed mode and obtains the latest configuration.

We recommend that you do not keep ESP configured to use a specific configuration ID for very long because if you deploy an updated service configuration, you will have to restart ESP to use the new configuration.

To remove the specific configuration ID:

  1. In the ESP flags for docker run, remove the --version option.

  2. Add the --rollout_strategy=managed option.

  3. Issue the docker run command to restart ESP.

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

GKE

To deploy ESP to GKE:

  1. Get the 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]",
          "--rollout_strategy=managed",
          "--backend=grpc://127.0.0.1:8000"
        ]
        ports:
          - containerPort: 9000
    

    Replace [SERVICE_NAME] with your API's service name.

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

        kubectl create -f deployment.yaml
    

If you need to configure ESP to use a specific configuration ID:

  1. In your Deployment manifest file, add the --version option and set it to a specific configuration ID.

  2. Either remove --rollout_strategy=managed or set --rollout_strategy to fixed. The fixed option configures ESP to use the service configuration that you specified in --version.

  3. Start the Kubernetes service: kubectl create -f deployment.yaml

If you specify both --rollout_strategy=managed and the --version option, ESP starts with the configuration that you specified in --version, but then it runs in managed mode and obtains the latest configuration.

We recommend that you do not keep ESP configured to use a specific configuration ID for very long because if you deploy an updated service configuration, you will have to restart ESP to use the new configuration.

To remove the specific configuration ID:

  1. In your Deployment manifest file, remove the --version option.

  2. Add --rollout_strategy=managed.

  3. Start the Kubernetes service: kubectl create -f deployment.yaml

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

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. If you do not get a successful response, see Troubleshooting Response Errors

After sending some requests, you can:

See also

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

Send feedback about...

Cloud Endpoints with gRPC
Need help? Visit our support page.