After you configure Cloud Endpoints in an OpenAPI
document, you deploy it so that
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 an OpenAPI document 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 to a user, group, or service account. See Granting and revoking access to the API for more information.
If you are using a custom domain name (such as
my-api.example.com
), you must verify the domain name before you can deploy the OpenAPI document.
Preparing the 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
.gcloud auth application-default login
A new browser tab opens and you are prompted to choose an account.
Validating openapi.json
syntax
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 your openapi.json
is a well-formatted JSON file, you can open it in
a JSON-validating text editor such as vim
, use an online JSON linter
service, or use Python, for example:
python -m json.tool openapi.json
To improve readability, you can pretty-print the JSON file:
python -m json.tool input.json > output.json
Replace input.json
with the path to your openapi.json
file. output.json
is
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.
To validate your OpenAPI document:
Change directory to the location containing your OpenAPI document.
Confirm the Google Cloud project where you want to create the service. If you are using a custom domain name (such as,
myapi.example.com
), make sure to validate the project ID returned from the following command so that the service isn't created in the wrong project.gcloud config list project
If you need to change the default project, run the following command and replace
[YOUR_PROJECT_ID]
with the Google Cloud project ID in which you want to create the service:gcloud config set project [YOUR_PROJECT_ID]
Run the following command, and replace
[YOUR_OPENAPI_DOCUMENT]
with the name of the OpenAPI document that describes your API:gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT] --validate-only
The gcloud
command then calls the
Service Management API to
create a managed service with the name that you specified in the host
field
in your OpenAPI document. When you specify the --validate-only
flag, a service
is still created, but the configuration isn't deployed. There isn't a way to
validate your OpenAPI document without creating a service. Although you can
delete the service,
Service Management prevents you from creating a service with the same
name for a period of approximately 30 days.
Deploying the OpenAPI document
When you are ready to deploy your API, you run the Google Cloud CLI, which uses Service Management to upload your API configuration and to create (or update) a managed service.
To deploy your OpenAPI document:
Change directory to the location containing your OpenAPI document.
Validate the project ID returned from the following command to make sure that the service isn't created in the wrong project.
gcloud config list project
If you need to change the default project, run the following command and replace
[YOUR_PROJECT_ID]
with the Google Cloud project ID in which you want to create the service::gcloud config set project [YOUR_PROJECT_ID]
Run the following command, and replace
[YOUR_OPENAPI_DOCUMENT]
with the name of the OpenAPI document that describes your API:gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT]
The first time that you run the previous command, Service Management
creates a new Endpoints service in the default project with a
name that matches the text that you specified in the host
field in your
OpenAPI document and uploads your service configuration.
As it is creating and configuring the service, Service Management outputs 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-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]
In the previous example, 2017-02-13r0
is the service configuration
ID and echo-api.endpoints.example-project-12345.cloud.goog
is the service
name.
After a successful deployment, you can view the API on the Endpoints > Services page in the Google Cloud console.
If you get an error message, see Troubleshooting Endpoints configuration deployment.
Redeploying
Whenever you change something in your OpenAPI document, be sure to deploy it
again so that Endpoints has the most recent version of
your API's service configuration. You don't need to redeploy
or restart ESP if you previously deployed ESP with
the
rollout
option set to managed
.
This 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
- Deploying on Kubernetes
- Running ESP locally or on another platform
- Getting the service name and configuration ID