Deploying the Endpoints Configuration

After you have configured your protobuf descriptor file and gRPC API configuration file, you deploy them so that Cloud Endpoints has the information that it needs to manage your API. This page describes how to deploy your configuration files to Cloud Endpoints using the gcloud endpoints services deploy command. The configuration files used on this page are based on the Python version of the Bookstore sample.

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 gRPC configuration files.

Preparing gcloud for deployment

You use the gcloud command line tool from the Cloud SDK 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 the Cloud SDK:
    gcloud components update
    
  3. Make sure that Cloud SDK is authorized to access your data and services on GCP:
    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.

Deploying the configuration files

  1. Make sure you are in the directory where api_descriptor.pb and api_config.yaml are located.
  2. Deploy the proto descriptor file and the configuration file using the gcloud command-line tool:
    gcloud endpoints services deploy api_descriptor.pb api_config.yaml
    

    As it is creating and configuring the service, Service Management outputs a great deal of information to the terminal. On successful completion, you will see a line like the following that displays the service configuration ID and the service name:

    Service Configuration [2017-02-13-r2] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
    

    In the above example, 2017-02-13-r2 is the service configuration ID and bookstore.endpoints.example-project.cloud.goog is the service name. If you get an error message, see Troubleshooting configuration deployment errors.

    See gcloud endpoints services deploy in the Cloud SDK Reference documentation for more information.

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 Cloud Endpoints handles merging multiple YAML files in Configuring a gRPC API Service.

Troubleshooting configuration deployment errors

This section describes some errors that you might encounter when you deploy your Endpoints configuration and how to troubleshoot them. After each step, run the gcloud endpoints services deploy command again to see if the error is resolved.

Not allowed to get project settings

ERROR: (gcloud.endpoints.services.deploy) PERMISSION_DENIED:
Not allowed to get project settings for project YOUR_PROJECT_ID

  1. Authenticate with the Cloud SDK again to confirm that you authenticated with an account that has permission to access the project displayed in the error message:
    gcloud auth login
    

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

  2. Confirm that the project ID displayed in the error message corresponds to the GCP project that you intend to deploy the Endpoints configuration to:
    gcloud projects list
    
  3. Confirm that the Cloud SDK has the correct project ID set as the current project:
    gcloud config set project [YOUR_PROJECT_ID]
    

Caller does not have permission

ERROR: (gcloud.endpoints.services.deploy) PERMISSION_DENIED:
Caller does not have permission 'servicemanagement.services.create' on project YOUR_PROJECT_ID

You must have the Editor or Owner role to deploy the Endpoints configuration. To check your permissions:

  1. Open the IAM page in the GCP Console.

    Open the IAM page

  2. Click Select a project.

    If you do not see the project that you want to deploy the Endpoints configuration to, then you are not a member of the project. You will have to have a project member with the Owner role grant you access to the project.

    If you see the project that you want to deploy Endpoints configuration to, select it, and click Open.

  3. Find your name in the Members list and confirm that you have either the Editor or Owner role.

    If you have some other role, you will have to have a project member with the Owner role change your role.

Ownership for domain name cannot be verified

ERROR: (gcloud.endpoints.services.deploy) PERMISSION_DENIED:
Ownership for domain name 'YOUR_DOMAIN_NAME' on project YOUR_PROJECT_ID cannot be verified

  • If you have a custom domain (for example, my-company.com) configured in the name field of your api_config.yaml file, you must verify the domain name before you can deploy the Endpoints configuration.
  • If you are using the cloud.goog domain, confirm that the value for the name field is in the following format, and that the project ID is correct:
    API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
    

What's next

Send feedback about...

Cloud Endpoints with gRPC