Documentação do Oracle Cloud Infrastructure

Migrando para Clusters Nativos de VCN

Descubra como migrar um cluster para integrar seu ponto final de API do Kubernetes à sua própria VCN, usando o Kubernetes Engine (OKE).

Em versões anteriores (antes de 16 de março de 2021), o Kubernetes Engine provisionou clusters com pontos finais de API do Kubernetes que não estavam integrados à sua própria VCN. O ponto final da API do Kubernetes era público e você não podia restringir o acesso a ele. Você pode continuar criando esses clusters usando a CLI ou API (até a data especificada no Anúncio de Alteração do Serviço aqui), mas não a Console.

Após 16 de março de 2021, o Kubernetes Engine pode provisionar clusters com seus pontos finais de API do Kubernetes em uma sub-rede em sua própria VCN (esses clusters são conhecidos como "clusters nativos da VCN"). Você tem mais flexibilidade para configurar clusters nativos da VCN para atender aos seus próprios requisitos de segurança e rede. Você pode configurar o ponto final da API do Kubernetes para torná-lo acessível de forma privada na sua VCN (e em uma rede local pareada) ou para torná-lo acessível publicamente pela internet:

  • Para tornar o ponto final da API do Kubernetes acessível de forma privada, hospede o ponto final da API do Kubernetes em uma sub-rede privada e não designe um endereço IP público a ele.
  • Para tornar o ponto final da API do Kubernetes acessível publicamente pela internet, hospede o ponto final da API do Kubernetes em uma sub-rede pública e designe um endereço IP público a ele.

Você pode controlar o acesso à sub-rede do ponto final da API do Kubernetes usando regras de segurança definidas para grupos de segurança de rede (recomendado) ou listas de segurança.

Para aproveitar o controle de segurança oferecido pelos clusters nativos da VCN, você pode migrar um cluster existente para integrar seu ponto final da API do Kubernetes à sua própria VCN.

A migração de cluster tem os seguintes estágios:

  • Estágio 1: Migrar o cluster

    Você inicia a migração selecionando o cluster a ser migrado e especificando a VCN existente e a sub-rede privada ou pública para hospedar o novo ponto final da API do Kubernetes. A migração geralmente leva cerca de 15 minutos.

    Durante esse tempo, a API do Kubernetes continua acessível por meio do ponto final público original que não está integrado à sua própria VCN. No entanto, as operações do ciclo de vida do cluster (como atualizações do cluster, criação e exclusão do pool de nós) não estão disponíveis.

    Consulte Migrando um Cluster Existente para ser nativo da VCN.

  • Estágio 2: Configurar o acesso ao cluster migrado

    Quando a migração é concluída, o cluster se torna acessível por meio do novo ponto final da API do Kubernetes em sua própria VCN, bem como por meio do ponto final da API pública original do Kubernetes que não está integrado à sua VCN. Agora você pode atualizar a configuração de seu kubectl, ferramentas e pipelines de CI/CD para usar o novo ponto final da API do Kubernetes.

    Para verificar se você atualizou corretamente seu kubectl, suas ferramentas e seus pipelines de CI/CD, você tem a opção de desativar temporariamente o ponto final da API pública original do Kubernetes, testar se as configurações atualizadas usam o novo ponto final da API do Kubernetes e, em seguida, fazer rollback da desativação do ponto final original.

    Consulte Configurando o Acesso a um Cluster Migrado.

  • Estágio 3: Descomissionar o ponto final original da API pública do Kubernetes que não está integrado à sua própria VCN

    Quando tiver certeza de que atualizou corretamente a configuração de seu kubectl, ferramentas e pipelines de CI/CD para usar o novo ponto final da API do Kubernetes em sua própria VCN, você poderá desativar o ponto final original da API pública do Kubernetes que não esteja integrado à sua VCN. Quando você desativa o ponto final original da API do Kubernetes, o cluster só é acessível por meio do novo ponto final da API do Kubernetes. Descomissionamento geralmente leva menos de cinco minutos.

    Observe que, se você não desativar explicitamente o ponto final original, o cluster continuará acessível por meio do ponto final original e do novo ponto final.

    Após desativar o ponto final original, você tem vários dias em que pode reverter a desativação e reativar esse ponto final original. O período de rollback padrão é 30 dias, mas você pode aumentar o período de rollback para um máximo de 60 dias.

    Consulte Desativando o Ponto Final Original da API Pública do Kubernetes de um Cluster Migrado.

Migrando um Cluster Existente para ser nativo da VCN

Usando a Console

Para migrar um cluster existente para ser nativo da VCN, tornando-o acessível por meio de um novo ponto final da API do Kubernetes na sua VCN:

  1. Na página da lista Clusters, selecione o nome do cluster que você deseja migrar. Se precisar de ajuda para localizar a página de lista ou o cluster, consulte Listando Clusters.

    Os labels Migração obrigatória aparecem na página de lista Clusters ao lado dos nomes de clusters com pontos finais da API do Kubernetes que não estão integrados à sua VCN.

    Quando você seleciona um cluster que pode migrar, o botão Migrar Cluster é exibido na parte superior da guia Detalhes do cluster.

  2. Se você quiser que o ponto final da API do Kubernetes do cluster seja acessível publicamente pela internet e hospedado em uma nova sub-rede pública na mesma VCN do cluster (criando e configurando novos recursos de rede conforme necessário), execute uma Migração Automática da seguinte forma:
    1. Na parte superior da guia Detalhes do cluster, selecione Migrar Cluster para integrar o ponto final da API do Kubernetes do cluster à sua própria VCN.
    2. Na caixa de diálogo Migrar para Cluster Nativo da VCN, selecione Migração Automática para criar uma nova sub-rede regional na VCN do cluster com um bloco CIDR 10.0.0.0/28, juntamente com listas de segurança e tabelas de roteamento.
    3. Selecione Iniciar Workflow e revise o resumo da migração na caixa de diálogo Migração de Cluster de Pontos Finais Nativos da VCN.
    4. Selecione Migrar para criar novos recursos de rede e migrar o cluster.

      O Kubernetes Engine começa a migrar o cluster, conforme mostrado na caixa de diálogo Migrando Cluster.

    5. Selecione Fechar para fechar a caixa Migrando Cluster.
  3. Se você quiser que o ponto final da API do Kubernetes do cluster seja acessível de forma privada dentro da sua VCN ou acessível publicamente pela internet e hospedado em uma sub-rede pública ou privada regional existente na mesma VCN do cluster, execute uma Migração Personalizada da seguinte forma:
    1. Confirme se os seguintes recursos de rede já existem na VCN e estão configurados corretamente para hospedar o ponto final da API do Kubernetes (caso contrário, crie-os e configure-os adequadamente): Por exemplo, configurações, consulte Exemplo de configurações de recursos de rede.
    2. Na parte superior da guia Detalhes do cluster, selecione Migrar Cluster para integrar o ponto final da API do Kubernetes do cluster à sua própria VCN.
    3. Na caixa de diálogo Migrar para Cluster Nativo da VCN, selecione Migração Personalizada.
    4. Selecione Iniciar Workflow e especifique:
      • Sub-rede de Ponto Final da API do Kubernetes: Uma sub-rede regional para hospedar o ponto final da API do Kubernetes do cluster. A sub-rede especificada pode ser pública ou privada. O ponto final de API do Kubernetes sempre recebe um endereço IP privado. Se você especificar uma sub-rede pública, poderá opcionalmente expor o ponto final da API do Kubernetes à internet designando um endereço IP público ao ponto final (bem como o endereço IP privado). Para simplificar o gerenciamento de acesso, a Oracle recomenda que o ponto final da API do Kubernetes esteja em outra sub-rede para nós de trabalho e balanceadores de carga. Para obter mais informações, consulte Plano de Controle de Cluster do Kubernetes e API do Kubernetes.
      • Usar grupos do serviço network security para controlar tráfego: Opcionalmente, restrinja o acesso ao ponto de extremidade da API do Kubernetes do cluster usando um ou mais grupos do serviço network security (NSGs) que você especificar. Para obter mais informações sobre as regras de segurança que devem ser especificadas para o NSG, consulte Regras de Segurança do Ponto Final da API do Kubernetes.
      • Designar um endereço IP público ao ponto de extremidade da API: Se você tiver selecionado uma sub-rede pública para o ponto de extremidade da API do Kubernetes, poderá, opcionalmente, expor o ponto de extremidade à internet designando um endereço IP público ao ponto de extremidade (assim como o endereço IP privado) Se você não designar um endereço IP público, atualize as regras de roteamento e as regras de segurança para permitir o acesso ao ponto final usando um gateway de serviço e um gateway NAT (consulte Configuração da Sub-rede de Ponto Final da API do Kubernetes).
    5. Selecione Migrar para criar novos recursos de rede e migrar o cluster.

      O Kubernetes Engine começa a migrar o cluster.

A migração geralmente leva cerca de 15 minutos para ser concluída. Durante esse tempo, a API do Kubernetes continua acessível por meio do ponto final público original que não está integrado à sua própria VCN. No entanto, as operações do ciclo de vida do cluster (como atualizações do cluster, criação e exclusão do pool de nós) não estão disponíveis.

Quando a migração é concluída, a guia Detalhes do cluster mostra o nome da sub-rede do ponto final da API do Kubernetes, o endereço IP do ponto final privado da API do Kubernetes e (se você tiver designado um endereço IP público ao ponto final da API do Kubernetes) o endereço IP do ponto final público da API do Kubernetes.

Uma mensagem indica que o cluster foi migrado e está pendente de desativação do ponto final da API pública. Nesse ponto, o cluster recém-migrado pode ser acessado por meio do novo ponto final da API do Kubernetes na sua VCN e por meio do ponto final original da API pública do Kubernetes que não está integrado à sua própria VCN.

Usando a CLI

Use o comando oci ce cluster-migrate-to-native-vcn e os parâmetros necessários para migrar um cluster existente a fim de integrar seu ponto final de API do Kubernetes à sua própria VCN:

oci ce cluster cluster-migrate-to-native-vcn --cluster-id <cluster-ocid> --endpoint-config "{\"subnetId\":\"<kube-api-endpoint-subnet-ocid>\"}" [OPTIONS]

Para ver uma lista completa de parâmetros e valores para comandos CLI, consulte a Referência de Comando CLI.

Usando a API

Execute a operação ClusterMigrateToNativeVcn para migrar um cluster e integrar seu ponto final da API do Kubernetes à sua própria VCN.

Configurando o Acesso a um Cluster Migrado

Depois de migrar um cluster para integrar seu ponto final da API do Kubernetes à sua própria VCN, você precisa atualizar a configuração do seu kubectl, ferramentas e pipelines de CI/CD para usar o novo ponto final da API do Kubernetes. No mínimo, você desejará atualizar o arquivo de configuração do Kubernetes do cluster (comumente conhecido como arquivo 'kubeconfig') para permitir o acesso ao cluster migrado usando o kubectl, conforme descrito neste tópico. Você também precisa atualizar qualquer arquivo de manifesto que inclua referências ao endereço IP do ponto final da API do Kubernetes original do cluster.

Siga as instruções deste tópico para gerar um novo arquivo kubeconfig. Essas instruções pressupõem que o arquivo kubeconfig do cluster seja salvo no local padrão ($HOME/.kube) e com o nome padrão (config). Se não for esse o caso, adapte as instruções em conformidade.

  1. Na janela do terminal em que você normalmente executa comandos da CLI do Oracle Cloud Infrastructure, execute o seguinte comando para atualizar o arquivo kubeconfig existente do cluster:

    oci ce cluster create-kubeconfig --cluster-id <cluster-ocid> --file <kubeconfig-file-location> --region <region-name> --token-version 2.0.0 --kube-endpoint PRIVATE_ENDPOINT|PUBLIC_ENDPOINT

    em que:

    • --cluster-id <cluster-ocid> é o OCID do cluster existente que você deseja tornar nativo da VCN.
    • --file <kubeconfig-file-location> é o local do arquivo kubeconfig do cluster.
    • --region <region-name> é a região na qual o cluster está localizado.
    • --kube-endpoint PRIVATE_ENDPOINT|PUBLIC_ENDPOINT especifica se o endereço IP privado ou o endereço IP público do ponto final da API do Kubernetes do cluster será adicionado ao arquivo kubeconfig. Para obter mais informações, consulte Plano de Controle de Cluster do Kubernetes e API do Kubernetes.

    Por exemplo:

    oci ce cluster create-kubeconfig --cluster-id ocid1.cluster.oc1.phx.aaaaaaaaae... --file $HOME/.kube/config --region us-phoenix-1 --token-version 2.0.0 --kube-endpoint PUBLIC_ENDPOINT

    Supondo que o arquivo kubeconfig já exista no local especificado, os detalhes do cluster serão adicionados como um novo contexto ao arquivo kubeconfig existente, incluindo o novo ponto final da API do Kubernetes do cluster na sua própria VCN. O elemento current-context: no arquivo kubeconfig é definido para apontar para o contexto adicionado recentemente.

    Para obter mais informações sobre como configurar o arquivo kubeconfig, consulte Configurando o Acesso ao Cluster.

  2. Certifique-se de que o kubectl possa se conectar ao cluster usando o novo ponto final da API do Kubernetes do cluster, digitando o seguinte comando:

    kubectl get nodes

    São mostradas informações sobre os nós do cluster.

    Agora, você pode usar o kubectl para executar operações no cluster usando o novo ponto final da API do Kubernetes do cluster.

Observação

Até que o ponto final da API original que não está integrado à sua VCN seja desativado, você poderá continuar a gerar o arquivo kubeconfig original omitindo a opção --kube-endpoint do comando oci ce cluster create-kubeconfig.

Desativando o Ponto Final Original da API Pública do Kubernetes de um Cluster Migrado

Usando a Console

Para desativar o ponto final original da API pública do Kubernetes que não esteja integrado à sua própria VCN:

  1. Na parte superior da guia Detalhes do cluster, selecione Desativar quando quiser:

    • Desative temporariamente o ponto final original, teste se as configurações atualizadas usam o novo ponto final da API do Kubernetes e, em seguida, faça rollback da desativação.
    • Desative permanentemente o ponto final original.

    A desativação geralmente leva menos de cinco minutos para ser concluída. Quando a desativação é concluída, um período de rollback padrão de 30 dias é adicionado. Durante o período de rollback, você pode:

    • restaurar o ponto final original
    • estender o período de rollback
    Importante

    Quando o período de rollback terminar, você não poderá mais fazer rollback da desativação do ponto final original. O terminal original é desativado permanentemente e o processo de desativação não pode ser revertido.

  2. (Opcional) Selecione Rollback para fazer rollback da desativação e restaurar o ponto final original. O rollback geralmente leva menos de cinco minutos para ser concluído.
  3. (Opcional) Selecione Estender prazo de rollback para aumentar o período de rollback para no máximo 60 dias.

Usando a CLI

Use o comando oci ce cluster start-public-api-endpoint-decommission e os parâmetros necessários para desativar o ponto final original de um cluster:

oci ce cluster start-public-api-endpoint-decommission --cluster-id <cluster-ocid> [OPTIONS]

Use o comando oci ce cluster rollback-public-api-endpoint-decommission e os parâmetros necessários para fazer rollback da desativação do ponto final original de um cluster:

oci ce cluster rollback-public-api-endpoint-decommission --cluster-id <cluster-ocid> [OPTIONS]

Use o comando oci ce cluster extend-endpoint-decommission-rollback-deadline e os parâmetros necessários para aumentar o período de rollback ao desativar o ponto final original de um cluster:

oci ce cluster extend-endpoint-decommission-rollback-deadline --cluster-id <cluster-ocid> --rollback-deadline-delay <duration> [OPTIONS]

em que --rollback-deadline-delay <delay> especifica uma duração no formato ISO 8601. Por exemplo, --rollback-deadline-delay P10d para aumentar o período de rollback em 10 dias.

Para ver uma lista completa de parâmetros e valores para comandos CLI, consulte a Referência de Comando CLI.

Perguntas Frequentes sobre Migração de Cluster

O que são clusters nativos da VCN?

O Kubernetes Engine cria clusters do Kubernetes totalmente integrados na Rede Virtual na Nuvem (VCN) do Oracle Cloud Infrastructure. Nós de trabalho, balanceadores de carga e o ponto final da API do Kubernetes fazem parte da sua própria VCN e você pode configurá-los como públicos ou privados. Esses clusters totalmente integrados em sua própria VCN são conhecidos como "clusters nativos da VCN".

Como posso saber se um cluster já é um cluster nativo da VCN?

Se você não tiver certeza se um cluster já é nativo da VCN, exiba informações sobre o cluster (por exemplo, na guia Detalhes do cluster na Console). Se o cluster já for nativo da VCN, os detalhes do cluster incluirão informações do Ponto Final da API do Kubernetes. Se o cluster ainda não for nativo da VCN, os detalhes do cluster simplesmente incluirão o Endereço do Kubernetes.

Preciso migrar todos os meus clusters existentes?

Não, você só precisa migrar clusters existentes que deseja transformar em clusters nativos da VCN. Se você não quiser integrar o ponto final da API do Kubernetes de um cluster à sua própria VCN, simplesmente não migre esse cluster.

A migração envolve algum tempo de inatividade?

Enquanto um cluster está sendo migrado para um cluster nativo da VCN, a API do Kubernetes do cluster continua acessível por meio do ponto final público original que não está integrado à sua própria VCN. No entanto, as operações do ciclo de vida do cluster (como atualizações do cluster, criação e exclusão do pool de nós) não estão disponíveis.

Devo escolher migração automática ou migração personalizada?

A migração automática cria uma sub-rede regional na VCN do cluster com um bloco CIDR 10.0.0.0/28, juntamente com listas de segurança e tabelas de roteamento. A sub-rede é pública e um endereço IP público é atribuído ao ponto final da API. A migração automática só suporta clusters com pools de nós no mesmo compartimento do cluster. Para clusters com pools de nós em compartimentos diferentes, execute uma migração personalizada.

A migração personalizada permite que você escolha uma sub-rede regional pública ou privada existente para hospedar o ponto final da API do Kubernetes do cluster. Se você escolher uma sub-rede regional pública, poderá expor opcionalmente o ponto final da API do Kubernetes à internet designando um endereço IP público ao ponto final. Opcionalmente, você pode optar por usar grupos de segurança de rede.

Como configuro uma sub-rede em minha VCN para hospedar o ponto final da API do Kubernetes?

Consulte Configuração de Recursos de Rede para Criação e Implantação de Cluster para obter detalhes sobre como configurar a sub-rede de ponto final da API do Kubernetes, as listas de segurança e a tabela de roteamento.

Quero testar a migração para um cluster nativo da VCN. Como posso criar um cluster com um ponto final de API do Kubernetes que não esteja integrado à minha VCN?

Na janela de terminal em que você normalmente executa comandos da CLI do Oracle Cloud Infrastructure (e até a data especificada no Anúncio de Alteração de Serviço aqui), execute o seguinte comando para criar um cluster de teste com um ponto final da API do Kubernetes que não esteja integrado à sua VCN:

oci ce cluster create --compartment-id <compartment-ocid> --kubernetes-version v<kubernetes-version-number> --name <cluster-name> --vcn-id <vcn-ocid>

em que:

  • --compartment-id <compartment-ocid> é o OCID do compartimento ao qual você deseja que o cluster de teste pertença.
  • --kubernetes-version v<kubernetes-version-number> é uma versão suportada do Kubernetes (consulte Versões do Kubernetes Suportadas Atualmente). Por exemplo, --kubernetes-version v1.19.7
  • --name <cluster-name> é o nome de sua escolha para o cluster de teste. Por exemplo, --name test-vcn-native-migration
  • --vcn-id <vcn-ocid> é o OCID da VCN na qual o cluster de teste será criado.

Tendo criado um cluster de teste com um ponto final de API do Kubernetes que não está integrado à sua VCN, agora você pode migrar o cluster de teste para torná-lo um cluster nativo da VCN. Consulte Migrando um Cluster Existente para ser nativo da VCN.

Lembre-se de excluir o cluster de teste quando não precisar mais dele.