Crea cluster Oracle Cloud Infrastructure Kubernetes Engine utilizzando Terraform

Introduzione

In questa esercitazione verrà illustrato come creare un cluster Oracle Cloud Infrastructure Kubernetes Engine (OKE) utilizzando Terraform e gestire il codice Terraform con Oracle Resource Manager. Questo approccio consente di implementare i principi Infrastructure as Code (IaC), migliorando l'automazione, la coerenza e la ripetibilità nelle implementazioni.

Oracle Cloud Infrastructure Kubernetes Engine (OKE)

Kubernetes (K8s) è una piattaforma open source per automatizzare l'implementazione, la scalabilità e la gestione delle applicazioni containerizzate. Originariamente sviluppato da Google e ora gestito dal CNCF, è lo standard del settore per l'esecuzione di applicazioni cloud native su larga scala.

OKE è un servizio completamente gestito su Oracle Cloud Infrastructure (OCI) che semplifica l'implementazione e la gestione dei cluster Kubernetes. Automatizza la gestione del piano di controllo e dei nodi di lavoro, si integra con i servizi di rete, storage e sicurezza di OCI e supporta carichi di lavoro senza conservazione dello stato e con conservazione dello stato. I nodi OKE sono organizzati in pool di nodi, che possono essere facilmente ridimensionati e gestiti, garantendo alta disponibilità e un utilizzo ottimale delle risorse per le applicazioni containerizzate. OKE segue il modello Kubernetes standard, con due componenti chiave (piano di controllo gestito e piano di dati gestito dal cliente).

Per ulteriori informazioni, esamina Gestisci OCI Kubernetes Engine con tipi di capacità diversi e risolvi problemi comuni sui nodi prerilasciabili.

Architettura

La seguente architettura di riferimento verrà utilizzata per dimostrare la creazione del cluster OKE.

OKEArchitecture

Il diagramma illustra un'architettura OKE resiliente distribuita all'interno di una singola area OCI distribuita tra più domini di errore (FD, Fault Domains). L'impostazione prevede una rete cloud virtuale (VCN) con tre subnet distinte: una subnet pubblica (LBSubnet) che ospita un gateway Internet e un load balancer OCI per distribuire il traffico in entrata e due subnet private, una per i nodi di lavoro OKE (NodeSubnet) e un'altra per il server API (APISubnet). I nodi di lavoro sono distribuiti su tre FD all'interno di un singolo dominio di disponibilità (AD), riducendo al minimo i rischi di errori. Il cluster si connette perfettamente a OCI Container Registry per lo storage e il recupero delle immagini dei container.

OCI Console offre un metodo semplice di Point-&-Click. Per utilizzarlo, passare all'interfaccia utente dei cluster Kubernetes. Selezionare Creazione rapida. Assegnare un nome al cluster. Selezionare un endpoint API privato. Configura i nodi di lavoro gestiti con la forma, l'immagine e il conteggio desiderati. L'opzione di OCI Console imposta un cluster OKE avanzato. Utilizza OCI_VCN_IP_NATIVE CNI, che è l'impostazione predefinita. Fornisce inoltre subnet private dedicate per i nodi di lavoro e l'endpoint API. Inoltre, crea una subnet pubblica per il load balancer. Tuttavia, questo approccio manuale richiede tempo e non è scalabile per distribuzioni di grandi dimensioni o ripetibili

Per superare le limitazioni della distribuzione manuale, questa esercitazione fornisce una soluzione semplificata basata su Terraform che automatizza l'intera configurazione del cluster OKE in tre passi:

Questa esercitazione è incentrata sulla distribuzione dell'infrastruttura cluster OKE di base. Le personalizzazioni a livello di applicazione e le configurazioni specifiche dei carichi di lavoro non rientrano nel relativo ambito. Per semplificare il provisioning, abbiamo incluso script Bash che automatizzano l'esecuzione dei comandi Terraform. Questi script sono progettati per una perfetta integrazione in una pipeline Jenkins trifase, consentendo la distribuzione automatica di One-Click dell'intero ambiente OKE.

Verrà descritto come automatizzare la creazione di risorse di rete (VCN, gateway, subnet), il cluster OKE e i relativi pool di nodi utilizzando sia l'interfaccia CLI Terraform che Oracle Resource Manager. Dimostreremo anche come estendere questa automazione utilizzando Bash, OCI CLI e Jenkins, riducendo gli sforzi manuali e garantendo una distribuzione coerente dell'infrastruttura.

Obiettivi

Prerequisiti

Automazione Terraform per la creazione del cluster OKE

Sono disponibili due opzioni di automazione per creare la VCN (OKE-VCN) e il cluster OKE: un modulo piatto o un modulo standard che utilizza moduli figlio. Quest'ultimo approccio è fuori dal campo di applicazione di questo articolo, ma offre una migliore organizzazione e scalabilità per implementazioni più grandi e complesse, promuovendo la riusabilità e la manutenibilità del codice, rendendolo ideale per gli ambienti di produzione. Useremo l'approccio semplice e uniforme, adatto a casi d'uso di sviluppo, scenari di test o una dimostrazione di distribuzione VCN una tantum. Per ulteriori informazioni, vedere terraform-oci-oke.

Task 1: Distribuzione delle risorse OKE con Terraform (Community Edition)

Prima di eseguire i comandi Terraform per pianificare e distribuire l'infrastruttura utilizzando l'interfaccia CLI Terraform, aggiornare la configurazione Terraform fornita con i dettagli specifici dell'ambiente, dal computer locale o tramite OCI Cloud Shell.

Puoi scaricare il codice sorgente completo di Terraform qui: oke_terraform_for_beginners.zip. Stiamo usando una struttura di directory flat. Quando decomprimi il pacchetto, assicurati che tutti i codici di origine del modello Terraform (.tf, .tfvars, chiavi ssh e così via) si trovino nella directory radice.

  1. Per indicare a Terraform di creare una delle risorse principali (VCN, OKE_Cluser o Node_Pool), è necessario impostare il flag appropriato (is_vcn_created, is_k8cluster_created o is_pool_created) su true nel terraform.tfvars. Specificare quindi i parametri rimanenti per la rete, il cluster OKE e il pool di nodi nei rispettivi blocchi di codice.

    1. Iniziare impostando is_vcn_created su true per indicare a Terraform di creare una nuova VCN o false per utilizzare una VCN esistente (è necessario fornire il relativo OCID). Se si crea una nuova VCN, assicurarsi di specificare una variabile di blocco CIDR vcn_cidr_block.

    2. Fornire i blocchi CIDR per le tre subnet seguenti.

      • Subnet privata dell'endpoint API K8 (k8apiendpoint_private_subnet_cidr_block).
      • Subnet privata del nodo di lavoro (workernodes_private_subnet_cidr_block).
      • Subnet pubblica del load balancer del servizio (serviceloadbalancers_public_subnet_cidr_block).
    3. Impostare il flag is_k8cluster_created per indicare a Terraform di creare un cluster Kubernetes e specificare il compartimento di destinazione utilizzando compartment_id. Se è necessario un pool di nodi di lavoro, impostare il flag is_nodepool_created di conseguenza.

    4. OKE supporta due tipi CNI: VCN nativo (impostazione predefinita), in cui ogni pod ottiene il proprio IP per prestazioni migliori e l'integrazione completa della rete OCI, e Flannel-Overlay, una rete di overlay più semplice in cui i pod condividono la VNIC del nodo. In questa impostazione, cni_type viene impostato su OCI_VCN_IP_NATIVE per corrispondere alla configurazione cluster predefinita creata dal workflow Creazione rapida in OCI Console.

    5. OKE offre due tipi di cluster: Basic e Enhanced. Per una maggiore flessibilità, abbiamo impostato cluster_type su ENHANCED_CLUSTER.

      • I cluster avanzati offrono funzionalità avanzate come la gestione dei componenti aggiuntivi, una maggiore sicurezza e un migliore controllo del ciclo di vita
      • I cluster di base offrono un ambiente Kubernetes semplice con funzioni essenziali
    6. La configurazione del ciclo dei nodi node_cycle_config definisce la modalità di creazione, sostituzione o aggiornamento dei nodi di lavoro all'interno di un pool di nodi, in particolare durante gli aggiornamenti, gli upgrade o gli eventi di ridimensionamento automatico. La configurazione definisce i seguenti attributi:

      • is_node_cycling_enabled (bool): Abilita il ciclo automatico (sostituzione) dei nodi durante un aggiornamento o un aggiornamento. Impostare su true per abilitare la rotazione sicura dei nodi.
      • maximum_surge (int): il numero massimo di nodi extra (oltre il conteggio desiderato) che possono essere aggiunti durante gli aggiornamenti. Consente di creare nuovi nodi prima che i vecchi vengano eliminati senza tempi di inattività.
      • maximum_unavailable (int): il numero massimo di nodi che possono essere non disponibili durante gli aggiornamenti. Utilizzato per controllare le interruzioni durante gli aggiornamenti in sequenza.
      • cycle_modes (list) (facoltativo): fornisce una lista ordinata di azioni per il ciclo dei nodi. Le modalità di ciclo disponibili sono:
        • REPLACE_BOOT_VOLUME: aggiorna il volume di avvio senza terminare il nodo.
        • REPLACE_NODES: connette, scollega, termina e ricrea i nodi con la configurazione aggiornata.
  2. Modificare i valori predefiniti solo se necessario. Il pacchetto include istruzioni chiare per l'impostazione dell'ambiente, le fasi di esecuzione e i concetti chiave relativi alla rete e alla sicurezza.

    Di seguito è riportato un esempio di configurazione Terraform nel file terraform.tfvars da personalizzare per l'esecuzione nell'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. Eseguire i comandi Terraform riportati di seguito.

    terraform init
    terraform validate
    terraform plan
    terraform apply
    

    Dopo l'esecuzione riuscita di terraform apply, il cluster OKE verrà creato nel compartimento di lavoro e nell'area con la configurazione seguente:

    • Un ENHANCED_CLUSTER con OCI_VCN_IP_NATIVE cni_type e la versione OKE specificata.
    • Subnet private dedicate sia per i nodi di lavoro che per l'endpoint API.
    • Subnet pubblica che consente al load balancer di accedere ai servizi cluster.
    • Un pool di nodi gestiti configurato con la forma, l'immagine e il conteggio dei nodi desiderati.
  4. Andare a OCI Console per confermare la distribuzione e la configurazione del cluster.

    OKECluster

    Le immagini riportate di seguito illustrano un'esecuzione riuscita di Terraform insieme ai log generati.

    OKETFLogs

  5. Al termine dei test, eseguire terraform destroy per eseguire il cleanup dell'ambiente. Questo comando rimuove tutte le risorse OKE create durante la distribuzione e consente di evitare il consumo non necessario di risorse nella tenancy.

Task 2: Automatizza l'esecuzione dell'interfaccia CLI Terraform con la pipeline CI/CD Jenkins

In questo compito, asterremo i passaggi precedentemente dettagliati in quattro fasi principali, progettate per l'orchestrazione successiva da parte di Jenkins. Questa pipeline aggregata viene implementata tramite un set di script Bash che eseguono i comandi dell'interfaccia CLI Terraform.

Task 2.1: Creare risorse di rete

Lo script seguente esegue una sequenza di più comandi Terraform per creare le risorse di rete.

Per gli script rimanenti, assicurarsi che terraform init sia già stato eseguito e che i comandi vengano eseguiti dalla directory di lavoro. Ad esempio, ~/oke_terraform_for_beginners.

Task 2.2: Crea cluster OKE

Questo script esegue il comando terraform apply per creare il cluster OKE.

Task 2.3. Crea pool di nodi di lavoro OKE

Lo script seguente esegue il comando terraform apply per creare il pool di nodi di lavoro per il cluster OKE.

Task 2.4: distruggere tutte le risorse

Questo script esegue un comando destroy, rimuovendo tutte le risorse del cluster OKE (risorse di rete, cluster OKE e pool di nodi di lavoro).

Abbiamo automatizzato il processo end-to-end della pipeline Jenkins, consolidandolo in quattro task di creazione Jenkins (Task 2.1, 2.2, 2.3). Questa pipeline aggregata viene eseguita tramite script Bash che eseguono i comandi dell'interfaccia CLI Terraform. L'immagine riportata di seguito mostra l'automazione One-Click per i primi tre task. Il passo destroy non è incluso per semplicità.

OKEArchitecture

Task 3: Orchestra le distribuzioni OKE con Oracle Resource Manager

Flusso di Oracle Resource Manager (illustrato):

OKEArchitecture

Il diagramma riportato di seguito descrive i sette passi che illustrano Oracle Resource Manager Code Manager.

  1. Configurazione di origine: definisce l'origine della configurazione IaC, ad esempio un compartimento in OCI, un bucket di storage degli oggetti OCI, un file ZIP, un Bitbucket o GitHub.
  2. Modello Terraform: la configurazione dell'infrastruttura viene definita utilizzando HashiCorp Terraform in un file modello.
  3. Oracle Resource Manager: l'offerta OCI Terraform as a Service prende il modello Terraform come input e gestisce il processo di provisioning dell'infrastruttura.
  4. Crea uno stack: Oracle Resource Manager utilizza il modello per creare uno stack, ovvero una raccolta di risorse OCI.
  5. Piano: prima di apportare eventuali modifiche, Oracle Resource Manager genera un piano che delinea le azioni che verranno intraprese per eseguire il provisioning o modificare l'infrastruttura.
  6. Applica: in base al piano, Oracle Resource Manager applica la configurazione e esegue il provisioning delle risorse specificate in OCI.
  7. Elimina: Oracle Resource Manager può anche essere utilizzato per eliminare (eliminare) o rimuovere le risorse create in precedenza dallo stack.

Task 3.1: Configurazione origine: Definizione dello stack di Oracle Resource Manager

Per distribuire un cluster OKE utilizzando Oracle Resource Manager, iniziare scaricando il modulo adatto ai principianti: oke_terraform_for_beginners_orm.zip. Stiamo usando una struttura di directory flat. Quando si decomprime il package, assicurarsi che tutti i codici di origine del modello Terraform (.tf) si trovino nella directory radice.

Questa versione del modulo è preconfigurata per Oracle Resource Manager; terraform.tfvars è stato rimosso e tutte le variabili sono impostate con valori segnaposto "generici", ad esempio "REPLACE_WITH_YOUR_OWN_VARIABLE_VALUE" in variables.tf.

Prima di creare la stack, aggiornare variables.tf con l'area, i CIDR di rete e i flag per controllare la creazione della VCN, del cluster OKE e del pool di nodi.

Il cluster OKE utilizza CNI VCN nativo (OCI_VCN_IP_NATIVE) per la rete pod, pertanto assicurarsi che il flag create_pod_network_subnet sia abilitato per definire i CIDR della subnet pod.

Quando si configura stack nell'interfaccia utente di Oracle Resource Manager, è possibile controllare la creazione di risorse OKE di base selezionando quanto riportato di seguito.

Task 3.2: Crea stack di Oracle Resource Manager

Durante la creazione di stack, selezionare il modello Terraform fornito e procedere alla configurazione delle variabili necessarie direttamente all'interno della console. Oracle Resource Manager rileva automaticamente le variabili di input definite nei file Terraform e le presenta in un formato di facile modifica. In questa fase, sarà necessario fornire dettagli specifici dell'ambiente, ad esempio l'OCID tenancy, l'OCID compartimento e altri valori obbligatori.

Le immagini seguenti illustrano il processo di creazione e configurazione delle variabili stack all'interno della console di Oracle Cloud.

OKEArchitecture

OKEArchitecture

Task 3.3: Esegui processo candidatura

Per semplicità, il passo Plan verrà saltato, poiché l'esecuzione di Apply in Oracle Resource Manager verrà eseguita automaticamente. Avviando il job Apply, Oracle Resource Manager utilizza la configurazione definita nel passo Source Configuration precedente per eseguire il provisioning delle risorse OKE specificate all'interno di OCI.

Le immagini seguenti illustrano un'esecuzione riuscita del job stack Apply insieme ai log generati.

OKEArchitecture

OKEArchitecture

Task 3.4: Esegui job di eliminazione

Una volta completata l'attività o i test, è possibile eseguire il job Destroy in Oracle Resource Manager per eseguire il cleanup dell'ambiente. Questa azione indica a Oracle Resource Manager di annullare il provisioning (rimozione) di tutte le risorse dell'infrastruttura create in precedenza come parte dello stack, inclusi il cluster OKE, i pool di nodi, i componenti di rete e qualsiasi servizio associato. L'esecuzione di Destroy garantisce la rimozione completa delle risorse inutilizzate, evitando costi non necessari e mantenendo una tenancy OCI pulita.

Passi successivi

L'uso di Terraform per eseguire il provisioning di un cluster OKE offre un approccio coerente, ripetibile e automatizzato alla gestione dell'infrastruttura Kubernetes su Oracle Cloud Infrastructure (OCI). Con Infrastructure as Code (IaC), i team possono orchestrare la creazione dei cluster, applicare le best practice e integrare i flussi di lavoro CI/CD nei loro processi di distribuzione. Oracle Resource Manager migliora questo aspetto semplificando le operazioni Terraform, gestendo lo stato e abilitando la collaborazione all'interno di OCI. Questo tutorial serve come introduzione per principianti e nella nostra prossima guida avanzata, tratteremo moduli personalizzabili, automazione di livello produttivo, modelli di architettura modulari e integrazione CI/CD completa. Rimani sintonizzato per un approccio più scalabile, sicuro e di livello Enterprise alla gestione di Kubernetes su larga scala.

Conferme

Altre risorse di apprendimento

Esplora altri laboratori su docs.oracle.com/learn o accedi a più contenuti di formazione gratuiti sul canale YouTube di Oracle Learning. Inoltre, visitare education.oracle.com/learning-explorer per diventare Oracle Learning Explorer.

Per la documentazione del prodotto, visitare Oracle Help Center.