Overview of configuring DNS

This page describes how to configure DNS for Cloud Endpoints APIs that use .endpoints.PROJECT_ID.cloud.goog as the Endpoints service name. The configuration steps on this page are applicable for APIs using OpenAPI running on Compute Engine, Google Kubernetes Engine, or Kubernetes.

After your API is deployed, you will want the users of your API to be able to access it through a domain name rather than an IP address. You can either:

  • Configure the .endpoints.PROJECT_ID.cloud.goog as the domain name, as described on this page.
  • Or register your own domain name (for example, my-company.com), which entails:
    • Configuring DNS name servers (or using Google Cloud DNS).
    • Updating registry addresses.
    • Creating and maintaining DNS records.
    • If you already have a DNS infrastructure, or you want to register your own domain name, see Serving an API from Your Domain Name for more information.

The .cloud.goog domain is managed by Google and shared by Google Cloud Platform (GCP) customers. Because GCP Console projects are guaranteed to have a globally unique project ID, a domain name in the format .endpoints.PROJECT_ID.cloud.goog is unique and can be used as the domain name in the URL for your API.

Note the following:

  • Configuring the .endpoints.PROJECT_ID.cloud.goog domain name is optional. If you prefer, you can register your own domain name.
  • The .endpoints.PROJECT_ID.cloud.goog domain name is not supported for APIs running on App Engine. For APIs on App Engine, we recommend that you use YOUR_PROJECT_ID.appspot.com as the Endpoints service name. When you deploy the API to App Engine, a DNS entry with a name in the format YOUR_PROJECT_ID.appspot.com is created automatically.

Prerequisites

As a starting point, this page assumes that you have already created your Endpoints API and deployed it to Compute Engine, Google Kubernetes Engine, or Kubernetes. If you need an API for testing, you can use one of the tutorials that walk you through configuring and deploying a sample API.

Configuring DNS

The following procedure describes how to configure DNS for Cloud Endpoints APIs that use .endpoints.PROJECT_ID.cloud.goog as the Endpoints service name. For convenience, the procedure refers to your OpenAPI configuration file as openapi.yaml.

To configure DNS:

  1. Open openapi.yaml, and add the x-google-endpoints field to the file as shown in the following snippet:
        swagger: "2.0"
        host: "[API_NAME].endpoints.[PROJECT_ID].cloud.goog"
        x-google-endpoints:
        - name: "[API_NAME].endpoints.[PROJECT_ID].cloud.goog"
          target: "[IP_ADDRESS]"
    

    Typically, you configure the host field and the x-google-endpoints.name field to be the same. When you deploy your OpenAPI specification, the text specified in the host field is used as the name of your Endpoints service.

  2. Replace [API_NAME] with the name of your API (for example, bookstore or my-cool-api).
  3. Replace [PROJECT_ID] with your Cloud project ID.
  4. Replace [IP_ADDRESS] with an IPv4 address.

    For example, if you deploy your Endpoints API service to a Compute Engine virtual machine instance, you can use the external IP of that virtual machine. Alternatively, if you run your code on a group of virtual machine instances (or Kubernetes Engine pods) behind a load balancer, you can use the IP address of the load balancer.

  5. Deploy your new OpenAPI specification to Service Management using the following command:
    gcloud endpoints services deploy openapi.yaml
    

For example, if the following is specified in an openapi.yaml file:

    swagger: "2.0"
    host: "my-cool-api.endpoints.my-project-id.cloud.goog"
    x-google-endpoints:
    - name: "my-cool-api.endpoints.my-project-id.cloud.goog"
      target: "192.0.2.1"

When you deploy the openapi.yaml using the above gcloud command, Service Management creates a DNS A-record, my-cool-api.endpoints.my-project- id.cloud.goog, which resolves to the target IP address, 192.0.2.1. You might need to wait a few minutes for the new DNS configuration to propagate.

See also

Send feedback about...

Cloud Endpoints with OpenAPI