Créer une grappe Oracle Cloud Infrastructure Kubernetes Engine à l'aide de Terraform

Présentation

Dans ce tutoriel, nous montrerons comment créer une grappe Oracle Cloud Infrastructure Kubernetes Engine (OKE) à l'aide de Terraform et comment gérer votre code Terraform à l'aide du gestionnaire de ressources d'Oracle. Cette approche vous permet de mettre en oeuvre les principes de l'infrastructure-code (IaC), en améliorant l'automatisation, la cohérence et la répétabilité de vos déploiements.

Oracle Cloud Infrastructure Kubernetes Engine (OKE)

Kubernetes (K8s) est une plate-forme à code source libre pour automatiser le déploiement, l'évolutivité et la gestion des applications conteneurisées. Développé à l'origine par Google et maintenant maintenu par la CNCF, il est la norme de l'industrie pour l'exécution d'applications cloud natives à grande échelle.

OKE est un service entièrement géré sur Oracle Cloud Infrastructure (OCI) qui simplifie le déploiement et la gestion des grappes Kubernetes. Il automatise la gestion des plans de contrôle et des noeuds de travail, s'intègre aux services de réseau, de stockage et de sécurité d'OCI et prend en charge les charges de travail sans état et avec état. Les noeuds OKE sont organisés en groupes de noeuds qui peuvent être facilement mis à l'échelle et gérés, ce qui garantit une haute disponibilité et une utilisation optimale des ressources pour les applications conteneurisées. OKE suit le modèle Kubernetes standard, avec deux composants clés (un plan de contrôle géré et un plan de données géré par le client).

Pour plus d'informations, consultez Gérer le moteur Kubernetes pour OCI avec différents types de capacité et résoudre les problèmes communs sur les noeuds préemptibles.

Architecture

L'architecture de référence suivante sera utilisée pour démontrer la création de la grappe OKE.

OKEArchitecture

Le diagramme présente une architecture OKE résiliente déployée dans une seule région OCI répartie entre plusieurs domaines d'erreur (FD). La configuration comporte un réseau en nuage virtuel (VCN) avec trois sous-réseaux distincts : un sous-réseau public (LBSubnet) hébergeant une passerelle Internet et un équilibreur de charge OCI pour répartir le trafic entrant, et deux sous-réseaux privés, l'un pour les noeuds de travail OKE (NodeSubnet) et l'autre pour le serveur d'API (APISubnet). Les noeuds de travail sont répartis sur trois fichiers FD dans un seul domaine de disponibilité, ce qui réduit le risque de défaillance. La grappe se connecte de façon transparente au registre de conteneurs d'OCI pour le stockage et l'extraction d'images de conteneur.

La console OCI offre une méthode simple Point-&-Click. Pour l'utiliser, naviguez jusqu'à l'interface utilisateur des grappes Kubernetes. Sélectionnez Création rapide. Nommez la grappe. Sélectionner un point d'extrémité d'API privé. Configurez les noeuds de travail gérés avec la forme, l'image et le nombre souhaités. L'option de la console OCI configure une grappe OKE améliorée. Il utilise OCI_VCN_IP_NATIVE CNI, qui est la valeur par défaut. Il fournit également des sous-réseaux privés dédiés pour les noeuds de travail et le point d'extrémité d'API. En outre, il crée un sous-réseau public pour l'équilibreur de charge. Toutefois, cette approche manuelle prend beaucoup de temps et n'est pas évolutive pour les déploiements volumineux ou reproductibles.

Pour surmonter les limites du déploiement manuel, ce tutoriel fournit une solution Terraform simplifiée et plate qui automatise la configuration complète de la grappe OKE en trois étapes :

Ce tutoriel porte sur le déploiement de l'infrastructure de base de la grappe OKE. Les personnalisations au niveau de l'application et les configurations propres à la charge de travail sont hors de sa portée. Pour rationaliser le provisionnement, nous avons inclus des scripts Bash qui automatisent l'exécution des commandes Terraform. Ces scripts sont conçus pour une intégration transparente dans un pipeline Jenkins en trois phases, ce qui permet le déploiement automatisé One-Click de l'ensemble de l'environnement OKE.

Vous apprendrez à automatiser la création de ressources de réseau (VCN, passerelles, sous-réseaux), de la grappe OKE et de ses groupes de noeuds à l'aide de l'interface de ligne de commande Terraform et du gestionnaire de ressources Oracle. Nous vous montrerons également comment étendre cette automatisation à l'aide de Bash, de l'interface de ligne de commande OCI et de Jenkins, ce qui réduit les interventions manuelles et assure une livraison uniforme de l'infrastructure.

Objectifs

Conditions requises

Automatisation Terraform pour la création de grappes OKE

Il existe deux options d'automatisation pour créer le VCN (OKE-VCN) et la grappe OKE : un module plat ou un module standard tirant parti des modules enfants. Cette dernière approche est hors de portée de cet article, mais elle offre une meilleure organisation et une meilleure évolutivité pour les déploiements plus grands et complexes, favorisant la réutilisabilité et la maintenabilité du code, ce qui le rend idéal pour les environnements de production. Nous utiliserons une approche plate et plus simple, adaptée aux cas d'utilisation de développement, aux scénarios de test ou à une démonstration ponctuelle du déploiement de VCN. Pour plus d'informations, voir terraform-oci-oke.

Tâche 1 : Déployer des ressources OKE avec Terraform (Édition Community)

Avant d'exécuter des commandes Terraform pour planifier et déployer votre infrastructure à l'aide de l'interface de ligne de commande Terraform, mettez à jour la configuration Terraform fournie avec les détails propres à votre environnement, à partir de votre machine locale ou au moyen de Cloud Shell pour OCI.

Vous pouvez télécharger le code source Terraform complet à l'adresse suivante : oke_terraform_for_beginners.zip. Nous utilisons une structure de répertoires à plat. Lorsque vous décompressez l'ensemble, assurez-vous que tous vos codes sources de modèle Terraform (.tf, .tfvars, clés SSH, etc.) se trouvent dans le répertoire racine.

  1. Pour demander à Terraform de créer l'une des ressources principales (VCN, OKE_Cluser ou Node_Pool), vous devez régler l'indicateur approprié (is_vcn_created, is_k8cluster_created ou is_pool_created) à true dans votre terraform.tfvars. Indiquez ensuite les paramètres restants pour le réseau, la grappe OKE et le groupe de noeuds dans leurs blocs de code respectifs.

    1. Commencez par régler is_vcn_created à true pour demander à Terraform de créer un nouveau VCN ou à false d'utiliser un VCN existant (vous devrez fournir son OCID). Si vous créez un nouveau VCN, veillez à spécifier une variable de bloc CIDR vcn_cidr_block.

    2. Indiquez les blocs CIDR pour les trois sous-réseaux suivants.

      • Sous-réseau privé de point d'extrémité d'API K8 (k8apiendpoint_private_subnet_cidr_block).
      • Sous-réseau privé de noeuds de travail (workernodes_private_subnet_cidr_block).
      • Sous-réseau public de l'équilibreur de charge du service (serviceloadbalancers_public_subnet_cidr_block).
    3. Définissez l'indicateur is_k8cluster_created pour indiquer à Terraform de créer une grappe Kubernetes et spécifiez le compartiment cible à l'aide de compartment_id. Si un groupe de noeuds de travail est nécessaire, réglez l'indicateur is_nodepool_created en conséquence.

    4. OKE supports two CNI types: VCN-Native (default), where each pod gets its own IP for better performance and full OCI network integration, and Flannel-Overlay, a simpler overlay network where pods share the node’s VNIC. Dans cette configuration, cni_type est réglé à OCI_VCN_IP_NATIVE pour correspondre à la configuration de grappe par défaut créée par le flux de travail Création rapide dans la console OCI.

    5. OKE offre deux types de grappe : De base et Amélioré. Pour plus de flexibilité, nous réglons cluster_type à ENHANCED_CLUSTER.

      • Les grappes améliorées fournissent des fonctions avancées telles que la gestion des modules complémentaires, une sécurité améliorée et un meilleur contrôle du cycle de vie
      • Les grappes de base fournissent un environnement Kubernetes simple avec des fonctions essentielles
    6. La configuration du cycle de noeuds node_cycle_config définit la façon dont les noeuds de travail sont créés, remplacés ou mis à jour dans un groupe de noeuds, en particulier lors des mises à jour, des mises à niveau ou des événements d'ajustement automatique. La configuration définit les attributs suivants :

      • is_node_cycling_enabled (bool): Active le cyclage automatique (remplacement) des noeuds lors d'une mise à jour ou d'une mise à niveau. Réglez à Vrai pour activer la rotation sécurisée des noeuds.
      • maximum_surge (int) : Nombre maximal de noeuds supplémentaires (au-delà du nombre souhaité) pouvant être ajoutés lors des mises à jour. Il permet de créer de nouveaux noeuds avant que les anciens ne soient supprimés sans temps d'arrêt.
      • maximum_unavailable (int) : Nombre maximal de noeuds qui peuvent être indisponibles lors des mises à jour. Permet de contrôler les interruptions lors des mises à jour non simultanées.
      • cycle_modes (list) (Facultatif) : Il fournit une liste ordonnée d'actions pour le cyclage de noeud. Les modes de cycle disponibles sont les suivants :
        • REPLACE_BOOT_VOLUME : Met à jour le volume de démarrage sans mettre fin au noeud.
        • REPLACE_NODES : Cordon, drain, arrêt et recréation des noeuds avec une configuration mise à jour.
  2. Modifiez les valeurs par défaut uniquement si nécessaire. L'ensemble comprend des instructions claires pour la configuration de l'environnement, les étapes d'exécution et les concepts clés liés au réseau et à la sécurité.

    Voici un exemple de configuration Terraform dans le fichier terraform.tfvars que vous devez personnaliser pour l'exécuter dans votre environnement.

    	##########################################################################
    	# 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. Exécutez les commandes Terraform suivantes.

    terraform init
    terraform validate
    terraform plan
    terraform apply
    

    Après l'exécution réussie de terraform apply, votre grappe OKE sera créée dans votre compartiment et votre région de travail avec la configuration suivante :

    • Un ENHANCED_CLUSTER avec OCI_VCN_IP_NATIVE cni_type et la version OKE spécifiée.
    • Sous-réseaux privés dédiés pour les noeuds de travail et le point d'extrémité d'API.
    • Sous-réseau public permettant à l'équilibreur de charge d'accéder aux services de grappe.
    • Groupe de noeuds gérés configuré avec la forme, l'image et le nombre de noeuds souhaités.
  4. Allez à la console OCI pour confirmer votre déploiement et votre configuration de grappe.

    OKECluster

    Les images suivantes illustrent une exécution Terraform réussie ainsi que les journaux générés.

    OKETFLogs

  5. Lorsque vous avez terminé le test, exécutez terraform destroy pour nettoyer votre environnement. Cette commande supprime toutes les ressources OKE créées lors du déploiement et permet d'éviter une consommation inutile de ressources dans votre location.

Tâche 2 : Automatiser l'exécution de l'interface de ligne de commande Terraform avec le pipeline d'intégration et de développement en continu Jenkins

Dans cette tâche, nous allons résumer les étapes précédemment détaillées en quatre étapes principales, conçues pour une orchestration ultérieure par Jenkins. Ce pipeline agrégé est mis en oeuvre au moyen d'un jeu de scripts Bash qui exécutent les commandes de l'interface de ligne de commande Terraform.

Tâche 2.1 : Créer des ressources de réseau

Le script suivant exécute une séquence de plusieurs commandes Terraform pour créer les ressources de réseau.

Pour les scripts restants, assurez-vous que terraform init a déjà été exécuté et que vous exécutez les commandes de votre répertoire de travail. Par exemple, ~/oke_terraform_for_beginners.

Tâche 2.2 : Créer une grappe OKE

Ce script exécute la commande terraform apply pour créer la grappe OKE.

Tâche 2.3. Créer un groupe de noeuds de travail OKE

Le script suivant exécute la commande terraform apply pour créer le groupe de noeuds de travail pour la grappe OKE.

Tâche 2.4 : Détruire toutes les ressources

Ce script exécute une commande destroy, épurant toutes les ressources de grappe OKE (ressources de réseau, grappe OKE et groupe de noeuds de travail).

Nous avons automatisé le processus de bout en bout du pipeline Jenkins, le consolidant en quatre tâches de création Jenkins (Tâche 2.1, 2.2, 2.3). Ce pipeline agrégé s'exécute au moyen de scripts Bash exécutant des commandes de l'interface de ligne de commande Terraform. L'image ci-dessous présente l'automatisation en un clic pour les trois premières tâches; l'étape destroy n'est pas incluse pour plus de simplicité.

OKEArchitecture

Tâche 3 : Orchestrer les déploiements OKE avec Oracle Resource Manager

Flux Oracle Resource Manager (illustré) :

OKEArchitecture

Le diagramme suivant décrit les sept étapes illustrant Oracle Resource Manager Code Manager :

  1. Configuration source : Définit l'origine de la configuration IaC, par exemple un compartiment dans OCI, un seau de stockage d'objets OCI, un fichier zip, Bitbucket ou GitHub.
  2. Modèle Terraform : La configuration de l'infrastructure est définie à l'aide de HashiCorp Terraform dans un fichier de modèle.
  3. Gestionnaire de ressources Oracle : L'offre Terraform as a Service pour OCI prend le modèle Terraform en entrée et gère le processus de provisionnement de l'infrastructure.
  4. Créer une pile : Le gestionnaire de ressources Oracle utilise le modèle pour créer une pile, qui est une collection de ressources OCI.
  5. Plan : Avant d'apporter des modifications, Oracle Resource Manager génère un plan qui décrit les actions à entreprendre pour provisionner ou modifier l'infrastructure.
  6. Appliquer : Selon le plan, le gestionnaire de ressources Oracle applique la configuration, en provisionnant les ressources spécifiées dans OCI.
  7. Détruire : Oracle Resource Manager peut également être utilisé pour détruire (déprovisionner) ou épurer les ressources précédemment créées par la pile.

Tâche 3.1 : Configuration de la source : Définir votre pile du gestionnaire de ressources Oracle

Pour déployer une grappe OKE à l'aide du gestionnaire de ressources Oracle, téléchargez le module destiné aux débutants : oke_terraform_for_beginners_orm.zip. Nous utilisons une structure de répertoires à plat. Lorsque vous décompressez l'ensemble, assurez-vous que tous vos codes sources de modèle Terraform (.tf) se trouvent dans le répertoire racine.

Cette version du module est préconfigurée pour le gestionnaire de ressources Oracle. terraform.tfvars a été supprimé et toutes les variables sont définies avec des valeurs de paramètre fictif "génériques" telles que "REPLACE_WITH_YOUR_OWN_VARIABLE_VALUE" dans variables.tf.

Avant de créer votre stack, mettez à jour variables.tf avec votre région, vos blocs CIDR de réseau et vos indicateurs pour contrôler la création du VCN, de la grappe OKE et du groupe de noeuds.

La grappe OKE utilise le CNI natif de VCN (OCI_VCN_IP_NATIVE) pour le réseau de pods. Assurez-vous donc que l'indicateur create_pod_network_subnet est activé pour définir les blocs CIDR de votre sous-réseau de pod.

Lors de la configuration de stack dans l'interface utilisateur du gestionnaire de ressources d'Oracle, vous pouvez contrôler la création des ressources OKE de base en sélectionnant les options suivantes :

Tâche 3.2 : Créer une pile Oracle Resource Manager

Lors de la création de stack, sélectionnez le modèle Terraform fourni et configurez les variables nécessaires directement dans la console. Oracle Resource Manager détecte automatiquement les variables d'entrée définies dans les fichiers Terraform et les présente sous une forme facile à modifier. À ce stade, vous devrez fournir des détails propres à l'environnement, tels que l'OCID de votre location, l'OCID du compartiment et d'autres valeurs requises.

Les images suivantes illustrent le processus de création et de configuration de variable stack dans la console Oracle Cloud.

OKEArchitecture

OKEArchitecture

Tâche 3.3 : Exécuter la tâche Apply

Pour simplifier, nous ignorons l'étape Plan, car l'exécution de Apply dans le gestionnaire de ressources Oracle l'exécutera automatiquement. En lançant la tâche Apply, le gestionnaire de ressources Oracle utilise la configuration définie à l'étape Source Configuration précédente pour provisionner les ressources OKE spécifiées dans OCI.

Les images suivantes illustrent une exécution de tâche stack Apply réussie ainsi que les journaux générés.

OKEArchitecture

OKEArchitecture

Tâche 3.4 : Exécuter la tâche Destroy

Une fois votre activité ou vos tests terminés, vous pouvez exécuter la tâche Destroy dans le gestionnaire de ressources Oracle pour nettoyer l'environnement. Cette action demande à Oracle Resource Manager de déprovisionner (épurer) toutes les ressources d'infrastructure précédemment créées dans le cadre de la pile, y compris la grappe OKE, les groupes de noeuds, les composants de réseau et tous les services associés. L'exécution de Destroy garantit que les ressources inutilisées sont entièrement supprimées, ce qui vous aide à éviter les coûts inutiles et à maintenir une location OCI propre.

Étapes suivantes

L'utilisation de Terraform pour provisionner une grappe OKE offre une approche cohérente, reproductible et automatisée de la gestion de l'infrastructure Kubernetes sur Oracle Cloud Infrastructure (OCI). Grâce à Infrastructure-code (IaC), les équipes peuvent orchestrer la création de grappes, appliquer les meilleures pratiques et intégrer des flux de travail d'intégration et de développement en continu dans leurs processus de déploiement. Le gestionnaire de ressources d'Oracle améliore cela en simplifiant les opérations Terraform, en gérant l'état et en facilitant la collaboration au sein d'OCI. Ce tutoriel est une introduction conviviale pour les débutants. Dans notre guide avancé à venir, nous aborderons les modules personnalisables, l'automatisation de niveau production, les modèles d'architecture modulaire et l'intégration continue et continue complète. Restez à l'affût d'une approche plus évolutive, sécurisée et prête pour l'entreprise pour la gestion de Kubernetes à grande échelle.

Remerciements

Ressources d'apprentissage supplémentaires

Explorez d'autres laboratoires sur le site docs.oracle.com/learn ou accédez à plus de contenu d'apprentissage gratuit sur le canal Oracle Learning YouTube. De plus, visitez education.oracle.com/learning-explorer pour devenir un explorateur Oracle Learning.

Pour obtenir la documentation sur le produit, visitez Oracle Help Center.