Nesta página, você aprende a configurar e executar uma instância do Extensible Service Proxy (ESP) em um computador local, em outro provedor de nuvem como a Amazon Web Services (AWS) ou em um cluster do Kubernetes que não esteja no Google Cloud.
É possível executar o ESP em uma máquina virtual (VM, na sigla em inglês) ou computador Linux ou macOS. O Microsoft Windows não é compatível. É possível implantar o aplicativo e o ESP no mesmo host ou em hosts diferentes. Hospedar uma instância local do ESP permite que você:
- teste o ESP antes de implantá-lo em uma plataforma de produção;
- verifique se as definições de segurança estão configuradas e funcionando corretamente e se as métricas e os registros aparecem na página Endpoints > Serviços conforme o esperado.
Pré-requisitos
Como ponto de partida nesta página, presume-se que você:
Instalou o Docker, se estiver implantando o contêiner do ESP localmente ou em uma VM. Consulte Instalar o Docker para mais informações.
Implantou uma API localmente ou em um host acessível ao host em que o ESP será executado.
Configurou o Cloud Endpoints e implantou a configuração para criar um serviço gerenciado para a API.
Se precisar de uma API para testar com o ESP, configure e implante o código de amostra na seção Opcional: como usar uma API de amostra. Se você já configurou e implantou a API, pule para Como criar uma conta de serviço.
Opcional: como usar uma API de amostra
Esta seção mostra como configurar e implantar a versão Python do
as
getting-started
para Endpoints
uma amostra local. Siga as etapas desta seção somente se não tiver uma API para testar com o ESP.
A amostra getting-started
do Cloud Endpoints está disponível em outras linguagens.
Para localizar getting-started
na linguagem de sua escolha no GitHub, consulte a página "Amostras". Siga as instruções apresentadas no arquivo README.md
da amostra para execução local e siga as instruções nesta seção para configurar e implantar a definição do Endpoints.
Consiga o software necessário
Se você ainda não configurou o ambiente de desenvolvimento Python, veja instruções em Como configurar um ambiente de desenvolvimento Python. Veja se você tem os itens a seguir instalados:
Acessar o exemplo de código
Clone o repositório do app de amostra na máquina local:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples
Acesse o diretório que contém o código de amostra:
cd python-docs-samples/endpoints/getting-started
Configurar o Endpoints
No diretório de código de amostra, abra o arquivo de configuração
openapi.yaml
.No campo
host
, substituaYOUR-PROJECT-ID
pelo próprio ID do projeto do Google Cloud.Salve o arquivo
openapi.yaml
.
Como implantar a configuração do Endpoints
Para implantar a configuração do Endpoints, use o comando gcloud endpoints services deploy
. Ele utiliza o Service Management para criar um serviço gerenciado.
Atualizar a CLI gcloud:
gcloud components update
Verifique se a gcloud CLI (
gcloud
) está autorizada a acessar seus dados e serviços no Google Cloud:gcloud auth login
Na nova guia aberta no navegador, selecione uma conta.
Defina o projeto padrão como o ID do projeto:
gcloud config set project YOUR-PROJECT-ID
Substitua
YOUR-PROJECT-ID
pelo ID do projeto do Google Cloud que você especificou no arquivoopenapi.yaml
.Implante a configuração:
gcloud endpoints services deploy openapi.yaml
O Service Management usa o texto que você especificou no campo host
do arquivo openapi.yaml
para criar um novo serviço do Endpoints com o nome echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog
, se ele não existir, e configura o serviço de acordo com o arquivo de configuração OpenAPI.
Durante a criação e a configuração do serviço, o Service Management envia informações ao terminal. Ignore os avisos sobre os caminhos no arquivo openapi.yaml
que não exigem uma chave de API. Após a conclusão, será exibida uma linha, conforme mostrado a seguir, com o ID de configuração e o nome do serviço entre colchetes:
Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]
No exemplo anterior, 2017-02-13r0
é o ID de configuração do serviço e echo-api.endpoints.example-project-12345.cloud.goog
é o nome do serviço.
Como iniciar o servidor local
Crie um
virtualenv
, ative-o e instale as dependências do aplicativo.virtualenv env
source env/bin/activate
pip install -r requirements.txt
Inicie o servidor:
python main.py
Abra outra janela de terminal e use
curl
para enviar uma solicitação:curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ http://localhost:8080/echo
A mensagem enviada é retornada pela API com a seguinte resposta:
{ "message": "hello world" }
Como criar uma conta de serviço
Para fornecer gerenciamento da API, o ESP e o ESPv2 exigem os serviços do Service Infrastructure. Para chamá-los, o ESP e o ESPv2 precisam usar tokens de acesso. Quando você implanta o ESP ou o ESPv2 nos ambientes do Google Cloud, como o GKE, o Compute Engine ou o ambiente flexível do App Engine, o ESP e o ESPv2 recebem tokens de acesso por meio do serviço de metadados do Google Cloud.
Ao implantar o ESP ou o ESPv2 em um ambiente que não seja do Google Cloud, como seu computador local, um cluster do Kubernetes local ou outro provedor em nuvem, é preciso fornecer um arquivo JSON da conta de serviço que contenha uma chave privada. O ESP e o ESPv2 usam a conta de serviço para gerar tokens de acesso e chamar os serviços necessários para gerenciar a API.
Use o console ou a Google Cloud CLI Para criar a conta de serviço e o arquivo de chave privada:
Console
- No console do Google Cloud, abra a página Contas de serviço .
- Clique em Selecione um projeto.
- Selecione o projeto em que a API foi criada e clique em Abrir.
- Clique em + Criar conta de serviço.
- No campo Nome da conta de serviço, insira o nome para sua conta de serviço.
- Clique em Criar
- Clique em Continuar.
- Clique em Concluído.
- Clique no endereço de e-mail da conta de serviço recém-criada.
- Clique em Chaves.
- Clique em Adicionar chave e em Criar nova chave.
Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.
Armazene o arquivo de chave com segurança, porque ele pode ser usado para autenticar como sua conta de serviço. Mova e renomeie esse arquivo como quiser.
Clique em Fechar.
gcloud
Insira o comando a seguir para exibir os IDs dos seus projetos do Google Cloud:
gcloud projects list
Substitua PROJECT_ID no comando a seguir para definir o projeto que contém sua API como padrão:
gcloud config set project PROJECT_ID
Verifique se a Google Cloud CLI (
gcloud
) tem autorização para acessar seus e serviços no Google Cloud:gcloud auth login
Se você tiver mais de uma conta, escolha a que está no projeto do Google Cloud e que contém a API. Se você executar
gcloud auth list
, a conta selecionada será mostrada como a ativa para o projeto.Para criar uma conta de serviço, execute o seguinte comando e substitua SERVICE_ACCOUNT_NAME e
My Service Account
pelo nome e pelo nome de exibição que você quer usar:gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \ --display-name "My Service Account"
O comando atribui um endereço de e-mail para a conta de serviço no seguinte formato:
SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
Esse endereço de e-mail é necessário nos comandos subsequentes.
Crie um arquivo da chave da conta de serviço:
gcloud iam service-accounts keys create ~/service-account-creds.json \ --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
Adicione os papéis necessários do IAM:
Nesta seção, descrevemos os recursos do IAM que o ESP e o ESPv2 usam, além dos papéis do IAM necessários para que a conta de serviço anexada acesse esses recursos.
Configuração do serviço de endpoint
O ESP e o ESPv2 chamam o Service Control, que usa a configuração do serviço do endpoint. A configuração do serviço do endpoint é um recurso do IAM, e o ESP e o ESPv2 precisam do papel Controlador de serviço para acessá-lo.
O papel do IAM está na configuração do serviço do endpoint, não no projeto. Os projetos podem ter várias configurações de serviço de endpoint.
Use o comando gcloud a seguir para adicionar o papel à conta de serviço anexada na configuração do serviço do endpoint.
gcloud endpoints services add-iam-policy-binding SERVICE_NAME \ --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \ --role roles/servicemanagement.serviceController
Em que
* SERVICE_NAME
é o nome do serviço do endpoint
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com
é a conta de serviço anexada.
Cloud Trace
O ESP e o ESPv2 chamam o serviço
Cloud Trace para
exportar o Trace para um projeto. Esse projeto é chamado de projeto de
rastreamento. No ESP, o projeto de rastreamento e o projeto que tem
a configuração do serviço de endpoint são os mesmos. No ESPv2, o
projeto de rastreamento pode ser especificado pela sinalização --tracing_project_id
e
assume como padrão o projeto de implantação.
O ESP e o ESPv2 exigem o papel Agente do Cloud Trace para ativar o Cloud Trace.
Use o seguinte comando gcloud para adicionar o papel à conta de serviço anexada:
gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \ --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \ --role roles/cloudtrace.agent
Em que
* TRACING_PROJECT_ID é o ID do projeto de rastreamento
.
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID,iam.gserviceaccount.com
é a conta de serviço anexada.
Para mais informações, consulte
O que são funções e permissões?
Consulte
gcloud iam service-accounts
para mais informações sobre os comandos.
Como executar o ESP em um contêiner
Nesta seção, descrevemos como implantar o contêiner do ESP. O procedimento usado depende de onde você implantará o contêiner do ESP:
- Como executar o ESP localmente em um contêiner do Docker ou em outra plataforma
- Como executar o ESP no contêiner em um cluster do Kubernetes
Como executar o ESP no local em um contêiner do Docker ou em outra plataforma
Renomeie o arquivo JSON que contém a chave privada da conta de serviço como
service-account-creds.json
e copie-o para$HOME/Downloads/
se ele tiver sido salvo em um diretório diferente. Dessa forma, o nome do caminho completo corresponde ao valor de--service_account_key
no seguinte comandodocker run
.No comando
docker run
a seguir, substituaYOUR_SERVICE_NAME
pelo nome do seu serviço.
Linux
sudo docker run \ --detach \ --name="esp" \ --net="host" \ --volume=$HOME/Downloads:/esp \ --publish=8082 \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=YOUR_SERVICE_NAME \ --rollout_strategy=managed \ --http_port=8082 \ --backend=localhost:8080 \ --service_account_key=/esp/service-account-creds.json
macOS
A opção --net="host"
do Docker não funciona no macOS.
Em vez disso, é preciso fazer o mapeamento explícito de portas do host no contêiner substituindo --net="host"
por --publish 8082:8082
. Também é necessário substituir localhost
pelo nome de DNS especial, somente para macOS, docker.for.mac.localhost
. Para mais informações, consulte Casos de uso e soluções alternativas (em inglês) na documentação do Docker.
sudo docker run \ --detach \ --name="esp" \ --publish=8082:8082 \ --volume=$HOME/Downloads:/esp \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=YOUR_SERVICE_NAME \ --rollout_strategy=managed \ --http_port=8082 \ --backend=docker.for.mac.localhost:8080 \ --service_account_key=/esp/service-account-creds.json
Outra plataforma
sudo docker run \ --detach \ --name="esp" \ --net="host" \ --volume=$HOME/Downloads:/esp \ --publish=8082 \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=YOUR_SERVICE_NAME \ --rollout_strategy=managed \ --http_port=8082 \ --backend=IP_Address:PORT \ --service_account_key=/esp/service-account-creds.json
Na tabela a seguir, são descritas as opções do Docker usadas nos comandos acima. Para informações sobre as opções de ESP usadas no exemplo, consulte Opções de inicialização do ESP.
Opção | Descrição |
---|---|
--detach
|
Esta opção do Docker inicia o contêiner no modo independente, portanto ele é executado em segundo plano. |
--name="esp"
|
Esta opção do Docker fornece um nome fácil de acessar para o contêiner.
Por exemplo, para ver os registros do contêiner, execute docker logs esp . |
--net="host"
|
Esta opção do Docker indica que o contêiner usa a mesma configuração de rede que a máquina host, permitindo que ele faça chamadas para o localhost na máquina host. Ela não funciona para executar o ESP localmente no macOS. |
--publish=8082:8082
|
No macOS, quando você quiser executar o ESP no local, use esta opção do Docker em vez de --net="host" para fazer o mapeamento explícito de portas do host no contêiner. |
--volume= $HOME/Downloads:/esp
|
Essa opção do Docker mapeia seu diretório $HOME/Downloads local no diretório /esp no contêiner. Esse mapeamento é usado pela opção do ESP --service_account_key . |
Executar o ESP no contêiner em um cluster do Kubernetes
Nesta seção, você aprende a implantar o ESP em um cluster do Kubernetes que não está no Google Cloud.
Para ter a API gerenciada pelo Endpoints, implante o contêiner ESP no mesmo pod do Kubernetes que o contêiner de API. O conjunto de pods que executam o ESP e sua API são agrupados em um serviço do Kubernetes (em inglês) por meio de um seletor de rótulos, como app: my-api
. Esse serviço especifica a política de acesso para balancear a carga de solicitações do cliente na porta do proxy.
Renomeie o arquivo JSON que contém a chave privada da conta de serviço como
service-account-creds.json
e copie-o para$HOME/Downloads/
se ele tiver sido salvo em um diretório diferente. Dessa forma, o nome do caminho completo corresponde ao comando na próxima etapa.Execute o seguinte comando para criar um secret do Kubernetes e ativá-lo como um volume do Kubernetes (ambos em inglês).
kubectl create secret generic service-account-creds \ --from-file=$HOME/Downloads/service-account-creds.json
Se o processo for bem-sucedido, a seguinte mensagem será exibida:
secret "service-account-creds" created
.No arquivo de configuração do Kubernetes, adicione o seguinte, substituindo
YOUR_APP_NAME
pelo nome da API eYOUR_SERVICE_NAME
pelo nome do serviço.spec: replicas: 1 template: metadata: labels: app: "YOUR_APP_NAME" spec: volumes: - name: service-account-creds secret: secretName: service-account-creds containers: - name: esp image: gcr.io/endpoints-release/endpoints-runtime:1 args: [ "--http_port=8082", "--backend=127.0.0.1:8081", "--service=YOUR_SERVICE_NAME", "--rollout_strategy=managed", "--service_account_key=/etc/nginx/creds/service-account-creds.json" ] ports: - containerPort: 8080 volumeMounts: - mountPath: /etc/nginx/creds name: service-account-creds readOnly: true
Para informações sobre as opções de ESP usadas no exemplo, consulte Opções de inicialização do ESP.
Implemente o ESP em Kubernetes. Substitua
YOUR_CONFIGURATION_FILE
pelo nome do arquivo de configuração do Kubernetes.kubectl apply -f YOUR_CONFIGURATION_FILE
Como enviar solicitações
Para confirmar que o arquivo da conta de serviço está correto e que as portas estão mapeadas adequadamente, envie algumas solicitações à API e verifique se elas estão passando pelo ESP. É possível ver os registros do ESP executando este comando:
sudo docker logs esp
Os exemplos a seguir enviam solicitações à API de amostra. Se você não a utiliza, execute testes semelhantes.
Você configurou o contêiner do ESP para receber solicitações na porta 8082
. Se você enviar uma solicitação diretamente ao servidor em http://localhost:8080
, as solicitações ignorarão o ESP. Exemplo:
curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ http://localhost:8080/echo
Resposta:
{ "message": "hello world" }
Quando você envia uma solicitação para http://localhost:8082
, que passa pelo ESP, sem uma chave de API, o ESP a rejeita. Exemplo:
curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ http://localhost:8082/echo
Resposta:
{ "code": 16, "message": "Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.", "details": [ { "@type": "type.googleapis.com/google.rpc.DebugInfo", "stackEntries": [], "detail": "service_control" } ] }
Para testar a API com uma chave de API:
Crie uma chave de API na página de credenciais da API.
Clique em Criar credenciais e selecione Chave de API.
Copie e cole a chave na seguinte instrução de variável de ambiente:
export KEY=AIza...
Envie uma solicitação com a chave:
curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ http://localhost:8082/echo?key=$KEY
Será exibida uma resposta informando que o processo foi bem-sucedido:
{ "message": "hello world" }
Como fazer a limpeza
Encerre e remova o Docker esp
usando a ferramenta docker
:
sudo docker stop esp
sudo docker rm esp