This page explains how to enable a Secure Sockets Layer (SSL) port when deploying the Extensible Service Proxy (ESP) with Google Kubernetes Engine, Kubernetes, or Compute Engine. You may want to enable an SSL port for your deployed Endpoints service for some use cases. For example, if you are using gRPC's transcoding feature, you might want your service to receive both HTTP 1.1 and gRPC requests on the same port.
Before you begin, make sure that you have already reviewed the tutorials for your chosen service type and environment, and know how to deploy ESP without SSL.
Configuring your SSL keys and certificates
To configure your SSL port to serve HTTPS requests, follow the steps below:
Check to ensure that your SSL key file is named
nginx.key
and your certificate file is namednginx.crt
. For testing, you can generate a self-signednginx.key
andnginx.cert
using OpenSSL with the following command:openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout ./nginx.key -out ./nginx.crt
Specify both
CN
andsubjectAltName
in your server certificate. The value of these attributes should match the DNS or IP used by clients to call your service; otherwise, the SSL handshake will fail.
Enabling SSL for ESP on Kubernetes
To enable the SSL port for ESP on Kubernetes:
Create a Kubernetes secret with your SSL key and certificate:
kubectl create secret generic nginx-ssl \ --from-file=./nginx.crt --from-file=./nginx.key
Edit the Kubernetes configuration files, for example,
esp_echo_gke.yaml
, as shown in the following snippet: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.
Mount the Kubernetes secrets you created as volumes, following the directions in the Kubernetes volumes page.
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.)Start the service with the updated Kubernetes configuration file by using
kubectl
.kubectl apply -f esp_echo_gke.yaml
Update SSL certificates
It is important to update your SSL certificates periodically. To update your SSL certificates, you must perform the following steps:
- Create new certificates, as described in Step 1 above.
- Mount the new certificates to the Kubernetes secrets, as described in Step 3 above.
- Update the ESP Kubernetes deployment, as described in Step 5 above.
Enabling SSL for ESP on Compute Engine
To enable SSL on Compute Engine, first copy the nginx.key
and nginx.crt
files to
your Compute Engine instance's /etc/nginx/ssl
folder, using the following steps:
Run the following command and replace INSTANCE_NAME with the name of your Compute Engine instance:
gcloud compute scp nginx.* INSTANCE-NAME
Connect to the instance using
ssh
.gcloud compute ssh INSTANCE-NAME
In the instance VM box, make the directory and copy in the files:
sudo mkdir -p /etc/esp/ssl
sudo cp server.* /etc/esp/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 \ --ssl_port=443
As compared to the non-SSL
docker run
command, the SSL version of the command creates a different configuration. For example, the SSL command:- Mounts the folder with the key and CRT files to the container by using
--volume
- Uses
--ssl_port=443
to tell ESP to enable SSL on port443
. - Changes the port mapping flag
--publish
.
- Mounts the folder with the key and CRT files to the container by using
Update SSL certificates
It is important to update your SSL certificates periodically. To update your SSL certificates, you must perform the following steps:
- Create new certificates and copy them into VM instances, as described in Step 1 above.
- Copy the new certificates into the
/etc/esp/ssl
directory, as described in Step 3 above. - Stop and restart the ESP container using the
sudo docker run
command, as described in Step 4 above.
Testing the SSL port
To make the testing easier, set the following environment variables:
Set IP_ADDRESS to the IP address of the Compute Engine instance with the new SSL certificate.
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, 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
Alternatively, generate the certificate in pem
format and use the --cacert
option to use the self-signed certificate in curl
, as shown below:
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