Como mapear domínios personalizados

Configure os domínios personalizados que serão usados para acessar os serviços de serviço do Knative. É possível mapear um ou mais domínios personalizados para um serviço individual ou um único domínio para o cluster usado por todos os serviços. Seu mapeamento de domínio personalizado pode ser o domínio base, como your-domain.com, ou um subdomínio, como your-subdomain.your-domain.com.

Por padrão, os serviços que você implanta nos clusters do Knative serving são definidos como o domínio base nip.io. Isso permite que você teste imediatamente seus serviços em um URL como:

http://{SERVICE_NAME}.{NAMESPACE}.kuberun.{EXTERNAL_IP}.nip.io

Saiba mais sobre domínios de teste.

Antes de começar

Como mapear um domínio personalizado

Use o Console do Google Cloud ou as ferramentas de linha de comando para mapear seu domínio personalizado.

Geralmente, para configurar um domínio personalizado:

  1. Opcional: reserve o endereço IP do seu balanceador de carga.
  2. Mapeie seus serviços ou o cluster para o domínio personalizado no Knative serving.
  3. Atualize seus registros de DNS no registrador de domínios.

Reservar o endereço IP do balanceador de carga

Quando o serviço Knative é instalado, o controlador de entrada do Istio cria um balanceador de carga com um endereço IP disponível.

Dependendo do cluster do GKE, talvez seja necessário reservar o endereço IP do balanceador de carga para o controlador de entrada do Istio:

Fora do Google Cloud
Consulte a documentação do ambiente em que você executa o cluster do GKE para determinar como os endereços IP são gerenciados e se o endereço IP do balanceador de carga é estático. Consulte também as páginas de configuração do cluster do GKE. Por exemplo, dependendo de como você configurou o balanceamento de carga para o Google Distributed Cloud, talvez você já tenha reservado esses endereços IP.
No Google Cloud

É necessário reservar o endereço IP externo do balanceador de carga para garantir que ele permaneça o mesmo se o serviço de entrada for excluído. Dependendo da configuração do cluster, o endereço IP está disponível externamente ou apenas internamente, por exemplo, clusters particulares.

Balanceadores de carga internos no Google Cloud
Consulte a página a seguir para detalhes sobre como reservar o endereço IP do balanceador de carga interno: como reservar um endereço IP interno estático
Balanceadores de carga externos no Google Cloud
Para reservar o endereço IP do balanceador de carga externo:

  1. Consiga o endereço IP do balanceador de carga:

    Console

    Para conseguir o endereço IP externo do balanceador de carga no console do Google Cloud:
    1. Acesse a página do GKE no Console do Google Cloud:
      Acessar o GKE
    2. Clique em Serviços e entrada.
    3. Identifique o serviço que é a entrada do Istio do seu cluster. O Tipo do serviço será Balanceador de carga externo e o Nome será istio-ingressgateway.
    4. Depois de encontrar o serviço de entrada do Istio do cluster, copie o Endpoint dele. Esse será o endereço IP sem o número da porta. Por exemplo, é possível ver 00.000.000.000:11 listado como um endpoint, mas só precisa copiar 00.000.000.000.

    kubectl

    Para conseguir o IP externo do balanceador de carga, execute o seguinte comando:

    kubectl get svc istio-ingressgateway -n ASM-INGRESS-NAMESPACE

    Substitua ASM-INGRESS-NAMESPACE pelo namespace em que a entrada do Cloud Service Mesh está localizada. Especifique istio-system se você instalou o Cloud Service Mesh usando a configuração padrão.

    A resposta resultante será semelhante a:

    NAME                   TYPE           CLUSTER-IP     EXTERNAL-IP  PORT(S)
istio-ingressgateway   LoadBalancer   XX.XX.XXX.XX   pending      80:32380/TCP,443:32390/TCP,32400:32400/TCP

    em que o valor EXTERNAL-IP é o endereço IP externo do balanceador de carga.

  2. Reserve o endereço IP como um IP estático:

    gcloud compute addresses create ADDRESS-NAME --addresses EXTERNAL-IP --region REGION

    Substitua:

    • ADDRESS-NAME pelo nome que você quer fornecer ao seu IP estático.
    • EXTERNAL-IP pelo endereço IP externo do balanceador de carga que você recebeu na etapa anterior.
    • REGION: pela região em que o cluster está localizado.

Depois de conseguir o endereço IP do seu balanceador de carga, será possível usá-lo para mapear seu domínio personalizado:

Serviços de mapeamento

Escolha um dos métodos a seguir para mapear seu domínio personalizado para um serviço de veiculação do Knative. Cada serviço individual pode ser mapeado para vários domínios.

Console

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

    Acessar Mapeamentos de domínio

    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.

  2. Clique em Adicionar mapeamento e selecione Adicionar mapeamento de domínio de serviço para mapear um domínio para um serviço individual. É possível mapear vários domínios para cada serviço.

  3. Na lista suspensa no formulário Adicionar mapeamento, selecione o serviço para o qual você quer mapear seu domínio personalizado:

  4. Insira o nome do domínio Por exemplo, your-domain.com ou subdomain.your-domain.com. Requisitos de domínio:

    • O mapeamento de caminho base não é compatível. O termo caminho base refere-se ao nome do caminho do URL que vem depois do nome do domínio. Por exemplo, users é o caminho base de your-domain.com/users. O Knative serving só permite mapear um domínio para /, não para um caminho base específico. Portanto, qualquer roteamento de caminho precisa ser processado usando um roteador dentro do contêiner do serviço ou usando o Firebase Hosting.
    • Não é possível mapear o domínio para um subdomínio que corresponda ao URL dos seus serviços. Os URLs para um serviço são definidos comohttp://{service}.{namespace}.{your-domain.com}. Portanto, se você tiver um serviço em test.default.your-domain.com, não crie um mapeamento de domínio para o mesmo subdomínio test.default.your-domain.com.

  5. Clique em Continuar.

  6. 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.

  7. Clique em Concluído.

gcloud

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

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

    Substitua:

    • SERVICE pelo nome do serviço.
    • DOMAIN pelo seu domínio personalizado. Por exemplo, your-domain.com ou subdomain.your-domain.com. Requisitos de domínio:
      • O mapeamento de caminho base não é compatível. O termo caminho base refere-se ao nome do caminho do URL que vem depois do nome do domínio. Por exemplo, users é o caminho base de your-domain.com/users. O Knative serving só permite mapear um domínio para /, não para um caminho base específico. Portanto, qualquer roteamento de caminho precisa ser processado usando um roteador dentro do contêiner do serviço ou usando o Firebase Hosting.
      • Não é possível mapear o domínio para um subdomínio que corresponda ao URL dos seus serviços. Os URLs para um serviço são definidos comohttp://{service}.{namespace}.{your-domain.com}. Portanto, se você tiver um serviço em test.default.your-domain.com, não crie um mapeamento de domínio para o mesmo subdomínio test.default.your-domain.com.

Agora que seu domínio personalizado está mapeado para a veiculação do Knative, é necessário adicionar registros DNS no registrador de domínios.

Como mapear clusters

Escolha um dos seguintes métodos para mapear seu domínio personalizado no cluster:

Console

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

    Acessar Mapeamentos de domínio

    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.

  2. Clique em Adicionar mapeamento e selecione Adicionar domínio padrão para mapear um domínio para todos os serviços no cluster. Por padrão, os novos serviços que você implanta usam o domínio mapeado.

  3. Clique na caixa de seleção para aplicar o novo mapeamento de domínio a todos os serviços no cluster.

  4. Na lista suspensa no formulário Adicionar mapeamento, selecione o cluster em que você quer mapear o domínio personalizado:

  5. Insira o nome do domínio Por exemplo, your-domain.com ou subdomain.your-domain.com. Requisitos de domínio:

    • O mapeamento de caminho base não é compatível. O termo caminho base refere-se ao nome do caminho do URL que vem depois do nome do domínio. Por exemplo, users é o caminho base de your-domain.com/users. O Knative serving só permite mapear um domínio para /, não para um caminho base específico. Portanto, qualquer roteamento de caminho precisa ser processado usando um roteador dentro do contêiner do serviço ou usando o Firebase Hosting.
    • Não é possível mapear o domínio para um subdomínio que corresponda ao URL dos seus serviços. Os URLs para um serviço são definidos comohttp://{service}.{namespace}.{your-domain.com}. Portanto, se você tiver um serviço em test.default.your-domain.com, não crie um mapeamento de domínio para o mesmo subdomínio test.default.your-domain.com.

  6. Clique em Continuar.

  7. 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.

  8. Clique em Concluído.

kubectl

  1. Execute o seguinte comando para remover o domínio base do ConfigMap config-domain e substituí-lo pelo domínio personalizado:

    kubectl patch configmap config-domain --namespace knative-serving --patch \
'{"data": {"nip.io": null, "DOMAIN": ""}}'

    Substitua DOMAIN pelo domínio personalizado. Por exemplo, your-domain.com ou subdomain.your-domain.com. Requisitos de domínio:

    • O mapeamento de caminho base não é compatível. O termo caminho base refere-se ao nome do caminho do URL que vem depois do nome do domínio. Por exemplo, users é o caminho base de your-domain.com/users. O Knative serving só permite mapear um domínio para /, não para um caminho base específico. Portanto, qualquer roteamento de caminho precisa ser processado usando um roteador dentro do contêiner do serviço ou usando o Firebase Hosting.
    • Não é possível mapear o domínio para um subdomínio que corresponda ao URL dos seus serviços. Os URLs para um serviço são definidos comohttp://{service}.{namespace}.{your-domain.com}. Portanto, se você tiver um serviço em test.default.your-domain.com, não crie um mapeamento de domínio para o mesmo subdomínio test.default.your-domain.com.

Agora que seu domínio personalizado está mapeado para a veiculação do Knative, é necessário adicionar registros DNS no registrador de domínios.

Adicionar registros DNS no registrador de domínios

Depois de mapear o serviço para um domínio personalizado no Knative serving, você precisará atualizar os registros DNS no registrador de domínios. Para facilitar, o Knative serving gera e mostra os registros DNS que você precisa inserir. Adicione esses registros que apontam ao serviço Knative serving 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.

  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 Knative serving:

      Acessar Mapeamentos de domínio

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

    gcloud

    gcloud run domain-mappings describe --domain DOMAIN

    Substitua DOMAIN pelo domínio personalizado. Por exemplo, your-domain.com ou subdomain.your-domain.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 Knative serving.

  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.your-domain.com;
    • use o nome @ para mapear your-domain.com.
    • Use o caractere curinga * para mapear para *.your-domain.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.your-domain.com. Pode levar alguns minutos para que o certificado SSL gerenciado seja emitido.

Como adicionar proprietários dos domínios 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.

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 em que 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 suas contas de serviço, abra a página "Contas de serviço" no Console do Cloud:

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

Como registrar um domínio com o Cloud Domains no console de veiculação do Knative

Para registrar um domínio com o Cloud Domains no console de veiculação do Knative:

  1. Acesse a página de mapeamentos de domínio do Knative serving:

    Acessar Mapeamentos de domínio

  2. Clique em Registrar domínio.

  3. Conclua o processo de registro seguindo as instruções em Como registrar um domínio.

  4. Conclua as etapas anteriores nesta página para Mapear seu domínio para o Knative serving e adicionar registros DNS ao registrador de domínios.

Solução de problemas

Veja os problemas comuns em Solução de problemas de domínios personalizados e TLS gerenciado.