Cette page explique comment activer un port SSL (Secure Sockets Layer) lors du déploiement d'Extensible Service Proxy V2 (ESPv2) avec Google Kubernetes Engine, Kubernetes ou Compute Engine. Vous pouvez activer un port SSL pour votre service Endpoints déployé dans certains cas d'utilisation.
Avant de commencer, assurez-vous d'avoir déjà consulté les tutoriels sur le type de service et l'environnement que vous avez choisis, et de savoir comment déployer ESPv2 sans SSL.
Configurer vos clés et certificats SSL
Pour configurer votre port SSL afin qu'il diffuse les requêtes HTTPS, procédez comme suit :
Assurez-vous que votre fichier de clé SSL est nommé server.key et que votre fichier de certificat s'appelle server.crt. Pour les tests, vous pouvez générer des fichiers autosignés server.key et server.crt à l'aide d'OpenSSL à l'aide de la commande suivante :
Indiquez à la fois CN et subjectAltName dans votre certificat de serveur. La valeur de ces attributs doit correspondre au DNS ou à l'adresse IP utilisés par les clients pour appeler votre service. Sinon, le handshake SSL échouera.
Activer SSL pour ESPv2 sur Kubernetes
Pour activer le port SSL pour ESPv2 sur Kubernetes, procédez comme suit :
Créez un secret Kubernetes contenant la clé et le certificat SSL :
Remarque : L'exemple de configuration affiche les lignes à modifier. Le fichier de configuration complet est nécessaire au déploiement du fichier sur Cloud Endpoints.
Installez les codes secrets Kubernetes créés en tant que volumes, à l'aide des instructions de la page relative aux Volumes Kubernetes.
Démarrez ESPv2, comme décrit dans la section Spécifier des options de démarrage pour ESPv2. N'oubliez pas d'ajouter l'option de démarrage --ssl_server_cert_path pour spécifier le chemin d'accès aux fichiers de certificat installés.
Démarrez le service avec le fichier de configuration Kubernetes mis à jour à l'aide de kubectl.
kubectl apply -f echo-ssl.yaml
Générez le certificat racine du client à l'aide de la commande OpenSSL suivante :
Si le client utilise curl, le fichier client.pem peut être spécifié avec l'option --caroot. Pour gRPC, client.pem est utilisé comme fichier du certificat racine pour l'identifiant SSL du canal gRPC.
Mettre à jour les certificats SSL
Il est important de mettre régulièrement à jour vos certificats SSL.
Pour mettre à jour vos certificats SSL, procédez comme suit :
Créez des certificats, comme décrit à l'étape 1 ci-dessus.
Installez les nouveaux certificats sur les secrets Kubernetes, comme décrit à l'étape 3 ci-dessus.
Mettez à jour le déploiement Kubernetes ESPv2, comme décrit à l'étape 5 ci-dessus.
Générez un nouveau fichier de certificat racine du client, comme décrit à l'étape 6 ci-dessus.
Activer SSL pour ESPv2 sur Compute Engine
Pour activer SSL sur Compute Engine, commencez par copier les fichiers server.key et server.crt dans le dossier /etc/nginx/ssl de l'instance Compute Engine, comme suit :
Exécutez la commande suivante et remplacez INSTANCE_NAME par le nom de l'instance Compute Engine :
gcloud compute scp server.* INSTANCE-NAME
Connectez-vous à l'instance via ssh.
gcloud compute ssh INSTANCE-NAME
Dans la zone d'instance de VM, créez le répertoire et copiez-y les fichiers :
Suivez les instructions applicables à votre type de service pour effectuer un déploiement avec Docker. Lorsque vous exécutez le conteneur Docker d'ESPv2, utilisez la commande suivante :
Par rapport à la commande non SSL docker run, la version SSL de la commande crée une configuration différente. Par exemple, la commande SSL :
installe le dossier contenant les fichiers de clé et CRT dans le conteneur à l'aide de --volume ;
fait appel à --ssl_server_cert_path=/etc/esp/ssl pour indiquer à ESPv2 de chercher les fichiers de certificat du serveur server.key et server.crt dans le dossier /etc/esp/ssl ;
modifie l'option de mappage de port --publish. Les requêtes entrantes vers le port HTTPS 443 sont mappées sur le port 9000 d'ESPv2.
Mettre à jour les certificats SSL
Il est important de mettre régulièrement à jour vos certificats SSL.
Pour mettre à jour vos certificats SSL, procédez comme suit:
Créez des certificats et copiez-les dans des instances de VM, comme décrit à l'étape 1 ci-dessus.
Copiez les nouveaux certificats dans le répertoire /etc/esp/ssl, comme décrit à l'étape 3 ci-dessus.
Arrêtez et redémarrez le conteneur ESPv2 à l'aide de la commande sudo docker run, comme décrit à l'étape 4 ci-dessus.
Tester le port SSL
Pour faciliter le test du port SSL, définissez les variables d'environnement suivantes :
Définissez IP_ADDRESS sur l'adresse IP de l'instance Compute Engine avec le nouveau certificat SSL.
Une fois le port SSL activé, vous pouvez utiliser HTTPS pour envoyer des requêtes à Extensible Service Proxy. Si votre certificat est autosigné, utilisez -k pour activer l'option non sécurisée dans la commande curl :
Vous pouvez également générer le certificat au format pem et vous servir de l'option --cacert pour utiliser le certificat autosigné dans le fichier curl, comme indiqué ci-dessous :
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/09/04 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Difficile à comprendre","hardToUnderstand","thumb-down"],["Informations ou exemple de code incorrects","incorrectInformationOrSampleCode","thumb-down"],["Il n'y a pas l'information/les exemples dont j'ai besoin","missingTheInformationSamplesINeed","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 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"]]
