Deploying the Endpoints Configuration

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.

Prerequisites

As a starting point, this page assumes that you have:

If you are using a custom domain name (for example, my.company.com), you 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:

  1. Install and initialize the Cloud SDK.
  2. Update Cloud SDK:
    gcloud components update
    
  3. Make sure that Cloud SDK is authorized to access your data and services:
    gcloud auth login
    

    A new browser tab opens and you are prompted to choose an account.

  4. Set the default project. Replace [YOUR-PROJECT-ID] with your GCP project ID
    gcloud config set project [YOUR-PROJECT-ID]
    
  5. 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 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 service.

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:

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 using the gcloud command-line tool.

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 Endpoints dashboard.

To deploy your OpenAPI document:

For simplicity, this page refers to the OpenAPI document as openapi.yaml.

  1. Change directory to the location containing your API's openapi.yaml file.

  2. 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 ID and echo-api.endpoints.example-project-12345.cloud.goog is the service name.

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 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 managed, 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.

What's next

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

Send feedback about...

Cloud Endpoints with OpenAPI