Création d'un cluster Oracle Cloud Infrastructure Kubernetes Engine à l'aide de Terraform

Introduction

Dans ce tutoriel, nous allons montrer comment créer un cluster Oracle Cloud Infrastructure Kubernetes Engine (OKE) à l'aide de Terraform et comment gérer votre code Terraform avec Oracle Resource Manager. Cette approche vous permet d'implémenter les principes Infrastructure as Code (IaC), ce qui améliore l'automatisation, la cohérence et la répétabilité dans vos déploiements.

Oracle Cloud Infrastructure Kubernetes Engine (OKE)

Kubernetes (K8s) est une plate-forme open source pour automatiser le déploiement, la mise à l'échelle et la gestion des applications en conteneur. Développée à l'origine par Google et maintenant gérée par la CNCF, elle est la norme du secteur 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 clusters Kubernetes. Il automatise la gestion des noeuds de plan de contrôle et de processus actif, 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 conservation de statut et avec conservation de statut. Les noeuds OKE sont organisés en pools 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 en conteneur. OKE suit le modèle Kubernetes standard, avec deux composants clés (plan de contrôle géré et plan de données géré par le client).

Pour plus d'informations, reportez-vous à Gestion d'OCI Kubernetes Engine avec différents types de capacité et résolution des problèmes courants sur les noeuds préemptifs.

Architecture

L'architecture de référence suivante sera utilisée pour illustrer la création du cluster OKE.

OKEArchitecture

Le diagramme illustre une architecture OKE résiliente déployée au sein d'une seule région OCI répartie entre plusieurs domaines de pannes (FD). La configuration dispose d'un réseau cloud 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 distribuer le trafic entrant, et deux sous-réseaux privés, l'un pour les noeuds de processus actif OKE (NodeSubnet) et l'autre pour le serveur d'API (APISubnet). Les noeuds de processus actif sont répartis sur trois FD au sein d'un seul domaine de disponibilité, ce qui réduit les risques d'échec. Le cluster se connecte de manière transparente à OCI Container Registry pour le stockage et l'extraction d'images de conteneur.

La console OCI propose une méthode simple Point-&-Click. Pour l'utiliser, accédez à l'interface utilisateur des clusters Kubernetes. Sélectionnez Création rapide. Nommez le cluster. Sélectionnez une adresse d'API privée. Configurez des noeuds de processus actif gérés avec la forme, l'image et le nombre souhaités. L'option de la console OCI configure un cluster OKE amélioré. 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 processus actif et l'adresse d'API. En outre, il crée un sous-réseau public pour l'équilibreur de charge. Toutefois, cette approche manuelle prend du 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 plate et simplifiée basée sur Terraform qui automatise l'ensemble de la configuration de cluster OKE en trois étapes :

Ce tutoriel se concentre sur le déploiement de l'infrastructure de cluster OKE de base. Les personnalisations au niveau de l'application et les configurations propres à la charge de travail n'entrent pas dans le champ d'application. 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 triphasé, permettant le déploiement automatisé de l'ensemble de l'environnement OKE sur One-Click.

Vous apprendrez à automatiser la création de ressources réseau (VCN, passerelles, sous-réseaux), le cluster OKE et ses pools de noeuds à l'aide de l'interface de ligne de commande Terraform et d'Oracle Resource Manager. Nous montrerons également comment étendre cette automatisation à l'aide de Bash, de l'interface de ligne de commande OCI et de Jenkins, en réduisant les efforts manuels et en garantissant une livraison cohérente de l'infrastructure.

Objectifs

Prérequis

Automatisation Terraform pour la création de clusters OKE

Il existe deux options d'automatisation pour créer le VCN (OKE-VCN) et le cluster OKE : un module plat ou un module standard utilisant des modules enfant. Cette dernière approche n'entre pas dans le cadre de cet article, mais elle offre une meilleure organisation et évolutivité pour les déploiements plus importants et complexes, favorisant la réutilisabilité et la maintenabilité du code, ce qui le rend idéal pour les environnements de production. Nous utiliserons l'approche simple et plate, adaptée aux cas d'utilisation de développement, aux scénarios de test ou à une démonstration de déploiement VCN unique. Pour plus d'informations, reportez-vous à terraform-oci-oke.

Tâche 1 : déploiement de ressources OKE avec Terraform (Community Edition)

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 ordinateur local ou via OCI Cloud Shell.

Vous pouvez télécharger le code source Terraform complet ici : oke_terraform_for_beginners.zip. Nous utilisons une structure de répertoires plate. Lorsque vous décompressez le package, assurez-vous que tous vos codes source 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 définir l'indicateur approprié (is_vcn_created, is_k8cluster_created ou is_pool_created) sur true dans votre terraform.tfvars. Spécifiez ensuite les paramètres restants pour le réseau, le cluster OKE et le pool de noeuds dans leurs blocs de code respectifs.

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

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

      • Sous-réseau privé d'adresse d'API K8 (k8apiendpoint_private_subnet_cidr_block).
      • Sous-réseau privé de noeud de processus actif (workernodes_private_subnet_cidr_block).
      • Sous-réseau public d'équilibreur de charge de service (serviceloadbalancers_public_subnet_cidr_block).

    3. Définissez l'indicateur is_k8cluster_created pour indiquer à Terraform de créer un cluster Kubernetes et indiquez le compartiment cible à l'aide de compartment_id. Si un pool de noeuds de processus actif est nécessaire, définissez l'indicateur is_nodepool_created en conséquence.

    4. OKE prend en charge deux types de CNI : VCN-Native (par défaut), où chaque pod obtient sa propre adresse IP pour de meilleures performances et une intégration réseau OCI complète, et Flannel-Overlay, un réseau superposé plus simple où les pods partagent la carte d'interface réseau virtuelle du noeud. Dans cette configuration, cni_type est défini sur OCI_VCN_IP_NATIVE pour correspondre à la configuration de cluster par défaut créée par le workflow Création rapide dans la console OCI.

    5. OKE propose deux types de cluster : Basic et Enhanced. Pour plus de flexibilité, nous définissons cluster_type sur ENHANCED_CLUSTER.

      • Les clusters améliorés fournissent des fonctionnalités 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 clusters de base offrent un environnement Kubernetes simple avec des fonctionnalités essentielles

    6. La configuration de cycle de noeud node_cycle_config définit la façon dont les noeuds de processus actif sont créés, remplacés ou mis à jour dans un pool de noeuds, en particulier lors des événements de mise à jour, de mise à niveau ou de redimensionnement 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. Définissez la valeur sur true 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 nœuds avant de supprimer les anciens sans temps d'arrêt.
      • maximum_unavailable (int) : nombre maximal de noeuds qui peuvent être indisponibles pendant les mises à jour. Permet de contrôler les perturbations lors des mises à jour non simultanées.
      • cycle_modes (list) (facultatif) : il fournit une liste ordonnée des actions de cyclage de noeud. Les modes de cycle disponibles sont les suivants :
        • REPLACE_BOOT_VOLUME : met à jour le volume d'initialisation sans mettre fin au noeud.
        • REPLACE_NODES : cordon, purge, terminaison et recréation des noeuds avec la configuration mise à jour.

  2. Modifiez les valeurs par défaut uniquement si nécessaire. Le package comprend des instructions claires pour la configuration de l'environnement, les étapes d'exécution et les concepts clés liés à la mise en 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

    Une fois l'exécution réussie de terraform apply, le cluster OKE sera créé dans votre compartiment de travail et votre région avec la configuration suivante :

    • Une valeur ENHANCED_CLUSTER avec OCI_VCN_IP_NATIVE cni_type et la version OKE indiquée.
    • Sous-réseaux privés dédiés pour les noeuds de processus actifs et l'adresse d'API.
    • Sous-réseau public permettant à l'équilibreur de charge d'accéder aux services de cluster.
    • Pool de noeuds gérés configuré avec la forme, l'image et le nombre de noeuds souhaités.

  4. Accédez à la console OCI pour confirmer le déploiement et la configuration du cluster.

    OKECluster

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

    OKETFLogs

  5. Lorsque vous avez terminé le test, exécutez terraform destroy pour nettoyer votre environnement. Cette commande enlève toutes les ressources OKE créées lors du déploiement et empêche toute utilisation inutile des 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 continue et de déploiement 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 implémenté via un ensemble de scripts Bash qui exécutent les commandes de l'interface de ligne de commande Terraform.

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

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

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

Tâche 2.2 : créer un cluster OKE

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

Tâche 2.3 : Créer un pool de noeuds de processus actif OKE

Le script suivant exécute la commande terraform apply pour créer le pool de noeuds de processus actif pour le cluster OKE.

Tâche 2.4 : détruire toutes les ressources

Ce script exécute une commande destroy, purgeant toutes les ressources de cluster OKE (ressources de mise en réseau, cluster OKE et pool de noeuds de processus actif).

Nous avons automatisé le processus de bout en bout du pipeline Jenkins, le consolidant en quatre tâches de construction Jenkins (tâche 2.1, 2.2, 2.3). Ce pipeline agrégé s'exécute via des scripts Bash exécutant des commandes de l'interface de ligne de commande Terraform. L'image ci-dessous illustre 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 schéma 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 bucket OCI Object Storage, un fichier ZIP, Bitbucket ou GitHub.
  2. Modèle Terraform : la configuration d'infrastructure est définie à l'aide de HashiCorp Terraform dans un fichier de modèle.
  3. Oracle Resource Manager : l'offre OCI Terraform as a Service utilise le modèle Terraform en tant qu'entrée et gère le processus de provisionnement d'infrastructure.
  4. Créer une pile : Oracle Resource Manager utilise le modèle pour créer une pile, qui est un ensemble de ressources OCI.
  5. Plan : avant d'apporter des modifications, Oracle Resource Manager génère un plan qui décrit les actions qui seront effectuées pour provisionner ou modifier l'infrastructure.
  6. Appliquer : selon le plan, Oracle Resource Manager applique la configuration et provisionne les ressources indiquées dans OCI.
  7. Détruire : Oracle Resource Manager peut également être utilisé pour détruire (déprovisionner) ou purger les ressources qui ont été précédemment créées par la pile.

Tâche 3.1 : Configuration de la source : Définir la pile Oracle Resource Manager

Pour déployer un cluster OKE à l'aide d'Oracle Resource Manager, commencez par télécharger le module adapté aux débutants : oke_terraform_for_beginners_orm.zip. Nous utilisons une structure de répertoires plate. Lorsque vous décompressez le package, assurez-vous que tous les codes source de modèle Terraform (.tf) se trouvent dans le répertoire racine.

Cette version du module est préconfigurée pour Oracle Resource Manager ; terraform.tfvars a été supprimé et toutes les variables sont définies avec des valeurs d'espace réservé "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, les CIDR de mise en réseau et les indicateurs pour contrôler la création du cluster VCN, OKE et du pool de noeuds.

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

Lorsque vous configurez stack dans l'interface utilisateur d'Oracle Resource Manager, vous pouvez contrôler la création des ressources OKE principales en sélectionnant les éléments suivants :

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. A ce stade, vous devrez fournir des détails propres à l'environnement, tels que l'OCID de votre location, le compartiment OCID 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 le travail d'application

Pour plus de simplicité, nous ignorons l'étape Plan, car l'exécution de Apply dans Oracle Resource Manager l'exécute automatiquement. En lançant le travail Apply, Oracle Resource Manager utilise la configuration définie à l'étape Source Configuration précédente pour provisionner les ressources OKE indiquées dans OCI.

Les images suivantes illustrent l'exécution réussie d'un travail stack Apply avec les journaux générés.

OKEArchitecture

OKEArchitecture

Tâche 3.4 : Exécuter le travail de destruction

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

Etapes suivantes

L'utilisation de Terraform pour provisionner un cluster OKE offre une approche cohérente, reproductible et automatisée de la gestion de l'infrastructure Kubernetes sur Oracle Cloud Infrastructure (OCI). Avec Infrastructure as Code (IaC), les équipes peuvent orchestrer la création de clusters, appliquer les meilleures pratiques et intégrer des workflows d'intégration continue et de déploiement continu dans leurs processus de déploiement. Oracle Resource Manager l'améliore en simplifiant les opérations Terraform, en gérant l'état et en favorisant la collaboration au sein d'OCI. Ce tutoriel sert d'introduction conviviale pour les débutants. Dans notre prochain guide avancé, nous aborderons les modules personnalisables, l'automatisation de la production, les modèles d'architecture modulaire et l'intégration complète de l'intégration continue et du déploiement continu. Restez à l'écoute pour une approche plus évolutive, sécurisée et adaptée à l'entreprise de la gestion de Kubernetes à grande échelle.

Accusés de réception

Ressources de formation supplémentaires

Explorez d'autres ateliers sur le site docs.oracle.com/learn ou accédez à d'autres contenus d'apprentissage gratuits sur le canal Oracle Learning YouTube. En outre, visitez le site education.oracle.com/learning-explorer pour devenir un explorateur Oracle Learning.

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