Ativar SSL para o Cloud Endpoints com o ESPv2

OpenAPI   |  gRPC

Esta página explica como ativar uma porta da camada Secure Sockets Layer (SSL) ao implementar o Extensible Service Proxy V2 (ESPv2) com o Google Kubernetes Engine, o Kubernetes ou o Compute Engine. Pode querer ativar uma porta SSL para o seu serviço de Endpoints implementado para alguns exemplos de utilização.

Antes de começar, certifique-se de que já reviu os tutoriais para o tipo de serviço e o ambiente escolhidos, e sabe como implementar o ESPv2 sem SSL.

Nota: este tutorial descreve como usar certificados SSL autogeridos com o ESPv2. Atualmente, os certificados SSL geridos pela Google não são suportados pelo ESPv2.

Configurar as chaves e os certificados SSL

Para configurar a porta SSL para processar pedidos HTTPS, siga os passos abaixo:

1. Verifique se o nome do ficheiro de chave SSL é server.key e o nome do ficheiro de certificado é server.crt. Para testes, pode gerar um server.key autoassinado e server.crt através do OpenSSL com o seguinte comando:

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

2. Especifique CN e subjectAltName no certificado do servidor. O valor destes atributos deve corresponder ao DNS ou ao IP usado pelos clientes para chamar o seu serviço; caso contrário, a sincronização SSL falha.

Ativar SSL para o ESPv2 no Kubernetes

Para ativar a porta SSL para o ESPv2 no Kubernetes:

1. Crie um segredo do Kubernetes com a sua chave e certificado SSL:

   kubectl create secret generic esp-ssl \
     --from-file=./server.crt --from-file=./server.key

2. Edite os ficheiros de configuração do Kubernetes, por exemplo, echo-ssl.yaml, conforme mostrado no fragmento seguinte:

   template:
     metadata:
       labels:
         app: esp-echo
     spec:
       volumes:
       - name: esp-ssl
         secret:
           secretName: esp-ssl
       containers:
       - name: esp
         image: gcr.io/endpoints-release/endpoints-runtime:2
         args: [
           "--listener_port", "9000",
           "--backend", "127.0.0.1:8081",
           "--service", "SERVICE_NAME",
           "--rollout_strategy", "managed",
           "--ssl_server_cert_path", "/etc/esp/ssl",
         ]
         ports:
           - containerPort: 9000
         volumeMounts:
         - mountPath: /etc/esp/ssl
           name: esp-ssl
           readOnly: true
       - name: echo
         image: gcr.io/endpoints-release/echo:latest
         ports:
           - containerPort: 8081

   Nota: o exemplo de configuração apresenta as linhas que têm de ser editadas. Para implementar o ficheiro nos Cloud Endpoints, é necessário o ficheiro de configuração completo.

   Nota: o contentor ESPv2 não pode ser associado a portas privilegiadas, incluindo a porta 443. Em alternativa, use um recurso de serviço do Kubernetes para mapear a porta 443 para uma porta não privilegiada --listener_port, como 9000.

3. Monte os segredos do Kubernetes que criou como volumes, seguindo as instruções na página de volumes do Kubernetes.

4. Inicie o ESPv2 conforme descrito em Especificar opções de arranque para o ESPv2, mas certifique-se de que adiciona a flag de arranque --ssl_server_cert_path para especificar o caminho para os ficheiros de certificados montados.

5. Inicie o serviço com o ficheiro de configuração do Kubernetes atualizado através de kubectl.

   kubectl apply -f echo-ssl.yaml

   Nota: se já tiver uma implementação do Kubernetes, pode atualizar a implementação diretamente.

6. Gere o certificado de raiz para o cliente através do seguinte comando OpenSSL:

      openssl x509 -in ./server.crt -out ./client.pem -outform PEM
    

   Se o cliente estiver a usar o curl, o ficheiro client.pem pode ser usado na flag --caroot. Para o gRPC, o client.pem é usado como o ficheiro de certificado de raiz da credencial SSL para o canal gRPC.

Atualize certificados SSL

É importante atualizar os seus certificados SSL periodicamente. Para atualizar os seus certificados SSL, tem de seguir estes passos:

• Crie novos certificados, conforme descrito no Passo 1 acima.
• Monte os novos certificados nos segredos do Kubernetes, conforme descrito no Passo 3 acima.
• Atualize a implementação do Kubernetes do ESPv2, conforme descrito no passo 5 acima.
• Volte a gerar o ficheiro do certificado de raiz do cliente, conforme descrito no Passo 6 acima.

Ativar SSL para o ESPv2 no Compute Engine

Para ativar o SSL no Compute Engine, copie primeiro os ficheiros server.key e server.crt para a pasta /etc/nginx/ssl da instância do Compute Engine através dos seguintes passos:

1. Execute o seguinte comando e substitua INSTANCE_NAME pelo nome da sua instância do Compute Engine:

   gcloud compute scp server.* INSTANCE-NAME
   

2. Ligue-se à instância através de ssh.

   gcloud compute ssh INSTANCE-NAME
   

3. Na caixa da VM da instância, crie o diretório e copie os ficheiros:

     sudo mkdir -p /etc/esp/ssl
     sudo cp server.* /etc/esp/ssl/

4. Siga as instruções para o seu tipo de serviço para fazer a implementação com o Docker. Quando executar o contentor Docker do ESPv2, use este comando:

   sudo docker run --name=esp \
    --detach \
    --publish=443:9000 \
    --net=esp_net \
    --volume=/etc/esp/ssl:/etc/esp/ssl \
     gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=echo:8080 \
    --ssl_server_cert_path=/etc/esp/ssl \
    --listener_port=9000

   Em comparação com o comando docker run não SSL, a versão SSL do comando cria uma configuração diferente. Por exemplo, o comando SSL:

   • Monta a pasta com os ficheiros KEY e CRT no contentor através de --volume.
   • Usa --ssl_server_cert_path=/etc/esp/ssl para indicar ao ESPv2 que encontre os ficheiros de certificado do servidor server.key e server.crt na pasta /etc/esp/ssl.

   • Altera a flag de mapeamento de portas --publish. Os pedidos recebidos para a porta HTTPS 443 são mapeados para a porta ESPv2 9000.

     Nota: o contentor ESPv2 não pode ser associado a portas privilegiadas, incluindo a porta 443. Em alternativa, use a flag --publish para mapear 443 para uma porta não privilegiada --listener_port, como 9000.

Atualize certificados SSL

É importante atualizar os seus certificados SSL periodicamente. Para atualizar os seus certificados SSL, tem de seguir estes passos:

• Crie novos certificados e copie-os para instâncias de VM, conforme descrito no Passo 1 acima.
• Copie os novos certificados para o diretório /etc/esp/ssl, conforme descrito no passo 3 acima.
• Pare e reinicie o contentor do ESPv2 com o comando sudo docker run, conforme descrito no passo 4 acima.

Testar a porta SSL

Para facilitar o teste da porta SSL, defina as seguintes variáveis de ambiente:

1. Defina IP_ADDRESS para o endereço IP da instância do Compute Engine com o novo certificado SSL.

   Nota: os comandos de teste de exemplo abaixo partem do princípio de que o servidor ainda não tem um nome de domínio totalmente qualificado (FQDN) e que IP_ADDRESS foi usado como o FQDN ao gerar o certificado autoassinado. Quando o servidor obtiver um FQDN, use o FQDN para gerar o certificado. Em seguida, substitua IP_ADDRESS pelo FQDN nos comandos de exemplo abaixo.

2. Defina ENDPOINTS_KEY como uma chave da API válida.

Assim que a porta SSL estiver ativada, pode usar HTTPS para enviar pedidos para o Extensible Service Proxy. Se o seu certificado for autoassinado, use -k para ativar a opção não segura em curl:

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

Em alternativa, gere o certificado no formato pem e use a opção --cacert para usar o certificado autoassinado em curl, conforme mostrado abaixo:

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