Serving an API from Your Domain Name

This page shows how to serve an API from a custom domain that you own (for example

As an alternative to using your own domain name, you can use a domain name managed by Google. See Using a domain managed by Google for more information.

Before you begin

Configure your API project to use your domain name

Follow the instructions in the appropriate tab below.

App Engine

To set your API project to use your verified domain, follow the instructions provided in Adding a custom domain for your application

Compute Engine

The recommended way to serve an API from Compute Engine instances is to use a load balancer across an instance group. You'll need to reserve an external IP for the domain name and use that external IP address for the load balancer.

To serve the API from a domain name:

  1. Reserve at least one static external IP address in your project.
    Reserve an external IP address

    1. Assign any name you want to the reserved IP address.
    2. Select Global for the type.
    3. Select None for Attached to; you'll attach the IP to a load balancer later.
  2. Visit your domain provider account and edit your domain settings. You must create an A record that contains your API name, for example, with the external IP address in its data field.

  3. Create an Instance Group that includes the instances running your API and ESP.
    Create an instance group

    1. Supply any name you want for the group and add a description.
    2. Select the zone used by your API instance.
    3. In the Instance definition dropdown menu, click Select existing instances.
    4. In VM Instances, add the VM instance running the API.
    5. Click Create.
  4. Create and configure an HTTP(S) load balancer.
    Create a load balancer

    1. Click Define a Backend Service > Create or select a backend service.

      Backend configuration

    2. Supply any name and description you want for this backend service configuration.

      1. Select the protocol you want to support through the load balancer: HTTP or HTTPS.
      2. Select your instance group in the Instance group dropdown menu.
      3. Enter 8080 as the port.
      4. Click Health check to configure health checks:
        1. Specify a name for the health check config./
        2. Assign the port 8080.
        3. Accept the remaining defaults by clicking Save.
      5. For now, accept the defaults for the rest of the configuration. You can make changes later as needed, such as additional ports.
    3. Notice the settings for Host and path rules. You don’t need to set anything here; you can forward everything to your backend API using the default Any unmatched filters. This means that all traffic into the load balancer will be directed to the API on the port 8080 as defined it above (the default port).

    4. Click Frontend configuration. Frontend configuration

      1. Select a protocol you want to support (HTTP or HTTPS)
      2. In the IP dropdown menu, select the external IP address you created earlier.
      3. For the HTTPS protocol, you'll need to use SSL: select the certificate you want from the Certificate dropdown menu.
      4. Optionally, to support another protocol, click Add frontend IP and port, specify the protocol, the same external IP address, and a different port.
    5. Click Create to create the fully configured load balancer. If the Create button isn't enabled, check the components you just configured: a checkmark should appear beside each of the configuration components. A missing checkmark means you haven't completed the configuration.

    6. After your DNS changes propagate, requests will be sent to your API via the load balancer.

Kubernetes Engine

To serve an API over a domain for GKE, you need to expose ESP as a service, using the returned external IP address for your domain's DNS settings. Note that GKE automatically does load balancing for your.

To expose your API as a service:

  1. If you don't have one already, configure a Kubernetes service for your API backends. Create a service configuration file, service.yaml, with content similar to the following:

    apiVersion: v1
    kind: Service
      name: echo
      - port: 80
        targetPort: 8081
        protocol: TCP
        app: echo-app
      type: LoadBalancer
    • Change the selector label to match your backend labels (app: echo-app in this example).
    • Make sure the target port matches the port used by ESP configured in your API backends (ESP uses port 8081 by default).
  2. Deploy the Kubernetes service:

    kubectl apply -f service.yaml
  3. View the external IP address assigned to your exposed service by invoking:

    kubectl get services

    Look for the value under EXTERNAL-IP:

    NAME         CLUSTER-IP     EXTERNAL-IP      PORT(S)    AGE
    hello-node   10.X.XXX.202   10X.XXX.XX.123   8080/TCP   1m
  4. Change the generated external IP from ephemeral to static.
    Change external IP address to static IP

    1. Locate the external IP in the list and select it.
    2. In the Type dropdown menu, select Static.
  5. Visit your domain provider account and edit your domain settings. You must create an A record that contains your API name, for example, with the external IP address in its data field.

What's next

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

Send feedback about...

Cloud Endpoints with OpenAPI
Need help? Visit our support page.