Enabling SSL for Cloud Endpoints

You might need to enable an SSL port for your deployed Endpoints service: for example, if you are using gRPC's transcoding feature and want your service to receive both HTTP 1.1 and gRPC requests on the same port. This document shows you how to enable the SSL port when deploying the Extensible Service Proxy (ESP) with Google Kubernetes Engine and Kubernetes, or Compute Engine. This document assumes that you've already followed the tutorials for your chosen service type and environment, and know how to deploy without SSL.

SSL keys and certificates

To enable the SSL port so it can serve HTTPS requests, make sure your SSL key and certificate files have the filename nginx.key and nginx.crt, respectively. For testing, you can generate a self-signed nginx.key and nginx.cert by using OpenSSL.

      openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
        -keyout ./nginx.key -out ./nginx.crt

You must specify both CN and subjectAltName in your server certificate. It should match the DNS or IP used by the clients to call your service. Otherwise SSL handshake will fail.

Enabling SSL for ESP on Kubernetes

To enable the SSL port for ESP on Kubernetes:

  1. Create a Kubernetes secret with your SSL key and certificate:

      kubectl create secret generic nginx-ssl \
         --from-file=./nginx.crt --from-file=./nginx.key
  2. Edit the Kubernetes configuration files, for example, esp_echo_gke.yaml, as shown in the following snippet:

          app: esp-echo
        - name: nginx-ssl
            secretName: nginx-ssl
        - name: esp
          image: gcr.io/endpoints-release/endpoints-runtime:1
          args: [
            "--http_port", "8080",
            "--ssl_port", "443",
            "--backend", "",
            "--service", "SERVICE_NAME",
            "--rollout_strategy", "managed",
            - containerPort: 8080
            - containerPort: 443
          - mountPath: /etc/nginx/ssl
            name: nginx-ssl
            readOnly: true
        - name: echo
          image: gcr.io/endpoints-release/echo:latest
            - containerPort: 8081

    Note: The configuration sample displays the lines that need to be edited. To deploy the file to Cloud Endpoints, the complete configuration file is required.

  3. Mount the Kubernetes secrets you created as volumes, following the directions in the Kubernetes volumes page.

  4. Start up ESP as described in Specifying startup options for ESP, but make sure you add the startup flag --ssl_port to enable the SSL port. (Note that the default SSL port is 443.)

  5. Start the service with the updated Kubernetes configuration file by using kubectl.

    kubectl apply -f esp_echo_gke.yaml

Enabling SSL for ESP on Compute Engine

To enable SSL on Compute Engine, first copy the key and crt files to your Compute Engine instance's /etc/nginx/ssl folder, as follows:

  1. Run the following command and replace INSTANCE_NAME with the name of your Compute Engine instance's:

    gcloud compute scp nginx.* INSTANCE-NAME:
  2. Connect to the instance by using ssh.

    gcloud compute ssh INSTANCE-NAME

  3. In the instance VM box, make the directory and copy in the files:

      sudo mkdir -p /etc/nginx/ssl
      sudo cp nginx.* /etc/nginx/ssl/

Follow the instructions for your service type to deploy with Docker. When you run the ESP Docker container, use this command:

 sudo docker run --name=esp \
     --detach \
     --publish=443:443 \
     --net=esp_net \
     --volume=/etc/nginx/ssl:/etc/nginx/ssl \
     --link=echo:echo \
     gcr.io/endpoints-release/endpoints-runtime:1 \
     --service=[SERVICE_NAME] \
     --rollout_strategy=managed \
     --backend=echo:8080 \

When you compare the non-SSL docker run command to the SSL version of the command, there are the following differences:

  • Mount the folder with the key and CRT files to the container by using --volume
  • Use --ssl_port=443 to tell ESP to enable SSL on port 443
  • The port mapping flag --publish is changed

Testing the SSL port

To make the testing easier, set the following environment variables:

  1. Set IP_ADDRESS to the IP address of the Compute Engine instance with the new SSL certificate.

    Note that the two examples assume that the server doesn't have a fully qualified domain name (FQDN) yet, and therefore the implicit assumption is that ${IP_ADDRESS} has been used as the FQDN when generating the self-signed certificate. When the server gets a FQDN, use the FQDN to generate the certificate and then in the two examples below replace ${IP_ADDRESS} with the FQDN.

  2. Set ENDPOINTS_KEY to a valid API key.

Once the SSL port is enabled, you can use HTTPS to send requests to the Extensible Service Proxy. If your certificate is self-signed, either use -k to turn on the insecure option in curl:

curl -k -d '{"message":"hello world"}' -H "content-type:application/json" https://${IP_ADDRESS}:443/echo?key=${ENDPOINTS_KEY}

Or, generate the certificate in pem format and use --cacert option to use the self-signed certificate in curl:

openssl x509 -in nginx.crt -out nginx.pem -outform PEM
curl --cacert "./nginx.pem" -d '{"message":"hello world"}' -H "content-type:application/json" https://${IP_ADDRESS}:443/echo?key=${ENDPOINTS_KEY}

Enabling SSL using Google-managed SSL certificates

GKE support for Google Managed SSL certificates is in beta. Follow the instructions in Using Google-managed SSL certificates to configure SSL.

If you don't want to rely on beta services, you can integrate your ESP on GKE deployment with a Certificate Authority directly. You can use:

For more information, see the Let's Encrypt on GKE tutorial on GitHub.