Creación de un cluster de Oracle Cloud Infrastructure Kubernetes Engine mediante Terraform

Introducción

En este tutorial, mostraremos cómo crear un cluster de Oracle Cloud Infrastructure Kubernetes Engine (OKE) mediante Terraform y cómo gestionar el código de Terraform con Oracle Resource Manager. Este enfoque permite implantar los principios de infraestructura como código (IaC), lo que mejora la automatización, la coherencia y la repetibilidad en los despliegues.

Oracle Cloud Infrastructure Kubernetes Engine (OKE)

Kubernetes (K8s) es una plataforma de código abierto para automatizar el despliegue, la ampliación y la gestión de aplicaciones en contenedores. Originalmente desarrollado por Google y ahora mantenido por CNCF, es el estándar del sector para ejecutar aplicaciones nativas de la nube a escala.

OKE es un servicio totalmente gestionado en Oracle Cloud Infrastructure (OCI) que simplifica el despliegue y la gestión de clusters de Kubernetes. Automatiza el plano de control y la gestión de nodos de trabajador, se integra con los servicios de redes, almacenamiento y seguridad de OCI y admite cargas de trabajo sin estado y con estado. Los nodos de OKE se organizan en pools de nodos, que se pueden escalar y gestionar fácilmente, lo que garantiza una alta disponibilidad y una utilización óptima de los recursos para las aplicaciones en contenedores. OKE sigue el modelo estándar de Kubernetes, con dos componentes clave (un plano de control gestionado y un plano de datos gestionado por el cliente).

Para obtener más información, consulta Gestión del motor de OCI Kubernetes con diferentes tipos de capacidad y resolución de problemas comunes en nodos preferentes.

Arquitectura

La siguiente arquitectura de referencia se utilizará para demostrar la creación del cluster de OKE.

OKEArchitecture

El diagrama ilustra una arquitectura de OKE resiliente desplegada en una única región de OCI distribuida entre varios dominios de errores (FD). La configuración cuenta con una red virtual en la nube (VCN) con tres subredes distintas: una subred pública (LBSubnet) que aloja un gateway de Internet y un equilibrador de carga de OCI para distribuir el tráfico entrante, y dos subredes privadas, una para los nodos de trabajador de OKE (NodeSubnet) y otra para el servidor de API (APISubnet). Los nodos de trabajador se distribuyen en tres FD dentro de un único dominio de disponibilidad (AD), lo que minimiza el riesgo de fallos. El cluster se conecta fácilmente a OCI Container Registry para el almacenamiento y la recuperación de imágenes de contenedor.

La consola de OCI ofrece un método sencillo de punto y clic. Para utilizarlo, vaya a la interfaz de usuario de los clusters de Kubernetes. Seleccione Creación rápida. Asigne un Nombre al Cluster. Seleccione un punto final de API privado. Configure los nodos de trabajador gestionados con la unidad, la imagen y el recuento que desee. La opción de la consola de OCI configura un cluster de OKE mejorado. Utiliza OCI_VCN_IP_NATIVE CNI, que es el valor predeterminado. También proporciona subredes privadas dedicadas para los nodos de trabajador y el punto final de API. Además, crea una subred pública para el equilibrador de carga. Sin embargo, este enfoque manual requiere mucho tiempo y no es escalable para despliegues grandes o repetibles.

Para superar las limitaciones del despliegue manual, este tutorial proporciona una solución simplificada y plana basada en Terraform que automatiza toda la configuración del cluster de OKE en tres pasos:

Este tutorial se centra en el despliegue de la infraestructura de cluster principal de OKE. Las personalizaciones de nivel de aplicación y las configuraciones específicas de carga de trabajo están fuera de su ámbito. Para simplificar el aprovisionamiento, hemos incluido scripts de Bash que automatizan la ejecución de comandos de Terraform. Estos scripts están diseñados para una integración perfecta en un pipeline de Jenkins trifásico, lo que permite el despliegue automatizado de One-Click de todo el entorno de OKE.

Aprenderá a automatizar la creación de recursos de red (VCN, gateways, subredes), el cluster de OKE y sus pools de nodos mediante la CLI de Terraform y Oracle Resource Manager. También demostraremos cómo ampliar esta automatización mediante Bash, OCI CLI y Jenkins, reduciendo el esfuerzo manual y garantizando una entrega de infraestructura coherente.

Objetivos

Requisitos

Automatización de Terraform para la creación de clusters de OKE

Hay dos opciones de automatización para crear la VCN (OKE-VCN) y el cluster de OKE: un módulo plano o un módulo estándar que aprovecha los módulos secundarios. Este último enfoque está fuera del alcance de este artículo, pero ofrece una mejor organización y escalabilidad para implementaciones más grandes y complejas, promoviendo la reutilización y la mantenibilidad del código, lo que lo hace ideal para entornos de producción. Utilizaremos el enfoque más sencillo y plano, adecuado para casos de uso de desarrollo, escenarios de prueba o una demostración de despliegue de VCN puntual. Para obtener más información, consulte terraform-oci-oke.

Tarea 1: Despliegue de recursos de OKE con Terraform (Community Edition)

Antes de ejecutar comandos de Terraform para planificar y desplegar la infraestructura mediante la CLI de Terraform, actualice la configuración de Terraform proporcionada con los detalles específicos del entorno, ya sea desde la máquina local o a través de OCI Cloud Shell.

Puede descargar el código fuente completo de Terraform aquí: oke_terraform_for_beginners.zip. Estamos utilizando una estructura de directorio plano. Al descomprimir el paquete, asegúrese de que todos los códigos de origen de plantilla de Terraform (.tf, .tfvars, claves ssh, etc.) se encuentran en el directorio raíz.

  1. Para indicar a Terraform que cree cualquiera de los recursos principales (VCN, OKE_Cluser o Node_Pool), debe definir el indicador adecuado (is_vcn_created, is_k8cluster_created o is_pool_created) en true en terraform.tfvars. A continuación, especifique los parámetros restantes para la red, el cluster de OKE y el pool de nodos dentro de sus respectivos bloques de código.

    1. Para empezar, defina is_vcn_created en true para indicar a Terraform que cree una nueva VCN o false que utilice una VCN existente (tendrá que proporcionar su OCID). Si crea una nueva VCN, asegúrese de especificar una variable de bloque CIDR vcn_cidr_block.

    2. Proporcione los bloques de CIDR para las tres subredes siguientes.

      • Subred privada de punto final de API K8 (k8apiendpoint_private_subnet_cidr_block).
      • Subred privada de nodo de trabajador (workernodes_private_subnet_cidr_block).
      • Subred pública del equilibrador de carga de servicio (serviceloadbalancers_public_subnet_cidr_block).

    3. Defina el indicador is_k8cluster_created para indicar a Terraform que cree un cluster de Kubernetes y especifique el compartimento de destino mediante compartment_id. Si se necesita un pool de nodos de trabajador, defina el indicador is_nodepool_created según corresponda.

    4. OKE admite dos tipos de CNI: VCN-Native (valor por defecto), donde cada pod obtiene su propia IP para un mejor rendimiento y una integración completa de la red de OCI, y Flannel-Overlay, una red de superposición más sencilla donde los pods comparten la VNIC del nodo. En esta configuración, cni_type se define en OCI_VCN_IP_NATIVE para que coincida con la configuración de cluster por defecto creada por el flujo de trabajo Creación rápida en la consola de OCI.

    5. OKE ofrece dos tipos de cluster: Básico y Mejorado. Para una mayor flexibilidad, definimos cluster_type en ENHANCED_CLUSTER.

      • Los clusters mejorados proporcionan capacidades avanzadas como la gestión de complementos, la seguridad mejorada y un mejor control del ciclo de vida
      • Los clusters básicos ofrecen un entorno de Kubernetes sencillo con funciones esenciales

    6. La configuración de ciclo de nodos node_cycle_config define cómo se crean, sustituyen o actualizan los nodos de trabajador dentro de un pool de nodos, especialmente durante actualizaciones, actualizaciones o eventos de escala automática. La configuración define los siguientes atributos:

      • is_node_cycling_enabled (bool): Activa el ciclo automático (reemplazo) de los nodos durante una actualización o actualización. Establézcalo en true para activar la rotación segura de nodos.
      • maximum_surge (int): número máximo de nodos adicionales (más allá del recuento deseado) que se pueden agregar durante las actualizaciones. Permite crear nuevos nodos antes de suprimir los antiguos sin tiempo de inactividad.
      • maximum_unavailable (int): número máximo de nodos que pueden no estar disponibles durante las actualizaciones. Se utiliza para controlar las interrupciones durante las actualizaciones sucesivas.
      • cycle_modes (list) (opcional): proporciona una lista ordenada de acciones para el ciclo de nodos. Los modos de ciclo disponibles son:
        • REPLACE_BOOT_VOLUME: actualiza el volumen de inicio sin terminar el nodo.
        • REPLACE_NODES: cordón, drenaje, terminación y recreación de nodos con la configuración actualizada.

  2. Modifique los valores por defecto solo si es necesario. El paquete incluye instrucciones claras para la configuración del entorno, los pasos de ejecución y los conceptos clave relacionados con las redes y la seguridad.

    A continuación, se muestra un ejemplo de configuración de Terraform en el archivo terraform.tfvars que debe personalizar para que se ejecute en el entorno.

    	##########################################################################
	# 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. Ejecute los siguientes comandos de Terraform.

    terraform init
terraform validate
terraform plan
terraform apply

    Después de la ejecución correcta de terraform apply, el cluster de OKE se creará en el compartimento de trabajo y la región con la siguiente configuración:

    • ENHANCED_CLUSTER con OCI_VCN_IP_NATIVE cni_type y la versión de OKE especificada.
    • Subredes privadas dedicadas tanto para nodos de trabajador como para el punto final de API.
    • Subred pública para que el equilibrador de carga acceda a los servicios de cluster.
    • Un pool de nodos gestionado configurado con la unidad, la imagen y el recuento de nodos que desee.

  4. Vaya a la consola de OCI para confirmar el despliegue y la configuración del cluster.

    OKECluster

    En las siguientes imágenes se muestra una ejecución correcta de Terraform junto con los logs generados.

    OKETFLogs

  5. Cuando haya terminado la prueba, ejecute terraform destroy para limpiar el entorno. Este comando elimina todos los recursos de OKE creados durante el despliegue y ayuda a evitar un consumo de recursos innecesario en su arrendamiento.

Tarea 2: Automatización de la ejecución de la CLI de Terraform con el pipeline de integración y despliegue continuos de Jenkins

En esta tarea, abstraeremos los pasos detallados anteriormente en cuatro etapas primarias, diseñadas para la orquestación posterior por Jenkins. Este pipeline agregado se implementa mediante un juego de scripts de Bash que ejecutan comandos de la CLI de Terraform.

Tarea 2.1: Creación de recursos de red

El siguiente script ejecuta una secuencia de varios comandos de Terraform para crear los recursos de red.

Para el resto de las secuencias de comandos, asegúrese de que terraform init ya se ha ejecutado y de que está ejecutando los comandos desde el directorio de trabajo. Por ejemplo, ~/oke_terraform_for_beginners.

Tarea 2.2: Crear cluster de OKE

Este script ejecuta el comando terraform apply para crear el cluster de OKE.

Tarea 2.3. Crear pool de nodos de trabajador de OKE

El siguiente script ejecuta el comando terraform apply para crear el pool de nodos de trabajador para el cluster de OKE.

Tarea 2.4: Destruir todos los recursos

Este script ejecuta un comando destroy, que depura todos los recursos de cluster de OKE (recursos de red, cluster de OKE y pool de nodos de trabajador).

Hemos automatizado el proceso integral del pipeline de Jenkins, consolidándolo en cuatro tareas de creación de Jenkins (tarea 2.1, 2.2, 2.3). Este pipeline agregado se ejecuta mediante scripts de Bash que ejecutan comandos de la CLI de Terraform. En la siguiente imagen se muestra la automatización de One-Click para las tres primeras tareas; el paso destroy no se incluye para simplificar.

OKEArchitecture

Tarea 3: Orquestación de despliegues de OKE con Oracle Resource Manager

Flujo de Oracle Resource Manager (ilustrado):

OKEArchitecture

En el siguiente diagrama se describen los siete pasos que ilustran Oracle Resource Manager Code Manager:

  1. Configuración de origen: define dónde se origina la configuración IaC, como un compartimento en OCI, un cubo de OCI Object Storage, un archivo Zip, Bitbucket o GitHub.
  2. Plantilla de Terraform: la configuración de infraestructura se define mediante Terraform HashiCorp en un archivo de plantilla.
  3. Gestor de recursos de Oracle: la oferta de Terraform as a Service de OCI toma la plantilla de Terraform como entrada y gestiona el proceso de aprovisionamiento de infraestructura.
  4. Crear una pila: Oracle Resource Manager utiliza la plantilla para crear una pila, que es una recopilación de recursos de OCI.
  5. Plan: antes de realizar cambios, el gestor de recursos de Oracle genera un plan que describe las acciones que se realizarán para aprovisionar o modificar la infraestructura.
  6. Aplicar: según el plan, Oracle Resource Manager aplica la configuración y aprovisiona los recursos especificados en OCI.
  7. Destruir: Oracle Resource Manager también se puede utilizar para destruir (desaprovisionar) o depurar los recursos que la pila creó anteriormente.

Tarea 3.1: Configuración de Origen: Definición de la Pila de Oracle Resource Manager

Para desplegar un cluster de OKE mediante Oracle Resource Manager, comience por descargar el módulo para principiantes: oke_terraform_for_beginners_orm.zip. Estamos utilizando una estructura de directorio plano. Al descomprimir el paquete, asegúrese de que todos los códigos de origen de plantilla de Terraform (.tf) se encuentran en el directorio raíz.

Esta versión del módulo está preconfigurada para Oracle Resource Manager; terraform.tfvars se ha eliminado y todas las variables se definen con valores de marcador de posición "genéricos", como "REPLACE_WITH_YOUR_OWN_VARIABLE_VALUE", en variables.tf.

Antes de crear stack, actualice variables.tf con la región, los CIDR de red y los indicadores para controlar la creación de la VCN, el cluster de OKE y el pool de nodos.

El cluster de OKE utiliza el CNI nativo de VCN (OCI_VCN_IP_NATIVE) para las redes de pod, por lo que asegúrese de que el indicador create_pod_network_subnet esté activado para definir los CIDR de la subred de pod.

Al configurar stack en la interfaz de usuario de Oracle Resource Manager, puede controlar la creación de recursos principales de OKE seleccionando lo siguiente:

Tarea 3.2: Creación de la pila de Oracle Resource Manager

Durante la creación de stack, seleccione la plantilla de Terraform proporcionada y continúe para configurar las variables necesarias directamente en la consola. El gestor de recursos de Oracle detecta automáticamente las variables de entrada definidas en los archivos de Terraform y las presenta en un formato fácil de editar. En esta etapa, deberá proporcionar detalles específicos del entorno, como el OCID de su arrendamiento, el OCID del compartimento y otros valores necesarios.

En las siguientes imágenes se muestra el proceso de creación y configuración de variables de stack en la consola de Oracle Cloud.

OKEArchitecture

OKEArchitecture

Tarea 3.3: Ejecutar trabajo de aplicación

Para simplificarlo, se omite el paso Plan, ya que al ejecutar Apply en Oracle Resource Manager se ejecutará automáticamente. Al iniciar el trabajo Apply, Oracle Resource Manager utiliza la configuración definida en el paso Source Configuration anterior para aprovisionar los recursos de OKE especificados en OCI.

Las siguientes imágenes muestran una ejecución correcta del trabajo stack Apply junto con los logs generados.

OKEArchitecture

OKEArchitecture

Tarea 3.4: Ejecutar trabajo de destrucción

Una vez finalizada la actividad o prueba, puede ejecutar el trabajo Destroy en Oracle Resource Manager para limpiar el entorno. Esta acción indica a Oracle Resource Manager que anule (depure) todos los recursos de infraestructura que se hayan creado anteriormente como parte de la pila, incluido el cluster de OKE, los pools de nodos, los componentes de red y cualquier servicio asociado. La ejecución de Destroy garantiza que los recursos no utilizados se eliminen por completo, lo que le ayuda a evitar costos innecesarios y a mantener un arrendamiento de OCI limpio.

Pasos Siguientes

El uso de Terraform para aprovisionar un cluster de OKE ofrece un enfoque consistente, repetible y automatizado para gestionar la infraestructura de Kubernetes en Oracle Cloud Infrastructure (OCI). Con la infraestructura como código (IaC), los equipos pueden orquestar la creación de clusters, aplicar mejores prácticas e integrar flujos de trabajo de integración y despliegue continuos en sus procesos de despliegue. Oracle Resource Manager mejora esto al simplificar las operaciones de Terraform, gestionar el estado y permitir la colaboración dentro de OCI. Este tutorial sirve como una introducción para principiantes, y en nuestra próxima guía avanzada, trataremos los módulos personalizables, la automatización de nivel de producción, los patrones de arquitectura modular y la integración completa de CI/CD. Esté atento a un enfoque más escalable, seguro y listo para la empresa para gestionar Kubernetes a escala.

Acuses de recibo

Más recursos de aprendizaje

Explore otros laboratorios en docs.oracle.com/learn o acceda a más contenido de aprendizaje gratuito en el canal YouTube de Oracle Learning. Además, visite education.oracle.com/learning-explorer para convertirse en un explorador de Oracle Learning.

Para obtener documentación sobre el producto, visite Oracle Help Center.