How API Deployment Works

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 your project API list in the console Endpoints page.

After the Extensible Service Proxy is deployed and your API is serving traffic, the proxy will communicate with the Google Service Control API to enforce the configuration specified in your OpenAPI configuration file (openapi.yaml) for items such as authentication configuration and API keys. For more information on using OpenAPI, see OpenAPI Overview.

The proxy and the Service Control API also report logs and metrics to Stackdriver's logging and monitoring features that are visible in the Google Cloud Platform Console. For more information, see Monitoring your API.

Deployment

These steps describe how to deploy the Extensible Service Proxy on supported platforms.

App Engine

In the App Engine flexible environment, the Extensible Service Proxy is automatically deployed along with your backend code and your API configuration. The backend code is deployed in an App Engine flexible instance, with the proxy deployed in a separate container on the same App Engine flexible instance.

  1. Deploy the OpenAPI specification:

    gcloud service-management deploy openapi.yaml
    
  2. Edit app.yaml to provide the Endpoints service name and configuration ID in the endpoints_api_service section.

  3. Deploy your App Engine flexible app using gcloud app deploy.

This will result in a Service Configuration being created in the Service Management API. You can later list all of your existing Service Configurations using the gcloud service-management configs list command.

All request traffic is routed to that proxy and it proxies requests and responses to and from the container running your backend server code. The Extensible Service Proxy and the Google Service Management service together enable logs, metrics, authentication and other Endpoints features.

Compute Engine

You must install and configure the Extensible Service Proxy as well as installing the backend server code for your API. We recommend running the proxy in a Docker container, although you can install the proxy directly on a Compute Engine instance if you wish.

The proxy uses a copy of your API's service configuration openapi.yaml file to manage your API traffic when it is started on the instance.

  1. Deploying your API specification via the gcloud service-management deploy openapi.yaml command configures Endpoints to manage your API: the supported API calls, the calls requiring authentication, the calls requiring API keys, and so forth.
  2. The Extensible Service Proxy fetches the configuration of the API using the service name and service version supplied to it at runtime.
  3. If you install the Extensible Service Proxy directly on a Compute Engine instance, the proxy uses Compute Engine Instance Metadata. This feature gets the API version using the two instance metadata keys you added when you created the instance: endpoints-service-name and endpoints-service-version.
  4. If you install the Extensible Service Proxy in a Docker container, the proxy uses the API name and version flags passed in the command that starts the Docker container to get the API name and version.

Container Engine

You must install and configure the Extensible Service Proxy as well as installing the backend server code for your API.

The proxy uses a copy of your API's service OpenAPI specification file to manage your API traffic when it is started on the instance.

  1. Deploying your API specification via the gcloud service-management deploy openapi.yaml command configures Endpoints to manage your API: the supported API calls, the calls requiring authentication, the calls requiring API keys, and so forth.
  2. The Extensible Service Proxy fetches the configuration of the API using the service name and service version supplied when you start the container.

Redeployment

The following tabs show how to redeploy in each of the supported platforms.

App Engine

You can use the gcloud service-management deploy command to update just the API specification without redeploying your backend API server code or the Extensible Service Proxy. This is useful if you are changing a configuration-only detail.

When you change the API specification, the Service Control API backing your running service instances will pick up the change because as it depends on the same service configuration. Therefore, it is important to be careful when making backwards incompatible changes such as removing an API method. Follow the safe deprecation steps described in Versioning an API.

When you'd like to re-deploy your backend API changes, update the 'app.yaml' file of your App Engine flexible app and change the 'endpoints_api_service.config_id' field. Then re-deploy your app using the gcloud app deploy command. This will deploy new Endpoints Service Proxy instances which will have your new API configuration (the one specified by the config_id).

Compute Engine

Whenever you deploy a change to your OpenAPI spec using the command gcloud service-management deploy openapi.yaml, make sure you manually propagate those changes to the Extensible Service Proxy. You can do this when running the proxy directly on a Compute Engine instance by updating the values for the metadata keys endpoints-service-name and endpoints-service-version as described in the metadata documentation

Optionally you can change the metadata values using the command:

gcloud compute instances add-metadata INSTANCE -metadata endpoints-server-version=[API-VERSION]

After changeing the metadata, restart Extensible Service Proxy so that it picks up the changes.

To restart the Extensible Service Proxy:

  1. gcloud compute instances add-metadata --metadata=endpoints-service-name=SERVICE_NAME,endpoints-service-config-id=CONFIG_ID

  2. SSH into the VM and run:

    sudo /etc/init.d/nginx restart

Restarting a Extensible Service Proxy container on Compute Engine:

  1. sudo docker stop esp; sudo docker rm esp;

  2. sudo docker run --name=esp -d -p 80:8080 --link=echo:echo gcr.io/endpoints-release/endpoints-runtime:1 -s [SERVICE_NAME] -v [NEW_SERVICE_VERSION] -a echo:8081

Container Engine

To update your API configuration, for example, if you add methods or change the authentication method, you can redeploy the configuration by invoking gcloud service-management deploy openapi.yaml.

Whenever you deploy a change to your OpenAPI spec using the command gcloud service-management deploy openapi.yaml, make sure you restart your Extensible Service Proxy container so that it picks up the changes.

Before restarting the proxy, update the -v argument in container-engine.yaml with the correct service version number. After updating the file, restart the container:

kubectl edit deployment/esp_echo

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Endpoints with OpenAPI