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 클러스터의 배포 및 관리를 간소화해 줍니다. 제어 플레인 및 작업자 노드 관리를 자동화하고, OCI의 네트워킹, 스토리지 및 보안 서비스와 통합되며, Stateless 및 Stateful 워크로드를 모두 지원합니다. OKE 노드는 간편하게 확장 및 관리할 수 있는 노드 풀로 구성되며, 컨테이너화된 애플리케이션에 대한 고가용성 및 최적의 리소스 활용률을 보장합니다. OKE는 표준 Kubernetes 모델을 따르며, 두 가지 주요 구성 요소(관리형 제어 플레인과 고객 관리형 데이터 플레인)가 있습니다.

자세한 내용은 용량 유형이 다른 OCI Kubernetes 엔진 관리 및 선점 가능한 노드에서 공통 문제 해결을 검토하십시오.

구조

다음 참조 아키텍처는 OKE 클러스터 생성을 보여주는 데 사용됩니다.

OKEArchitecture

이 다이어그램은 여러 FD(폴트 도메인)에 분산된 단일 OCI 리전에 배포된 복원형 OKE 아키텍처를 보여줍니다. 이 설정은 세 개의 개별 서브넷(인터넷 게이트웨이를 호스팅하는 공용 서브넷(LBSubnet)과 수신 트래픽을 분산하는 OCI 로드 밸런서, OKE 작업자 노드(NodeSubnet) 및 API 서버(APISubnet)용 전용 서브넷 두 개를 갖춘 VCN(가상 클라우드 네트워크)을 제공합니다. 작업자 노드는 단일 가용성 도메인(AD) 내에 있는 3개의 FD에 분산되어 실패 위험을 최소화합니다. 이 클러스터는 컨테이너 이미지 저장 및 검색을 위해 OCI 컨테이너 레지스트리에 원활하게 연결됩니다.

OCI 콘솔은 간단한 포인트-클릭 방법을 제공합니다. 이를 사용하려면 Kubernetes 클러스터 UI로 이동합니다. 빠른 생성을 선택합니다. 클러스터 이름을 지정합니다. 프라이빗 API 끝점을 선택합니다. 원하는 구성, 이미지 및 개수로 관리 대상 작업자 노드를 구성합니다. OCI 콘솔의 옵션은 향상된 OKE 클러스터를 설정합니다. 기본값인 OCI_VCN_IP_NATIVE CNI를 사용합니다. 또한 작업자 노드 및 API 엔드포인트를 위한 전용 프라이빗 서브넷을 제공합니다. 또한 로드 밸런서에 대한 공용 서브넷을 생성합니다. 그러나 이 수동 접근 방식은 시간이 많이 걸리고 대규모 또는 반복 가능한 배포의 경우 확장 불가능합니다.

이 자습서에서는 수동 배포의 한계를 극복하기 위해 다음 세 단계로 전체 OKE 클러스터 설정을 자동화하는 단순화된 플랫 Terraform 기반 솔루션을 제공합니다.

이 자습서에서는 핵심 OKE 클러스터 기반구조를 배치하는 방법에 대해 중점적으로 설명합니다. 응용 프로그램 레벨 사용자 정의 및 작업 로드별 구성은 범위를 벗어납니다. 프로비저닝을 간소화하기 위해 Terraform 명령 실행을 자동화하는 Bash 스크립트가 포함되었습니다. 이러한 스크립트는 3상 Jenkins 파이프라인에 원활하게 통합되도록 설계되어 전체 OKE 환경을 One-Click에서 자동으로 배포할 수 있습니다.

Terraform CLI와 Oracle Resource Manager를 모두 사용하여 네트워킹 리소스(VCN, 게이트웨이, 서브넷), OKE 클러스터 및 해당 노드 풀 생성을 자동화하는 방법을 배웁니다. 또한 Bash, OCI CLI 및 Jenkins를 사용하여 이 자동화를 확장하여 수동 작업을 줄이고 일관된 인프라 제공을 보장하는 방법을 시연할 것입니다.

목표

필수 조건

OKE 클러스터 생성을 위한 Terraform 자동화

VCN(OKE-VCN) 및 OKE 클러스터를 만들기 위한 두 가지 자동화 옵션인 플랫 모듈 또는 하위 모듈을 활용하는 표준 모듈이 있습니다. 후자의 접근 방식은 이 문서의 범위를 벗어나지만, 대규모의 복잡한 배포를 위해 더 나은 조직과 확장성을 제공하고, 코드 재사용성과 유지 관리 용이성을 높여 운영 환경에 이상적입니다. 개발 사용 사례, 테스트 시나리오 또는 일회성 VCN 배포 데모에 적합한 단순하고 간단한 접근 방식을 사용합니다. 자세한 내용은 terraform-oci-oke를 참조하십시오.

작업 1: Terraform을 사용하여 OKE 리소스 배치(Community Edition)

Terraform 명령을 실행하여 Terraform CLI를 사용하여 인프라를 계획하고 배치하기 전에 제공된 Terraform 구성을 로컬 머신 또는 OCI Cloud Shell을 통해 환경별 세부정보로 업데이트합니다.

전체 Terraform 소스 코드는 oke_terraform_for_beginners.zip에서 다운로드할 수 있습니다. 플랫 디렉토리 구조를 사용하고 있습니다. 패키지의 압축을 풀 때 모든 Terraform 템플리트 소스 코드(.tf, .tfvars, ssh 키 등)가 루트 디렉토리에 있는지 확인합니다.

  1. 기본 리소스(VCN, OKE_Cluser 또는 Node_Pool)를 생성하도록 Terraform에 지시하려면 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).
      • 워커 노드 프라이빗 서브넷(workernodes_private_subnet_cidr_block)입니다.
      • 서비스 로드 밸런서 퍼블릭 서브넷(serviceloadbalancers_public_subnet_cidr_block).

    3. Kubernetes 클러스터를 생성하도록 Terraform에 알리고 compartment_id을 사용하여 대상 컴파트먼트를 지정하도록 is_k8cluster_created 플래그를 설정합니다. 작업자 노드 풀이 필요한 경우 그에 따라 is_nodepool_created 플래그를 설정합니다.

    4. OKE는 두 가지 CNI 유형인 VCN-Native(기본값)를 지원합니다. 여기서 각 포드는 더 나은 성능과 완전한 OCI 네트워크 통합을 위해 자체 IP를 가져오고, 포드가 노드의 VNIC를 공유하는 더 간단한 오버레이 네트워크인 Flannel-Overlay를 가져옵니다. 이 설정에서 cni_type는 OCI 콘솔의 빠른 생성 워크플로우에 의해 생성된 기본 클러스터 구성과 일치하도록 OCI_VCN_IP_NATIVE로 설정됩니다.

    5. OKE는 Basic 및 Enhanced의 두 가지 클러스터 유형을 제공합니다. 유연성이 향상되도록 cluster_type를 ENHANCED_CLUSTER로 설정합니다.

      • 향상된 클러스터는 추가 기능 관리, 향상된 보안, 향상된 수명 주기 제어와 같은 고급 기능을 제공합니다.
      • 기본 클러스터는 필수 기능을 갖춘 간단한 Kubernetes 환경을 제공합니다.

    6. 노드 주기 구성 node_cycle_config은 특히 업데이트, 업그레이드 또는 자동 스케일링 이벤트 중에 노드 풀 내에서 작업자 노드가 생성, 교체 또는 업데이트되는 방식을 정의합니다. 구성은 다음 속성을 정의합니다.

      • 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 클러스터가 다음 구성을 사용하여 작업 컴파트먼트 및 영역에 생성됩니다.

    • OCI_VCN_IP_NATIVE cni_type 및 지정된 OKE 버전이 포함된 ENHANCED_CLUSTER입니다.
    • 작업자 노드 및 API 끝점 모두에 대한 전용 프라이빗 서브넷입니다.
    • 클러스터 서비스에 액세스하기 위한 로드 밸런서의 공용 서브넷입니다.
    • 원하는 구성, 이미지 및 노드 수로 구성된 관리 대상 노드 풀입니다.

  4. OCI 콘솔로 이동하여 클러스터 배포 및 구성을 확인합니다.

    OKECluster

    다음 이미지는 생성된 로그와 함께 성공적인 Terraform 실행을 보여줍니다.

    OKETFLogs

  5. 테스트가 완료되면 terraform destroy를 실행하여 환경을 정리합니다. 이 명령은 배치 중 생성된 모든 OKE 리소스를 제거하고 테넌시에서 불필요한 리소스 사용을 방지하는 데 도움이 됩니다.

작업 2: Jenkins CI/CD 파이프라인을 사용하여 Terraform CLI 실행 자동화

이 작업에서는 이전에 설명된 단계를 Jenkins의 이후 통합관리를 위해 설계된 네 가지 기본 단계로 요약합니다. 이 집계된 파이프라인은 Terraform CLI 명령을 실행하는 Bash 스크립트 세트를 통해 구현됩니다.

작업 2.1: 네트워킹 리소스 만들기

다음 스크립트는 여러 Terraform 명령 시퀀스를 실행하여 네트워크 리소스를 만듭니다.

나머지 스크립트의 경우 terraform init가 이미 실행되었는지, 작업 디렉토리에서 명령을 실행 중인지 확인합니다. 예: ~/oke_terraform_for_beginners.

작업 2.2: OKE 클러스터 만들기

이 스크립트는 terraform apply 명령을 실행하여 OKE 클러스터를 만듭니다.

작업 2.3. OKE 워커 노드 풀 생성

다음 스크립트는 terraform apply 명령을 실행하여 OKE 클러스터에 대한 워커 노드 풀을 만듭니다.

작업 2.4: 모든 리소스 삭제

이 스크립트는 destroy 명령을 실행하여 모든 OKE 클러스터 리소스(네트워킹 리소스, OKE 클러스터 및 워커 노드 풀)를 비웁니다.

Jenkins 파이프라인의 엔드투엔드 프로세스를 자동화하여 4개의 Jenkins 빌드 작업으로 통합했습니다(작업 2.1, 2.2, 2.3). 이 집계된 파이프라인은 Terraform CLI 명령을 실행하는 Bash 스크립트를 통해 실행됩니다. 아래 이미지는 처음 3개 태스크에 대한 원클릭 자동화를 보여줍니다. 단순성을 위해 destroy 단계는 포함되지 않습니다.

OKEArchitecture

작업 3: Oracle Resource Manager로 OKE 배치 조정

Oracle Resource Manager 흐름(그림):

OKEArchitecture

다음 다이어그램은 Oracle Resource Manager Code Manager를 보여주는 7가지 단계에 대해 설명합니다.

  1. 소스 구성: OCI의 구획, OCI Object Storage 버킷, Zip 파일, Bitbucket, GitHub 등 IaC 구성이 시작되는 위치를 정의합니다.
  2. Terraform 템플리트: 기반 구조 구성은 템플리트 파일에서 HashiCorp Terraform을 사용하여 정의됩니다.
  3. Oracle Resource Manager: OCI Terraform as a Service 오퍼링은 Terraform 템플릿을 입력으로 사용하고 인프라 프로비저닝 프로세스를 관리합니다.
  4. 스택 생성: Oracle Resource Manager는 템플리트를 사용하여 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를 생성하기 전에 variables.tf를 지역, 네트워킹 CIDR 및 플래그로 업데이트하여 VCN, OKE 클러스터 및 노드 풀 생성을 제어합니다.

OKE 클러스터는 Pod 네트워킹에 VCN-Native CNI(OCI_VCN_IP_NATIVE)를 활용하므로 Pod 서브넷 CIDR을 정의하려면 create_pod_network_subnet 플래그가 사용으로 설정되었는지 확인하십시오.

Oracle Resource Manager UI에서 stack를 구성할 때 다음을 선택하여 핵심 OKE 리소스 생성을 제어할 수 있습니다.

작업 3.2: Oracle Resource Manager 스택 생성

stack 생성 중 제공된 Terraform 템플리트를 선택하고 콘솔 내에서 필요한 변수를 직접 구성합니다. Oracle Resource Manager는 Terraform 파일에 정의된 입력 변수를 자동으로 감지하여 쉽게 편집할 수 있는 형식으로 표시합니다. 이 단계에서는 테넌시 OCID, 컴파트먼트 OCID 및 기타 필요한 값과 같은 환경별 세부정보를 제공해야 합니다.

다음 이미지는 Oracle Cloud 콘솔 내의 stack 생성 및 변수 구성 프로세스를 보여줍니다.

OKEArchitecture

OKEArchitecture

작업 3.3: 적용 작업 실행

Oracle Resource Manager에서 Apply를 실행하면 자동으로 실행되므로 단순성을 위해 Plan 단계를 건너뜁니다. Apply 작업을 실행하여 Oracle Resource Manager는 이전 Source Configuration 단계에서 정의된 구성을 사용하여 OCI 내에서 지정된 OKE 리소스를 프로비전합니다.

다음 이미지는 생성된 로그와 함께 성공적인 stack Apply 작업 실행을 보여줍니다.

OKEArchitecture

OKEArchitecture

작업 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를 대규모로 관리하는 보다 확장 가능하고 안전하며 엔터프라이즈급 접근 방식에 맞게 조정하십시오.

승인

추가 학습 자원

docs.oracle.com/learn에서 다른 랩을 탐색하거나 Oracle Learning YouTube 채널에서 더 많은 무료 학습 콘텐츠에 액세스하세요. 또한 education.oracle.com/learning-explorer를 방문하여 Oracle Learning Explorer가 되십시오.

제품 설명서는 Oracle Help Center를 참조하십시오.