Testar um serviço do Cloud Run localmente

Durante o desenvolvimento, é possível executar e testar a imagem de contêiner localmente, antes da implantação. É possível usar o Cloud Code ou o Docker instalado localmente para executar e testar no local, incluindo a execução local com acesso aos serviços do Google Cloud .

Antes de começar

Se esta é a primeira vez que você está tentando executar localmente, talvez não tenha todas as permissões necessárias para acessar a imagem do seu Container Registry compatível em uso.

Consulte a documentação do Container Registry compatível para saber como ter acesso. É possível configurar o Docker para ter acesso ao Artifact Registry usando o auxiliar de credenciais da gcloud CLI:

gcloud auth configure-docker LOCATION-docker.pkg.dev

Substitua LOCATION pelo nome da região do repositório de contêineres, por exemplo, us-west2.

Atenção: o Container Registry foi descontinuado e está programado para ser desativado. As organizações que não usaram o Container Registry antes de 8 de janeiro de 2024 terão novos repositórios gcr.io hospedados no Artifact Registry por padrão. A partir de 15 de maio de 2024, os projetos Google Cloud sem uso anterior do Container Registry só vão ser compatíveis com a hospedagem e o gerenciamento de imagens para o domínio gcr.io no Artifact Registry.

A desativação do Container Registry está programada para 18 de março de 2025. Para detalhes sobre a descontinuação, consulte Descontinuação do Container Registry.

Testar localmente

É possível testar localmente usando o Docker, o Docker com acesso do Google Cloud , o emulador do Cloud Code ou a CLI do Google Cloud. Selecione a guia apropriada para ver instruções:

Docker

Para testar sua imagem de contêiner localmente usando o Docker, siga estas etapas:

1. Use o comando do Docker:

   PORT=8080 && docker run -p 9090:${PORT} -e PORT=${PORT} IMAGE_URL

   IMAGE_URL por uma referência à imagem de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest; Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

   A variável de ambiente PORT especifica a porta que o aplicativo usará para detectar solicitações HTTP ou HTTPS. Esse é um requisito do contrato do ambiente de execução do contêiner. Neste exemplo, usamos a porta 8080.

   Atenção: usando a conta de serviço padrão:

   Se você depender da conta de serviço padrão ao implantar no Cloud Run, esteja ciente de que ela não está disponível localmente. Portanto, é necessário ter uma conta de serviço junto com um par de chaves públicas/privadas salvo localmente para executar essa imagem localmente com o Docker. Para mais informações, consulte a próxima guia Acesso ao Docker com o Google Cloud.

2. Abra http://localhost:9090 no seu navegador.

Se você tem pouca experiência trabalhando com contêineres, consulte o guia de primeiros passos com o Docker. Para saber mais sobre os comandos do Docker, consulte a documentação do Docker.

Acesso ao Docker com o Google Cloud

Se você estiver usando bibliotecas de cliente Google Cloud para integrar seu aplicativo aos serviços Google Cloud e ainda não tiver protegido esses serviços para controlar o acesso externo, será possível configurar o contêiner local para autenticação com os serviços Google Cloud usando o Application Default Credentials.

Para executar localmente:

1. Consulte as instruções para configurar uma chave de conta de serviço.

   Observação:as chaves de conta de serviço poderão causar problemas de segurança se não forem gerenciadas corretamente. Sempre que possível, escolha uma alternativa mais segura do que as chaves de conta de serviço. Se você precisar autenticar com uma chave de conta de serviço, será responsável pela segurança da chave privada e por outras operações descritas em Práticas recomendadas para gerenciar chaves de contas de serviço. Se não for possível criar uma chave de conta de serviço, a criação pode ser desativada para sua organização. Para mais informações, consulte Gerenciar recursos da organização com segurança por padrão.

   Se você adquiriu a chave de conta de serviço de uma fonte externa, ela precisa ser validada antes do uso. Para mais informações, consulte Requisitos de segurança para credenciais de origem externa.

2. As sinalizações de execução do Docker a seguir injetam as credenciais e a configuração do seu sistema local no contêiner local:

   1. Use a sinalização --volume (-v) para injetar o arquivo de credencial no contêiner (presumindo que você já tenha definido a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS na máquina):

      -v $GOOGLE_APPLICATION_CREDENTIALS:/tmp/keys/FILE_NAME.json:ro

   2. Use a sinalização --environment (-e) para definir a variável GOOGLE_APPLICATION_CREDENTIALS no contêiner:

      -e GOOGLE_APPLICATION_CREDENTIALS=/tmp/keys/FILE_NAME.json

3. Como opção, use este comando run do Docker totalmente configurado:

   PORT=8080 && docker run \
   -p 9090:${PORT} \
   -e PORT=${PORT} \
   -e K_SERVICE=dev \
   -e K_CONFIGURATION=dev \
   -e K_REVISION=dev-00001 \
   -e GOOGLE_APPLICATION_CREDENTIALS=/tmp/keys/FILE_NAME.json \
   -v $GOOGLE_APPLICATION_CREDENTIALS:/tmp/keys/FILE_NAME.json:ro \
   IMAGE_URL

   Observe que o caminho

   /tmp/keys/FILE_NAME.json

   mostrado no exemplo acima é um local razoável para colocar suas credenciais no contêiner.

   No entanto, outros locais de diretório também funcionarão. O requisito crucial é que a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS precisa corresponder ao local de ativação da vinculação dentro do contêiner.

   Além disso, com alguns Google Cloud serviços, convém usar uma configuração alternativa para isolar a solução de problemas local do desempenho e dos dados de produção.

Emulador do Cloud Code

O plug-in do Cloud Code para os ambientes de desenvolvimento integrado do VS Code e da JetBrains permite executar e depurar localmente sua imagem de contêiner em um emulador do Cloud Run no seu ambiente de desenvolvimento integrado. O emulador permite configurar um ambiente que representa o serviço em execução no Cloud Run.

É possível configurar propriedades como alocação de memória e CPU, especificar variáveis de ambiente e definir conexões de banco de dados do Cloud SQL.

1. Instale o Cloud Code em um ambiente de desenvolvimento integrado do VS Code ou da JetBrains (links em inglês).
2. Siga as instruções para desenvolver e depurar localmente no ambiente de desenvolvimento integrado.
3. VS Code: desenvolvimento e depuração no local
4. IntelliJ: desenvolvimento e depuração no local

CLI da gcloud

A Google Cloud CLI contém um ambiente de desenvolvimento local para emular o Cloud Run. Ele pode criar um contêiner a partir da origem, executar o contêiner na máquina local e recriar o contêiner automaticamente quando o código-fonte é alterado.

Para iniciar o ambiente de desenvolvimento local, siga estas etapas:

1. Altere o diretório para o diretório que contém o código-fonte do seu serviço.

2. Chame o comando:

   gcloud beta code dev

   Se houver um Dockerfile no diretório local, ele será usado para criar o contêiner. Se nenhum Dockerfile estiver presente, o contêiner será criado com os buildpacks do Google Cloud.

Para ver o serviço em execução, acesse http://localhost:8080/ no seu navegador. Caso tenha especificado uma porta personalizada com a opção --local-port, lembre-se de abrir seu navegador para ela.

Para interromper o servidor local:

• Mac OS e Linux: Control-C
• Windows: Control-Break

Personalizar a configuração do serviço

É possível personalizar a configuração do Cloud Run do serviço em execução localmente usando um arquivo YAML. O formato YAML é o mesmo que pode ser usado para implantar um serviço do Cloud Run, mas é suportado apenas por um subconjunto das configurações do serviço do Cloud Run. O gcloud beta code dev procura e usa qualquer arquivo que termine em *.service.dev.yaml no diretório atual. Se nenhum for encontrado, ele usará qualquer arquivo que termine com *.service.yaml.

É possível definir as seguintes configurações para desenvolvimento local:

• Variáveis de ambiente
• Limites de memória do contêiner
• Limites de CPU do contêiner
• Nome do serviço
• Contas de serviço

O campo de contêiner image não é obrigatório para o desenvolvimento local, porque a imagem é criada e fornecida ao serviço quando o comando é executado.

Use o exemplo de arquivo service.dev.yaml a seguir para desenvolvimento local:

  apiVersion: serving.knative.dev/v1
  kind: Service
  metadata:
    name: my-service-name
  spec:
    template:
      spec:
        containers:
        - env:
          - name: FOO
            value: bar

Testar usando credenciais

Para conceder permissão ao contêiner para usar serviços Google Cloud , você precisa fornecer a ele uma credencial de acesso.

• Para conceder ao contêiner acesso a uma credencial usando sua própria conta, faça login usando gcloud e use a sinalização --application-default-credential:

  gcloud auth application-default login
  gcloud beta code dev --dockerfile=PATH_TO_DOCKERFILE --application-default-credential

• Para fornecer as credenciais do aplicativo como uma conta de serviço, use a sinalização --service-account:

  gcloud beta code dev --dockerfile=PATH_TO_DOCKERFILE --service-account=SERVICE_ACCOUNT_EMAIL

  Observação:a flag --service-account faz o download e o armazenamento em cache de uma chave de conta de serviço localmente. As chaves da conta de serviço são um risco de segurança quando não são gerenciadas corretamente. Sempre que possível, escolha uma alternativa mais segura para as chaves de conta de serviço. Caso seja necessário autenticar com uma chave de conta de serviço, você será responsável pela segurança da chave privada e por outras operações descritas em Práticas recomendadas para gerenciar chaves de contas de serviço. Se não for possível criar uma chave de conta de serviço, a criação pode ser desativada para sua organização. Para mais informações, consulte Gerenciar recursos da organização com segurança por padrão.

  Se você adquiriu a chave de conta de serviço de uma fonte externa, ela precisa ser validada antes do uso. Para mais informações, consulte Requisitos de segurança para credenciais de origem externa.

Confirmar se o código está sendo executado localmente

Ao testar localmente no Cloud Run, é possível confirmar no código que o contêiner está sendo executado localmente verificando a variável de ambiente K_REVISION, que o Cloud Run disponibiliza para todos os contêineres.

Docker

Para confirmar se você está executando seu código localmente na Google Cloud CLI, tente consultar a variável de ambiente K_REVISION. No entanto, como ela não foi definida, nenhum valor estará presente.

Acesso ao Docker com o Google Cloud

Se você usou os valores exatos da seção acima na etapa 3 para confirmar que está executando o código localmente na CLI do Google Cloud, consulte a variável de ambiente K_REVISION e procure o valor dev-00001 para confirmar se ele está sendo executado localmente.

Emulador do Cloud Code

Para confirmar se você está executando seu código localmente no Cloud Code, consulte a variável de ambiente K_REVISION e procure um valor de local para confirmar se ele está sendo executado localmente.

CLI da gcloud

Para confirmar se você está executando seu código localmente na CLI do Google Cloud, consulte a variável de ambiente K_REVISION e procure um valor que comece com dev- para confirmar se ele está sendo executado localmente.

A seguir

• Para saber como solucionar problemas de um aplicativo do Cloud Run com falha localmente, consulte o tutorial Solução de problemas locais de um serviço do Cloud Run.
• Para saber como implantar seus contêineres criados, veja Como implantar serviços.