Questa pagina spiega come attivare una porta Secure Sockets Layer (SSL) durante il deployment di Extensible Service Proxy V2 (ESPv2) con Google Kubernetes Engine, Kubernetes o Compute Engine. Per alcuni casi d'uso, potresti voler attivare una porta SSL per il servizio Endpoints di cui è stato eseguito il deployment.
Prima di iniziare, assicurati di aver già esaminato i tutorial per il tipo di servizio e l'ambiente scelti e di sapere come eseguire il deployment
di ESPv2 senza SSL.
Configurazione di chiavi e certificati SSL
Per configurare la porta SSL in modo che gestisca le richieste HTTPS, segui questi passaggi:
Verifica che il file della chiave SSL si chiami server.key e che il file del certificato si chiami server.crt. Per i test, puoi generare un server.key e un server.crt autofirmati utilizzando OpenSSL con il seguente comando:
Specifica sia CN sia subjectAltName nel certificato server. Il valore di questi attributi
deve corrispondere al DNS o all'IP utilizzato dai client per chiamare il servizio; in caso contrario, l'handshake SSL non andrà a buon fine.
Abilitazione di SSL per ESPv2 su Kubernetes
Per abilitare la porta SSL per ESPv2 su Kubernetes:
Crea un secret Kubernetes con la chiave e il certificato SSL:
Nota: l'esempio di configurazione mostra le righe
che devono essere modificate. Per eseguire il deployment del file in Cloud Endpoints, è necessario il file di configurazione completo.
Monta i secret Kubernetes che hai creato come volumi, seguendo le istruzioni nella pagina Volumi Kubernetes.
Avvia ESPv2 come descritto in
Specifica delle opzioni di avvio per ESPv2,
ma assicurati di aggiungere il flag di avvio --ssl_server_cert_path per specificare il percorso dei file di certificato montati.
Avvia il servizio con il file di configurazione Kubernetes aggiornato utilizzando kubectl.
kubectl apply -f echo-ssl.yaml
Genera il certificato radice per il client utilizzando il seguente comando OpenSSL:
Se il client utilizza curl, il file client.pem può essere utilizzato nel
flag --caroot. Per gRPC, client.pem viene utilizzato come file di certificato radice
della credenziale SSL per il canale gRPC.
Aggiorna i certificati SSL
È importante aggiornare periodicamente i certificati SSL.
Per aggiornare i certificati SSL, devi svolgere i seguenti passaggi:
Crea nuovi certificati, come descritto nel passaggio 1.
Monta i nuovi certificati nei secret Kubernetes, come descritto nel passaggio 3 sopra.
Aggiorna il deployment Kubernetes di ESPv2 come descritto nel passaggio 5 precedente.
Rigenera il file del certificato radice client come descritto nel passaggio 6.
Abilitazione di SSL per ESPv2 su Compute Engine
Per abilitare SSL su Compute Engine, copia prima i file server.key e server.crt nella
cartella /etc/nginx/ssl dell'istanza Compute Engine seguendo questi passaggi:
Esegui il comando seguente e sostituisci INSTANCE_NAME
con il nome della tua istanza Compute Engine:
gcloud compute scp server.* INSTANCE-NAME
Connettiti all'istanza utilizzando ssh.
gcloud compute ssh INSTANCE-NAME
Nella casella della VM dell'istanza, crea la directory e copia i file:
Segui le istruzioni per il tuo tipo di servizio per eseguire il deployment con Docker. Quando
esegui il container Docker ESPv2, utilizza questo comando:
Rispetto al comando docker run non SSL, la versione SSL del
comando crea una configurazione diversa. Ad esempio, il comando SSL:
Monta la cartella con i file della chiave e CRT nel container utilizzando
--volume.
Utilizza --ssl_server_cert_path=/etc/esp/ssl per indicare a ESPv2 di trovare
i file di certificato del server server.key e server.crt nella cartella /etc/esp/ssl.
Modifica il flag di mappatura delle porte --publish. Le richieste in entrata alla porta HTTPS 443 vengono mappate alla porta ESPv2 9000.
Aggiorna i certificati SSL
È importante aggiornare periodicamente i certificati SSL.
Per aggiornare i certificati SSL, devi svolgere i seguenti passaggi:
Crea nuovi certificati e copiali nelle istanze VM, come descritto nel passaggio 1.
Copia i nuovi certificati nella directory /etc/esp/ssl, come descritto nel passaggio 3.
Arresta e riavvia il container ESPv2 utilizzando il comando sudo docker run, come descritto nel passaggio 4.
Test della porta SSL
Per semplificare il test della porta SSL, imposta le seguenti variabili di ambiente:
Imposta IP_ADDRESS sull'indirizzo IP dell'istanza Compute Engine con il nuovo certificato SSL.
Una volta attivata la porta SSL, puoi utilizzare HTTPS per inviare richieste a
Extensible Service Proxy. Se il certificato è autofirmato,
utilizza -k per attivare l'opzione non sicura in curl:
In alternativa, genera il certificato in formato pem e utilizza l'opzione --cacert per utilizzare il certificato autofirmato in curl, come mostrato di seguito:
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Difficile da capire","hardToUnderstand","thumb-down"],["Informazioni o codice di esempio errati","incorrectInformationOrSampleCode","thumb-down"],["Mancano le informazioni o gli esempi di cui ho bisogno","missingTheInformationSamplesINeed","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-09-04 UTC."],[[["\u003cp\u003eThis document guides you through enabling a Secure Sockets Layer (SSL) port for Extensible Service Proxy V2 (ESPv2) when deploying with Google Kubernetes Engine, Kubernetes, or Compute Engine.\u003c/p\u003e\n"],["\u003cp\u003eSelf-managed SSL certificates (server.key and server.crt) are required for this process, as Google-managed certificates are not currently supported by ESPv2.\u003c/p\u003e\n"],["\u003cp\u003eFor Kubernetes, you must create a secret with your SSL key and certificate, mount these secrets as volumes, and then specify the path for the mounted files with the \u003ccode\u003e--ssl_server_cert_path\u003c/code\u003e flag when starting ESPv2.\u003c/p\u003e\n"],["\u003cp\u003eFor Compute Engine, you need to copy the SSL key and certificate files to your instance, mount them to the ESPv2 container using \u003ccode\u003e--volume\u003c/code\u003e, and map incoming HTTPS requests on port 443 to a non-privileged listener port, such as 9000, with \u003ccode\u003e--publish\u003c/code\u003e and adjust the \u003ccode\u003essl_server_cert_path\u003c/code\u003e accordingly.\u003c/p\u003e\n"],["\u003cp\u003eUpdating SSL certificates requires creating new certificates, mounting them to secrets (Kubernetes) or copying them to the instance (Compute Engine), and then updating the ESPv2 deployment or restarting the container, along with client root certificate regeneration.\u003c/p\u003e\n"]]],[],null,["# Enabling SSL for Cloud Endpoints with ESPv2\n\n[OpenAPI](/endpoints/docs/openapi/enabling-ssl-espv2 \"View this page for the Cloud Endpoints OpenAPI docs\") \\| gRPC\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/grpc/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/grpc/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"]]
