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 Cloud Endpoints service configuration. With this information, ESP can obtain your API's Endpoints configuration, which lets ESP 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 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 Container Registry.
Before you deploy:
Before you can deploy your API and ESP to Compute Engine, complete the following steps:
- Create, configure, and start your VM instance.
- Install Docker Enterprise Edition (EE) or Docker Community Edition (CE) on your VM instance.
- Create a Docker container for your backend server code.
- Push the container to Artifact Registry} or another registry.
Make sure that you can successfully:
- Connect to the VM instance.
- Run the Docker image to start your backend server on the VM instance. See Docker run reference.
- Send requests to your API.
GKE
When you create a cluster in the Google Cloud console, by default, the OAuth scopes that are granted to the cluster's service account include the scopes that Endpoints requires:
- Service Control: Enabled
- Service Management: Read Only
When you create a cluster by using the
gcloud container clusters create
command or by 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. Before you can deploy your API with ESP to GKE, complete the following steps:
Deploy your containerized application to the container clusters. The general steps as described in the GKE documentation are:
- Package your application into a Docker image.
- Upload the image to a registry.
- Create a container cluster.
- Deploy your application to the cluster.
- Expose your application to the internet.
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:
Connect to your VM instance. Replace
INSTANCE_NAME
with the name of your VM instance:gcloud compute ssh INSTANCE_NAME
Create your own container network called
esp_net
:sudo docker network create --driver bridge esp_net
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 Google Cloud project ID that you used when you pushed the image. - Replace
YOUR_IMAGE
with the name of your image.
- Replace
Get the service name of your API. This is the name that you specified in the
name
field of your service configuration YAML file.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, up to 5 minutes 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.- Replace
If you need to configure ESP to use a specific configuration ID:
Include the
--version
option and set it to a specific configuration ID.Either remove the
--rollout_strategy=managed
option or set--rollout_strategy
tofixed
. Thefixed
option configures ESP to use the service configuration that you specified in--version
.Run 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 don't keep ESP configured to use a specific configuration ID for too long because if you deploy an updated service configuration, you have to restart ESP to use the new configuration.
To remove the specific configuration ID:
In the ESP flags for
docker run
, remove the--version
option.Add the
--rollout_strategy=managed
option.To restart ESP, run the
docker run
command.
See ESP startup options for the full list of options that you can specify when starting ESP.
GKE
To deploy ESP to GKE:
Get the service name of your API.
Open your Deployment manifest file (referred to as
deployment.yaml
) and add the following to thecontainers
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.Start the Kubernetes service by using the
kubectl create
command:kubectl create -f deployment.yaml
If you need to configure ESP to use a specific configuration ID:
In your Deployment manifest file, add the
--version
option and set it to a specific configuration ID.Either remove
--rollout_strategy=managed
or set--rollout_strategy
tofixed
. Thefixed
option configures ESP to use the service configuration that you specified in--version
.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 don't keep ESP configured to use a specific configuration ID for too long because if you deploy an updated service configuration, you have to restart ESP to use the new configuration.
To remove the specific configuration ID:
In your Deployment manifest file, remove the
--version
option.Add
--rollout_strategy=managed
.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 don't get a successful
response, see
Troubleshooting response errors
After sending some requests, you can:
To view the activity graphs for your API, go to Endpoints > Services. 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 Cloud Logging page.