Terraform

목적

Lumie의 Terraform 계층은 K3s가 실행될 OCI 인프라를 프로비저닝합니다. 이 페이지는 이후 부트스트랩 단계가 의존하는 OCI 토폴로지, 교차 계정 라우팅, 노드 및 디스크 배치, 로드 밸런서 계약을 위한 레퍼런스 문서입니다.

소스 경로

경로	역할
lumie-infra/provision/terraform/provider.tf	0214와 0213 OCI 계정용 제공자 alias
lumie-infra/provision/terraform/variables.tf	네트워크 CIDR, 노드 맵, tenancy OCID, SSH 키 입력값
lumie-infra/provision/terraform/network_0214.tf	마스터 계정 VCN, 서브넷, 라우트 테이블, 시큐리티 리스트
lumie-infra/provision/terraform/network_0213.tf	워커 계정 VCN, 서브넷, 라우트 테이블, 시큐리티 리스트
lumie-infra/provision/terraform/peering.tf	두 OCI VCN 간 로컬 피어링 게이트웨이
lumie-infra/provision/terraform/compute_0214.tf	마스터와 0214 계정 워커 인스턴스, 선택된 MinIO 디스크
lumie-infra/provision/terraform/compute_0213.tf	0213 계정 워커 인스턴스와 MinIO 디스크
lumie-infra/provision/terraform/nlb_0214.tf	TCP 443용 퍼블릭 앱 ingress NLB
lumie-infra/provision/terraform/nlb_teleport_0213.tf	NodePort 30443으로 TCP 443을 전달하는 별도 Teleport NLB
lumie-infra/provision/terraform/outputs*.tf	운영자가 사용하고 Ansible 동적 inventory가 소비하는 출력값

퍼블릭 표면

Terraform은 다음 인프라 계약을 생성합니다.

표면	계약
네트워크	계정별 퍼블릭 OCI VCN 2개, 이들 사이의 로컬 피어링 게이트웨이와 라우트 규칙
컴퓨트	퍼블릭 SSH 접근과 프라이빗 K3s 트래픽을 갖춘 ARM64 VM.Standard.A1.Flex Ubuntu 24.04 인스턴스
스토리지	MinIO 데이터 배치를 위한 50 GiB 블록 볼륨 연결
퍼블릭 ingress	예약 퍼블릭 IP와 워커 private IP로 TCP 443을 전달하는 OCI NLB
Teleport edge	예약 퍼블릭 IP와 Teleport NodePort 30443으로 TCP 443을 전달하는 별도 OCI NLB
자동화 출력값	인스턴스 퍼블릭/프라이빗 IP, master URL, Ansible inventory 스크립트용 힌트

런타임 흐름

OCI 계층의 멀티 테넌시

Terraform은 의도적으로 두 개의 OCI 계정에 걸쳐 동작합니다.

• oci.account_0214는 기본 프로필이며, 마스터 VCN, 마스터 노드, 일부 워커, 메인 퍼블릭 ingress NLB를 소유합니다.
• oci.account_0213는 두 번째 프로필이며, 추가 워커와 전용 Teleport NLB를 소유합니다.

VCN CIDR 기본값은 0214 계정이 10.0.0.0/16, 0213 계정이 10.1.0.0/16입니다. peering.tf가 둘을 로컬 피어링 게이트웨이로 연결하고, 두 라우트 테이블 모두 피어 CIDR로 향하는 목적지 규칙을 추가합니다.

노드 및 볼륨 모델

인스턴스 리소스는 다음을 생성합니다.

• nodes_0214에 나열된 워커들과 서버 1대
• nodes_0213에 나열된 워커들
• 각 인스턴스의 base image 정의를 통해 제공되는 50 GiB 부트 볼륨
• MinIO 데이터를 위한 추가 50 GiB 블록 볼륨

compute_0214.tf는 local.minio_nodes_0214를 통해 선택된 노드에만 MinIO 디스크를 제한하고, compute_0213.tf는 모든 0213 워커에 MinIO 디스크를 붙입니다.

인그레스 NLB 계약

메인 퍼블릭 ingress 경로는 OCI에서 HTTP 종료를 수행하지 않는 layer-4 TCP passthrough입니다. 핵심은 예약 IP 수명주기 규칙입니다.

resource "oci_core_public_ip" "nlb_public_ip_0214" {
  lifetime = "RESERVED"

  lifecycle {
    ignore_changes = [private_ip_id]
  }
}

이 ignore_changes는 장식이 아닙니다. nlb_0214.tf의 인라인 주석은, 이후 실행에서 private_ip_id를 무시하지 않으면 NLB가 관리하는 연결이 해제되어 ingress가 조용히 깨질 수 있는 OCI 제공자 동작을 설명합니다.

앱 NLB는 모든 워커 private IP로 TCP 443을 전달하고, 노드에서 Traefik이 SNI 기준으로 TLS를 종료하도록 맡깁니다.

시큐리티 리스트 모델

양쪽 VCN 시큐리티 리스트는 비교적 개방적이며 상위 계층의 통제를 전제로 합니다.

• 0.0.0.0/0에서 들어오는 22, 80, 443, 6443
• Pod CIDR 10.42.0.0/16 및 Service CIDR 10.43.0.0/16
• 로컬 VCN과 피어링된 VCN에서 오는 전체 트래픽
• 0213 측의 Flannel VXLAN용 8472/udp와 WireGuard용 51820/udp

이 설정은 부트스트랩을 단순하게 유지하지만, 애플리케이션 수준 인증, Kubernetes RBAC, 네트워크 정책이 여전히 중요한 안전 계층임을 뜻합니다.

출력값과 Ansible로의 핸드오프

outputs.tf와 outputs_ansible.tf는 Terraform을 다음 단계와 연결합니다.

• 두 계정의 퍼블릭/프라이빗 IP 맵
• SSH 헬퍼 문자열
• 마스터 프라이빗 API URL
• Cloudflare DNS용 NLB 퍼블릭 IP
• inventory/terraform_inventory.py가 쓰기 쉬운 JSON 값

동적 inventory 스크립트는 상태 파일을 직접 파싱하지 않습니다. 대신 terraform output -json을 호출하므로 Ansible이 현재 적용된 상태와 정렬된 채 유지됩니다.

계약 드리프트

• terraform.tfvars.example는 아직 worker-1을 모델링하지만, 2026년 6월 14일에 확인한 라이브 클러스터에는 해당 노드가 없었습니다.
• outputs.tf에는 여전히 Traefik을 비활성화하는 레거시 수동 k3s_install_guide 블록이 남아 있지만, 실제 Ansible role과 라이브 클러스터는 번들 Traefik addon을 활성 상태로 유지합니다.

리소스 파일을 권위 있는 소스로 취급하고, 예시 출력값은 운영자 힌트 정도로만 보세요.

장애 지점

장애 지점	영향
예약 퍼블릭 IP가 NLB 연결을 잃음	워커가 정상이어도 퍼블릭 HTTPS 트래픽이 타임아웃될 수 있음
피어링 또는 라우트 규칙 드리프트	교차 계정 워커가 마스터나 NLB 백엔드에 도달하지 못함
노드 맵과 운영자 기대 불일치	Ansible inventory와 문서가 더 이상 존재하지 않는 노드를 설명할 수 있음
시큐리티 리스트가 지나치게 엄격하게 변경됨	K3s 제어 평면 조인, Flannel, 퍼블릭 ingress가 실패할 수 있음

검증

cd lumie-infra/provision/terraform
terraform output -json
terraform plan

cd ../ansible
./inventory/terraform_inventory.py --list

적용 후 라이브 확인:

kubectl get nodes -o wide
kubectl get applications -n argocd

성공 신호:

• terraform output -json이 운영자와 Ansible이 소비하는 master IP, 워커 IP 맵, 퍼블릭 NLB 출력값을 포함한 예상 브리지 값을 반환합니다.
• terraform plan은 현재 변경에서 의도한 인프라 드리프트만 보여줍니다.
• ./inventory/terraform_inventory.py --list는 수동 호스트 수정 없이 Terraform 출력값에서 masters, workers_0214, workers_0213을 렌더링합니다.
• 적용 후 kubectl get nodes -o wide가 예상 노드 집합을 보여주고, kubectl get applications -n argocd가 프로비저닝된 클러스터가 여전히 GitOps 계층에 도달함을 확인합니다.