Criar Cluster do Oracle Cloud Infrastructure Kubernetes Engine usando o Terraform

Introdução

Neste tutorial, demonstraremos como criar um cluster do Oracle Cloud Infrastructure Kubernetes Engine (OKE) usando o Terraform e gerenciar o código do Terraform com o Oracle Resource Manager. Essa abordagem permite implementar princípios de Infraestrutura como Código (IaC), aprimorando a automação, a consistência e a repetibilidade em suas implantações.

Oracle Cloud Infrastructure Kubernetes Engine (OKE)

O Kubernetes (K8s) é uma plataforma de código aberto para automatizar a implantação, o dimensionamento e o gerenciamento de aplicativos conteinerizados. Originalmente desenvolvido pelo Google e agora mantido pela CNCF, é o padrão do setor para executar aplicações nativas da nuvem em escala.

O OKE é um serviço totalmente gerenciado na Oracle Cloud Infrastructure (OCI) que simplifica a implantação e o gerenciamento de clusters do Kubernetes. Ele automatiza o plano de controle e o gerenciamento de nós de trabalho, se integra aos serviços de rede, armazenamento e segurança da OCI e oferece suporte a cargas de trabalho sem monitoramento de estado e com monitoramento de estado. Os nós do OKE são organizados em pools de nós, que podem ser facilmente dimensionados e gerenciados, garantindo alta disponibilidade e utilização ideal de recursos para aplicativos em contêineres. O OKE segue o modelo padrão do Kubernetes, com dois componentes principais (plano de controle gerenciado e um plano de dados gerenciado pelo cliente).

Para obter mais informações, consulte Gerenciar o OCI Kubernetes Engine com Diferentes Tipos de Capacidade e Resolver Problemas Comuns em Nós Preemptíveis.

Arquitetura

A arquitetura de referência a seguir será usada para demonstrar a criação do cluster do OKE.

OKEArchitecture

O diagrama ilustra uma arquitetura resiliente do OKE implantada em uma única região da OCI distribuída entre vários FDs (Fault Domains). A configuração apresenta uma VCN (Rede Virtual na Nuvem) com três sub-redes distintas: uma sub-rede pública (LBSubnet) que hospeda um gateway de internet e um Balanceador de Carga do OCI para distribuir o tráfego de entrada e duas sub-redes privadas, uma para nós de trabalho do OKE (NodeSubnet) e outra para o servidor de API (APISubnet). Os nós de trabalho são distribuídos em três FDs em um único domínio de disponibilidade (AD), minimizando o risco de falha. O cluster se conecta perfeitamente ao OCI Container Registry para armazenamento e recuperação de imagens de contêiner.

A Console do OCI oferece um método Point-&-Click simples. Para usá-lo, navegue até a interface do usuário dos clusters do Kubernetes. Selecione Criar Rápido. Nomeie o cluster. Selecione um ponto final de API privado. Configure nós de trabalho gerenciados com a forma, a imagem e a contagem desejadas. A opção da Console do OCI configura um cluster do OKE aprimorado. Ele utiliza o CNI OCI_VCN_IP_NATIVE, que é o padrão. Ele também fornece sub-redes privadas dedicadas para nós de trabalho e o ponto final da API. Além disso, ele cria uma sub-rede pública para o balanceador de carga. No entanto, essa abordagem manual é demorada e não pode ser dimensionada para implantações grandes ou repetíveis

Para superar as limitações da implantação manual, este tutorial fornece uma solução simplificada e simples baseada no Terraform que automatiza toda a configuração do cluster do OKE em três etapas:

Este tutorial se concentra na implantação da infraestrutura de cluster do OKE principal. As personalizações no nível do aplicativo e as configurações específicas da carga de trabalho estão fora de seu escopo. Para simplificar o provisionamento, incluímos scripts Bash que automatizam a execução de comandos do Terraform. Esses scripts foram projetados para integração perfeita em um pipeline de Jenkins trifásico, permitindo a implantação automatizada One-Click de todo o ambiente OKE.

Você aprenderá a automatizar a criação de recursos de rede (VCN, gateways, sub-redes), o cluster do OKE e seus pools de nós usando a CLI do Terraform e o Oracle Resource Manager. Também demonstraremos como estender essa automação usando Bash, OCI CLI e Jenkins, reduzindo o esforço manual e garantindo a entrega consistente da infraestrutura.

Objetivos

Pré-requisitos

Automação do Terraform para Criação de Cluster do OKE

Há duas opções de automação para criar a VCN (OKE-VCN) e o Cluster do OKE: um Módulo Simples ou um Módulo Padrão que utiliza módulos filhos. Esta última abordagem está fora do escopo deste artigo, mas oferece melhor organização e escalabilidade para implementações maiores e complexas, promovendo a reutilização e a capacidade de manutenção do código, tornando-o ideal para ambientes de produção. Usaremos a abordagem simples e simples, adequada para casos de uso de desenvolvimento, cenários de teste ou uma demonstração única de implantação de VCN. Para obter mais informações, consulte terraform-oci-oke.

Tarefa 1: Implantar Recursos do OKE com o Terraform (Community Edition)

Antes de executar comandos do Terraform para planejar e implantar sua infraestrutura usando a CLI do Terraform, atualize a configuração do Terraform fornecida com os detalhes específicos do seu ambiente, seja da sua máquina local ou por meio do OCI Cloud Shell.

Você pode fazer download do código-fonte completo do Terraform aqui: oke_terraform_for_beginners.zip. Estamos usando uma estrutura de diretório simples. Quando você descompactar o pacote, certifique-se de que todos os seus códigos-fonte de modelo do Terraform (.tf, .tfvars, chaves ssh etc) estejam localizados no diretório raiz.

  1. Para instruir o Terraform a criar qualquer um dos recursos principais (VCN, OKE_Cluser ou Node_Pool), defina o flag apropriado (is_vcn_created, is_k8cluster_created ou is_pool_created) como true no seu terraform.tfvars. Em seguida, especifique os parâmetros restantes para a rede, o cluster do OKE e o pool de nós dentro de seus respectivos blocos de código.

    1. Comece definindo is_vcn_created como true para instruir o Terraform a criar uma nova VCN ou false para usar uma VCN existente (você precisará fornecer seu OCID). Se estiver criando uma nova VCN, certifique-se de especificar uma variável de bloco CIDR vcn_cidr_block.

    2. Forneça os blocos CIDR para as três sub-redes a seguir.

      • Sub-rede privada do ponto final da API K8 (k8apiendpoint_private_subnet_cidr_block).
      • Sub-rede privada do nó de trabalho (workernodes_private_subnet_cidr_block).
      • Sub-rede pública do balanceador de carga de serviço (serviceloadbalancers_public_subnet_cidr_block).

    3. Defina o flag is_k8cluster_created para informar ao Terraform para criar um cluster do Kubernetes e especificar o compartimento de destino usando compartment_id. Se um pool de nós de trabalho for necessário, defina o flag is_nodepool_created adequadamente.

    4. O OKE suporta dois tipos de CNI: Nativo da VCN (padrão), em que cada pod obtém seu próprio IP para melhor desempenho e integração total da rede OCI, e Sobreposição do Flannel, uma rede de sobreposição mais simples em que os pods compartilham a VNIC do nó. Nesta configuração, o cni_type é definido como OCI_VCN_IP_NATIVE para corresponder à configuração de cluster padrão criada pelo workflow Criação Rápida na Console do OCI.

    5. O OKE oferece dois tipos de cluster: Básico e Melhorado. Para maior flexibilidade, definimos cluster_type como ENHANCED_CLUSTER.

      • Clusters aprimorados fornecem recursos avançados, como gerenciamento de complementos, segurança aprimorada e melhor controle do ciclo de vida
      • Os clusters básicos oferecem um ambiente Kubernetes direto com recursos essenciais

    6. A configuração do ciclo de nós node_cycle_config define como os nós de trabalho são criados, substituídos ou atualizados em um pool de nós, especialmente durante atualizações, upgrades ou eventos de dimensionamento automático. A configuração define os seguintes atributos:

      • is_node_cycling_enabled (bool): Permite o ciclo automático (substituição) de nós durante uma atualização ou upgrade. Defina como verdadeiro para ativar a rotação do nó seguro.
      • maximum_surge (int): O número máximo de nós extras (além da contagem desejada) que podem ser adicionados durante as atualizações. Permite que novos nós sejam criados antes que os antigos sejam excluídos sem tempo de inatividade.
      • maximum_unavailable (int): O número máximo de nós que podem estar indisponíveis durante as atualizações. Usado para controlar a interrupção durante atualizações contínuas.
      • cycle_modes (list) (Opcional): Fornece uma lista ordenada de ações para o ciclo do nó. Os modos de ciclo disponíveis são:
        • REPLACE_BOOT_VOLUME: Atualiza o volume de inicialização sem encerrar o nó.
        • REPLACE_NODES: Cordonar, drenar, encerrar e recriar nós com configuração atualizada.

  2. Modifique os valores padrão somente se necessário. O pacote inclui instruções claras de configuração de ambiente, etapas de execução e conceitos-chave relacionados a rede e segurança.

    Veja a seguir uma amostra da configuração do Terraform no arquivo terraform.tfvars que você precisa personalizar para ser executado no seu ambiente.

    	##########################################################################
	# Terraform module: OKE Cluster with Flat Network.                       #
	#                                                                        #
	# Author: Mahamat H. Guiagoussou and Payal Sharma    		             #
	#                                                                        #
	# Copyright (c) 2025 Oracle                                              #
	##########################################################################

	# Working Compartment
	compartment_id = "WORKING_COMPARTMENT"

	#------------------------------------------------------------------------#
	# Step 2.1:  Create Flat Network                                         #
	#------------------------------------------------------------------------#
	is_vcn_created = false   # Terraform creates VCN if set to 'true'

	# Display Name Prefix & Host Name Prefix 
	display_name_prefix = "DISPLAY_NAME_PREFIX" # e.g.: "ACME-DEV"
	host_name_prefix    = "HOST_PREFIX"         # e.g.: "myvcn" 

	# VCN & Subnets CIDR Blocks
	vcn_cidr_block                                = "VCN_CIDR_BLOCK" 
	k8apiendpoint_private_subnet_cidr_block       = "ENDPOINT_CIDR_BLOCK" 
	workernodes_private_subnet_cidr_block         = "WRKRNODE_CIDR_BLOCK" 
	serviceloadbalancers_public_subnet_cidr_block = "LB_CIDR_BLOCK" 

	#------------------------------------------------------------------------#
	# Step 2.2: Create the OKE Cluster                                       #
	#------------------------------------------------------------------------#

	is_k8cluster_created             = false # Terraform creates OKE cluster if 'true' 
	control_plane_kubernetes_version = "K8_VERSION" # e.g.: "v1.32.1"
	cni_type                         = "OCI_VCN_IP_NATIVE" # FLANNEL_OVERLAY
	control_plane_is_public          = false

	# Set the below flag to true for 'OCI_VCN_IP_NATIVE'. This is needed to 
	# provision a dedicated subnet for pods when using the VCN-Native CNI.
	create_pod_network_subnet        = true               # NO subnet 'false'           
	image_signing_enabled            = false              # image not signed
	cluster_type                     = "ENHANCED_CLUSTER" # or "BASIC_CLUSTER"

	#------------------------------------------------------------------------#
	# Step 2.3: Create a Node Pool for the cluster                           #
	#------------------------------------------------------------------------#
	is_nodepool_created             = false # Terraform creates Node_Pool if 'true'
	worker_nodes_kubernetes_version = "WORKER_NODE_VERSION" # e.g.: "v1.32.1"

	# Detailed configuration for the Node Pool
	node_pools = {
	  node_pool_one = {
		name  = "WORKER_NODE_POOL_DISPLAY_NAME" # e.g. "my_worker_node_pool",
		# https://docs.oracle.com/en-us/iaas/Content/ContEng/Reference/contengimagesshapes.htm
		shape = "WORKER_NODE_SHAPE_NAME" # e.g.: "VM.Standard.E4.Flex",   
		shape_config = {
			ocpus  = "WORKER_NODE_NB_OF_OCPUS" # e.g.: 1
			memory = "WORKER_NODE_MEMOR_SIZE"  # e.g.: 16
		},
		boot_volume_size =  "WORKER_BOOT_VOLUME_SIZE"  # e.g.: 50
		# Oracle maintains a list of supported OKE worker node images here:
		# https://docs.oracle.com/en-us/iaas/images/oke-worker-node-oracle-linux-8x/ 
		# https://docs.oracle.com/en-us/iaas/Content/ContEng/Reference/contengimagesshapes.htm#images__oke-images
		image = "WORKER_NODE_OKE_IMAGE"  # e.g.: ocid1.image.oc1.iad...."

		node_labels = { hello = "Demo"},

		# Run command "oci iam availability-domain list" to list region's ADs.
		# No need to set Fault Domains, they are selected automatically
		availability_domains     = ["YOUR_AD_NAME"] # e.g. "GqIF:US-ASHBURN-AD-1", 
		number_of_nodes          = "NB_OF_NODES_IN_THE_POOL" # e.g. 1,
		pv_in_transit_encryption = false,
		node_cycle_config = {
			node_cycling_enabled   = false
			maximum_surge          = 1
			maximum_unavailable    = 0
		},
		ssh_key = "YOUR_SSH_KEY_PATH" # e.g.: "worker_node_ssh_key.pub" 
	  }
	}

  3. Execute os comandos do Terraform a seguir.

    terraform init
terraform validate
terraform plan
terraform apply

    Após a execução bem-sucedida de terraform apply, seu cluster do OKE será criado no seu compartimento de trabalho e região com a seguinte configuração:

    • Um ENHANCED_CLUSTER com o OCI_VCN_IP_NATIVE cni_type e a versão especificada do OKE.
    • Sub-redes privadas dedicadas para nós de trabalho e o ponto final da API.
    • Uma sub-rede pública para que o balanceador de carga acesse os serviços de cluster.
    • Um pool de nós gerenciados configurado com a forma, imagem e contagem de nós desejados.

  4. Vá para a Console do OCI para confirmar a implantação e a configuração do cluster.

    OKECluster

    As imagens a seguir ilustram uma execução bem-sucedida do Terraform com os logs gerados.

    OKETFLogs

  5. Quando terminar de testar, execute terraform destroy para limpar seu ambiente. Este comando remove todos os recursos do OKE criados durante a implantação e ajuda a evitar o consumo desnecessário de recursos em sua tenancy.

Tarefa 2: Automatizar a Execução da CLI do Terraform com o Pipeline de CI/CD do Jenkins

Nesta tarefa, vamos abstrair as etapas previamente detalhadas em quatro estágios primários, projetados para orquestração posterior por Jenkins. Esse pipeline agregado é implementado por meio de um conjunto de scripts Bash que executam comandos da CLI do Terraform.

Tarefa 2.1: Criar Recursos de Rede

O script a seguir executa uma sequência de vários comandos do Terraform para criar os recursos de rede.

Para os scripts restantes, verifique se terraform init já foi executado e se você está executando os comandos do diretório de trabalho. Por exemplo, ~/oke_terraform_for_beginners.

Tarefa 2.2: Criar Cluster do OKE

Este script executa o comando terraform apply para criar o cluster do OKE.

Tarefa 2.3. Criar Pool de Nós de Trabalho do OKE

O script a seguir executa o comando terraform apply para criar o pool de nós de trabalho do cluster do OKE.

Tarefa 2.4: Destruir todos os Recursos

Este script executa um comando destroy, expurgando todos os recursos do cluster do OKE (recursos de rede, cluster do OKE e pool de nós de trabalho).

Automatizamos o processo de ponta a ponta do pipeline do Jenkins, consolidando-o em quatro tarefas de construção do Jenkins (Tarefa 2.1, 2.2, 2.3). Esse pipeline agregado é executado por meio de scripts Bash que executam comandos da CLI do Terraform. A imagem abaixo mostra a automação de Um Clique para as três primeiras tarefas; a etapa destroy não é incluída para simplificar.

OKEArchitecture

Tarefa 3: Orquestrar Implantações do OKE com o Oracle Resource Manager

Fluxo do Oracle Resource Manager (ilustrado):

OKEArchitecture

O diagrama a seguir descreve as sete etapas que ilustram o Oracle Resource Manager Code Manager:

  1. Configuração de Origem: Define onde a configuração IaC se origina, como um compartimento no OCI, um bucket do OCI Object Storage, um arquivo Zip, Bitbucket ou GitHub.
  2. Modelo do Terraform: A configuração da infraestrutura é definida usando o Terraform HashiCorp em um arquivo de modelo.
  3. Oracle Resource Manager: A oferta do OCI Terraform as a Service usa o modelo do Terraform como entrada e gerencia o processo de provisionamento de infraestrutura.
  4. Criar uma Pilha: O Oracle Resource Manager usa o modelo para criar uma pilha, que é um conjunto de recursos do OCI.
  5. Plano: Antes de fazer qualquer alteração, o Oracle Resource Manager gera um plano, que descreve as ações que serão tomadas para provisionar ou modificar a infraestrutura.
  6. Aplicar: Com base no plano, o Oracle Resource Manager aplica a configuração, provisionando os recursos especificados no OCI.
  7. Destruir: O Oracle Resource Manager também pode ser usado para destruir (desprovisionar) ou expurgar os recursos que foram criados anteriormente pela pilha.

Tarefa 3.1: Configuração de Origem: Definindo a Pilha do Oracle Resource Manager

Para implantar um cluster do OKE usando o Oracle Resource Manager, comece fazendo download do módulo amigável para iniciantes: oke_terraform_for_beginners_orm.zip. Estamos usando uma estrutura de diretório simples. Quando você descompactar o pacote, certifique-se de que todos os códigos-fonte do modelo do Terraform (.tf) estejam localizados no diretório raiz.

Esta versão do módulo é pré-configurada para o Oracle Resource Manager; terraform.tfvars foi removida e todas as variáveis são definidas com valores de espaço reservado "genéricos", como "REPLACE_WITH_YOUR_OWN_VARIABLE_VALUE" em variables.tf.

Antes de criar sua stack, atualize a variables.tf com sua região, CIDRs de rede e flags para controlar a criação da VCN, do cluster do OKE e do pool de nós.

O cluster do OKE utiliza CNI Nativo da VCN (OCI_VCN_IP_NATIVE) para rede de pods; portanto, certifique-se de que o flag create_pod_network_subnet esteja ativado para definir seus CIDRs de sub-rede de pods.

Ao configurar seu stack na IU do Oracle Resource Manager, você pode controlar a criação dos principais recursos do OKE selecionando o seguinte:

Tarefa 3.2: Criar Pilha do Oracle Resource Manager

Durante a criação do stack, selecione o modelo do Terraform fornecido e continue para configurar as variáveis necessárias diretamente na console. O Oracle Resource Manager detecta automaticamente as variáveis de entrada definidas nos arquivos do Terraform e as apresenta em um formato fácil de editar. Nesse estágio, você precisará fornecer detalhes específicos do ambiente, como o OCID da tenancy, o OCID do compartimento e outros valores obrigatórios.

As imagens a seguir ilustram o processo de criação e configuração de variável stack na Console do Oracle Cloud.

OKEArchitecture

OKEArchitecture

Tarefa 3.3: Executar Job de Candidatura

Para simplificar, estamos ignorando a etapa Plan, pois a execução de Apply no Oracle Resource Manager a executará automaticamente. Ao iniciar o job Apply, o Oracle Resource Manager usa a configuração definida na etapa Source Configuration anterior para provisionar os recursos do OKE especificados no OCI.

As imagens a seguir ilustram uma execução bem-sucedida do job stack Apply com os logs gerados.

OKEArchitecture

OKEArchitecture

Tarefa 3.4: Executar Job de Destruição

Depois que sua atividade ou teste for concluído, você poderá executar o job Destroy no Oracle Resource Manager para limpar o ambiente. Esta ação instrui o Oracle Resource Manager a desprovisionar (expurgar) todos os recursos de infraestrutura que foram criados anteriormente como parte da pilha, incluindo o cluster do OKE, pools de nós, componentes de rede e quaisquer serviços associados. A execução do Destroy garante que os recursos não utilizados sejam totalmente removidos, ajudando você a evitar custos desnecessários e manter uma tenancy limpa da OCI.

Próximas Etapas

O uso do Terraform para provisionar um cluster do OKE oferece uma abordagem consistente, repetível e automatizada para gerenciar a infraestrutura do Kubernetes na Oracle Cloud Infrastructure (OCI). Com a Infraestrutura como Código (IaC), as equipes podem orquestrar a criação de clusters, aplicar as melhores práticas e integrar workflows de CI/CD aos seus processos de implantação. O Oracle Resource Manager aprimora isso simplificando as operações do Terraform, gerenciando o estado e permitindo a colaboração na OCI. Este tutorial serve como uma introdução para iniciantes e, em nosso próximo guia avançado, abordaremos módulos personalizáveis, automação de nível de produção, padrões de arquitetura modular e integração completa de CI/CD. Fique atento a uma abordagem mais escalável, segura e pronta para a empresa para gerenciar o Kubernetes em escala.

Confirmações

Mais Recursos de Aprendizado

Explore outros laboratórios em docs.oracle.com/learn ou acesse mais conteúdo de aprendizado gratuito no canal do Oracle Learning YouTube. Além disso, acesse education.oracle.com/learning-explorer para se tornar um Oracle Learning Explorer.

Para obter a documentação do produto, visite o Oracle Help Center.