Como mapear domínios personalizados

É possível usar um domínio personalizado em vez do endereço padrão fornecido pelo Cloud Run para um serviço implantado.

Há algumas maneiras de configurar um domínio personalizado para um serviço do Cloud Run:

• Use um balanceador de carga de aplicativo externo global (recomendado)
• Use o recurso de integrações do Cloud Run para o Firebase Hosting (a maneira mais fácil de usar o Firebase Hosting)
• Use o Firebase Hosting com configuração manual se você não quiser usar o recurso de integração
• Use o mapeamento de domínios do Cloud Run (disponibilidade e visualização limitadas)

É possível mapear vários domínios personalizados para o mesmo serviço do Cloud Run.

Antes de começar

Compre um domínio novo, a menos que você já tenha um e queira usá-lo. É possível usar qualquer registrador de domínios.

Mapear um domínio personalizado usando um balanceador de carga de aplicativo externo global

Com essa opção, você adiciona um balanceador de carga de aplicativo externo global na frente do serviço do Cloud Run e configura um domínio personalizado no nível do balanceador de carga.

Uma vantagem de usar um balanceador de carga de aplicativo externo global é que ele oferece muito controle sobre a configuração do domínio personalizado. Por exemplo, é possível usar seu próprio certificado TLS ou encaminhar caminhos de URL específicos para o serviço do Cloud Run. Ele também permite que você configure o Cloud CDN para armazenamento em cache e o Google Cloud Armor para maior segurança.

Também é possível mapear vários serviços para um nome de host ou caminho dinâmico no padrão de URL de domínio personalizado para um único balanceador de carga, por exemplo, <service>.example.com, usando máscaras de URL.

Como usar as integrações do Cloud Run

Se você não estiver usando um balanceador de carga de aplicativo externo global, poderá usar o recurso de integrações do Cloud Run para configurar rapidamente um balanceador de carga para seu serviço do Cloud Run. Consulte a página de integrações para domínios personalizados no Cloud Run usando um balanceador de carga de aplicativo externo global.

Como usar diretamente o balanceador de carga de aplicativo externo global

Se você já estiver usando um balanceador de carga de aplicativo externo global, consulte a documentação sobre como configurar um balanceador de carga de aplicativo externo global com o Cloud Run. Se você usar recurso de integrações, poderá substituir algumas configurações do balanceador de carga, como a ativação da CDN.

Mapear um domínio personalizado usando o Firebase Hosting

Observação: o Firebase Hosting não está coberto pelos Termos de Serviço do Google Cloud. Consulte os Termos de Serviço dos serviços do Firebase.

Com essa opção, você configura o Firebase Hosting na frente do serviço do Cloud Run e conecta um domínio de configuração ao Firebase Hosting.

O uso do Firebase Hosting tem um preço baixo e, opcionalmente, permite que você hospede e exiba conteúdo estático junto com o conteúdo dinâmico exibido pelo serviço do Cloud Run.

Como usar a integração do Cloud Run

A maneira mais fácil e recomendada de usar o Firebase Hosting para mapear um domínio personalizado é usar o recurso de integrações do Cloud Run para o Firebase Hosting.

Como usar o firebase.json

Se você não quiser usar o recurso de integrações do Firebase Hosting, use uma abordagem manual para configurar o Firebase Hosting.

Para mapear manualmente um domínio personalizado usando o Firebase Hosting:

1. Adicione o Firebase ao projeto do Google Cloud.
2. Instalar a CLI do Firebase

3. Em uma pasta diferente do código-fonte do serviço, crie um arquivo firebase.json com o seguinte conteúdo:

     {
       "hosting": {
         "rewrites": [{
           "source": "**",
           "run": {
             "serviceId": "SERVICE_NAME",
             "region": "REGION"
           }
         }]
       }
     }
   

   Substitua SERVICE_NAME e REGION pelo nome e região do serviço do Cloud Run.

4. Implante a configuração do Firebase Hosting:

   firebase deploy --only hosting --project PROJECT_ID

5. Conecte um domínio personalizado ao Firebase Hosting

Leia mais sobre o Firebase Hosting e o Cloud Run.

Mapear um domínio personalizado usando o mapeamento de domínios do Cloud Run (disponibilidade e visualização limitadas)

Visualização — Cloud Run domain mappings

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Limitações de mapeamento de domínio do Cloud Run

As seguintes considerações se aplicam aos mapeamentos de domínio do Cloud Run:

• Os mapeamentos de domínio do Cloud Run estão no estágio de lançamento da prévia. Devido a problemas de latência, eles não estão prontos para produção e não são compatíveis com a Disponibilidade geral. No momento, essa opção não é recomendada para serviços de produção.
• Um certificado gerenciado pelo Google para conexões HTTPS é emitido e renovado automaticamente quando você mapeia um serviço para um domínio personalizado.
• O provisionamento do certificado SSL geralmente leva cerca de 15 minutos, mas pode levar até 24 horas.
• Não é possível desativar o TLS 1.0 e 1.1. Se isso for um problema, use o Firebase Hosting ou o Cloud Load Balancing para ativar o tráfego somente de TLS 1.2.
• Não é possível fazer o upload e usar seus próprios certificados (autogerenciados).
• Os mapeamentos de domínio do Cloud Run são limitados a 64 caracteres.
• O mapeamento de domínio está disponível nas seguintes regiões:
  • asia-east1
  • asia-northeast1
  • asia-southeast1
  • europe-north1
  • europe-west1
  • europe-west4
  • us-central1
  • us-east1
  • us-east4
  • us-west1
• Para mapear domínios personalizados em outras regiões, use uma das outras opções de mapeamento.
• Ao usar mapeamentos de domínio do Cloud Run, você mapeia um domínio personalizado para o serviço e atualiza seus registros DNS.
• É possível mapear um domínio, como example.com, ou um subdomínio, como subdomain.example.com.
• Você só pode mapear um domínio para /, não para um caminho de URL específico, como /users.
• Não é possível usar certificados curinga com esse recurso.

Mapear um domínio personalizado para um serviço

É possível usar o console do Google Cloud, a gcloud CLI ou o Terraform para mapear um domínio personalizado para um serviço.

Console

1. Abra a página de mapeamentos de domínio no Console do Google Cloud:
   página de mapeamentos de domínio

2. Clique em Adicionar mapeamento.

   Se a sua janela de exibição for muito pequena, o botão Mapeamento de domínios personalizados não será exibido, e você precisará clicar no ícone de três pontos verticais no canto direito da página.

3. Na lista suspensa, selecione o serviço para o qual você está mapeando o domínio personalizado.

4. Dependendo da região definida para o serviço selecionado, o formulário mostra as opções disponíveis para adicionar um domínio personalizado:

   • Firebase Hosting usando integrações do Cloud Run
   • Domínios personalizados: Google Cloud Load Balancing usando integrações do Cloud Run
   • Mapeamentos de domínios do Cloud Run

   Selecione Mapeamentos de domínio do Cloud Run.

5. No formulário Adicionar mapeamento, selecione Verificar um novo domínio.

6. No campo Domínio de base para verificar, você precisa verificar a propriedade de um domínio antes de poder usá-lo, a menos que tenha comprado o domínio do Google.

   Se você quiser mapear subdomain.example.com ou subdomain1.subdomain2.example.com, verifique a propriedade de example.com. Para mais informações sobre como verificar a propriedade do domínio, consulte a Ajuda do Search Console.

7. Clique em Continuar.

8. Após a verificação do domínio, clique em Continuar a verificação e fechar.

9. Atualize seus registros DNS no site de registro de domínios usando os registros DNS exibidos na última etapa. É possível exibir os registros a qualquer momento clicando em Registros DNS no menu de ação "…" para um mapeamento de domínio.

10. Clique em Concluído.

gcloud

1. Você precisa verificar a propriedade do domínio na primeira vez que usá-lo no projeto do Google Cloud, a menos que tenha comprado seu domínio personalizado do Google. É possível determinar se o domínio personalizado que você quer usar foi verificado usando o comando:

   gcloud domains list-user-verified

   Se a propriedade do domínio precisar ser verificada, abra a página de verificação do Search Console:

   gcloud domains verify BASE-DOMAIN

   em que BASE-DOMAIN é o domínio de base que você quer confirmar. Por exemplo, se quiser mapear subdomain.example.com, confirme a propriedade de example.com.

   No Search Console, conclua a verificação de propriedade do domínio. Para mais informações, consulte a Ajuda do Search Console.

2. Mapeie seu serviço para o domínio personalizado:

   gcloud beta run domain-mappings create --service SERVICE --domain DOMAIN

   • Substitua SERVICE pelo nome do serviço.
   • Substitua DOMAIN pelo seu domínio personalizado, por exemplo, example.com ou subdomain.example.com.

Observação: se você estiver usando um domínio que já está mapeado para outro serviço, use a flag --force-override ao criar o mapeamento do domínio. Esse domínio será removido do outro serviço para apontar para este.

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

Para criar um serviço do Cloud Run, adicione o seguinte ao arquivo main.tf existente:

resource "google_cloud_run_v2_service" "default" {
  name     = "cloud-run-srv"
  location = "us-central1"
  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
  }
}

Substitua o valor de name pelo nome do seu serviço.

Associar o serviço do Cloud Run para o domínio personalizado:

data "google_project" "project" {}

resource "google_cloud_run_domain_mapping" "default" {
  name     = "verified-domain.com"
  location = google_cloud_run_v2_service.default.location
  metadata {
    namespace = data.google_project.project.project_id
  }
  spec {
    route_name = google_cloud_run_v2_service.default.name
  }
}

Substitua verified-domain.com pelo domínio personalizado verificado, por exemplo, example.com ou subdomain.example.com.

Adicionar registros DNS no registrador de domínios

Depois de mapear seu serviço para um domínio personalizado no Cloud Run, é preciso atualizar seus registros DNS no registrador de domínios. Para facilitar, o Cloud Run gera e exibe os registros DNS que você precisa inserir. Adicione esses registros que apontam ao serviço Cloud Run no registrador de domínios para que o mapeamento entre em vigor.

Se você estiver usando o Cloud DNS como provedor de DNS, consulte Como adicionar um registro.

Observação: alguns provedores de CDN de terceiros podem interceptar acidentalmente solicitações de validação, impedindo-as de acessar o serviço do Cloud Run e fazendo com que o mapeamento de domínio ou a renovação do certificado falhem. Por exemplo, se você estiver usando o CDN da Cloudflare, desative a opção "Always use https" na guia "Edge Certificates" da guia SSL/TLS.

1. Recupere as informações de registro DNS para seus mapeamentos de domínio usando:

   Console

   1. Acesse a página de mapeamentos de domínio do Cloud Run:
      Página de mapeamentos de domínio

   2. Clique no ícone de três pontos à direita do seu serviço e, em seguida, clique em REGISTROS DNS para exibir todos os registros:

   

   gcloud

   gcloud beta run domain-mappings describe --domain [DOMAIN]

   Substitua [DOMAIN] pelo seu domínio personalizado, por exemplo, example.com ou subdomain.example.com.

   Você precisa de todos os registros retornados no cabeçalho resourceRecords.

2. Faça login na conta do registro de domínios e abra a página de configuração de DNS.

3. Localize a seção de registros de host da página de configuração do domínio e adicione cada um dos registros de recurso que você recebeu ao mapear o domínio para o serviço do Cloud Run.

4. Quando você adiciona cada um dos registros de DNS acima à conta no provedor de DNS:

   • selecione o tipo retornado no registro de DNS na etapa anterior: A, ou AAAA ou CNAME;
   • use o nome www para mapear para www.example.com;
   • use o nome @ para mapear example.com.

5. Salve as alterações na página de configuração do DNS da conta do domínio. Na maioria dos casos, leva apenas alguns minutos para que essas alterações entrem em vigor. No entanto, em alguns casos, pode levar várias horas, dependendo do registrador e do time to live (TTL) (em inglês) de qualquer registro DNS anterior para seu domínio. É possível usar uma ferramenta dig, como esta versão dig on-line, para confirmar se os registros de DNS foram atualizados.

6. Teste navegando até o serviço no novo URL, por exemplo, https://www.example.com. Pode levar alguns minutos para que o certificado SSL gerenciado seja emitido.

Adicionar proprietários de domínio verificados a outros usuários ou contas de serviço

Quando um usuário verifica um domínio, esse domínio só é verificado para a conta desse usuário. Isso significa que somente ele pode adicionar mapeamentos que usam esse mesmo domínio. Assim, para permitir que outros usuários adicionem mapeamentos, é preciso adicioná-los como proprietários verificados.

Observação: um proprietário de domínio verificado pode substituir os mapeamentos de domínio atuais de outros projetos após a confirmação.

Se você precisar adicionar proprietários verificados do seu domínio a outros usuários ou contas de serviço, poderá adicionar permissão por meio da página do Search Console

1. Navegue até este endereço no seu navegador da Web:

   https://search.google.com/search-console/welcome

2. Em Propriedades, clique no domínio para o qual você quer adicionar um usuário ou uma conta de serviço.

3. Vá até a lista de Proprietários verificados, clique em Adicionar um proprietário e insira o e-mail da Conta do Google ou o ID da conta de serviço.

   Para ver uma lista das contas de serviço, abra a página "Contas de serviço" no Console do Google Cloud:

   Acessar a página "Contas de serviço"

Excluir um mapeamento de domínio do Cloud Run

Use o Console do Google Cloud ou a ferramenta de linha de comando gcloud para excluir um mapeamento de domínio.

Console

1. Abra a página de mapeamentos de domínio no Console do Google Cloud:
   página de mapeamentos de domínio

2. Na página Mapeamentos de domínio, selecione o mapeamento que você quer excluir e clique em Excluir.

gcloud

1. Exclua o mapeamento de domínio:

   gcloud beta run domain-mappings delete --domain DOMAIN

   • Substitua DOMAIN pelo seu domínio personalizado, por exemplo, example.com ou subdomain.example.com.

Como usar domínios personalizados com serviços autenticados

Os serviços autenticados são protegidos pelo IAM. Esses serviços do Cloud Run exigem autenticação de cliente que declara o destinatário pretendido de uma solicitação no momento da geração de credenciais (o público-alvo).

Geralmente, o público é o URL completo do serviço de destino que, por padrão, é um URL gerado com final run.app nos serviços do Cloud Run. No entanto, se você usar um domínio personalizado, evite usar esse URL run.app gerado automaticamente como o público-alvo. Em vez disso, configure o serviço para um público personalizado para que ele aceite seu domínio personalizado como um público de autenticação válido.

A seguir

• Para configurar um domínio personalizado para o Cloud Run usando um balanceador de carga de aplicativo externo global com o Terraform, confira este exemplo de código.