Auf dieser Seite wird erläutert, wie Sie einen SSL-Port (Secure Sockets Layer) für die Bereitstellung von Extensible Service Proxy V2 (ESPv2) mit Google Kubernetes Engine, Kubernetes oder Compute Engine aktivieren. Möglicherweise möchten Sie für einige Anwendungsfälle einen SSL-Port für den bereitgestellten Endpoints-Dienst aktivieren.
Lesen Sie, bevor Sie beginnen, die Anleitungen für den ausgewählten Diensttyp und die ausgewählte Umgebung. Außerdem sollten Sie wissen, wie Sie ESPv2 ohne SSL bereitstellen.
SSL-Schlüssel und -Zertifikate konfigurieren
So konfigurieren Sie den SSL-Port für die Bereitstellung von HTTPS-Anfragen:
Prüfen Sie, ob die SSL-Schlüsseldatei den Namen server.key hat und die Zertifikatdatei den Namen server.crt hat. Zu Testzwecken können Sie mithilfe von OpenSSL mit dem folgenden Befehl ein selbst signiertes server.key und server.crt generieren:
Geben Sie in Ihrem Serverzertifikat CN und subjectAltName an. Der Wert dieser Attribute sollte mit dem DNS oder der IP-Adresse übereinstimmen, die von Clients zum Aufrufen Ihres Dienstes verwendet wird. Andernfalls schlägt der SSL-Handshake fehl.
SSL für ESPv2 in Kubernetes aktivieren
So aktivieren Sie den SSL-Port für den ESPv2 in Kubernetes:
Erstellen Sie mit Ihrem SSL-Schlüssel und -Zertifikat ein Kubernetes-Secret:
Hinweis: Sie sehen in dem Konfigurationsbeispiel die zu bearbeitenden Zeilen. Zur Bereitstellung der Datei in Cloud Endpoints ist die vollständige Konfigurationsdatei erforderlich.
Stellen Sie die generierten Kubernetes-Schlüssel als Volumes bereit. Dabei können Sie sich an den Anweisungen zu Volumes auf der Kubernetes-Seite orientieren.
Starten Sie ESPv2 wie unter Startoptionen für ESPv2 festlegen beschrieben. Achten Sie jedoch darauf, das Start-Flag --ssl_server_cert_path hinzuzufügen, um den Pfad für die bereitgestellten Zertifikatsdateien anzugeben.
Starten Sie den Dienst mit der aktualisierten Kubernetes-Konfigurationsdatei über den Befehl kubectl.
kubectl apply -f echo-ssl.yaml
Generieren Sie das Root-Zertifikat für den Client mit folgendem OpenSSL-Befehl:
Wenn der Client curl nutzt, kann die Datei client.pem im Flag --caroot verwendet werden. Für gRPC wird client.pem als Root-Zertifikatsdatei der SSL-Anmeldedaten für den gRPC-Kanal verwendet.
SSL-Zertifikate aktualisieren
SSL-Zertifikate sollten regelmäßig aktualisiert werden.
Zum Aktualisieren von SSL-Zertifikaten führen Sie die folgenden Schritte aus:
Erstellen Sie wie in Schritt 1 oben beschrieben neue Zertifikate.
Stellen Sie die neuen Zertifikate wie in Schritt 3 oben beschrieben für die Kubernetes-Secrets bereit.
Aktualisieren Sie das ESPv2-Kubernetes-Deployment wie in Schritt 5 beschrieben.
Generieren Sie die Root-Zertifikatsdatei des Clients neu, wie in Schritt 6 oben beschrieben.
SSL für ESPv2 in Compute Engine aktivieren
Zum Aktivieren von SSL in Compute Engine kopieren Sie zuerst die Dateien server.key und server.crt in den Ordner /etc/nginx/ssl der Compute Engine-Instanz. Gehen Sie dabei so vor:
Führen Sie den folgenden Befehl aus und ersetzen Sie INSTANCE_NAME durch den Namen Ihrer Compute Engine-Instanz:
gcloud compute scp server.* INSTANCE-NAME
Stellen Sie mit ssh eine Verbindung zur Instanz her.
gcloud compute ssh INSTANCE-NAME
Geben Sie im Feld für die Instanz-VM das Verzeichnis an und kopieren Sie die Dateien:
Im Vergleich zum Befehl docker run ohne SSL erstellt die SSL-Version des Befehls eine andere Konfiguration. Beispiel für den SSL-Befehl:
Der Ordner mit den Schlüssel- und CRT-Dateien wird mit --volume im Container bereitgestellt.
Verwendet --ssl_server_cert_path=/etc/esp/ssl, um ESPv2 mitzuteilen, dass die Serverzertifikatsdateien server.key und server.crt im Ordner /etc/esp/ssl gefunden werden.
Ändert das Flag --publish für die Portzuordnung. Eingehende Anfragen an den HTTPS-Port 443 werden dem ESPv2-Port 9000 zugeordnet.
SSL-Zertifikate aktualisieren
SSL-Zertifikate sollten regelmäßig aktualisiert werden.
Zum Aktualisieren von SSL-Zertifikaten führen Sie die folgenden Schritte aus:
Erstellen Sie neue Zertifikate und kopieren Sie sie wie in Schritt 1 oben beschrieben nach VM-Instanzen.
Kopieren Sie die neuen Zertifikate wie in Schritt 3 oben beschrieben in das Verzeichnis /etc/esp/ssl.
Beenden Sie den ESPv2-Container mit dem Befehl sudo docker run, wie in Schritt 4 oben beschrieben, und starten Sie ihn neu.
SSL-Port testen
Legen Sie die folgenden Umgebungsvariablen fest, um das Testen des SSL-Ports zu erleichtern:
Legen Sie für IP_ADDRESS die IP-Adresse der Compute Engine-Instanz mit dem neuen SSL-Zertifikat fest.
Legen Sie für ENDPOINTS_KEY einen gültigen API-Schlüssel fest.
Nachdem Sie den SSL-Port aktiviert haben, können Sie mithilfe von HTTPS Anfragen an den Extensible Service Proxy senden: Wenn Sie ein selbst signiertes Zertifikat verwenden, aktivieren Sie die unsichere Option in curl mit -k.
Alternativ können Sie das Zertifikat im Format pem generieren und das selbst signierte Zertifikat mithilfe der Option --cacert wie unten dargestellt in curl verwenden:
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-09-04 (UTC)."],[[["\u003cp\u003eThis document provides instructions on how to enable a Secure Sockets Layer (SSL) port for Extensible Service Proxy V2 (ESPv2) deployments on Google Kubernetes Engine, Kubernetes, or Compute Engine.\u003c/p\u003e\n"],["\u003cp\u003eTo use SSL, users must configure self-managed SSL keys and certificates, ensuring that the \u003ccode\u003eserver.key\u003c/code\u003e and \u003ccode\u003eserver.crt\u003c/code\u003e files are correctly named and contain both \u003ccode\u003eCN\u003c/code\u003e and \u003ccode\u003esubjectAltName\u003c/code\u003e matching the DNS or IP of the service.\u003c/p\u003e\n"],["\u003cp\u003eFor Kubernetes, an SSL secret must be created and mounted as a volume to the ESPv2 container, with the ESPv2 startup options updated to include the \u003ccode\u003e--ssl_server_cert_path\u003c/code\u003e flag.\u003c/p\u003e\n"],["\u003cp\u003eOn Compute Engine, the \u003ccode\u003eserver.key\u003c/code\u003e and \u003ccode\u003eserver.crt\u003c/code\u003e files need to be copied to the \u003ccode\u003e/etc/esp/ssl\u003c/code\u003e directory on the instance, and the ESPv2 Docker command must include volume mounting and the \u003ccode\u003e--ssl_server_cert_path\u003c/code\u003e flag.\u003c/p\u003e\n"],["\u003cp\u003eSSL certificates need to be updated periodically by creating new certificates, mounting them to the respective environments (Kubernetes secrets or Compute Engine directories), updating the ESPv2 deployment or container, and regenerating the client root certificate file.\u003c/p\u003e\n"]]],[],null,["# Enabling SSL for Cloud Endpoints with ESPv2\n\nOpenAPI \\| [gRPC](/endpoints/docs/grpc/enabling-ssl-espv2 \"View this page for the Cloud Endpoints gRPC docs\")\n\n\u003cbr /\u003e\n\nThis page explains how to enable a Secure Sockets Layer (SSL) port when deploying Extensible Service Proxy V2\n(ESPv2) with Google Kubernetes Engine, Kubernetes, or\nCompute Engine. You may want to enable an SSL port for your deployed Endpoints service for some use cases.\n\nBefore you begin, make sure that you have already reviewed the [tutorials](/endpoints/docs/openapi/tutorials) for your chosen service type and environment, and know how to deploy\nESPv2 without SSL.\n| **Note:** This tutorial describes how to use *self-managed SSL certificates* with ESPv2. Google-managed SSL certificates aren't currently supported by ESPv2.\n\nConfiguring your SSL keys and certificates\n------------------------------------------\n\nTo configure your SSL port to serve HTTPS requests, follow the steps below:\n\n1. Check to ensure that your SSL key file is named `server.key` and your certificate file is named `server.crt`. For testing, you can generate a self-signed `server.key` and\n `server.crt` using OpenSSL with the following command:\n\n ```\n openssl req -x509 -nodes -days 365 -newkey rsa:2048 \\\n -keyout ./server.key -out ./server.crt\n ```\n2. Specify both `CN` and `subjectAltName` in your server certificate. The value of these attributes\n should match the DNS or IP used by clients to call your service; otherwise, the\n SSL handshake will fail.\n\nEnabling SSL for ESPv2 on Kubernetes\n------------------------------------\n\nTo enable the SSL port for ESPv2 on Kubernetes:\n\n1. Create a Kubernetes secret with your SSL key and certificate:\n\n ```\n kubectl create secret generic esp-ssl \\\n --from-file=./server.crt --from-file=./server.key\n ```\n2. Edit the Kubernetes configuration files, for example, `echo-ssl.yaml`,\n as shown in the following snippet:\n\n template:\n metadata:\n labels:\n app: esp-echo\n spec:\n volumes:\n - name: esp-ssl\n secret:\n secretName: esp-ssl\n containers:\n - name: esp\n image: gcr.io/endpoints-release/endpoints-runtime:2\n args: [\n \"--listener_port\", \"9000\",\n \"--backend\", \"127.0.0.1:8081\",\n \"--service\", \"SERVICE_NAME\",\n \"--rollout_strategy\", \"managed\",\n \"--ssl_server_cert_path\", \"/etc/esp/ssl\",\n ]\n ports:\n - containerPort: 9000\n volumeMounts:\n - mountPath: /etc/esp/ssl\n name: esp-ssl\n readOnly: true\n - name: echo\n image: gcr.io/endpoints-release/echo:latest\n ports:\n - containerPort: 8081\n\n\n **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.\n | **Note:** The ESPv2 container cannot bind to privileged ports, including port 443. Instead, use a Kubernetes Service resource to map 443 to a non-privileged `--listener_port`, such as `9000`.\n3. Mount the Kubernetes secrets you created as volumes, following the\n directions in the [Kubernetes volumes\n page](https://kubernetes.io/docs/concepts/storage/volumes/).\n\n4. Start up ESPv2 as described in\n [Specifying startup options for ESPv2](/endpoints/docs/openapi/specify-esp-v2-startup-options),\n but make sure you add the startup flag `--ssl_server_cert_path` to specify the path for the mounted certificate files.\n\n5. Start the service with the updated Kubernetes configuration file by using `kubectl`.\n\n \u003cbr /\u003e\n\n ```\n kubectl apply -f echo-ssl.yaml\n ```\n\n \u003cbr /\u003e\n\n | **Note:** If you already have an existing [Kubernetes\n | deployment](http://kubernetes.io/docs/user-guide/deployments/), you can [update the deployment](http://kubernetes.io/docs/user-guide/deployments/#updating-a-deployment) directly.\n6. Generate the root certificate for the client by using the following OpenSSL\n command:\n\n \u003cbr /\u003e\n\n ```\n openssl x509 -in ./server.crt -out ./client.pem -outform PEM\n \n ```\n\n \u003cbr /\u003e\n\n If the client is using `curl`, the file `client.pem` can be used in the\n `--caroot` flag. For gRPC, the `client.pem` is used as the root certificate\n file of the SSL credential for gRPC channel.\n\n### Update SSL certificates\n\nIt is important to update your SSL certificates periodically.\nTo update your SSL certificates, you must perform the following steps:\n\n- Create new certificates, as described in Step 1 above.\n- Mount the new certificates to the Kubernetes secrets, as described in Step 3 above.\n- Update the ESPv2 Kubernetes deployment, as described in Step 5 above.\n- Regenerate the client root certificate file, as described in Step 6 above.\n\nEnabling SSL for ESPv2 on Compute Engine\n----------------------------------------\n\nTo enable SSL on Compute Engine, first copy the `server.key` and `server.crt` files to\nyour Compute Engine instance's `/etc/nginx/ssl` folder, using the following steps:\n\n1. Run the following command and replace \u003cvar translate=\"no\"\u003eINSTANCE_NAME\u003c/var\u003e\n with the name of your Compute Engine instance:\n\n ```\n gcloud compute scp server.* INSTANCE-NAME\n ```\n2. Connect to the instance using `ssh`.\n\n ```\n gcloud compute ssh INSTANCE-NAME\n ```\n3. In the instance VM box, make the directory and copy in the files:\n\n sudo mkdir -p /etc/esp/ssl\n sudo cp server.* /etc/esp/ssl/\n\n4. Follow the instructions for your service type to deploy with Docker. When you\n run the ESPv2 Docker container, use this command:\n\n ```\n sudo docker run --name=esp \\\n --detach \\\n --publish=443:9000 \\\n --net=esp_net \\\n --volume=/etc/esp/ssl:/etc/esp/ssl \\\n gcr.io/endpoints-release/endpoints-runtime:2 \\\n --service=SERVICE_NAME \\\n --rollout_strategy=managed \\\n --backend=echo:8080 \\\n --ssl_server_cert_path=/etc/esp/ssl \\\n --listener_port=9000\n ```\n\n As compared to the non-SSL `docker run` command, the SSL version of the\n command creates a different configuration. For example, the SSL command:\n - Mounts the folder with the key and CRT files to the container by using `--volume`.\n - Uses `--ssl_server_cert_path=/etc/esp/ssl` to tell ESPv2 to find the server certificate files `server.key` and `server.crt` in the `/etc/esp/ssl` folder.\n - Changes the port mapping flag `--publish`. Incoming requests to HTTPS port 443 are mapped to ESPv2 port 9000.\n\n | **Note:** The ESPv2 container cannot bind to privileged ports, including port 443. Instead, use the `--publish` flag to map 443 to a non-privileged `--listener_port`, such as `9000`.\n\n### Update SSL certificates\n\nIt is important to update your SSL certificates periodically.\nTo update your SSL certificates, you must perform the following steps:\n\n- Create new certificates and copy them into VM instances, as described in Step 1 above.\n- Copy the new certificates into the `/etc/esp/ssl` directory, as described in Step 3 above.\n- Stop and restart the ESPv2 container using the `sudo docker run` command, as described in Step 4 above.\n\nTesting the SSL port\n--------------------\n\nTo make the testing the SSL port easier, set the following environment variables:\n\n1. Set \u003cvar translate=\"no\"\u003eIP_ADDRESS\u003c/var\u003e to the IP address of the Compute Engine instance with the new SSL certificate.\n\n | **Note:** The example test commands below assume that the server does not yet have a fully qualified domain name (FQDN) and that \u003cvar translate=\"no\"\u003eIP_ADDRESS\u003c/var\u003e has been used as the FQDN when generating the self-signed certificate. When the server does get an FQDN, use the FQDN to generate the certificate. Then, replace \u003cvar translate=\"no\"\u003eIP_ADDRESS\u003c/var\u003e with the FQDN in the example commands below.\n2. Set \u003cvar translate=\"no\"\u003eENDPOINTS_KEY\u003c/var\u003e to a valid [API key](https://console.cloud.google.com/apis/credentials).\n\nOnce the SSL port is enabled, you can use HTTPS to send requests to the\nExtensible Service Proxy. If your certificate is self-signed,\nuse `-k` to turn on the insecure option in `curl`: \n\n```\ncurl -k -d '{\"message\":\"hello world\"}' -H \"content-type:application/json\" \\\nhttps://IP_ADDRESS:443/echo?key=ENDPOINTS_KEY\n```\n\nAlternatively, generate the certificate in `pem` format and use the `--cacert` option to use the self-signed certificate in `curl`, as shown below: \n\n openssl x509 -in server.crt -out client.pem -outform PEM\n curl --cacert \"./client.pem\" -d '{\"message\":\"hello world\"}' -H \"content-type:application/json\" \\\n https://\u003cvar translate=\"no\"\u003eIP_ADDRESS\u003c/var\u003e:443/echo?key=\u003cvar translate=\"no\"\u003eENDPOINTS_KEY\u003c/var\u003e"]]
