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 os benefícios e os requisitos dos clusters nativos de VPC, consulte 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.

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

Nas instruções a seguir, demonstramos como criar um cluster do 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.
    • 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 o menu do Google Kubernetes Engine no Console do Cloud.

    Acessar o menu do Google Kubernetes Engine

  2. Clique no botão Criar cluster.

  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

Nas instruções a seguir, demonstramos como criar um cluster do GKE nativo de VPC e uma sub-rede 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ários da sub-rede para pods. Se omitido, o GKE usa /14, o tamanho padrão do intervalo de endereços IP do pod.
  • 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ários da sub-rede para serviços. 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 que usam o 1.14.2-gke.1 e versões mais recentes 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 de endereços IP públicos reutilizados de maneira particular

Os clusters do GKE que usam o 1.14.2-gke.1 e versões mais recentes podem reutilizar de maneira particular determinados intervalos de endereços IP públicos como intervalos de endereços IP de sub-rede internos. É possível reutilizar 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 particular para usar intervalos de endereços IP públicos reutilizados de maneira particular. Clusters nativos de VPC não particulares e clusters baseados em rotas não são permitidos.

Os intervalos públicos reutilizados de maneira particular são os de sub-rede. É possível usá-los exclusivamente ou 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ê reutiliza um intervalo de endereços IP públicos como um intervalo de sub-redes, o cluster pode não se comunicar mais com sistemas na Internet que usam esse intervalo público, que se tornará um intervalo de endereços IP internos na rede VPC do cluster.

  • Os intervalos de sub-redes, mesmo aqueles que reutilizam de maneira particular os intervalos de endereços IP públicos, 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 reutilizados de maneira particular, a menos que você substitua o cluster.

  • Os pacotes enviados de pods que usam um intervalo de endereços IP públicos reutilizados de maneira particular não podem ter as origens alteradas (SNAT) para endereços de nó. Portanto, você precisa criar o cluster com a sinalização --disable-default-snat. Para mais detalhes sobre essa sinalização, consulte Mascaramento de IP no GKE.

  • Como um cluster com pods que reutilizam de maneira particular os intervalos de endereços IP públicos precisa ser um cluster particular, o cluster precisa usar uma solução NAT, como Cloud NAT, se os pods precisarem enviar tráfego para destinos na Internet. Ao usar o Cloud NAT, você precisa configurar pelo menos o gateway NAT para usar no intervalo de endereços IP secundários da sub-rede do cluster para pods. Desse modo, o Cloud NAT executa o SNAT dos pacotes enviados dos endereços IP do pod porque a configuração de mascaramento de IP do cluster precisa ter o comportamento padrão do SNAT desativado.

Exemplo de cluster com intervalos públicos reutilizados 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 as sinalizações a seguir:

  • --enable-ip-alias: cria um cluster nativo de VPC, que é necessário quando você reutiliza de maneira particular intervalos de endereços IP públicos.
  • --enable-private-nodes: cria um cluster particular, que é necessário quando você reutiliza de maneira particular intervalos de endereços IP públicos.
  • --disable-default-snat: essa opção será necessária se você reutilizar endereços IP públicos de maneira particular para seus pods ou nós. É necessário desativar o SNAT a fim de que as respostas possam ser roteadas para o pod que originou o tráfego.

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 reutilizam de maneira particular o intervalo de endereços IP públicos 5.0.0.0/16 como o intervalo de endereços IP secundários da sub-rede para pods.
  • Os serviços reutilizam de maneira particular o intervalo de endereços IP públicos 5.1.0.0/16 como o intervalo de endereços IP secundários 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 pods e serviços

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 o menu do Google Kubernetes Engine no Console do Cloud.

    Acessar o menu do Google Kubernetes Engine

  2. Selecione o cluster pretendido.

Os intervalos secundários são exibidos na seção Cluster sob a guia Detalhes:

  • O intervalo de endereços do contêiner é 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

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, talvez solucione o problema se você criar um novo pool de nós com um número máximo de pods por nó menor. 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.

A seguir