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).
-
Plano de control: totalmente gestionado por Oracle y sus componentes se encargan de la orquestación y gestión del cluster:
kube-apiserver
: API central para la comunicación con el cluster.etcd
: almacena la configuración y el estado del cluster.kube-scheduler
: asigna pods a los nodos adecuados.kube-controller-manager
: garantiza el estado deseado mediante la gestión de controladores.cloud-controller-manager
(CCM): se integra con OCI para gestionar recursos en la nube como OCI Load Balancer y OCI Block Volumes.
-
Plano de datos: desplegado en el arrendamiento del cliente y ejecuta las cargas de trabajo reales. Se compone de:
Worker Nodes
: instancias informáticas (aprovisionadas por el cliente) que ejecutan pods.kubelet
: agente de nodo que gestiona la ejecución de pod.kube-proxy
: maneja las reglas de red y el tráfico de enrutamiento hacia/desde pods.
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.
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:
- Creación de recursos de red.
- Aprovisionamiento de cluster de OKE.
- Creación de pool de nodos de trabajador.
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
- Cree un cluster de OKE con Terraform para la infraestructura como código y describa el proceso de gestión del despliegue a través de Oracle Resource Manager. En el camino, también cubriremos los conceptos fundamentales de OKE.
Requisitos
-
Rol de administrador raíz de arrendamiento de OCI para la configuración inicial, no recomendado para producción.
- Usuario de OCI no administrador con las políticas de red y IAM de OCI de OKE necesarias. Para obtener más información, consulte Configuración de políticas para despliegue y creación de clusters.
-
Familiaridad con los principios de infraestructura como código y Terraform (versión comunitaria), que incluyen:
- Cloud Shell de Oracle
- Interfaz de línea de comandos (CLI) de Oracle,
- Gestor de Recursos de Oracle,
- Código de Visual Studio
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.
-
Para indicar a Terraform que cree cualquiera de los recursos principales (
VCN
,OKE_Cluser
oNode_Pool
), debe definir el indicador adecuado (is_vcn_created
,is_k8cluster_created
ois_pool_created
) entrue
enterraform.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.-
Para empezar, defina
is_vcn_created
entrue
para indicar a Terraform que cree una nueva VCN ofalse
que utilice una VCN existente (tendrá que proporcionar su OCID). Si crea una nueva VCN, asegúrese de especificar una variable de bloque CIDRvcn_cidr_block
. -
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
).
- Subred privada de punto final de API K8 (
-
Defina el indicador
is_k8cluster_created
para indicar a Terraform que cree un cluster de Kubernetes y especifique el compartimento de destino mediantecompartment_id
. Si se necesita un pool de nodos de trabajador, defina el indicadoris_nodepool_created
según corresponda. -
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 enOCI_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. -
OKE ofrece dos tipos de cluster: Básico y Mejorado. Para una mayor flexibilidad, definimos
cluster_type
enENHANCED_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
-
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.
-
-
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" } }
-
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
conOCI_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.
-
Vaya a la consola de OCI para confirmar el despliegue y la configuración del cluster.
En las siguientes imágenes se muestra una ejecución correcta de Terraform junto con los logs generados.
-
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.
-
Script de Bash:
create_network_resources.sh
.#!/bin/bash # Change directory to your working directory cd ~/oke_terraform_for_beginners # Run terraform init (at least once) /usr/local/bin/terraform init # Create the OKE Cluster Network resources (VCN, Gateways, RT, K8 API Endpoint Subnet, Worker Node Subnet and LB subnet) /usr/local/bin/terraform apply \ --var is_vcn_created=true \ # Create OKE Cluster Networking Resources --auto-approve
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.
-
Script de Bash:
create_oke_cluster.sh
.#!/bin/bash ..... # Create OKE Cluster (auto-approve - not advised for production) /usr/local/bin/terraform apply \ --var is_vcn_created=true \ # Use the created network --var is_k8cluster_created=false \ # Create a new OKE cluster --auto-approve
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.
-
Script de Bash:
create_worker_node_pool.sh
#!/bin/bash # Create Worker Node Pool (auto-approve - not advised for production) /usr/local/bin/terraform apply \ --var is_vcn_created=true \ # Use the created network --var is_k8cluster_created=true \ # For the existing OKE cluster --var is_nodepool_created=true \ # Create new Worker Node Pool --auto-approve
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).
-
Script de Bash:
destroy_all_cluster_resources.sh
.#!/bin/bash # Run terraform destroy (for testing purposes only, not for production) /usr/local/bin/terraform destroy --auto-approve
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.
Tarea 3: Orquestación de despliegues de OKE con Oracle Resource Manager
Flujo de Oracle Resource Manager (ilustrado):
En el siguiente diagrama se describen los siete pasos que ilustran Oracle Resource Manager Code Manager:
- 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.
- Plantilla de Terraform: la configuración de infraestructura se define mediante Terraform HashiCorp en un archivo de plantilla.
- 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.
- Crear una pila: Oracle Resource Manager utiliza la plantilla para crear una pila, que es una recopilación de recursos de OCI.
- 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.
- Aplicar: según el plan, Oracle Resource Manager aplica la configuración y aprovisiona los recursos especificados en OCI.
- 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:
- VCN: seleccione
is_vcn_created
. - Cluster de OKE: seleccione
is_k8cluster_created
. - Pool de nodos de OKE: seleccione
is_nodepool_created
.
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.
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.
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.
Enlaces relacionados
Acuses de recibo
- Autores: Mahamat Guiagoussou (arquitecto de nube residente principal), Payal Sharma (arquitecto de nube residente principal)
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.
Create Oracle Cloud Infrastructure Kubernetes Engine Cluster using Terraform
G38263-01
Copyright ©2025, Oracle and/or its affiliates.