Terraform과 Ansible로 클러스터를 코드에서 다시 세울 수 있게 만드는 절차

목표

시리즈 1~2에서 손으로 실행한 절차(VM 준비, kubeadm init/join, CNI/스토리지 설치, 애플리케이션 배포)를 코드로 옮긴다. 클라우드 리소스는 Terraform, 노드의 OS/쿠버네티스 레벨 준비는 Ansible로 나눈다. 코드화가 끝났다고 선언하기 전에, 라이브 클러스터를 실제로 통째로 파기하고 코드만으로 다시 세울 수 있는지까지 검증한다.

개념: IaC(Infrastructure as Code)란 무엇인가

콘솔에 로그인해 클릭으로 서버를 만들거나, SSH로 접속해 손으로 패키지를 설치하면 "지금 이 서버가 왜 이런 상태인지"는 그 작업을 한 사람의 기억에만 남는다. 시간이 지나거나 담당자가 바뀌면 같은 환경을 다시 만들 방법이 없다 - IaC는 인프라의 상태를 코드로 선언해두고, 그 코드를 실행하면 실제 인프라가 그 상태가 되도록 만드는 방식이다. 코드 자체가 곧 "지금 인프라가 어떤 모습이어야 하는지"에 대한 살아있는 문서가 된다.

IaC 도구는 크게 두 방식으로 나뉜다.

• 선언적(declarative): "최종적으로 이런 모습이어야 한다"만 적으면, 도구가 현재 상태와 비교해서 차이만 계산해 적용한다. Terraform이 이 방식이다.
• 절차적(procedural): "이 순서대로 이 작업들을 해라"를 적어두면 그대로 실행한다. Ansible이 이 방식이다.

두 방식 모두에서 **멱등성(idempotency)**이 핵심이다 - 같은 코드를 몇 번을 실행해도 결과가 항상 같아야 한다. "이미 존재하면 건너뛰고, 없으면 만든다"는 판단을 도구가 대신 해주기 때문에, 사람이 "이거 이미 실행했었나?"를 기억할 필요가 없어진다.

역할 분담: 왜 두 도구를 같이 쓰는가

실제 구축 절차

1. Terraform - AWS 리소스 코드화

가장 먼저 결정해야 했던 건 "무엇을 resource로 선언하고, 무엇을 data로만 참조할 것인가"였다. VPC·서브넷·SSH 키페어(k8s-lab)는 계정에 이미 존재하는 리소스다 - 이걸 Terraform resource로 선언하면, terraform destroy나 설정 변경 한 번에 실수로 그 리소스 자체가 재생성/파기될 위험이 생긴다. 특히 키페어가 무효화되면 기존에 떠 있는 인스턴스에 대한 SSH 접근 자체가 통째로 불가능해진다 - 그래서 이런 계정 레벨 리소스는 전부 data 소스로만 참조하고, resource로는 이번에 새로 만들고 지울 대상(보안그룹, 인스턴스)만 선언했다.

# terraform/main.tf
# 이 랩은 기본 VPC를 그대로 쓴다. Terraform이 VPC/서브넷/키페어까지 만들지 않고
# "이미 있는 것"으로 참조만 하는 이유:
# - 기본 VPC는 AWS 계정에 이미 존재 (destroy 대상이 아님 - 실수로 계정 전체
#   네트워크를 건드리지 않게 분리)
# - 키페어(k8s-lab.pem)는 로컬에만 있는 개인키와 짝이 맞아야 하므로, Terraform이
#   새로 만들면 기존 .pem 파일이 무용지물이 됨 → 반드시 기존 키페어를 "참조"만 해야 함.
data "aws_vpc" "default" {
  default = true
}

# 인스턴스 3대가 기존에 놓였던 두 AZ(2c: CP, 2b: 워커 2대)에 맞춰 서브넷을 고른다.
data "aws_subnet" "az_2c" {
  filter {
    name   = "availability-zone"
    values = ["ap-northeast-2c"]
  }
  vpc_id = data.aws_vpc.default.id
}

data "aws_key_pair" "k8s_lab" {
  key_name = var.key_pair_name   # 기본값 "k8s-lab" - Terraform이 새로 만들지 않고 참조만
}

# Ubuntu 22.04 최신 AMI를 SSM 파라미터로 조회 (수동 조회 절차와 동일한 소스)
data "aws_ssm_parameter" "ubuntu_2204_ami" {
  name = "/aws/service/canonical/ubuntu/server/22.04/stable/current/amd64/hvm/ebs-gp2/ami-id"
}

# terraform/security_group.tf - 그날그날 하나씩 열어온 인바운드 규칙을 그대로 코드화
# (실제 계정의 sg-xxxxxxxxxxxxxxxxx 규칙을 조회해 옮김)
resource "aws_security_group" "k8s_lab" {
  name        = "k8s-lab-sg"
  description = "k8s lab"
  vpc_id      = data.aws_vpc.default.id
}

# 노드 간 통신: 전체 프로토콜, 자기 자신(같은 SG) 참조 → 쿠버네티스 노드 간 모든 통신 허용
resource "aws_vpc_security_group_ingress_rule" "node_to_node" {
  security_group_id            = aws_security_group.k8s_lab.id
  ip_protocol                  = "-1"
  referenced_security_group_id = aws_security_group.k8s_lab.id
  description                  = "node-to-node all traffic"
}

# GitHub 웹훅 수신 (Argo Events) - 발신 IP가 고정이 아니라 전체 개방 필요,
# 대신 HMAC 서명 검증으로 위조 요청 차단
resource "aws_vpc_security_group_ingress_rule" "github_webhook" {
  security_group_id = aws_security_group.k8s_lab.id
  ip_protocol       = "tcp"
  from_port         = var.webhook_nodeport
  to_port           = var.webhook_nodeport
  cidr_ipv4         = "0.0.0.0/0"
  description       = "Argo Events GitHub webhook"
}

# Jenkins UI - 빌드 실행 권한이 있어 접속자 IP만 허용 (ArgoCD/Hubble과 다른 보안 수준)
resource "aws_vpc_security_group_ingress_rule" "jenkins" {
  security_group_id = aws_security_group.k8s_lab.id
  ip_protocol       = "tcp"
  from_port         = 30880
  to_port           = 30880
  cidr_ipv4         = var.my_ip_cidr
  description       = "Jenkins UI (restricted to admin IP)"
}
# ingress-nginx/ArgoCD/Hubble UI 등 나머지 규칙도 같은 패턴으로 이어진다

# terraform/instances.tf
resource "aws_instance" "k8s_cp" {
  ami                    = data.aws_ssm_parameter.ubuntu_2204_ami.value
  instance_type          = var.cp_instance_type   # t3.medium
  subnet_id              = data.aws_subnet.az_2c.id
  key_name               = data.aws_key_pair.k8s_lab.key_name
  vpc_security_group_ids = [aws_security_group.k8s_lab.id]

  # 스팟(persistent) - 중단되면 stop, 종료 아님 (저녁마다 정지하는 운영과 호환)
  instance_market_options {
    market_type = "spot"
    spot_options {
      spot_instance_type             = "persistent"
      instance_interruption_behavior = "stop"
    }
  }

  root_block_device {
    volume_size = var.cp_root_volume_size   # 30
    volume_type = "gp3"
  }
}

variables.tf에서 한 가지 눈에 띄는 설계 포인트 - Jenkins/Argo Workflows처럼 민감한 UI에 접속을 허용할 my_ip_cidr 변수는 기본값을 아예 지정하지 않았다. 반드시 -var나 terraform.tfvars로 명시적으로 넘겨야만 apply가 되게 만들어서, "깜빡하고 0.0.0.0/0으로 열어버리는" 실수를 원천 차단한 것이다.

state 파일이 하는 역할은 이렇다 - Terraform은 .tf 코드만 보고는 "이 리소스가 실제로 이미 있는지"를 알 수 없다. terraform.tfstate에 "내가 마지막으로 만든 리소스가 무엇이었는지"를 기록해두고, 다음 실행 때 이 state와 코드를 비교해 차이만 적용한다. 이번 랩은 혼자 쓰는 학습 환경이라 로컬 state로 진행했지만, 여러 사람/여러 세션이 같은 인프라를 다룬다면 원격 백엔드(S3+DynamoDB 락)로 옮겨야 두 사람이 동시에 apply해서 state가 꼬이는 걸 막을 수 있다.

2. Ansible - 노드 프로비저닝

시리즈 1에서 손으로 했던 사전 준비(스왑 비활성화, 커널 모듈, containerd, kubeadm)와 CNI(Cilium)·스토리지(Longhorn) 설치를 플레이북으로 옮겼다.

# ansible/bootstrap.sh
# sshd의 MaxStartups(동시 미인증 연결 제한)에 걸려 간헐적으로 "Permission denied"가
# 나는 현상이 있어(연결 시도가 몰릴 때 관측됨), 위험한 호출들은 짧게 재시도한다.
ssh_retry() {
  local tries=15
  local i=1
  while [ $i -le $tries ]; do
    if ssh $SSH_OPTS "$@"; then
      return 0
    fi
    echo "  (ssh 실패, ${i}/${tries}차 재시도 대기 중...)" >&2
    sleep 5
    i=$((i + 1))
  done
  return 1
}

for ip in $WORKER_PUBLIC_IPS; do
  # ProxyJump으로 CP를 경유하면 원인 미상의 간헐적 publickey 실패가 있어(재현 어려움),
  # 워커도 공인 IP가 있으므로 로컬에서 직접 접속해 등록한다.
  cat /tmp/ansible_orchestrator.pub | ssh $SSH_OPTS ubuntu@"$ip" \
    'mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys'
done

# ansible/playbook.yml
- name: 공통 노드 준비 (모든 노드)
  hosts: all
  become: true
  tasks:
    - name: swap 비활성화
      command: swapoff -a
      when: ansible_swaptotal_mb > 0

    - name: 커널 모듈 로드 (overlay, br_netfilter)
      modprobe:
        name: "{{ item }}"
        state: present
      loop: [overlay, br_netfilter]

    - name: sysctl 파라미터 설정 (브릿지 트래픽이 iptables를 타도록)
      copy:
        dest: /etc/sysctl.d/k8s.conf
        content: |
          net.bridge.bridge-nf-call-iptables  = 1
          net.bridge.bridge-nf-call-ip6tables = 1
          net.ipv4.ip_forward                 = 1
        mode: "0644"

    - name: sysctl 즉시 적용 (핸들러는 파일이 changed일 때만 실행되어, 파일만
        쓰이고 실제 커널 파라미터는 미적용인 채로 남는 경우가 있어 항상 실행)
      command: sysctl --system
      changed_when: false

    - name: containerd 기본 설정 생성 여부 확인
      stat:
        path: /etc/containerd/config.toml
      register: containerd_config

    - name: /etc/containerd 디렉터리 생성
      file:
        path: /etc/containerd
        state: directory
        mode: "0755"
      when: not containerd_config.stat.exists

- name: 컨트롤플레인 초기화
  hosts: control_plane
  become: true
  tasks:
    - name: kubeadm init (Cilium이 kube-proxy를 대체하므로 addon/kube-proxy 스킵)
      command: >
        kubeadm init
        --skip-phases=addon/kube-proxy
        --control-plane-endpoint={{ control_plane_endpoint }}:6443
        --upload-certs
      when: not kubeadm_done.stat.exists

    - name: Cilium 설치 (kube-proxy 대체 모드 + Hubble)
      command: >
        helm install cilium cilium/cilium --version 1.16.0
        --namespace kube-system
        --set kubeProxyReplacement=true
        --set k8sServiceHost={{ control_plane_endpoint }}
        --set k8sServicePort=6443
        --set hubble.enabled=true
        --set hubble.relay.enabled=true
        --set hubble.ui.enabled=true
      when: "'STATUS: deployed' not in cilium_status.stdout"

3. Day-0 재구축 검증 (실제로 파기하고 다시 세워봤다)

코드화가 끝났다고 선언하는 대신, 라이브 클러스터(Harbor·ArgoCD·Jenkins·CNPG·Argo Workflows/Events·애플리케이션까지 전부 떠 있는 상태)를 실제로 통째로 파기하고 코드만으로 재현되는지 검증했다.

파기부터 재구축까지 전체 소요 시간을 실측했다 - 파기 시작부터 전 노드 Ready + 전 파드 Running 확인까지 약 24분이 걸렸다. kubectl get storageclass로 Longhorn StorageClass가 정상 등록된 것까지 확인했다.

이번 IaC화의 범위는 "VM 준비 → kubeadm init/join → CNI(Cilium)/스토리지(Longhorn) 설치"까지다. Harbor·ArgoCD·Jenkins·CNPG·Argo Workflows/Events와 애플리케이션 자체는 범위 밖으로 남겨뒀다 - 전부 한 번에 코드화하려다 검증 자체가 흐려지는 것보다, 가장 자주 파기·재구축하게 되는 클러스터 하단부터 확실히 코드화하는 쪽을 택했다.

검증 방법

terraform plan     # apply 없이 실행해도 diff가 없어야("No changes") IaC가 실제 상태를 정확히 반영하는 것
ansible-playbook -i inventory.ini playbook.yml --check   # dry-run으로 멱등성 확인 - 두 번째 실행부터는 변경사항이 없어야 함

체크리스트

• Terraform으로 AWS 리소스 코드화 (계정 레벨 리소스는 data로만 참조)
• Ansible로 노드 프로비저닝 자동화 (kubeadm + CNI/스토리지까지)
• Day-0 재구축 실험: 라이브 클러스터 전체 파괴 후 코드만으로 재현 (~24분)
• 재구축 중 사람이 개입해야 했던 지점 목록화 (7가지, 그중 2가지는 플레이북 수정으로 해소)
• Harbor/ArgoCD/Jenkins/CNPG/Argo Workflows·Events 및 앱 자체의 IaC화 (범위 밖, 후속 과제)