使用 Terraform 创建 Oracle Cloud Infrastructure Kubernetes Engine 集群

简介

在本教程中，我们将演示如何使用 Terraform 创建 Oracle Cloud Infrastructure Kubernetes Engine (OKE) 集群以及如何使用 Oracle Resource Manager 管理 Terraform 代码。通过此方法，您可以实施基础设施即代码 (IaC) 原则，从而增强部署中的自动化、一致性和可重复性。

Oracle Cloud Infrastructure Kubernetes Engine (OKE)

Kubernetes (K8s) 是一个开源平台，用于自动部署、扩展和管理容器化应用。它最初由 Google 开发，现在由 CNCF 维护，是大规模运行云原生应用的行业标准。

OKE 是一项基于 Oracle Cloud Infrastructure (OCI) 的完全托管服务，可简化 Kubernetes 集群的部署和管理。它自动执行控制层和 worker 节点管理，与 OCI 的网络、存储和安全服务集成，并支持无状态和有状态工作负载。OKE 节点组织到节点池中，可以轻松扩展和管理，从而确保容器化应用的高可用性和最佳资源利用率。OKE 采用标准 Kubernetes 模型，包含两个关键组件（管理控制层和客户管理的数据层）。

• 控制层：由 Oracle 全面管理，其组件可处理集群的编排和管理：

  • kube-apiserver：用于与集群通信的中央 API。
  • etcd：存储群集的配置和状态。
  • kube-scheduler：将 pod 分配给合适的节点。
  • kube-controller-manager：通过管理控制器来确保所需状态。
  • cloud-controller-manager (CCM)：与 OCI 集成，以管理 OCI Load Balancer 和 OCI Block Volumes 等云资源。

• 数据层：部署在客户租户中，运行实际工作负载。它由以下各项组成：

  • Worker Nodes：运行云池的计算实例（由客户预配）。
  • kubelet：管理 pod 执行的节点代理。
  • kube-proxy：处理网络规则以及向云池/从云池路由流量。

有关详细信息，请查看管理具有不同容量类型的 OCI Kubernetes 引擎并解决可抢占节点上的常见问题。

体系结构

以下参考体系结构将用于演示 OKE 群集的创建。

图中展示了部署在分布在多个容错域 (Fault Domains，FD) 中的单个 OCI 区域中的具有弹性的 OKE 架构。该设置使用具有三个不同子网的虚拟云网络 (VCN)：一个托管互联网网关的公共子网 (LBSubnet) 和一个用于分配传入流量的 OCI 负载平衡器，以及两个专用子网，一个用于 OKE worker 节点 (NodeSubnet)，另一个用于 API 服务器 (APISubnet)。Worker 节点分布在单个可用性域 (Availability Domain，AD) 中的三个 FD 中，从而最大限度降低故障风险。该集群可无缝连接到 OCI Container Registry，以进行容器映像存储和检索。

OCI 控制台提供简单的点击和点击方法。要使用它，请导航到 Kubernetes 集群 UI。选择快速创建。为集群命名。选择专用 API 端点。使用所需的配置、映像和计数配置托管 worker 节点。OCI 控制台的选项用于设置增强的 OKE 集群。它使用 OCI_VCN_IP_NATIVE CNI，这是默认值。它还为 Worker 节点和 API 端点提供专用子网。此外，它还会为负载平衡器创建公共子网。但是，这种手动方法对于大型或可重复的部署来说非常耗时且不可扩展

为了克服手动部署的限制，本教程提供了基于 Terraform 的简化平面解决方案，该解决方案通过三个步骤自动完成整个 OKE 集群设置：

• 网络资源创建。
• OKE 集群预配。
• 员工节点池创建。

本教程重点介绍部署核心 OKE 集群基础结构。应用程序级别的自定义和特定于工作负载的配置超出了其范围。为了简化预配，我们提供了用于自动执行 Terraform 命令的 Bash 脚本。这些脚本可无缝集成到三阶段 Jenkins 管道中，从而实现整个 OKE 环境的 One-Click 自动部署。

学生将学习如何使用 Terraform CLI 和 Oracle Resource Manager 自动创建网络资源（VCN、网关、子网）、OKE 集群及其节点池。我们还将演示如何使用 Bash、OCI CLI 和 Jenkins 扩展此自动化，从而减少手动工作并确保一致的基础设施交付。

目标

• 使用 Terraform for Infrastructure as Code 创建 OKE 集群，并描述通过 Oracle 资源管理器管理部署的过程。在此过程中，还将介绍基本 OKE 概念。

Prerequisites

• 初始设置的 OCI 租户根管理员角色，不建议用于生产。

  • 具有必要网络和 OKE OCI IAM 策略的非管理员 OCI 用户。有关更多信息，请参见 Policy Configuration for Cluster Creation and Deployment 。

• 熟悉基础设施即代码原则和 Terraform（社区版本），包括：

  • Oracle 云 Shell
  • Oracle Command Line Interface，CLI（命令行界面）；
  • Oracle 资源管理器、
  • Visual Studio Code

用于创建 OKE 集群的 Terraform 自动化

有两个自动化选项可用于创建 VCN (OKE-VCN) 和 OKE 群集：平面模块或利用子模块的标准模块。后一种方法超出了本文的范围，但它为大型、复杂的部署提供了更好的组织和可扩展性，促进了代码的可重用性和可维护性，使其成为生产环境的理想选择。我们将使用更加扁平且简单的方法，适用于开发用例、测试场景或一次性 VCN 部署演示。有关详细信息，请参阅 terraform-oci-oke 。

任务 1：使用 Terraform 部署 OKE 资源 (Community Edition)

在使用 Terraform CLI 运行 Terraform 命令规划和部署基础设施之前，请从本地计算机或通过 OCI Cloud Shell 使用特定于环境的详细信息更新提供的 Terraform 配置。

您可以在此处下载完整的 Terraform 源代码：oke_terraform_for_beginners.zip 。我们正在使用平面目录结构。解压缩程序包时，请确保所有 Terraform 模板源代码（.tf、.tfvars、ssh 密钥等）都位于根目录中。

1. 要指示 Terraform 创建任何主要资源（VCN、OKE_Cluser 或 Node_Pool），您需要将 terraform.tfvars 中的相应标志（is_vcn_created、is_k8cluster_created 或 is_pool_created）设置为 true。然后，在其各自的代码块中指定网络、OKE 群集和节点池的其余参数。

   1. 首先将 is_vcn_created 设置为 true，指示 Terraform 创建新 VCN 或 false 以使用现有 VCN（您需要提供其 OCID）。如果创建新的 VCN，请确保指定 CIDR 块变量 vcn_cidr_block。

   2. 为以下三个子网提供 CIDR 块。

      • K8 API 端点专用子网 (k8apiendpoint_private_subnet_cidr_block)。
      • Worker 节点专用子网 (workernodes_private_subnet_cidr_block)。
      • 服务负载平衡器公共子网 (serviceloadbalancers_public_subnet_cidr_block)。

   3. 设置 is_k8cluster_created 标志以告知 Terraform 创建 Kubernetes 集群，并使用 compartment_id 指定目标区间。如果需要 worker 节点池，请相应地设置 is_nodepool_created 标志。

   4. OKE 支持两种 CNI 类型：VCN 本机（默认设置），其中每个云池都有自己的 IP 以实现更高的性能和完整的 OCI 网络集成； Flannel-Overlay （一个更简单的叠加网络，云池共享节点的 VNIC）。在此设置中，cni_type 设置为 OCI_VCN_IP_NATIVE，以匹配由 OCI 控制台中的快速创建工作流创建的默认集群配置。

   5. OKE 提供了两种群集类型： Basic 和 Enhanced 。为了提高灵活性，我们将 cluster_type 设置为 ENHANCED_CLUSTER。

      • 增强集群提供附加管理、增强的安全性和更好的生命周期控制等高级功能
      • 基本集群提供具有基本功能的简单 Kubernetes 环境

   6. 节点周期配置 node_cycle_config 定义如何在节点池中创建、替换或更新 worker 节点，尤其是在更新、升级或自动缩放事件期间。配置定义以下属性：

      • is_node_cycling_enabled (bool): 允许在更新或升级期间自动循环（替换）节点。设置为 true 以启用安全节点旋转。
      • maximum_surge (int)：更新期间可以添加的最大额外节点数（超出所需计数）。它允许在删除旧节点之前创建新节点，而不会停机。
      • maximum_unavailable (int)：更新期间可能不可用的最大节点数。用于控制滚动更新期间的中断。
      • cycle_modes (list)（可选）：它提供了用于节点循环的有序操作列表。可用的周期模式包括：
        • REPLACE_BOOT_VOLUME：更新引导卷而不终止节点。
        • REPLACE_NODES：使用更新的配置对节点进行封锁、排空、终止和重新创建。

2. 仅在必要时修改默认值。该软件包包含有关环境设置、执行步骤以及与网络和安全性相关的关键概念的明确说明。

   下面是 terraform.tfvars 文件中的 Terraform 配置示例，您需要对其进行定制才能在环境中运行。

   	##########################################################################
   	# 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. 运行以下 Terraform 命令。

   terraform init
   terraform validate
   terraform plan
   terraform apply
   

   成功执行 terraform apply 后，将在工作区间和区域中使用以下配置创建 OKE 集群：

   • ENHANCED_CLUSTER，带有 OCI_VCN_IP_NATIVE cni_type 和指定的 OKE 版本。
   • 适用于 worker 节点和 API 端点的专用子网。
   • 负载平衡器用于访问集群服务的公共子网。
   • 配置有所需配置、映像和节点计数的托管节点池。

4. 转到 OCI 控制台以确认集群部署和配置。

   

   下图展示了成功的 Terraform 执行以及生成的日志。

   

5. 完成测试后，运行 terraform destroy 以清理环境。此命令将删除在部署期间创建的所有 OKE 资源，并有助于防止租户中不必要的资源消耗。

任务 2：使用 Jenkins CI/CD 管道自动执行 Terraform CLI

在此任务中，我们将以前详细步骤抽象为四个主要阶段，这些阶段是为 Jenkins 以后的编排而设计的。此聚合管道通过一组执行 Terraform CLI 命令的 Bash 脚本来实现。

任务 2.1：创建网络资源

以下脚本运行多个 Terraform 命令序列以创建网络资源。

• 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
  

对于其余脚本，请确保已执行 terraform init，并且您正在运行工作目录中的命令。例如，~/oke_terraform_for_beginners。

任务 2.2：创建 OKE 集群

此脚本运行 terraform apply 命令以创建 OKE 群集。

• 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
  

任务 2.3。创建 OKE Worker 节点池

以下脚本运行 terraform apply 命令为 OKE 群集创建 worker 节点池。

• 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
  

任务 2.4：销毁所有资源

此脚本运行 destroy 命令，清除所有 OKE 群集资源（网络资源、OKE 群集和 worker 节点池）。

• 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
  

我们实现了 Jenkins 管道端到端流程的自动化，并将其整合到四个 Jenkins 构建任务中（任务 2.1、2.2、2.3）。此聚合管道通过执行 Terraform CLI 命令的 Bash 脚本运行。下图显示了前三个任务的一键式自动化；为了简单起见，未包括 destroy 步骤。

任务 3：使用 Oracle Resource Manager 编排 OKE 部署

Oracle Resource Manager Flow（图示）：

下图介绍了 Oracle Resource Manager Code Manager 的七个步骤：

1. 源配置：定义 IaC 配置的源位置，例如 OCI 中的区间、OCI 对象存储存储桶、Zip 文件、Bitbucket 或 GitHub。
2. Terraform 模板：基础结构配置是使用模板文件中的 HashiCorp Terraform 定义的。
3. Oracle 资源管理器： OCI Terraform as a Service 产品将 Terraform 模板作为输入，并管理基础设施预配流程。
4. 创建堆栈：Oracle 资源管理器使用该模板创建堆栈，堆栈是 OCI 资源的集合。
5. 计划：在进行任何更改之前，Oracle Resource Manager 会生成计划，其中概述了预配或修改基础结构时将采取的操作。
6. 应用：Oracle Resource Manager 根据计划应用配置，在 OCI 中预配指定的资源。
7. 销毁：Oracle Resource Manager 也可用于销毁（取消预配）或清除先前由堆栈创建的资源。

任务 3.1：源配置：定义 Oracle Resource Manager 堆栈

要使用 Oracle Resource Manager 部署 OKE 集群，请首先下载初学者友好的模块：oke_terraform_for_beginners_orm.zip 。我们正在使用平面目录结构。解压缩程序包时，请确保所有 Terraform 模板源代码 (.tf) 都位于根目录中。

此版本的模块是为 Oracle Resource Manager 预配置的；terraform.tfvars 已删除，所有变量均使用“通用”占位符值设置 , 如 variables.tf 中的 ”REPLACE_WITH_YOUR_OWN_VARIABLE_VALUE”。

在创建 stack 之前，请使用区域、网络 CIDR 和标志更新 variables.tf，以控制 VCN、OKE 集群和节点池的创建。

OKE 集群将 VCN 本机 CNI (OCI_VCN_IP_NATIVE) 用于云池网络，因此请确保启用了 create_pod_network_subnet 标志来定义云池子网 CIDR。

在 Oracle Resource Manager UI 中配置 stack 时，您可以通过选择以下选项来控制核心 OKE 资源的创建：

• VCN：选择 is_vcn_created。
• OKE Cluster：选择 is_k8cluster_created。
• OKE Node Pool（确定节点池）：选择 is_nodepool_created。

任务 3.2：创建 Oracle Resource Manager 堆栈

在 stack 创建期间，选择提供的 Terraform 模板，然后直接在控制台中配置必要的变量。Oracle Resource Manager 会自动检测 Terraform 文件中定义的输入变量，并以易于编辑的表单显示这些变量。在此阶段，您需要提供特定于环境的详细信息，例如您的租户 OCID、区间 OCID 和其他必需值。

下图显示了 Oracle Cloud 控制台中的 stack 创建和变量配置过程。

任务 3.3：执行应用作业

为简单起见，我们将跳过 Plan 步骤，因为在 Oracle Resource Manager 中运行 Apply 将自动执行该步骤。通过启动 Apply 作业，Oracle Resource Manager 将使用上一个 Source Configuration 步骤中定义的配置在 OCI 中预配指定的 OKE 资源。

下图展示了成功的 stack Apply 作业执行以及生成的日志。

任务 3.4：执行销毁作业

活动或测试完成后，您可以在 Oracle Resource Manager 中运行 Destroy 作业以清理环境。此操作会指示 Oracle Resource Manager 取消预配（清除）以前在堆栈中创建的所有基础结构资源，包括 OKE 群集、节点池、网络组件以及任何关联服务。运行 Destroy 可确保完全删除未使用的资源，从而避免不必要的成本并维护干净的 OCI 租户。

后续步骤

使用 Terraform 预配 OKE 集群提供了一种一致、可重复且自动化的方法来管理 Oracle Cloud Infrastructure (OCI) 上的 Kubernetes 基础设施。借助基础设施即代码 (IaC)，团队可以编排集群创建，实施优秀实践，并将 CI/CD 工作流集成到其部署流程中。Oracle Resource Manager 通过简化 Terraform 操作、管理状态以及在 OCI 中启用协作来增强这一点。本教程是初学者友好的介绍，在即将推出的高级指南中，我们将介绍可定制模块、生产级自动化、模块化架构模式以及完整的 CI/CD 集成。敬请关注，以采用更可扩展、更安全、更适合企业的方式大规模管理 Kubernetes。

相关链接

• Kubernetes 引擎 (OKE) 概述

• Terraform 提供程序

• terraform-oci-oke

• Oracle 资源管理器

• 管理具有不同容量类型的 OCI Kubernetes 引擎并解决可抢占节点上的常见问题

• 基础设施即规范

确认

• 作者 — Mahamat Guiagoussou（首席驻地云架构师），Payal Sharma（高级驻地云架构师）

更多学习资源

通过 docs.oracle.com/learn 浏览其他实验室，或者通过 Oracle Learning YouTube 频道访问更多免费学习内容。此外，请访问 education.oracle.com/learning-explorer 以成为 Oracle Learning Explorer。

有关产品文档，请访问 Oracle 帮助中心。

---

标题和版权信息

Create Oracle Cloud Infrastructure Kubernetes Engine Cluster using Terraform

G38270-01

Copyright ©2025, Oracle and/or its affiliates.