Como criar um cluster nativo de VPC

Nesta página, explicamos como configurar clusters nativos de VPC no Google Kubernetes Engine (GKE).

Para saber mais sobre benefícios e requisitos dos clusters nativos de VPC, consulte a visão geral dos clusters nativos de VPC.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

Defina as configurações padrão da gcloud usando um dos métodos a seguir:

  • Use gcloud init se quiser orientações para definir os padrões.
  • Use gcloud config para definir individualmente a região, a zona e o ID do projeto.

Como usar o gcloud init

Se você receber o erro One of [--zone, --region] must be supplied: Please specify location, conclua esta seção.

  1. Execute gcloud init e siga as instruções:

    gcloud init

    Se você estiver usando SSH em um servidor remoto, utilize a sinalização --console-only para impedir que o comando inicie um navegador:

    gcloud init --console-only
  2. Siga as instruções para autorizar a gcloud a usar sua conta do Google Cloud.
  3. Crie uma nova configuração ou selecione uma atual.
  4. Escolha um projeto do Google Cloud.
  5. Escolha uma zona padrão do Compute Engine para clusters zonais ou uma região para clusters regionais ou de Autopilot.

Como usar o gcloud config

  • Defina o ID do projeto padrão:
    gcloud config set project PROJECT_ID
  • Se você estiver trabalhando com clusters zonais, defina a zona do Compute padrão:
    gcloud config set compute/zone COMPUTE_ZONE
  • Se você estiver trabalhando com clusters de Autopilot ou regionais, defina a região do Compute padrão:
    gcloud config set compute/region COMPUTE_REGION
  • Atualize gcloud para a versão mais recente:
    gcloud components update

Procedimentos

Siga os procedimentos abaixo para criar um cluster nativo de VPC e verificar os intervalos de endereços IP do pod e do serviço.

Como criar um cluster em uma sub-rede atual

As instruções a seguir demonstram como criar um cluster GKE nativo de VPC em uma sub-rede atual com o método de atribuição de intervalo secundário de sua escolha.

gcloud

  • Para usar um método de atribuição de intervalo secundário gerenciado pelo GKE:

    gcloud container clusters create cluster-name \
      --region=region \
      --enable-ip-alias \
      --subnetwork=subnet-name \
      --cluster-ipv4-cidr=pod-ip-range \
      --services-ipv4-cidr=services-ip-range
    
  • Para usar um método de atribuição de intervalo secundário gerenciado pelo usuário:

    gcloud container clusters create cluster-name \
      --region=region \
      --enable-ip-alias \
      --subnetwork=subnet-name \
      --cluster-secondary-range-name=secondary-range-pods \
      --services-secondary-range-name=secondary-range-services
    

Substitua os marcadores por valores válidos:

  • cluster-name é o nome do cluster do GKE;
  • region é a região em que o cluster foi criado. Para criar um cluster de zona, substitua essa sinalização por --zone=zone, em que zone é uma zona do Google Cloud.
  • subnet-name é o nome de uma sub-rede atual. O intervalo de endereços IP primário da sub-rede é usado para os nós. A sub-rede precisa estar na mesma região do cluster. Se omitido, o GKE tentará usar uma sub-rede na rede VPC default na região do cluster.
  • Se o método de atribuição do intervalo secundário for gerenciado pelo GKE:
    • pod-ip-range é um intervalo de endereços IP na notação CIDR (por exemplo, 10.0.0.0/14) ou o tamanho da máscara de sub-rede de um bloco CIDR (por exemplo, /14). Isso é usado para criar o intervalo de endereços IP secundário da sub-rede para pods. Se você omitir a opção --cluster-ipv4-cidr, o GKE escolherá automaticamente um intervalo /14 (dois 18 endereços). O intervalo escolhido automaticamente é selecionado aleatoriamente de 10.0.0.0/8 (um intervalo de 224 endereços) e não incluirá intervalos de endereços IP alocados para VMs, rotas existentes ou intervalos alocados a outros clusters. O intervalo escolhido automaticamente pode entrar em conflito com endereços IP reservados, rotas dinâmicas ou rotas em VPCs que fazem peering com esse cluster. Se você usar qualquer um deles, especifique --cluster-ipv4-cidr para evitar conflitos.
    • services-ip-range é um intervalo de endereços IP na notação CIDR (por exemplo, 10.4.0.0/19) ou o tamanho da máscara de sub-rede de um bloco CIDR (por exemplo, /19). Isso é usado para criar o intervalo de endereços IP secundário da sub-rede para Services.
  • Se o método de atribuição do intervalo secundário for gerenciado pelo usuário:
    • secondary-range-pods é o nome de um intervalo atual de endereços IP secundários no subnet-name especificado. O GKE usa todo o intervalo de endereços IP secundários da sub-rede para os pods do cluster.
    • secondary-range-services é o nome de um intervalo atual de endereços IP secundários no subnet-name especificado. O GKE usa todo o intervalo de endereços IP secundários da sub-rede para os serviços do cluster.

Console

  1. Acesse a página do Google Kubernetes Engine no Console do Cloud:

    Acessar o Google Kubernetes Engine

  2. Clique em Criar.

  3. No painel de navegação, em Cluster, clique em Rede.

  4. Na lista suspensa Rede, selecione uma VPC.

  5. Na lista suspensa Sub-rede de nós, selecione uma sub-rede para o cluster.

  6. Verifique se a caixa de seleção Ativar roteamento de tráfego nativo de VPC (usa IP do alias) está marcada.

  7. Marque a caixa de seleção Criar intervalos secundários automaticamente se você quiser que o método de atribuição do intervalo secundário seja gerenciado pelo GKE. Desmarque essa caixa de seleção se você já tiver criado intervalos secundários para a sub-rede escolhida e quiser que o método de atribuição de intervalo secundário seja gerenciado pelo usuário.

  8. No campo Intervalo de endereços do pod, especifique um intervalo de pods (exemplo: 10.0.0.0/14).

  9. No campo Intervalo de endereços de serviço, especifique um intervalo de serviços (exemplo: 10.4.0.0/19).

  10. Configure o cluster como quiser.

  11. Clique em Criar.

API

Ao criar um cluster nativo de VPC, você define um objeto IPAllocationPolicy. É possível referir-se a intervalos atuais de endereços IP secundários de sub-redes ou especificar blocos CIDR. Refira-se a intervalos atuais de endereços IP secundários de sub-redes para criar um cluster com o método de atribuição de intervalo secundário que seja gerenciado pelo usuário. Especifique blocos CIDR se quiser que o método de atribuição de intervalos seja gerenciado pelo GKE.

{
  "name": cluster-name,
  "description": description,
  ...
  "ipAllocationPolicy": {
    "useIpAliases": true,
    "clusterIpv4CidrBlock"      : string,
    "servicesIpv4CidrBlock"     : string,
    "clusterSecondaryRangeName" : string,
    "servicesSecondaryRangeName": string,

  },
  ...
}

em que:

  • "clusterIpv4CidrBlock" é o tamanho/local do intervalo CIDR para pods. Determina o tamanho do intervalo secundário de pods e pode ser IP/tamanho em notação CIDR (como 10.0.0.0/14) ou /tamanho (como /14). Um espaço vazio com o tamanho especificado é escolhido do espaço disponível na VPC. Se deixado em branco, um intervalo válido será encontrado e criado com um tamanho padrão;
  • "servicesIpv4CidrBlock" é o tamanho/local do intervalo CIDR para Serviços. Veja a descrição de "clusterIpv4CidrBlock";
  • "clusterSecondaryRangeName" é o nome do intervalo secundário de pods. É obrigatório que o intervalo secundário já exista e pertença à sub-rede associada ao cluster (como a sub-rede especificada com a sinalização --subnetwork);
  • "serviceSecondaryRangeName" é o nome do intervalo secundário para Serviços. O intervalo secundário já precisa existir e pertencer à sub-rede associada ao cluster (como a sub-rede especificada pela sinalização --subnetwork).

Terraform

É fácil criar um cluster nativo de VPC por meio do Terraform usando um módulo Terraform.

Por exemplo, você pode adicionar este bloco à configuração do Terraform:

module "gke" {
  source  = "terraform-google-modules/kubernetes-engine/google"
  version = "~> 12.0"

  project_id        = "project-id"
  name              = "cluster-name"
  region            = "region"
  network           = "network-name"
  subnetwork        = "subnet-name"
  ip_range_pods     = "secondary-range-pods"
  ip_range_services = "secondary-range-services"
}

Substitua:

  • project-id é o ID do projeto em que o cluster é criado.
  • cluster-name é o nome do cluster do GKE;
  • region é a região em que o cluster foi criado.
  • network-name é o nome de uma rede existente.
  • subnet-name é o nome de uma sub-rede atual. O intervalo de endereços IP primário da sub-rede é usado para os nós. A sub-rede precisa estar na mesma região do cluster.
  • secondary-range-pods é o nome de um intervalo atual de endereços IP secundários no subnet-name especificado. O GKE usa todo o intervalo de endereços IP secundários da sub-rede para os pods do cluster.
  • secondary-range-services é o nome de um intervalo atual de endereços IP secundários no subnet-name especificado. O GKE usa todo o intervalo de endereços IP secundários da sub-rede para os serviços do cluster.

Como criar um cluster e uma sub-rede simultaneamente

As instruções a seguir demonstram como criar um cluster e uma sub-rede do GKE nativo de VPC ao mesmo tempo. O método de atribuição de intervalo secundário é gerenciado pelo GKE quando você executa estas duas etapas com um comando.

gcloud

Para criar um cluster nativo e uma sub-rede VPC simultaneamente:

gcloud container clusters create cluster-name \
    --region=region \
    --enable-ip-alias \
    --create-subnetwork name=subnet-name,range=node-ip-range \
    --cluster-ipv4-cidr=pod-ip-range \
    --services-ipv4-cidr=services-ip-range

em que:

  • cluster-name é o nome do cluster do GKE;
  • region é a região em que o cluster foi criado. Para criar um cluster de zona, substitua essa sinalização por --zone=zone, em que zone é uma zona do GKE;
  • subnet-name é o nome da sub-rede a ser criada. A região da sub-rede é a mesma região do cluster (ou a região que contém o cluster zonal). Use uma string vazia (name="") se quiser que o GKE gere um nome para você;
  • node-ip-range é um intervalo de endereços IP na notação CIDR (por exemplo, 10.5.0.0/20) ou o tamanho da máscara de sub-rede de um bloco CIDR (por exemplo, /20). Isso é usado para criar o intervalo de endereços IP principais da sub-rede para nós. Se omitido, o GKE escolhe um intervalo de IP disponível na VPC com um tamanho de /20;
  • pod-ip-range é um intervalo de endereços IP na notação CIDR (por exemplo, 10.0.0.0/14) ou o tamanho da máscara de sub-rede de um bloco CIDR (por exemplo, /14). Isso é usado para criar o intervalo de endereços IP secundário da sub-rede para pods. Se omitido, o GKE usa um intervalo /14 escolhido aleatoriamente, contendo 218 endereços. O intervalo escolhido automaticamente é selecionado aleatoriamente a partir de 10.0.0.0/8 (um intervalo de 224 endereços) e não incluirá intervalos de endereços IP alocados para VMs, rotas atuais ou intervalos alocados a outros clusters. O intervalo escolhido automaticamente pode entrar em conflito com endereços IP reservados, rotas dinâmicas ou rotas em VPCs que fazem peering com esse cluster. Se você usar qualquer um deles, especifique --cluster-ipv4-cidr para evitar conflitos.
  • services-ip-range é um intervalo de endereços IP na notação CIDR (por exemplo, 10.4.0.0/19) ou o tamanho da máscara de sub-rede de um bloco CIDR (por exemplo, /19). Isso é usado para criar o intervalo de endereços IP secundário da sub-rede para Services. Se omitido, o GKE usa /20, o tamanho padrão do intervalo de endereços IP para serviços.

Console

Não é possível criar um cluster e uma sub-rede simultaneamente usando o Console do Cloud. Em vez disso, primeiro crie uma sub-rede e depois crie o cluster em uma sub-rede existente.

API

Para criar um cluster nativo de VPC, defina um objeto [IPAllocationPolicy] no recurso do cluster:

{
  "name": cluster-name,
  "description": description,
  ...
  "ipAllocationPolicy": {
    "useIpAliases": true,
    "createSubnetwork": true,
    "subnetworkName": subnet-name
  },
  ...
}

O campo createSubnetwork cria e provisiona automaticamente uma sub-rede para o cluster. O campo subnetworkName é opcional. Se for deixado em branco, um nome será automaticamente escolhido para a sub-rede.

Como usar intervalos de endereços IP particulares não RFC 1918

Os clusters do GKE podem usar intervalos de endereços IP particulares fora dos intervalos RFC 1918 para nós, pods e serviços. Consulte intervalos válidos na documentação da rede VPC para ver uma lista de intervalos particulares não RFC 1918 que podem ser usados como endereços IP internos para intervalos de sub-rede.

Os intervalos de endereços IP particulares não RFC 1918 são compatíveis com clusters particulares e não particulares.

Os intervalos particulares não RFC 1918 são intervalos de sub-redes. É possível usá-los exclusivamente ou com os intervalos de sub-redes RFC 1918. Nós, pods e serviços continuam a usar os intervalos de sub-redes, conforme descrito em Intervalos de IPs para clusters nativos de VPC. Se você usa intervalos não RFC 1918, lembre-se do seguinte:

  • Os intervalos de sub-redes, mesmo aqueles que usam intervalos não RFC 1918, precisam ser atribuídos manualmente ou pelo GKE antes da criação dos nós do cluster. Não é possível alternar ou parar de usar intervalos de sub-redes não RFC 1918, a menos que você substitua o cluster.

  • Os balanceadores de carga TCP/UDP internos usam apenas endereços IP do intervalo de endereços IP primários da sub-rede. Para criar um balanceador de carga TCP/UDP interno com um endereço não RFC 1918, o intervalo de endereços IP primários da sub-rede precisa ser não RFC 1918.

Os destinos fora do cluster podem ter dificuldade para receber tráfego de intervalos particulares não RFC 1918. Por exemplo, os intervalos particulares RFC 1112 (classe E) são normalmente usados como endereços multicast. Se um destino fora do cluster não puder processar pacotes com origens que são endereços IP particulares fora do intervalo RFC 1918, será possível realizar as seguintes ações:

  • Usar um intervalo RFC 1918 para o intervalo de endereços IP primários da sub-rede. Desse modo, os nós no cluster usam endereços RFC 1918.

  • Garantir que seu cluster esteja executando o agente de mascaramento de IP e que os destinos não estejam na lista nonMasqueradeCIDRs. Dessa maneira, os pacotes enviados dos pods têm as fontes alteradas (SNAT) para os endereços dos nós, que são RFC 1918.

Ativar intervalos públicos de endereços IP de uso particular

Os clusters do GKE podem usar de maneira particular determinados intervalos de endereços IP públicos como intervalos de endereços IP de sub-rede internos. É possível usar qualquer endereço IP público de maneira particular, exceto determinados intervalos restritos, conforme descrito na documentação da rede VPC.

Seu cluster precisa ser um cluster nativo de VPC para usar intervalos de endereços IP públicos usados de maneira particular. Os clusters baseados em rotas não são compatíveis.

Intervalos públicos de uso particular são intervalos de sub-rede. É possível usá-los exclusivamente ou em conjunto com outros intervalos de sub-rede que usam endereços particulares. Nós, pods e serviços continuam a usar os intervalos de sub-redes, conforme descrito em Intervalos de IPs para clusters nativos de VPC. Considere as seguintes informações ao reutilizar endereços IP públicos de maneira particular:

  • Quando você usa um intervalo público de endereços IP como um intervalo de sub-rede, o cluster não pode mais se comunicar com sistemas na Internet que usam esse intervalo público. Ele se tornará um intervalo interno de endereços IP na rede VPC do cluster.

  • Os intervalos de sub-redes (mesmo os que utilizam de maneira particular os intervalos públicos de endereços IP) precisam ser atribuídos manualmente ou pelo GKE antes da criação dos nós do cluster. Não é possível alternar ou parar de usar endereços IP públicos de maneira particular, a menos que você substitua o cluster.

Por padrão, o GKE implementa o SNAT nos nós para destinos de IP públicos. Ao usar intervalos de endereços IP públicos de uso privado para o CIDR do pod, isso resultaria nas regras SNAT aplicadas ao tráfego entre pods. Para evitar isso, você tem duas opções:

Exemplo de cluster com intervalos públicos usados de maneira particular

No exemplo a seguir, gcloud é usado para criar um cluster que usa intervalos de endereços IP públicos reutilizados de maneira particular. Use a sinalização a seguir:

  • --enable-ip-alias: cria um cluster nativo de VPC, necessário quando você utiliza de maneira particular intervalos públicos de endereços IP.

Esse comando cria um cluster particular nativo de VPC com:

  • nós que usam o intervalo de endereços IP primários 10.0.0.0/24 da sub-rede;
  • Os pods utilizam de maneira particular o intervalo de endereços IP públicos 5.0.0.0/16 como intervalo secundário de endereços IP da sub-rede para pods.
  • Os serviços utilizam de maneira particular o intervalo público de endereços IP 5.1.0.0/16 como o intervalo secundário de endereços IP da sub-rede para serviços.
gcloud container clusters create cluster-name \
  --enable-ip-alias \
  --enable-private-nodes \
  --disable-default-snat \
  --zone=zone \
  --create-subnetwork name=cluster-subnet,range=10.0.0.0/24 \
  --cluster-ipv4-cidr=5.0.0.0/16 \
  --services-ipv4-cidr=5.1.0.0/16 \
  --master-ipv4-cidr=master-CIDR

Como verificar intervalos de pod e Service

Depois de criar um cluster nativo de VPC, é possível verificar os intervalos de pod e Serviço.

gcloud

Para verificar o cluster, execute o seguinte comando:

gcloud container clusters describe cluster-name

Na saída do comando, observe o campo ipAllocationPolicy:

  • clusterIpv4Cidr é o intervalo secundário de pods.
  • servicesIpv4Cidr é o intervalo secundário de serviços.

Console

Para verificar o cluster, siga estas etapas:

  1. Acesse a página do Google Kubernetes Engine no Console do Cloud.

    Acessar o Google Kubernetes Engine

  2. Na lista de clusters, clique no nome do cluster que você quer inspecionar.

Os intervalos secundários são exibidos na seção Rede:

  • O intervalo de endereços do pod é o intervalo secundário dos pods.
  • O intervalo de endereços de serviço é o intervalo secundário dos serviços.

Solução de problemas

Nesta seção há orientações para resolver problemas relacionados a clusters nativos de VPC.

O recurso "projects/[PROJECT_NAME]/regions/XXX/subnetworks/default" não está pronto

Causas possíveis
Há operações paralelas na mesma sub-rede. Por exemplo, outro cluster nativo de VPC está sendo criado ou um intervalo secundário está sendo adicionado ou excluído na sub-rede.
Resolução
Repetir o comando.

Valor inválido para o campo "resource.secondaryIpRanges [1].ipCidrRange": "XXX". IPCidrRange inválido: XXX está em conflito com a sub-rede "padrão" atual na região "XXX".

Causas possíveis

Outro cluster nativo de VPC está sendo criado simultaneamente, e está tentando alocar os mesmos intervalos na mesma rede VPC.

O mesmo intervalo secundário está sendo adicionado à sub-rede na mesma rede VPC.

Resolução

Se esse erro reaparecer na criação do cluster, quando nenhum intervalo secundário foi especificado, tente executar novamente o comando de criação do cluster.

Não há espaço de IP suficiente para os pods

Sintomas

O cluster está preso em um estado de provisionamento por um longo período de tempo

A criação de cluster retorna um erro do grupo de instâncias gerenciadas (MIG)

Novos nós não podem ser adicionados a um cluster existente

Causas possíveis

O espaço disponível no intervalo de endereços IP do pod não é grande o suficiente para os nós solicitados no cluster. Por exemplo, se o intervalo de endereços IP do pod de um cluster tiver uma máscara de rede com tamanho de /23 (512 endereços), e o máximo de pods por nó for 110, não será possível criar mais de dois nós. Cada nó recebe um intervalo de endereços IP do alias com uma máscara de rede com tamanho de /24.

Soluções

É possível adicionar intervalos de IP do pod ao cluster usando CIDR de vários pods distintos.

Crie um cluster substituto depois de analisar e planejar os intervalos de endereços IP primários e secundários com o tamanho adequado. Consulte Intervalos de IPs para clusters nativos de VPC e Planejamento de intervalo de IPs.

Se não for possível substituir o cluster, você poderá solucionar o problema se criar um novo pool de nós com um número máximo de pods por nó. Se possível, migre as cargas de trabalho para esse pool de nós e, em seguida, exclua o pool de nós anterior. Reduzir o número máximo de pods por nó permite acomodar mais nós em um intervalo de endereços IP secundários fixo para pods. Consulte Intervalo de endereços IP secundários da sub-rede para pods e Intervalos de limitação de nós para detalhes sobre os cálculos envolvidos.

Confirmar se o sNAT padrão está desativado

Use o seguinte comando para verificar o status do sNAT padrão:

gcloud container clusters describe cluster-name

Substitua cluster-name pelo nome do cluster.

A saída incluirá um campo disableDefaultSnat como este:

networkConfig:
  disableDefaultSnat: true
  network: ...

Não é possível usar --disable-default-snat sem --enable-ip-alias

Essa mensagem de erro e must disable default sNAT (--disable-default-snat) before using public IP address privately in the cluster significam que você precisa definir explicitamente a sinalização --disable-default-snat ao criar o cluster, já que está usando endereços IP públicos no cluster particular.

Se você vir mensagens de erro como cannot disable default sNAT ... , isso significa que o SNAT padrão não pode ser desativado no cluster. Revise a configuração do cluster.

Como depurar o Cloud NAT com o sNAT padrão desativado

Se você tiver um cluster particular criado com a sinalização --disable-default-snat, tiver configurado o Cloud NAT para acesso à Internet e não estiver vendo o tráfego vinculado à Internet dos seus pods, verifique se o intervalo de pods está incluído na configuração do Cloud NAT.

Se houver um problema com a comunicação entre pods, examine as regras de iptables nos nós para verificar se os intervalos de pods não estão mascarados por regras de iptables. Consulte o exemplo de saída de iptables do mascaramento de IP para saber como listar as regras iptables e quais são as regras padrão. Se você não tiver configurado um agente de mascaramento de IP para o cluster, o GKE garantirá automaticamente que a comunicação entre pods não seja mascarada. No entanto, se um agente de mascaramento de IP estiver configurado, ele substituirá as regras de mascaramento de IP padrão. Verifique se as regras extras estão configuradas no agente de mascaramento de IP para ignorar o mascaramento dos intervalos de pod.

Restrições

  • Não é possível converter um cluster nativo de VPC em um cluster baseado em rotas, assim como não é possível converter um cluster baseado em rotas em um cluster nativo de VPC.
  • Os clusters nativos de VPC exigem redes VPC. Redes legadas não são compatíveis.
  • Como acontece com qualquer cluster do GKE, os endereços do Serviço (em inglês) (ClusterIP) só estão disponíveis no cluster. Se você precisar acessar um Serviço do Kubernetes de instâncias de VM fora do cluster, mas dentro da rede de VPC e região do cluster, crie um balanceador de carga TCP/UDP interno.
  • Se você usar todos os endereços IP do pod em uma sub-rede, não será possível substituir o intervalo de endereços IP secundário da sub-rede sem colocar o cluster em um estado instável. No entanto, é possível criar outros intervalos de endereços IP de pod usando CIDR de vários pods descontínuos.

A seguir