Resolver problemas do Cloud Run com SSH

O SSH permite estabelecer uma conexão de shell segura e interativa com as instâncias de contêiner em execução. Isso fornece acesso direto ao sistema de arquivos e ao ambiente de execução do contêiner, permitindo que você inspecione recursos do sistema, verifique configurações e resolva problemas.

O SSH para Cloud Run usa os seguintes serviços para proteger as conexões:

  • O encaminhamento de TCP do Identity-Aware Proxy atua como proxy para conexões SSH. Assim, as solicitações precisam passar por verificações de autenticação e autorização antes de chegar ao contêiner. É possível estender as políticas de acesso do IAP com o acesso baseado no contexto para restringir o acesso com base em atributos como endereço IP e dispositivo do usuário final.
  • O Login do SO usa a autenticação de certificado SSH para autenticar usuários. Quando você se conecta, a CLI gcloud gera um certificado SSH de curta duração que expira após cinco minutos. O certificado é validado dentro do contêiner. O Google verifica as permissões do IAM em cada tentativa de login.

O SSH para Cloud Run adiciona automaticamente os binários gerenciados pelo Google necessários, incluindo sshd e os binários que validam seu certificado, ao sistema de arquivos do contêiner. Esses binários só podem ser acessados durante a sessão SSH e são removidos quando ela termina. As configurações de SSH atuais, incluindo as entradas /etc/passwd, são ignoradas pelo SSH do Cloud Run em favor das configurações gerenciadas pelo Google.

Os avisos de direitos autorais de código aberto de terceiros para dependências SSH gerenciadas pelo Google são montados dentro do contêiner quando uma sessão SSH é estabelecida no seguinte caminho: /usr/share/licenses/google_ssh/THIRD_PARTY_NOTICES.

Sessões SSH e instâncias de serviço

Ao se conectar a um serviço usando SSH, observe o seguinte:

  • Se nenhuma instância do serviço estiver em execução, o Cloud Run vai iniciar uma nova instância para a sessão SSH.
  • O Cloud Run visa manter a instância de serviço ativa durante a sessão SSH. Você vai receber uma cobrança pela instância como de costume enquanto ela estiver ativa.

Limitações

As seguintes limitações se aplicam ao SSH:

  • As sessões SSH duram no máximo 24 horas. Após 24 horas, a sessão é desconectada e você precisa se reconectar.
  • O IAP desconecta as sessões SSH após uma hora de inatividade. Para mais informações, consulte Limitações conhecidas do encaminhamento de TCP do IAP.
  • O SSH só está disponível para serviços executados no ambiente de segunda geração do Cloud Run e em instâncias do Cloud Run.
  • Ao usar SSH, as chaves de host na imagem são substituídas. As chaves permanecem substituídas após o término da sessão SSH, até que a instância de serviço seja reiniciada.
  • Windows: o PuTTY não é compatível. Use o cliente OpenSSH.
  • É preciso ter cuidado extra para proteger o contêiner ao usar o SSH. Considere as práticas recomendadas de segurança, como executar o código do aplicativo como um usuário não raiz.
  • Quando uma conexão SSH inicia a frio um serviço de vários contêineres com ordem de inicialização de contêiner (container-dependencies), a solicitação é roteada antes que o ambiente do contêiner esteja pronto. O Cloud Run retorna um erro HTTP 500 e interrompe imediatamente a nova instância. Se você se conectar usando a Google Cloud CLI, o comando vai falhar. Para contornar esse problema, conecte-se usando SSH somente quando uma instância já estiver em execução. Por exemplo, envie uma solicitação ao serviço primeiro para iniciar uma instância ou configure instâncias mínimas.

Antes de começar

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Ative a API Cloud Run Admin, Cloud Resource Manager, Identity-Aware Proxy e Login do SO do Cloud: 
      gcloud services enable run.googleapis.com \
      cloudresourcemanager.googleapis.com \
      iap.googleapis.com \
      oslogin.googleapis.com
  7. Instale e inicialize a CLI gcloud.
  8. Atualize os componentes: 
    gcloud components update
  9. Windows:verifique se o cliente OpenSSH está instalado.

    O cliente OpenSSH geralmente é instalado por padrão no Windows 10 e versões mais recentes. Se não estiver instalado, execute o seguinte comando no PowerShell como administrador:

    Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0

    Para mais informações, consulte Instalar o OpenSSH.

  10. Consulte a página de preços do Cloud Run. Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. O SSH cobra por bytes de saída de rede. Você também vai receber cobranças normais pela instância enquanto ela estiver ativa para uma sessão SSH.
  11. Se o projeto usa o VPC Service Controls (VPC-SC), o processo de tunelamento verifica iaptunnel.googleapis.com como o nome do serviço, em vez de run.googleapis.com.

Funções exigidas

Para receber as permissões necessárias para concluir estas etapas, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Se você não for membro da organização de que o projeto faz parte, o Cloud Run bloqueará o acesso SSH. Para ter acesso SSH, adicione o papel roles/compute.osLoginExternalUser ou use um papel personalizado com a permissão compute.oslogin.updateExternalUser.

É possível conceder o papel de usuário do túnel protegido pelo IAP no nível do projeto. Para restringir esse papel a um serviço ou uma instância específica do Cloud Run, execute o seguinte comando:

Para um serviço específico 

gcloud beta iap tcp add-iam-policy-binding \
    --resource-type=cloud-run \
    --service=SERVICE \
    --region=REGION \
    --member=MEMBER \
    --role=roles/iap.tunnelResourceAccessor

Substitua:

  • SERVICE: o nome do serviço.
  • REGION: a região em que o serviço está implantado.
  • MEMBER: a identidade que vai receber acesso.

Para uma instância específica 

gcloud beta iap tcp add-iam-policy-binding \
    --resource-type=cloud-run \
    --instance=INSTANCE \
    --region=REGION \
    --member=MEMBER \
    --role=roles/iap.tunnelResourceAccessor

Substitua:

  • INSTANCE: o nome da instância.
  • REGION: a região em que o serviço está implantado.
  • MEMBER: a identidade que vai receber acesso.

Para conceder o roles/iap.tunnelResourceAccessor no nível do projeto e da região, consulte Configurar políticas de acesso do IAP.

Usar SSH com serviços do Cloud Run

Configurar o acesso SSH no nível do serviço e se conectar ao serviço usando SSH.

Configurar o acesso SSH no nível do serviço

É possível permitir o acesso de inspeção em um serviço específico usando a CLI gcloud ou o YAML:

gcloud

Para ativar o acesso em um serviço, use o seguinte comando:

gcloud beta run services update SERVICE --ssh

Também é possível permitir o acesso de inspeção em um serviço usando a flag --ssh ao implantar o serviço.

YAML

  1. Se você estiver criando um novo serviço, pule esta etapa. Se você estiver atualizando um serviço existente, faça o download da configuração YAML correspondente:

    gcloud run services describe SERVICE --format export > service.yaml

  2. O exemplo a seguir contém a configuração YAML:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  labels:
    cloud.googleapis.com/location: REGION
  annotations:
    run.googleapis.com/ssh-enabled: "true"
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    spec:
      containers:
        image: IMAGE_URL

    Substitua:

    • SERVICE: o nome do serviço do Cloud Run.
    • REGION: a região do Google Cloud . Por exemplo, us-central1.
    • IMAGE_URL: uma referência à imagem do 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 segue o formato de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

  3. Crie ou atualize o serviço usando o seguinte comando:

    gcloud run services replace service.yaml

    O comando gcloud run services replace usa o arquivo service.yaml por padrão, se ele estiver presente.

É possível desativar o acesso SSH por serviço usando a CLI gcloud ou YAML:

gcloud

Para desativar o acesso no serviço, use o seguinte comando:

gcloud beta run services update SERVICE --no-ssh

YAML

  1. Se você estiver criando um novo serviço, pule esta etapa. Se você estiver atualizando um serviço existente, faça o download da configuração YAML correspondente:

    gcloud run services describe SERVICE --format export > service.yaml

  2. O exemplo a seguir contém a configuração YAML:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  labels:
    cloud.googleapis.com/location: REGION
  annotations:
    run.googleapis.com/ssh-enabled: "false"
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    spec:
      containers:
        image: IMAGE_URL

    Substitua:

    • SERVICE: o nome do serviço do Cloud Run.
    • REGION: a região do Google Cloud . Por exemplo, us-central1.
    • IMAGE_URL: uma referência à imagem do 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 segue o formato de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

  3. Crie ou atualize o serviço usando o seguinte comando:

    gcloud run services replace service.yaml

    O comando gcloud run services replace usa o arquivo service.yaml por padrão, se ele estiver presente.

Conectar-se ao serviço com SSH

Para se conectar a um serviço usando SSH, use a CLI gcloud:

Console

  1. No console do Google Cloud , acesse a página Serviços do Cloud Run:

    Acessar o Cloud Run

  2. Clique em um serviço para abrir a página Detalhes do serviço.

  3. Selecione SSH. Isso abre o Cloud Shell com o comando SSH da gcloud.

  4. Pressione Enter.

  5. Se for preciso digitar uma senha longa para a chave SSH, deixe-a em branco. No entanto, se você inserir uma senha longa, use a mesma senha longa para todas as sessões SSH subsequentes do mesmo espaço de trabalho.

  6. Quando a sessão SSH é concluída, o Cloud Run exibe a seguinte mensagem:

    Project: PROJECT_ID
Region: REGION
Service: SERVICE
Revision: REVISION
Instance: INSTANCE_ID
Container: CONTAINER
Image: IMAGE

  7. Para encerrar a sessão SSH, digite exit. Todas as alterações feitas no contêiner persistem enquanto ele é mantido ativo. Sair da sessão não reinicia nem encerra o contêiner.

gcloud

Para se conectar a um serviço usando SSH, use o seguinte comando da Google Cloud CLI:

gcloud beta run services ssh SERVICE --region=REGION --project=PROJECT_ID

Substitua:

  • SERVICE: o nome do serviço.
  • REGION: a região em que o serviço está implantado.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Se for preciso digitar uma senha longa para a chave SSH, deixe-a em branco. No entanto, se você inserir uma senha longa, use a mesma senha longa para todas as sessões SSH subsequentes do mesmo espaço de trabalho.

Quando a sessão SSH é concluída, o Cloud Run exibe a seguinte mensagem:

Project: PROJECT_ID
Region: REGION
Service: SERVICE
Revision: REVISION
Instance: INSTANCE_ID
Container: CONTAINER
Image: IMAGE

Para encerrar a sessão SSH, digite exit. Todas as alterações feitas no contêiner persistem enquanto ele é mantido ativo. Sair da sessão não reinicia nem encerra o contêiner.

Especificar uma instância de serviço

Para se conectar a uma instância de serviço específica usando SSH, use a Google Cloud CLI.

Console

  1. No console do Google Cloud , acesse a página Serviços do Cloud Run:

    Acessar o Cloud Run

  2. Clique no serviço de seu interesse para abrir a página Detalhes do serviço.

  3. Selecione Registros.

  4. Clique na entrada de registro da instância de serviço para expandi-la.

  5. Selecione SSH para acessar esta instância. Isso abre o Cloud Shell com o comando SSH da gcloud.

  6. Pressione Enter.

gcloud

Para se conectar a uma instância de serviço do Cloud Run usando SSH, use o seguinte comando da Google Cloud CLI:

gcloud beta run services ssh SERVICE --region=REGION --project=PROJECT_ID \
  --revision=REVISION \
  --instance=INSTANCE_ID

Substitua:

  • SERVICE: o nome do serviço.
  • REGION: a região em que o serviço está implantado.
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • REVISION: o nome da revisão.
  • INSTANCE_ID: o ID da instância Para encontrar o ID da instância de serviço, acesse a página Registros na seção Observabilidade. O ID da instância está localizado no campo labels de uma entrada de registro. Não será possível encontrar o ID da instância se você encerrar a instância específica antes de se conectar a ela.

Especificar uma revisão

Para se conectar a uma revisão específica usando SSH, use a Google Cloud CLI.

Console

  1. No console do Google Cloud , acesse a página Serviços do Cloud Run:

    Acessar o Cloud Run

  2. Clique no serviço de seu interesse para abrir a página Detalhes do serviço.

  3. Selecione Histórico de revisões.

  4. Clique no ícone de reticências à direita da revisão que você quer acessar por SSH.

  5. Selecione SSH nas revisões. Isso abre o Cloud Shell com o comando SSH da gcloud.

  6. Pressione Enter.

gcloud

Para se conectar a uma revisão de serviço do Cloud Run usando SSH, use o seguinte comando da Google Cloud CLI:

gcloud beta run services ssh SERVICE --region=REGION --project=PROJECT_ID --revision=REVISION

Substitua:

  • SERVICE: o nome do serviço.
  • REGION: a região em que o serviço está implantado.
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • REVISION: o nome da revisão.

Usar SSH com instâncias do Cloud Run

Configurar o acesso SSH no nível da instância e se conectar à instância usando SSH.

Configurar o acesso SSH no nível da instância

O SSH é ativado por padrão para instâncias.

É possível desativar o acesso SSH por instância usando a CLI gcloud ou YAML:

gcloud

Para desativar o acesso na instância, use o seguinte comando:

gcloud beta run instances update INSTANCE --no-ssh

YAML

  1. Se você estiver criando uma nova instância, pule esta etapa. Se você estiver atualizando uma instância, faça o download da configuração YAML correspondente:

    gcloud beta run instances describe INSTANCE --format export > instance.yaml

  2. O exemplo a seguir contém a configuração YAML:

    apiVersion: run.googleapis.com/v1
kind: Instance
metadata:
  name: INSTANCE
  labels:
    cloud.googleapis.com/location: REGION
  annotations:
    run.googleapis.com/ssh-enabled: "false"
    run.googleapis.com/launch-stage: BETA
spec:
  containers:
    image: IMAGE_URL

    Substitua:

    • INSTANCE: o nome da instância do Cloud Run.
    • REGION: a região do Google Cloud . Por exemplo, us-central1.
    • IMAGE_URL: uma referência à imagem do contêiner, como us-docker.pkg.dev/cloudrun/container/hello:latest.

  3. Crie ou atualize a instância usando o seguinte comando:

    gcloud beta run instances replace instance.yaml

É possível permitir o acesso de inspeção em uma instância específica usando a CLI gcloud ou o YAML.

gcloud

Para ativar o acesso em uma instância atual, use o seguinte comando:

gcloud beta run instances update INSTANCE --ssh

Também é possível permitir o acesso de inspeção em uma instância usando a flag --ssh ao implantar a instância.

YAML

  1. Se você estiver criando uma nova instância, pule esta etapa. Se você estiver atualizando uma instância, faça o download da configuração YAML correspondente:

    gcloud beta run instances describe INSTANCE --format export > instance.yaml

  2. O exemplo a seguir contém a configuração YAML:

    apiVersion: run.googleapis.com/v1
kind: Instance
metadata:
  name: INSTANCE
  labels:
    cloud.googleapis.com/location: REGION
  annotations:
    run.googleapis.com/ssh-enabled: "true"
    run.googleapis.com/launch-stage: BETA
spec:
  containers:
    image: IMAGE_URL

    Substitua:

    • INSTANCE: o nome da instância do Cloud Run.
    • REGION: a região do Google Cloud . Por exemplo, us-central1.
    • IMAGE_URL: uma referência à imagem do contêiner, como us-docker.pkg.dev/cloudrun/container/hello:latest.

  3. Crie ou atualize a instância usando o seguinte comando:

    gcloud beta run instances replace instance.yaml

Conecte-se à instância com SSH

Para se conectar a uma instância usando SSH, use o seguinte comando da Google Cloud CLI:

  gcloud beta run instances ssh INSTANCE --region=REGION --project=PROJECT_ID

Substitua:

  • INSTANCE: o nome da instância.
  • REGION: a região em que o serviço está implantado.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Se for preciso digitar uma senha longa para a chave SSH, deixe-a em branco. No entanto, se você inserir uma senha longa, use a mesma senha longa para todas as sessões SSH subsequentes do mesmo espaço de trabalho.

Quando a sessão SSH é concluída, o Cloud Run exibe a seguinte mensagem:

  Project: PROJECT_ID
  Region: REGION
  Instance: INSTANCE
  Revision: REVISION
  Container: CONTAINER
  Image: IMAGE

Para encerrar a sessão SSH, digite exit.

Usar o cliente OpenSSH para se conectar

Para usar o cliente OpenSSH para se conectar:

  1. Execute o comando gcloud beta run services ssh no serviço de destino. Isso inicia o túnel SSH e gera o certificado.

  2. Adicione o seguinte à sua configuração SSH:

    Host cloud-run-ssh
    HostName cloud-run-default
    User root
    IdentityFile /Users/USER/.ssh/google_compute_engine
    CertificateFile /Users/USER/.ssh/google_compute_engine_cert/PROJECT_ID_REGION_SERVICE-cert.pub
    CheckHostIP no
    HashKnownHosts no
    HostKeyAlias cloud-run-default
    IdentitiesOnly yes
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
    ProxyUseFdpass no
    ProxyCommand /usr/local/bin/python3 -S /Users/USER/google-cloud-sdk/lib/gcloud.py beta run start-iap-tunnel --project_number=PROJECT_NUMBER --project_id=PROJECT_ID --workload_type=service --deployment_name=SERVICE --region=REGION

    Substitua:

    • USER: o nome de usuário na máquina local.
    • PROJECT_ID: o ID do projeto do Google Cloud .
    • PROJECT_NUMBER: o número do projeto do Google Cloud .
    • REGION: a região em que o serviço está implantado.
    • SERVICE: o nome do serviço.

    Se a CLI gcloud estiver instalada em uma pasta diferente, talvez seja necessário atualizar o local na última linha.

  3. Execute este comando:

    ssh cloud-run-ssh

Seu certificado SSH expira após cinco minutos. Se você tentar estabelecer uma conexão SSH com o serviço após cinco minutos, será necessário executar novamente gcloud beta run services ssh para gerar o certificado de novo.

Registros de acesso SSH

Para capturar registros de auditoria para o gerenciamento de chaves SSH, é necessário ativar os registros de auditoria para a API Login do SO do Cloud. Consulte Ver registros de auditoria do Login do SO. Para acessar os registros SSH dos recursos do Cloud Run, é preciso ter acesso aos Registros de Auditoria do Cloud desse projeto.

O exemplo a seguir consulta todos os serviços do Cloud Run no último dia:

gcloud logging read '
  logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access" AND
  protoPayload.serviceName="oslogin.googleapis.com" AND
  protoPayload.request.instance:"run.googleapis.com"
' --project=PROJECT_ID \
  --freshness=1d \
  --format="table(timestamp, protoPayload.authenticationInfo.principalSubject:label=USER, protoPayload.request.instance:label=CLOUD_RUN_SERVICE)"

Proteger e controlar o acesso SSH

Você pode controlar quem pode usar o SSH e como ele é restrito no seu ambiente.

Desativar o acesso SSH com políticas da organização

Para definir uma política da organização que desative o SSH, use a restrição personalizada que restringe a ativação do acesso de depuração SSH nos serviços do Cloud Run.

A seguir