After you have configured Endpoints in an OpenAPI document, you deploy it 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 Google Service Management, an infrastructure service of GCP that manages other APIs and services, including services created using Cloud Endpoints. This page describes how to deploy an OpenAPI document to Cloud Endpoints.
As a starting point, this page assumes that you have:
- Created a Google Cloud Platform (GCP) project in which you have the Editor or Owner role. See Controlling API Access of Project Members for more information.
- Configured Endpoints.
If you are using a custom domain name (for example,
must verify the domain name
before you can deploy the OpenAPI document.
Preparing Cloud SDK 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 Cloud SDK.
- Update Cloud SDK:
gcloud components update
- Make sure that Cloud SDK is authorized to access your data and
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 ID
gcloud 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
gcloud auth application-default loginA new browser tab opens and you are prompted to choose an account.
The OpenAPI document file can be in YAML format or JSON format. If it is in JSON format, we recommend that you verify the syntax before deploying the file.
To check that a
openapi.json is a well-formatted JSON file, you can open it in
a JSON-validating text editor such as
vim or use an online JSON linter
python can also be used to validate JSON syntax:
python -m json.tool openapi.json
To improve readability, pretty-print the JSON file using
python -m json.tool input.json > output.json
input.json with the path to your
the pretty-printed JSON file.
Validating your OpenAPI document
Not all OpenAPI constructs are currently supported by Cloud Endpoints. Before
deploying, you can validate your OpenAPI document using the
gcloud endpoints services deploy --validate-only openapi.json
See OpenAPI Feature Limitations for more information.
Deploying the OpenAPI document
When you deploy your API, the
gcloud command-line tool uses the
Google Service Management API to upload your API
configuration to create a managed service. After a successful deployment, you
can view the API in the
To deploy your OpenAPI document:
For simplicity, this page refers to the OpenAPI document as
Change directory to the location containing your API's
Invoke the following command:
gcloud endpoints services deploy openapi.yaml
The first time that you deploy
openapi.yaml, Service Management
creates a new Cloud Endpoints service with a name that matches
the text that you specified in the
host field in the
openapi.yaml file, and
then configures the service according to your OpenAPI document.
As it is creating and configuring the service, Service Management outputs a great deal of information to the terminal. On successful completion, you see a line like the following that displays the service configuration ID and the service name:
Service Configuration [2017-02-13-r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]
In the above example,
2017-02-13-r0 is the service configuration
echo-api.endpoints.example-project-12345.cloud.goog is the
If you get an error message, see Troubleshooting Endpoints Configuration Deployment
Whenever you change something in your OpenAPI document, be sure to deploy it
again so that Cloud Endpoints has the most recent version of
your API's service configuration. If the configuration change does not require
that you redeploy your API (for example, perhaps you added or changed something
in the security section), if you have previously deployed ESP with the
rollout_strategy option set to
you do not need to redeploy/restart ESP. This 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.