Ansible

목적

Ansible은 원시 OCI 인스턴스와 GitOps로 관리되는 클러스터 사이에 놓인 Lumie의 가변 부트스트랩 계층입니다. 이 페이지는 Argo CD가 제어권을 넘겨받기 전에 수행되는 플레이북, 역할, inventory 생성, 부트스트랩 부작용을 위한 레퍼런스 문서입니다.

소스 경로

경로	역할
lumie-infra/provision/ansible/ansible.cfg	런타임 기본값, SSH 동작, 역할 경로, 병렬성
lumie-infra/provision/ansible/inventory/terraform_inventory.py	terraform output -json 기반 동적 inventory 생성기
lumie-infra/provision/ansible/group_vars/*.yml	K3s 버전, master URL, 노드 그룹화, 공통 기본값
lumie-infra/provision/ansible/playbooks/site.yml	전체 end-to-end 클러스터 부트스트랩
lumie-infra/provision/ansible/roles/common/tasks/main.yml	OS 준비, iptables 초기화, 커널 모듈, sysctl
lumie-infra/provision/ansible/roles/storage-setup/tasks/main.yml	MinIO 블록 디바이스 포맷 및 마운트
lumie-infra/provision/ansible/roles/k3s-master/tasks/main.yml	K3s 서버 설치와 토큰 내보내기
lumie-infra/provision/ansible/roles/k3s-worker/tasks/main.yml	K3s 에이전트 조인 흐름
lumie-infra/provision/ansible/roles/argocd-bootstrap/tasks/main.yml	Helm 설치, 부트스트랩 시크릿, Git clone, 루트 앱 적용
lumie-infra/provision/ansible/playbooks/fetch-kubeconfig.yml	운영자용 kubeconfig 내보내기

진입점

운영자가 다루는 주 표면은 다음 플레이북 세트입니다.

플레이북	목적
playbooks/site.yml	전체 부트스트랩: 준비, 마스터, 스토리지, 워커, 검증, Argo CD
playbooks/k3s-master.yml	마스터 전용 설치
playbooks/k3s-workers.yml	이미 마스터가 존재하는 상태에서 워커만 롤아웃
playbooks/fetch-kubeconfig.yml	퍼블릭/프라이빗 kubeconfig를 로컬에 저장
playbooks/k3s-reset.yml	모든 노드에서 K3s를 파괴적으로 제거

site.yml이 권위 있는 순서입니다.

- name: Prepare all nodes
- name: Install K3s Master
- name: Setup storage partitions on workers
- name: Install K3s Workers (Account 0214)
- name: Install K3s Workers (Account 0213)
- name: Verify cluster
- name: Bootstrap ArgoCD and GitOps

런타임 흐름

인벤토리 계약

inventory/terraform_inventory.py는 Terraform과 Ansible 사이의 브리지입니다.

• terraform output -json을 셸로 호출합니다.
• masters, workers_0214, workers_0213 그룹을 구성합니다.
• ansible_host, private_ip, k3s_master_url을 주입합니다.
• 복사된 정적 파일이 아니라 실제 master private IP에서 워커 join 대상을 도출합니다.

즉, Ansible 부트스트랩은 암묵적으로 성공적이고 최신의 Terraform apply에 의존합니다.

역할 동작

common

common role은 의도적으로 기본 OS 상태를 정규화합니다.

• cloud-init 완료 대기
• iptables, netfilter-persistent, open-iscsi를 포함한 패키지 설치
• 기본 iptables 체인 정책을 모두 ACCEPT로 설정
• 기존 iptables 규칙 flush
• br_netfilter와 overlay 로드
• K3s 관련 sysctl 적용

이는 일반적인 애플리케이션 부트스트랩보다 더 침습적입니다. 해당 노드가 전용 클러스터 호스트라는 전제를 둡니다.

storage-setup

스토리지 role은 /dev/sdb를 ext4로 포맷하고, 호스트별로 minio-<hostname> 라벨을 부여한 뒤 /mnt/minio-data에 마운트합니다. 라벨 기반 마운트가 멱등성 가드 역할을 하므로, 올바르게 라벨링되고 마운트된 디스크를 다시 실행해도 재포맷하지 않습니다.

k3s-master

master role은 다음을 수행합니다.

• 필요할 때만 get.k3s.io 다운로드
• /etc/rancher/k3s/registries.yaml 템플릿 생성
• K3s 서버 설치
• 로컬 API와 노드 토큰 대기
• 워커 조인에 사용할 수 있도록 토큰을 Ansible fact로 읽기

k3s-worker

워커 role은 다음을 수행합니다.

• 토큰 읽기를 master에 위임
• 10.0.0.241:6443의 TCP 도달 가능 여부 대기
• k3s-agent 설치
• master에서 kubectl get nodes에 해당 워커가 나타날 때까지 대기

플레이북은 각 계정 그룹 내 워커를 직렬로 적용해 레이스 조건을 줄이고 장애 지점을 더 쉽게 특정할 수 있게 합니다.

argocd-bootstrap

이 부트스트랩 role은 GitOps 이전 마지막 명령형 단계를 수행합니다.

1. 필요 시 Helm 설치
2. argocd, minio, vault 네임스페이스 생성
3. minio-root-password와 vault-config-secret 생성
4. 최소 부트스트랩 values 파일로 Helm에서 Argo CD 설치
5. lumie-infra를 /tmp로 clone
6. 구성된 루트 앱 매니페스트 적용

부트스트랩 values는 첫 설치를 위해 의도적으로 익명 Argo CD 접근을 활성화합니다. 그 이후에는 Git으로 관리되는 Argo CD 구성이 이 부트스트랩 상태를 대체해야 합니다.

Kubeconfig 내보내기

fetch-kubeconfig.yml은 master의 /etc/rancher/k3s/k3s.yaml을 읽어 다음 파일을 작성합니다.

• master 퍼블릭 IP를 가리키는 k3s-public.yaml
• master 프라이빗 IP를 가리키는 k3s-private.yaml
• 퍼블릭 변형본을 가리키는 심볼릭 링크 config

이를 통해 서버 로컬 127.0.0.1 kubeconfig를 재사용하지 않고 운영자 로컬 접근을 명시적으로 제공합니다.

계약 드리프트

검사된 불일치 두 가지가 중요합니다.

• roles/argocd-bootstrap/defaults/main.yml에는 여전히 app_of_apps_paths에 web-apps/application.yaml이 포함되어 있지만, 현재 저장소에는 lumie-infra/web-apps/가 존재하지 않습니다. 부트스트랩 role을 새로 다시 실행하려면 먼저 이 경로를 수정해야 합니다.
• provision/ansible/README.md는 여전히 Traefik이 비활성화된다고 말하지만, 실제 server role은 이를 비활성화하지 않으며 2026년 6월 14일에 확인한 라이브 클러스터에는 번들 Traefik addon이 실행 중입니다.

장애 지점

장애 지점	영향
Terraform 출력값이 오래되었거나 없음	어떤 호스트 작업도 시작하기 전에 동적 inventory 생성 실패
k3s_master_private_ip가 잘못됨	SSH는 되더라도 워커 join 대기가 타임아웃됨
워커에 /dev/sdb가 없음	워커 롤아웃이 계속되기 전에 storage role이 즉시 실패
Vault 시크릿 부트스트랩 누락	Vault가 S3 백엔드 설정으로 시작하지 못해 하위 VaultStaticSecret 소비자를 막음
루트 앱 경로 누락	초기 앱 적용 중 Argo CD 부트스트랩 실패

검증

inventory와 연결성:

cd lumie-infra/provision/ansible
./inventory/terraform_inventory.py --list | jq .
ansible all -i inventory/terraform_inventory.py -m ping

부트스트랩 로직 dry-run:

ansible-playbook -i inventory/terraform_inventory.py playbooks/site.yml --check

실제 실행 후 라이브 클러스터 확인:

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

성공 신호:

• ./inventory/terraform_inventory.py --list에 masters, workers_0214, workers_0213 그룹과 k3s_master_url이 포함됩니다.
• ansible all ... -m ping이 생성된 inventory의 모든 호스트에 대해 SUCCESS를 반환합니다.
• ansible-playbook ... playbooks/site.yml --check가 현재 부트스트랩 계약에서 실패한 호스트 없이 PLAY RECAP에 도달합니다.
• 실제 실행 후 kubectl get nodes -o wide는 조인된 워커를 보여주고, kubectl get applications -n argocd는 argocd-bootstrap이 생성한 루트 GitOps 앱을 보여줍니다.