After you configure your .proto
file and gRPC API configuration
file, you deploy them so that
Cloud Endpoints has the information that it needs to manage your API. To
deploy the Endpoints configuration, you use the gcloud
endpoints services deploy
command. This command uses
Service Infrastructure, Google's
foundational services platform, used by Endpoints and other
services to create and manage APIs and services. This page describes how to
deploy your configuration files to Endpoints.
Prerequisites
As a starting point, this page assumes that you have:
Created a Google Cloud project in which you have the Editor or Owner role. After the initial deployment, you can grant the more restrictive Service Config Editor role. See Granting and revoking access to the API for more information.
Configured Endpoints, which includes:
If you use a custom domain name (such as,
example.com
), you must verify the domain name before you can deploy the gRPC configuration files.
Preparing Google Cloud CLI for deployment
You use the gcloud
command line tool to
deploy the configuration. See the
gcloud Reference for more information about the commands.
To prepare for the deployment:
- Install and initialize the gcloud CLI.
- Update gcloud CLI:
gcloud components update
- Make sure that gcloud CLI is authorized to access your data and
services:
gcloud auth login
A new browser tab opens and you are prompted to choose an account.
- Set the default project. Replace
[YOUR-PROJECT-ID]
with your GCP project IDgcloud config set project [YOUR-PROJECT-ID]
- If you will be deploying your API backend to either Kubernetes or Kubernetes
Engine, run the following command to acquire new user credentials to use for
Application Default Credentials. The user credentials are needed to authorize
kubectl
. A new browser tab opens and you are prompted to choose an account.gcloud auth application-default login
Deploying the configuration files
- Make sure you are in the directory where the
api_descriptor.pb
andapi_config.yaml
files are located. - Confirm that the default project that the
gcloud
command-line tool is currently using is the Google Cloud project that you want to deploy the Endpoints configuration to. Validate the project ID returned from the following command to make sure that the service doesn't get created in the wrong project.gcloud config list project
If you need to change the default project, run the following command:
gcloud config set project YOUR_PROJECT_ID
- Deploy the
proto descriptor
file and the configuration file by using the Google Cloud CLI:gcloud endpoints services deploy api_descriptor.pb api_config.yaml
As it is creating and configuring the service, Service Management outputs information to the terminal. When the deployment completes, a message similar to the following is displayed:
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
CONFIG_ID is the unique Endpoints service configuration ID created by the deployment. For example:
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
In the previous example,
2017-02-13r0
is the service configuration ID andbookstore.endpoints.example-project.cloud.goog
is the service name. The service configuration ID consists of a date stamp followed by a revision number. If you deploy the Endpoints configuration again on the same day, the revision number is incremented in the service configuration ID.
If your service's configuration is in multiple YAML files, you can pass them all
to the deploy
command. For example, the Bookstore has its basic configuration
in api_config.yaml
, but you can enable HTTP transcoding for the service by
also deploying api_config_http.yaml
, which has additional configuration for
this feature:
gcloud endpoints services deploy api_descriptor.pb api_config.yaml api_config_http.yaml
Note that if there are conflicting values in your YAML files, the values in the last specified file override the others. You can find out more about how Endpoints handles merging multiple YAML files in Configuring a gRPC service.
If you get an error message, see Troubleshooting Endpoints configuration deployment for information on troubleshooting the error.
Redeploying
Whenever you change something in your .proto
or service configuration YAML
file, deploy the files again so that the Extensible Service Proxy (ESP) has
the most recent version of your API's service configuration. If you previously
deployed ESP with the rollout
option set to
managed
,
you don't need to restart or redeploy ESP. The rollout=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.
After the initial Endpoints configuration deployment, you can grant a user, service account, or group a role that allows them to redeploy the Endpoints configuration. See Granting and revoking access to the API for more information.
What's next
- Getting started using the Cloud Endpoints Portal
- Deploying the API backend
- Running ESP Locally or on another platform
- Getting the service name and configuration ID