Como configurar serviços de vários clusters

Esta página mostra como ativar e usar serviços de vários clusters (MCS, na sigla em inglês). Para saber mais sobre como o MCS funciona e os benefícios dele, consulte Serviços de vários clusters.

O recurso de MCS do Google Kubernetes Engine (GKE) estende o alcance do Serviço do Kubernetes além do limite do cluster e permite descobrir e invocar Serviços em vários clusters do GKE. É possível exportar um subconjunto de serviços existentes ou novos.

Quando você exporta um serviço com MCS, esse serviço é disponibilizado em todos os clusters da frota.

Recursos do Google Cloud gerenciados pela MCS

O MCS gerencia os seguintes componentes do Google Cloud:

  • Cloud DNS: o MCS configura zonas e registros do Cloud DNS para cada serviço exportado nas frotas do environ. Isso permite que você se conecte a serviços em execução em outros clusters. Essas zonas e registros são criados, lidos, atualizados e excluídos com base nos serviços escolhidos para exportação entre clusters.

  • Regras de firewall: o MCS configura regras de firewall que permitem que os pods se comuniquem uns com os outros entre clusters na frota. As regras de firewall são criadas, lidas, atualizadas e excluídas com base nos clusters adicionados à frota. Essas regras são semelhantes às regras que o GKE cria para permitir a comunicação entre pods em um cluster do GKE.

  • Traffic Director: o MCS usa o Traffic Director como plano de controle para acompanhar os endpoints e a integridade deles nos clusters.

Requisitos

O MCS tem os seguintes requisitos:

  • O MCS só é compatível com a exportação de serviços de clusters nativos do GKE no Google Cloud. Para mais informações, consulte Como criar um cluster nativo de VPC. Não é possível usar clusters padrão do GKE que não sejam nativos de VPC.

  • A conectividade entre clusters depende dos clusters em execução na mesma rede VPC, nas redes VPC com peering ou compartilhadas. Caso contrário, as chamadas para serviços externos não poderão ultrapassar o limite da rede.

  • Uma frota pode abranger vários projetos do Google Cloud e redes VPC. No entanto, um único serviço de vários clusters precisa ser exportado de um único projeto e uma única rede VPC.

  • O MCS não oferece suporte às políticas de rede.

  • Os clusters precisam ter o complemento HttpLoadBalancing ativado. Verifique se o complemento HttpLoadBalancing está ativado. O complemento HttpLoadBalancing é ativado por padrão e não pode ser desativado.

Preços

Os serviços de vários clusters estão incluídos como parte da taxa de gerenciamento de cluster do GKE e não têm custo extra para uso. Você precisa ativar a API Traffic Director, mas o MCS não gera cobranças de endpoint do Traffic Director. O licenciamento do GKE Enterprise não é necessário para usar o MCS.

Antes de começar

Antes de começar, veja se você realizou as seguintes tarefas:

  1. Instale o SDK do Google Cloud.

  2. Ative a API Google Kubernetes Engine:

    Ativar a API Google Kubernetes Engine

  3. Ative o MCS, a frota (hub), o Resource Manager, Traffic Director e as APIs do Cloud DNS:

    gcloud services enable \
    multiclusterservicediscovery.googleapis.com \
    gkehub.googleapis.com \
    cloudresourcemanager.googleapis.com \
    trafficdirector.googleapis.com \
    dns.googleapis.com \
    --project=PROJECT_ID

    Substitua PROJECT_ID pelo ID do projeto em que você pretende registrar os clusters em uma frota.

Como ativar o MCS no projeto

O MCS exige que os clusters do GKE participantes sejam registrados na mesma frota. Depois que o recurso MCS for ativado para uma frota, qualquer cluster poderá exportar serviços entre os clusters na frota.

Embora o MCS exija registro em uma frota, ele não exige a ativação da plataforma do GKE Enterprise.

GKE Enterprise

Se a API GKE Enterprise estiver ativada no projeto host da frota como um pré-requisito para usar outros componentes do GKE Enterprise, todos os clusters registrados na frota do projeto serão cobrados de acordo com os preços do GKE Enterprise. Com esse modelo de preços, você usa todos os recursos do GKE Enterprise em clusters registrados com uma cobrança única por vCPU. Confirme se a API GKE Enterprise está ativada usando o seguinte comando:

gcloud services list --project=PROJECT_ID | grep anthos.googleapis.com

Se a saída for semelhante a esta, a plataforma completa do GKE Enterprise estará ativada e todos os clusters registrados na frota incorrerão em cobranças do GKE Enterprise:

anthos.googleapis.com                        Anthos API

Se isso não for esperado, entre em contato com o administrador do projeto.

Uma saída vazia indica que o GKE Enterprise não está ativado.

Como ativar o MCS no cluster do GKE

  1. Ative o recurso MCS para a frota do seu projeto:

    gcloud container fleet multi-cluster-services enable \
    --project PROJECT_ID

    Substitua PROJECT_ID pelo ID do projeto em que você pretende registrar os clusters em uma frota. Este é seu projeto host de frota.

  2. Registre os clusters do GKE em uma frota. É altamente recomendável registrar o cluster com a federação de identidade da carga de trabalho para o GKE ativada. Se você não ativar a federação de identidade da carga de trabalho, precisará registrar o cluster com uma conta de serviço do Google Cloud para autenticação e concluir as outras etapas em Como autenticar contas de serviço.

    Para registrar o cluster com a federação de identidade da carga de trabalho do GKE, execute o seguinte comando:

    gcloud container fleet memberships register MEMBERSHIP_NAME \
   --gke-cluster CLUSTER_LOCATION/CLUSTER_NAME \
   --enable-workload-identity \
   --project PROJECT_ID

    Substitua:

    • MEMBERSHIP_NAME: o nome da assinatura que você escolhe para representar o cluster de maneira exclusiva na frota. Normalmente, o nome da assinatura da frota do cluster é o nome do cluster, mas talvez seja necessário especificar um novo nome se outro cluster com o nome original já existir na frota.
    • CLUSTER_LOCATION: a zona ou região em que o cluster está localizado.
    • CLUSTER_NAME: o nome do cluster.

  3. Conceda as permissões do Identity and Access Management (IAM) necessárias para o importador do MCS:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member "serviceAccount:PROJECT_ID.svc.id.goog[gke-mcs/gke-mcs-importer]" \
    --role "roles/compute.networkViewer"

    Substitua PROJECT_ID pelo ID do projeto host da frota.

  4. Certifique-se de que cada cluster na frota tenha um namespace em que compartilhar serviços. Se necessário, crie um namespace usando o seguinte comando:

    kubectl create ns NAMESPACE

    Substitua NAMESPACE por um namespace.

  5. Para verificar se o MCS está ativado, execute o seguinte comando:

    gcloud container fleet multi-cluster-services describe \
    --project PROJECT_ID

    A saída será assim:

    createTime: '2021-08-10T13:05:23.512044937Z'
membershipStates:
  projects/PROJECT_ID/locations/global/memberships/MCS_NAME:
    state:
      code: OK
      description: Firewall successfully updated
      updateTime: '2021-08-10T13:14:45.173444870Z'
name: projects/PROJECT_NAME/locations/global/features/multiclusterservicediscovery
resourceState:
  state: ACTIVE
spec: {}

    Se o valor de state não for ACTIVE, consulte a seção Solução de problemas.

Como autenticar contas de serviço

Se você registrou os clusters do GKE em uma frota usando uma conta de serviço, será necessário seguir etapas adicionais para autenticar a conta de serviço. O MCS implanta um componente chamado gke-mcs-importer. Esse componente recebe atualizações de endpoint do Traffic Director. Por isso, como parte da ativação do MCS, é necessário conceder permissão à conta de serviço para ler informações do Traffic Director.

Ao usar uma conta de serviço, utilize a conta de serviço padrão do Compute Engine ou sua própria conta de serviço de nó:

Como usar o MCS

As seções a seguir mostram como usar o MCS. O MCS usa a API de serviços de vários clusters do Kubernetes.

Como registrar um serviço para exportação

Para registrar um serviço para exportação em outros clusters na frota, conclua as etapas a seguir:

  1. Crie um objeto ServiceExport chamado export.yaml:

    # export.yaml
kind: ServiceExport
apiVersion: net.gke.io/v1
metadata:
 namespace: NAMESPACE
 name: SERVICE_EXPORT_NAME

    Substitua:

    • NAMESPACE: o namespace do objeto ServiceExport. Esse namespace precisa corresponder ao namespace do serviço que você está exportando.
    • SERVICE_EXPORT_NAME: o nome de um serviço no cluster que você quer exportar para outros clusters na frota.

  2. Crie o recurso ServiceExport executando o seguinte comando:

    kubectl apply -f export.yaml

A exportação inicial do serviço leva aproximadamente cinco minutos para sincronizar com os clusters registrados na frota. Depois que um serviço é exportado, as sincronizações de endpoint subsequentes ocorrem imediatamente.

É possível exportar o mesmo serviço de vários clusters para criar um único endpoint de serviço de vários clusters altamente disponível com distribuição de tráfego entre clusters. Antes de exportar serviços com o mesmo nome e o mesmo namespace, considere se realmente quer que eles estejam agrupados dessa maneira. Não recomendamos a exportação de serviços nos namespaces default e kube-system devido à alta probabilidade de conflitos de nomes não intencionais e ao agrupamento não intencional resultante. Se você estiver exportando mais de cinco serviços com o mesmo nome e o mesmo namespace, a distribuição de tráfego em serviços importados poderá ser limitada a cinco serviços exportados.

Como consumir serviços entre clusters

O MCS é compatível apenas com ClusterSetIP e serviços headless. Somente os registros de DNS "A" estão disponíveis.

Depois de criar um objeto ServiceExport, o nome de domínio a seguir será resolvido para o serviço exportado de qualquer pod em qualquer cluster da frota:

 SERVICE_EXPORT_NAME.NAMESPACE.svc.clusterset.local

A saída inclui os seguintes valores:

  • SERVICE_EXPORT_NAME e NAMESPACE: os valores definidos no objeto ServiceExport.

Para os serviços do ClusterSetIP, o domínio é resolvido para o ClusterSetIP. Para encontrar esse valor, localize o objeto ServiceImport em um cluster no namespace em que o objeto ServiceExport foi criado. O objeto ServiceImport é criado automaticamente.

Exemplo:

kind: ServiceImport
apiVersion: net.gke.io/v1
metadata:
 namespace: EXPORTED-SERVICE-NAMESPACE
 name: external-svc-SERVICE-EXPORT-TARGET
status:
 ports:
 - name: https
   port: 443
   protocol: TCP
   targetPort: 443
 ips: CLUSTER_SET_IP

O MCS cria um objeto Endpoints como parte da importação de um Service para um cluster. Ao investigar esse objeto, é possível monitorar o progresso de uma importação de serviço. Para encontrar o nome do objeto Endpoints, procure o valor da anotação net.gke.io/derived-service em um objeto ServiceImport correspondente ao serviço importado. Exemplo:

kind: ServiceImport
apiVersion: net.gke.io/v1
annotations: net.gke.io/derived-service: DERIVED_SERVICE_NAME
metadata:
 namespace: EXPORTED-SERVICE-NAMESPACE
 name: external-svc-SERVICE-EXPORT-TARGET

Em seguida, procure o objeto Endpoints para verificar se o MCS já propagou os endpoints para o cluster de importação. O objeto Endpoints é criado no mesmo namespace que o objeto ServiceImport, com o nome armazenado na anotação net.gke.io/derived-service. Exemplo:

kubectl get endpoints DERIVED_SERVICE_NAME -n NAMESPACE

Substitua:

  • DERIVED_SERVICE_NAME: o valor da anotação net.gke.io/derived-service no objeto ServiceImport.
  • NAMESPACE: o namespace do objeto ServiceExport.

Saiba mais sobre o status de integridade dos endpoints usando o painel do Traffic Director no console do Google Cloud.

Para os serviços sem comando, o domínio resolve para a lista de endereços IP dos endpoints nos clusters de exportação. Cada pod de back-end com um nome do host também pode ser endereçado de forma independente com um nome de domínio da seguinte forma:

 HOSTNAME.MEMBERSHIP_NAME.LOCATION.SERVICE_EXPORT_NAME.NAMESPACE.svc.clusterset.local

A saída inclui os seguintes valores:

  • SERVICE_EXPORT_NAME e NAMESPACE: os valores definidos no objeto ServiceExport.
  • MEMBERSHIP_NAME: o identificador exclusivo na frota do cluster em que o pod está.
  • LOCATION: o local da assinatura. As assinaturas são global, ou o local delas é uma das regiões ou zonas em que o pod está, como us-central1.
  • HOSTNAME: o nome do host do pod.

Também é possível endereçar um pod de back-end com um nome do host exportado de um cluster, registrado com uma assinatura global, usando um nome de domínio do seguinte formato:

HOSTNAME.MEMBERSHIP_NAME.SERVICE_EXPORT_NAME.NAMESPACE.svc.clusterset.local

Como desativar o MCS

Para desativar o MCS, siga estas etapas:

  1. Para cada cluster na frota, exclua cada objeto ServiceExport que você criou:

    kubectl delete serviceexport SERVICE_EXPORT_NAME \
    -n NAMESPACE

    Substitua:

    • SERVICE_EXPORT_NAME: nome do objeto ServiceExport.
    • NAMESPACE: o namespace do objeto ServiceExport.

  2. Verifique se o ServiceExport desaparece da lista em 30 minutos.

  3. Cancele o registro dos clusters da frota se eles não precisarem ser registrados para outra finalidade.

  4. Desative o recurso multiclusterservicediscovery:

    gcloud container fleet multi-cluster-services disable \
    --project PROJECT_ID

    Substitua PROJECT_ID pelo ID do projeto em que você registrou os clusters.

  5. Desative a API do MCS:

    gcloud services disable multiclusterservicediscovery.googleapis.com \
    --project PROJECT_ID

    Substitua PROJECT_ID pelo ID do projeto em que você registrou os clusters.

Limitações

Os limites a seguir não são aplicados e, em alguns casos, é possível exceder esses limites dependendo da carga nos clusters ou no projeto e na taxa de desligamento de endpoints. No entanto, podem ocorrer problemas de desempenho quando essas limitações forem excedidas.

  • Exportação de clusters: um único serviço, identificado por um nome de namespace, pode ser exportado com segurança de até cinco clusters simultaneamente. Além desse limite, é possível que apenas um subconjunto de endpoints possa ser importado para clusters de consumo. É possível exportar serviços diferentes de subconjuntos variados de clusters.

  • O número de pods por trás de um único serviço: é seguro quando você continuar com menos de 250 pods em um único serviço. Essa é a mesma limitação de serviços de cluster único. Com cargas de trabalho relativamente estáticas e um pequeno número de serviços com vários clusters, é possível exceder significativamente esse número em milhares de endpoints por serviço. Como acontece com os serviços de cluster único, todos os endpoints são monitorados por kube-proxy em cada nó. Ao ultrapassar esse limite, especialmente ao exportar de vários clusters simultaneamente, nós maiores podem ser necessários.

  • O número de serviços de vários clusters exportados simultaneamente: recomendamos que você exporte simultaneamente não mais de 50 portas de serviço exclusivas, identificadas pelo nome com namespace de um serviço e portas declaradas. Por exemplo, exportar um serviço que expõe as portas 80 e 443 contaria de acordo com dois dos 50 limites de portas de serviço únicas. Serviços com o mesmo nome de namespace exportado de vários clusters contam como um único serviço exclusivo. O serviço de porta 2 mencionado anteriormente ainda só contaria duas portas se fosse exportado de cinco clusters simultaneamente. Cada serviço de vários clusters é contabilizado na cota dos serviços de back-end e cada cluster de exportação ou zona cria um grupo de endpoints da rede (NEG, na sigla em inglês):

  • Tipos de serviço: o MCS é compatível apenas com ClusterSetIP e serviços headless. Os serviços NodePort e LoadBalancer não são compatíveis e podem causar um comportamento inesperado.

  • Como usar o agente IPmasq com o MCS: o MCS opera conforme esperado quando você usa um intervalo de IP de pod padrão ou não mascarado.

    Se você usar um intervalo de IP de pod personalizado ou um ConfigMap do agente IPmasq personalizado, será possível mascarar o tráfego do MCS. Isso impede que o MCS funcione porque as regras de firewall só permitem o tráfego de IPs de pod.

    Para evitar esse problema, use o intervalo de IP de pod padrão ou especifique todos os intervalos de IP de pod no campo nonMasqueradeCIDRs do ConfigMap do agente IPmasq. Se você usar o Autopilot ou se precisar usar um intervalo de IP de pod não padrão e não puder especificar todos os intervalos de IP de pod no ConfigMap, use a política de NAT de saída para configurar o mascaramento de IP.

MCS com clusters em vários projetos

Não será possível exportar um serviço se ele já estiver sendo exportado por outros clusters em um projeto diferente na frota com o mesmo nome e namespace. É possível acessar o serviço em outros clusters da frota em outros projetos, mas esses clusters não podem exportar o mesmo serviço no mesmo namespace.

Solução de problemas

As seções a seguir fornecem dicas de solução de problemas para o MCS.

Como visualizar o featureState

A visualização do estado do recurso pode confirmar se o MCS foi configurado. Visualize o estado do recurso do MCS usando o seguinte comando:

gcloud container fleet multi-cluster-services describe

A saída será assim:

createTime: '2021-08-10T13:05:23.512044937Z'
membershipStates:
 projects/PROJECT_ID/locations/global/memberships/MCS_NAME:
   state:
     code: OK
     description: Firewall successfully updated
     updateTime: '2021-08-10T13:14:45.173444870Z'
name: projects/PROJECT_NAME/locations/global/features/multiclusterservicediscovery
resourceState:
 state: ACTIVE
spec: {}

Os campos mais úteis para resolver problemas são code e description.

Códigos no featureState

Um código indica o estado geral do membro em relação ao MCS. Esses campos podem ser encontrados no campo state.code. Há três códigos possíveis:

  • OK: a assinatura foi adicionada ao MCS e está pronta para uso.

  • WARNING: o MCS está em processo de reconciliação da configuração da assinatura. O campo de descrição pode fornecer mais informações sobre o que causou esse código.

  • FAILED: esta assinatura não foi adicionada ao MCS. Outras assinaturas na frota com um código OK não são afetadas por esta assinatura de FAILED. O campo de descrição pode fornecer mais informações sobre o que causou esse código.

  • ERROR: essa assinatura não tem recursos. Outras assinaturas na frota com um código OK não são afetadas por esta assinatura de ERROR. O campo de descrição pode fornecer mais informações sobre o que causou esse código.

Descrições no featureState

Uma descrição fornece mais informações sobre o estado da assinatura no MCS. Essas descrições estão disponíveis no campo state.description, e é possível que as seguintes sejam exibidas:

  • Firewall successfully created: essa mensagem indica que a regra de firewall do membro foi criada e atualizada. O código da assinatura é OK.

  • Firewall creation pending: essa mensagem indica que a regra de firewall do membro está com criação ou atualização pendente. O código da assinatura é WARNING. Essa assinatura pode ter problemas para atualizar e se conectar a novos serviços de vários clusters e assinaturas adicionados enquanto a regra de firewall está pendente.

  • GKE Cluster missing: essa mensagem indica que o cluster registrado do GKE está indisponível e/ou excluído. O código da assinatura é ERROR. Essa assinatura precisa ser manualmente cancelada do registro da frota depois que um cluster do GKE for excluído.

  • Project that member lives in is missing required permissions and/or has not enabled all required APIs - additional setup steps are required: esta mensagem indica que há erros internos StatusForbidden (403) e o código da assinatura é FAILED. Esse erro ocorre nos seguintes cenários:

    • Você não ativou as APIs necessárias no projeto do membro.

      Se o cluster do membro residir em um projeto separado da frota, consulte configuração entre projetos para garantir que você concluiu todas as etapas necessárias. Se você concluiu todas as etapas, verifique se as seguintes APIs estão ativadas no projeto de registro com os seguintes comandos:

      gcloud services enable multiclusterservicediscovery.googleapis.com --project PROJECT_ID
gcloud services enable dns.googleapis.com --project PROJECT_ID
gcloud services enable trafficdirector.googleapis.com --project PROJECT_ID
gcloud services enable cloudresourcemanager.googleapis.com --project PROJECT_ID

      Substitua PROJECT_ID pelo ID do projeto em que você registrou os clusters.

    • A conta de serviço mcsd ou gkehub requer mais permissões no projeto do membro.

      As contas de serviço mcsd e gkehub precisam ter sido criadas automaticamente no projeto host da frota com todas as permissões necessárias. Para verificar se as contas de serviço existem, execute os seguintes comandos:

      gcloud projects get-iam-policy PROJECT_ID | grep gcp-sa-mcsd
gcloud projects get-iam-policy PROJECT_ID | grep gcp-sa-gkehub

      Substitua PROJECT_ID pelo ID do projeto host da frota.

    Esses comandos mostram o nome completo das contas de serviço mcsd e gkehub.

  • Multiple VPCs detected in the hub - VPC must be peered with other VPCs for successful connectivity: essa mensagem ocorre quando os clusters hospedados em VPCs diferentes são registrados na mesma frota. O status da assinatura é OK. A rede VPC de um cluster é definida pela rede do NetworkConfig dele. Os serviços de vários clusters precisam de uma rede simples, e essas VPCs precisam estar ativamente em peering para que os serviços de vários clusters se conectem uns aos outros adequadamente. Para saber mais, consulte Exemplo de configuração de peering de rede VPC.

  • Member does not exist in the same project as hub - additional setup steps are required, errors may occur if not completed.: essa mensagem enfatiza que os clusters entre projetos exigem etapas de configuração adicionais. O status da assinatura é OK. As associações entre projetos são definidas como um cluster de membro que não está no mesmo projeto que a frota. Para mais informações, consulte a configuração entre projetos.

  • Non-GKE clusters are currently not supported: esta mensagem enfatiza que o MCS é compatível apenas com clusters do GKE. Clusters que não são do GKE não podem ser adicionados ao MCS. O status da assinatura é FAILED.

Problemas conhecidos

Serviços MCS com várias portas

Há um problema conhecido com serviços de vários clusters com várias portas (TCP/UDP) no GKE Dataplane V2, em que alguns endpoints não estão programados no plano de dados. Esse problema afeta as versões do GKE anteriores à 1.26.3-gke.400.

Como solução alternativa, ao usar o GKE Dataplane V2, use vários MCS com uma única porta em vez de um MCS com várias portas.

MCS com VPC compartilhada

Com a implementação atual do MCS, se você implantar mais de uma frota na mesma VPC compartilhada, os metadados serão compartilhados entre as frotas. Quando um serviço é criado em uma frota, os metadados dele são exportados ou importados em todas as outras frotas que fazem parte da mesma VPC compartilhada e visíveis ao usuário.

Esse comportamento será corrigido em uma versão futura do MCS.

A verificação de integridade usa a porta padrão em vez de containerPort

Quando você implanta um Serviço com um campo targetPort que faz referência a uma porta nomeada em uma implantação, o MCS configura a porta padrão para a verificação de integridade em vez do containerPort especificado.

Para evitar esse problema, use valores numéricos no campo de serviço ports.targetPort e no campo de implantação readinessProbe.httpGet.port em vez de valores nomeados.

Esse comportamento será corrigido em uma versão futura do MCS.

A seguir