Serving an API from your domain name

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

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.

Compute Engine

The recommended way to serve an API from Compute Engine instances is to use a load balancer across an instance group. You need to reserve an external IP address 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:

    Go to the External IP Addresses page

    1. Assign any name you want to the reserved IP address
    2. For Type, click Global.
    3. For Attached to, click None. You attach the IP address 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, myapi.example.com with the external IP address in its data field
  3. Create an instance group that includes the instances running your API and Extensible Service Proxy (ESP:

    Go to the Create a New Instance group page

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

    Go to the Create a New HTTP(S) load balancer page

    1. Click Define a Backend Service > Create or select a backend service.
      Backend configuration
    2. Assign any name and description you want for this backend service configuration.
    3. In the Protocol field, select the protocol you want to support through the load balancer, HTTP or HTTPS.
    4. In the Instance group list, click your instance group.
    5. In the Port Numbers field, enter 8080.
    6. Click Health check to configure health checks:
      • Enter a name for the health check configuration.
      • Assign the port 8080.
      • To accept the remaining default values, click Save.
    7. For now, accept the defaults for the rest of the configuration. You can make changes later as needed, such as additional ports.
    8. You don't need to set anything in the Host and path rules; you can forward everything to your backend API by using the default Any unmatched filters. This means that all traffic into the load balancer is directed to the API on the port 8080 (the default port) as defined in the preceding steps.
    9. Click Frontend configuration.
      Frontend configuration
      • In the Protocol field, select the protocol you want to support through the load balancer, HTTP or HTTPS.
      • In the IP list, click the external IP address you created earlier.
      • For the HTTPS protocol, you need to use SSL. In the Certificate list, click the certificate you want.
      • Optionally, if you want to support another protocol, click Add frontend IP and port, specify the protocol, the same external IP address, and a different port.
    10. To create the fully configured load balancer, click Create. 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.
    11. After your DNS changes propagate, requests are sent to your API by using the load balancer.

GKE

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

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
                metadata:
                  name: echo
                spec:
                  ports:
                  - port: 80
                    targetPort: 8081
                    protocol: TCP
                  selector:
                    app: echo-app
                  type: LoadBalancer
                  
    • Change the selector label to match your backend labels (app: echo-app in this example)
    • Make sure the targetPort 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:
                kubectl get services
                
    The output displays an EXTERNAL-IP address similar to the following:
                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.

    Go to the External IP Addresses page

    1. Select your external IP address from the list.
    2. In the Type list, click 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, myapi.example.com, with the external IP address in its data field.

What's next