Getting Started with Endpoints on Kubernetes

This tutorial shows you how to configure and deploy a sample API and the Extensible Service Proxy (ESP) to a Kubernetes cluster. The sample code's REST API is described using the OpenAPI Specification. The tutorial also shows you how to create an API key and use it when sending requests to the API.

The tutorial uses prebuilt container images of the sample code and ESP, which are stored in Google Container Registry. If you are unfamiliar with containers, see the following for more information:

For an overview of Cloud Endpoints, see About Cloud Endpoints and Cloud Endpoints Architecture.

Prerequisites

This tutorial assumes that you already have a Kubernetes cluster setup. For more information, see the Kubernetes Documentation.

Task List

Use the following high-level task list as you work through the tutorial. All tasks in Part 1 are required to successfully send requests to the API.

Before you begin

  1. Sign in to your Google account.

    If you don't already have one, sign up for a new account.

  2. Select or create a Cloud Platform project.

    Go to the Manage resources page

  3. Enable billing for your project.

    Enable billing

  4. Note the GCP project ID, because you'll need it later.

Installing and configuring required software

In this tutorial, you'll install the Google Cloud SDK so that you can use the gcloud command line interface to manage your project. You will use kubectl, a command line interface for running commands against Kubernetes clusters. You will also need a way to test the API. This tutorial uses curl, but you could use an application such as Postman for Google Chrome. On Windows, this tutorial uses PowerShell's built in WebRequest support.

In the following procedure, if you already have the required software installed, continue with the next step.

To install and configure required software

  1. Install curl for testing purposes. On Windows, this tutorial uses PowerShell's built in WebRequest support.
  2. Install and initialize the Cloud SDK.
  3. Update the Cloud SDK and install the Endpoints components:
    gcloud components update
  4. Make sure that Cloud SDK (gcloud) is authorized to access your data and services on Google Cloud Platform:
    gcloud auth login
    A new browser tab opens and you are prompted to choose an account.
  5. Set the default project to your project ID:
    gcloud config set project [YOUR-PROJECT-ID]

    Replace [YOUR-PROJECT-ID] with your project ID. If you have other Cloud Platform projects, and you want to use gcloud to manage them, see Managing Cloud SDK Configurations.

  6. Install kubectl:
    gcloud components install kubectl
  7. 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.

Getting the sample code

To help you get up and running quickly, sample code is provided in several languages.

To get the sample code:

Java

To clone or download the sample API:

  1. Clone the sample app repository to your local machine:
    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

    Alternatively, download the sample as a zip file and extract it.

  2. Change to the directory that contains the sample code:
    cd java-docs-samples/endpoints/getting-started
Python

To clone or download the sample API:

  1. Clone the sample app repository to your local machine:
    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    Alternatively, download the sample as a zip file and extract it.

  2. Change to the directory that contains the sample code:
    cd python-docs-samples/endpoints/getting-started
Go

To clone or download the sample API:

  1. Make sure your GOPATH environment variable is set.
  2. Clone the sample app repository to your local machine:
    go get -u -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
  3. Change to the directory that contains the sample code:
    cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
PHP

To clone or download the sample API:

  1. Clone the sample app repository to your local machine:
    git clone https://github.com/GoogleCloudPlatform/php-docs-samples

    Alternatively, download the sample as a zip file and extract it.

  2. Change to the directory that contains the sample code:
    cd php-docs-samples/endpoints/getting-started
Ruby

To clone or download the sample API:

  1. Clone the sample app repository to your local machine:
    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    Alternatively, download the sample as a zip file and extract it.

  2. Change to the directory that contains the sample code:
    cd ruby-docs-samples/endpoints/getting-started
NodeJS

To clone or download the sample API:

  1. Clone the sample app repository to your local machine:
    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

    Alternatively, download the sample as a zip file and extract it.

  2. Change to the directory that contains the sample code:
    cd nodejs-docs-samples/endpoints/getting-started

Getting the Kubernetes configuration file

  1. Clone the GitHub repository that contains the yaml files used in this tutorial to your local machine:

    git clone https://github.com/googlecloudplatform/endpoints-samples
    

    Alternatively, download the sample as a zip file and extract it.

  2. Change to the directory that contains the configuration files:

    cd endpoints-samples/k8s
    

Configuring Endpoints

The sample code includes the OpenAPI configuration file, openapi.yaml, which is based on OpenAPI Specification v2.0.

To configure Endpoints:
  1. In the sample code directory, open the openapi.yaml configuration file.

    swagger: "2.0"
    info:
      description: "A simple Google Cloud Endpoints API example."
      title: "Endpoints Example"
      version: "1.0.0"
    host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

    Note the following:

    • The configuration sample displays the line that needs to be edited. To deploy openapi.yaml to Cloud Endpoints, the complete configuration file is required.
    • The example openapi.yaml contains a section for configuring authentication that is not needed for this tutorial. You do not need to configure the lines with YOUR-SERVICE-ACCOUNT-EMAIL and YOUR-CLIENT-ID.

  2. In the host field, replace the text with the Cloud Endpoints service name, which should be in the following format:
    host: "echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog"
    

    Replace [YOUR_PROJECT_ID] with your project ID. Do not include the square brackets. For example:

    host: "echo-api.endpoints.example-project.cloud.goog"
    

Note that echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog is the Endpoints service name. It is not the fully qualified domain name (FQDN) that you use for sending requests to the API.

After you have finished all the following configuration steps such that you can successfully send requests to the sample API using an IP address, see Configuring Endpoints DNS for information on how to configure echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog to be the FQDN.

Creating credentials for your service

To provide management for your API, ESP requires the services in Google Service Control and Google Service Management. To call these services, ESP must use access tokens. When you deploy ESP to GCP platforms such as Kubernetes Engine, Compute Engine, or App Engine flexible environment, ESP obtains access tokens through the GCP metadata service.

When you deploy ESP to your local desktop, a Kubernetes cluster, or another platform such as AWS, you must provide ESP with a service account JSON file that contains a private key. ESP uses the service account to generate access tokens to call the services that it needs to manage your API.

To create credentials for your service:

  1. In the Google Cloud Platform, go to Google Service Control API page and click Enable.
  2. In the left-navigation bar, click Credentials.
  3. Under APIs Credentials, click Create credentials, and select Service account key. The Create service account key page displays.
  4. From the Service account drop-down, click New service account.
  5. In the Service account name field, enter: echo-api.endpoints.[YOUR-PROJECT-ID].cloud.goog

    Replace [YOUR-PROJECT-ID] with your project ID. For example:

    echo-api.endpoints.example-project.cloud.goog
  6. Click the Role drop-down.

    You can either select the following roles:

    • Cloud Trace > Cloud Trace Agent
    • Service Management > Service Controller
    • Project > Viewer

    Or, you can select Project > Editor.

  7. For Key type, use the default JSON.
  8. Click Create. The file automatically downloads to your computer.

    If the Create button is not enabled, click the refresh arrow to the right of the Service account ID field. The service account ID automatically updates to ensure that it is unique.

    This creates the service account and downloads its private key to a JSON file. When you start ESP, you specify the full path name of the JSON file in the `--service_account_key` option.

  9. Move the .json file you just downloaded to the endpoints-samples/k8s directory.
  10. Rename the .json file to: service-account-creds.json

Deploying the Endpoints configuration

To deploy the Endpoints configuration, you use Google Service Management, an infrastructure service of Google Cloud Platform that manages other APIs and services, including services created using Cloud Endpoints.

To deploy the Endpoints configuration:

  1. Deploy the service account credentials to the cluster:

    kubectl create secret generic service-account-creds \
      --from-file=service-account-creds.json
    

    On success, you see the message: secret "service-account-creds" created

  2. Invoke the following command:

    gcloud endpoints services deploy openapi.yaml
    

Service Management uses the text that you specified in the host field in the openapi.yaml file to create a new Cloud Endpoints service with the name echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog (if it does not exist), and then configures the service according to your OpenAPI configuration file.

As it is creating and configuring the service, Service Management outputs a great deal of information to the terminal. You can safely ignore the warnings about the paths in openapi.yaml not requiring an API key. 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 [echo-api.endpoints.example-project.cloud.goog]

Deploying the API backend

So far you have deployed the OpenAPI configuration to Service Management, but you have not yet deployed the code that will serve the API backend. This section walks you through deploying the API on Kubernetes.

  1. Display the service configuration ID by invoking the command:

    gcloud endpoints configs list --service=echo-api.endpoints.[PROJECT-ID].cloud.goog
    

    Replace [PROJECT-ID] with your project ID.

  2. Edit the Kubernetes configuration file replacing SERVICE_NAME and SERVICE_CONFIG_ID shown in the snippet below with your service name and the service configuration ID returned in the previous step.

    containers:
      - name: esp
        image: gcr.io/endpoints-release/endpoints-runtime:1
        args: [
          "--http_port", "8080",
          "--backend", "127.0.0.1:8081",
          "--service", "SERVICE_NAME",
          "--version", "SERVICE_CONFIG_ID",
          "--service_account_key", "/etc/nginx/creds/service-account-creds.json",
        ]

    For example:

    containers:
      - name: esp
      image: gcr.io/endpoints-release/endpoints-runtime:1
      args: [
        "--http_port", "8080",
        "--backend", "127.0.0.1:8081",
        "--service", "echo-api.endpoints.example-project.cloud.goog",
        "--version", "2016-12-14r1",
        "--service_account_key", "/etc/nginx/creds/service-account-creds.json",
      ]
    

    For information about the ESP options used above, see Specifying Startup Options for ESP.

  3. Mount the Kubernetes secrets created above as Volumes.

    volumes:
      - name: service-account-creds
        secret:
          secretName: service-account-creds

    volumeMounts:
      - mountPath: /etc/nginx/creds
        name: service-account-creds
        readOnly: true

  4. Start the service:

    kubectl create -f esp_echo_http.yaml
    

You have deployed the Cloud Endpoints Service on Kubernetes.

Get the service's external IP address

If you are using Minikube, skip to Sending a request via IP address.

It can take a few minutes after you start your service in the container before the external IP address is ready.

To view the service's external IP address:

  1. Invoke the command:

    kubectl get service
    
  2. Note the value for EXTERNAL-IP; you'll need it to send requests to the API.

Sending a request via IP address

After the sample API is running in the container cluster, you can send requests to the API.

To send a request to the API:

  1. Create an API key in the API credentials page.

    Create an API key

    1. Click Create credentials, then select API key.

    2. Copy the key, then paste it into the following environment variable statement:

      • In Linux or Mac OS: export ENDPOINTS_KEY=AIza...
      • In Windows PowerShell: $Env:ENDPOINTS_KEY="AIza..."
    3. Send an HTTP request:

      • If you are using minikube:

        • In Linux or Mac OS:

          NODE_PORT=`kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}'`
          MINIKUBE_IP=`minikube ip`
          curl -d '{"message":"hello world"}' -H "content-type:application/json" ${MINIKUBE_IP}:${NODE_PORT}/echo?key=${ENDPOINTS_KEY}
          
        • In Windows Powershell:

          $Env:NODE_PORT=$(kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}')
          $Env:MINIKUBE_IP=$(minikube ip)
          (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://$Env:MINIKUBE_IP:$Env:NODE_PORT/echo?key=$Env:ENDPOINTS_KEY").Content
          
      • Otherwise, use the following curl or Invoke-WebRequest:

        • In Linux or Mac OS:
          curl -d '{"message":"hello world"}' -H "content-type:application/json" "http://[IP_ADDRESS]:80/echo?key=${ENDPOINTS_KEY}"
        • In Windows PowerShell:
          (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://[IP_ADDRESS]:80/echo?key=$Env:ENDPOINTS_KEY").Content

      Replace [IP_ADDRESS] with the external IP address of your instance.

You just deployed and tested an API in Cloud Endpoints!

Tracking API activity

To track API activity:

  1. Look at the activity graphs for your API in the Endpoints page.
    View Endpoints activity graphs
    It may take a few moments for the request to be reflected in the graphs.

  2. Look at the request logs for your API in the Logs Viewer page.
    View Endpoints request logs

Configuring DNS for Endpoints

Because the Cloud Endpoints service name for the API is in the .endpoints.PROJECT-ID.cloud.goog domain, you can use it as the fully qualified domain name (FQDN) by making a small configuration change in your openapi.yaml file. This way, you can send requests to the sample API using echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog instead of the IP address.

To configure Endpoints DNS:

  1. Open your OpenAPI configuration file, openapi.yaml, and add the x-google-endpoints property at the top level of the file (not indented or nested) as shown in the following snippet:
        host: "echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog"
        x-google-endpoints:
        - name: "echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog"
          target: "[IP_ADDRESS]"
    
  2. In the name property, replace [YOUR_PROJECT_ID] with your project ID. Do not include the square brackets.
  3. In the target property, replace [IP_ADDRESS] with the IP address that you used when you sent a request to the sample API. Do not include the square brackets.
  4. Deploy your updated OpenAPI configuration file to Service Management using the following command:
        gcloud endpoints services deploy openapi.yaml
    

For example, assume openapi.yaml has the following configured:

    host: "echo-api.endpoints.example-project.cloud.goog"
    x-google-endpoints:
    - name: "echo-api.endpoints.example-project.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, echo-api.endpoints.my-project-id.cloud.goog, which resolves to the target IP address, 192.0.2.1. Note that it could take a few minutes for the new DNS configuration to propagate.

Sending a request via FQDN

Now that you've got the DNS record configured for the sample API, send a request to it using the FQDN (replace [YOUR_PROJECT_ID] with your project ID):
  • In Linux or Mac OS:
    curl -d '{"message":"hello world"}' -H "content-type:application/json" "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=${ENDPOINTS_KEY}"
  • In Windows PowerShell:
    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID]:80/echo?key=$Env:ENDPOINTS_KEY").Content

Clean up

To avoid incurring charges to your Google Cloud Platform account for the resources used in this quickstart:

  • Delete the Kubernetes service and deployment:

    kubectl delete -f esp_echo_http.yaml
    

See Deleting an API and API Instances for information on stopping the services used by this tutorial.

What's next

Send feedback about...

Cloud Endpoints with OpenAPI