[k8s] K3s와 AWX 통합 사례 연구: 경량 Kubernetes 자동화 워크플로우 구축

목차

• K3s와 AWX, 왜 이 조합일까요?
• K3s: 가볍지만 강력한 경량 Kubernetes
• AWX: Ansible 자동화 플랫폼의 중앙 허브
• 통합의 시너지: 경량 K3s 위의 자동화 플랫폼
• 실전 구현: K3s 위에 AWX 배포하기
• 1. AWX Operator 설치
• 2. AWX 인스턴스 배포
• ⚠️ 삽질 경험과 트러블슈팅
• 1. 리소스 부족 문제
• 2. Persistent Volume(영구 볼륨) 설정
• 3. Ingress(인그레스) 접근 문제
• 검증 및 결과: AWX로 K3s 자동화하기
• 마무리: 경량 Kubernetes 자동화, 여러분도 해보세요!

안녕하세요, 13년차의 서버실입니다. 오늘은 제가 홈랩에서 직접 경험하고 삽질하면서 얻은 지식 하나를 여러분과 공유해볼게요. 바로 K3s(케이쓰리쓰)와 AWX(에이더블유엑스)를 통합하여 경량 Kubernetes(쿠버네티스) 환경에서 자동화 워크플로우를 구축하는 사례입니다.

작은 규모의 인프라나 홈랩에서 Kubernetes를 운영하다 보면, 리소스 제약 때문에 고민이 많아지죠. 게다가 반복적인 배포나 설정 변경 작업을 수동으로 하다 보면 시간 낭비는 물론이고 휴먼 에러 발생 확률도 높아지고요. 저도 "이걸 어떻게 하면 좀 더 효율적으로 관리할 수 있을까?" 하는 고민에 빠져있었거든요. 그러다가 경량 Kubernetes인 K3s와 Ansible(앤서블) 기반의 자동화 플랫폼인 AWX의 조합을 떠올리게 됐습니다.

이 둘을 잘 엮으면 리소스 효율적인 환경에서 강력한 자동화 시스템을 만들 수 있겠다는 확신이 들었죠. 그래서 직접 부딪혀가며 구축해봤고, 그 과정과 삽질 경험을 솔직하게 풀어보려 합니다. 혹시 여러분도 비슷한 고민을 하고 계셨다면, 이 글이 좋은 가이드가 될 수 있을 거예요. 💡

K3s 클러스터 위에 AWX가 배포되어 외부 Git 리포지토리의 Ansible 플레이북을 가져와 다른 K3s/Kubernetes 클러스터에 배포하는 통합 아키텍처 다이어그램입니다.

K3s와 AWX, 왜 이 조합일까요?

먼저, 이 두 가지 기술이 무엇인지, 그리고 왜 함께 사용하면 시너지가 나는지 간단하게 짚고 넘어가겠습니다.

K3s: 가볍지만 강력한 경량 Kubernetes

K3s(케이쓰리쓰)는 Rancher Labs(랜처 랩스)에서 만든 경량 Kubernetes(쿠버네티스) 배포판입니다. 이름에서 알 수 있듯이 'K8s(케이츠) - 5 = K3s'라는 유머러스한 의미를 가지고 있어요. 그만큼 바이너리 크기가 작고, 메모리 사용량도 적으니까요. 일반적인 Kubernetes는 컨트롤 플레인(Control Plane) 구성 요소들이 많은 리소스를 요구하는데, K3s는 SQLite를 기본 데이터베이스로 사용하고 불필요한 기능을 제거해서 엣지 컴퓨팅(Edge Computing), IoT(사물 인터넷), 또는 저사양 환경에 정말 딱 맞습니다. 제가 홈랩에서 운영하는 라즈베리 파이(Raspberry Pi) 클러스터 같은 곳에 정말 찰떡이더라고요. ✅

AWX: Ansible 자동화 플랫폼의 중앙 허브

AWX(에이더블유엑스)는 Red Hat(레드햇)의 Ansible Tower(앤서블 타워)의 오픈소스 업스트림 프로젝트입니다. Ansible(앤서블)은 강력한 IT 자동화 도구인데, AWX는 이 Ansible 플레이북(Playbook)들을 웹 UI를 통해 중앙에서 관리하고 실행할 수 있게 해줍니다. 그냥 복잡한 커맨드 라인(Command Line) 없이도 프로젝트, 인벤토리(Inventory), 자격 증명(Credential) 등을 관리하고, 잡 템플릿(Job Template)을 만들어 반복적인 작업을 예약하거나 실행 결과를 쉽게 확인할 수 있죠. 특히 팀 단위로 자동화 작업을 공유하고 접근 제어를 해야 할 때 진짜 빛을 발합니다. 🎉

통합의 시너지: 경량 K3s 위의 자동화 플랫폼

저는 K3s의 가벼움 위에 AWX를 올려서 경량 Kubernetes 환경을 위한 자동화 허브를 구축하고 싶었습니다. K3s에서 돌아가는 애플리케이션의 배포나 설정을 AWX를 통해 관리하려는 거였거든요. 예를 들어, 새로운 컨테이너 이미지를 빌드하면 AWX가 자동으로 K3s 클러스터에 배포하도록 하거나, 특정 서비스의 스케일링(Scaling) 작업을 AWX 잡 템플릿으로 만들어서 필요할 때마다 클릭 한 번으로 실행하는 식입니다. 이렇게 하면 인프라 관리가 정말 수월해지더라고요. 💡

실전 구현: K3s 위에 AWX 배포하기

이제 제가 직접 K3s 클러스터에 AWX를 배포했던 과정을 단계별로 설명해 드릴게요. 저는 이미 K3s 클러스터가 구성되어 있다는 가정하에 진행했습니다. 아직 K3s 설치가 안 되어 있다면, 다음 명령어로 간단하게 설치할 수 있습니다.

curl -sfL https://get.k3s.io | sh -

1. AWX Operator 설치

AWX는 Kubernetes 환경에 AWX Operator(오퍼레이터)를 통해 배포하는 것이 가장 일반적입니다. Operator는 특정 애플리케이션(여기서는 AWX)을 Kubernetes의 컨트롤러처럼 관리해주는 도구라고 생각하시면 돼요. 배포부터 업데이트, 스케일링까지 알아서 처리해주니까요.

AWX Operator를 설치하려면 공식 AWX Operator 저장소에서 최신 설치 가이드를 확인하시고, 다음 명령어로 설치합니다.

kubectl apply -f https://raw.githubusercontent.com/ansible/awx-operator/devel/deploy/operator.yaml

이 명령어가 AWX Operator와 필요한 CRD(Custom Resource Definition, 사용자 정의 리소스 정의)를 모두 설치해줍니다. CRD는 Kubernetes가 AWX라는 새로운 리소스 타입을 이해할 수 있도록 해주는 설정 파일이거든요. 이 과정을 거치면 awx-operator 파드(Pod)가 실행되면서 AWX 인스턴스를 배포할 준비가 완료됩니다.

2. AWX 인스턴스 배포

Operator가 준비되었다면, 이제 우리가 원하는 AWX 인스턴스를 생성할 차례입니다. AWX라는 Custom Resource(CR) 객체를 생성하면, Operator가 이 CR을 감지하고 실제 AWX 애플리케이션을 배포해줍니다. 저는 awx.yaml이라는 파일을 만들어서 다음과 같이 설정했습니다.

apiVersion: awx.ansible.com/v1beta1
kind: AWX
metadata:
  name: my-awx
spec:
  # AWX Operator가 배포할 AWX 인스턴스의 이름
  # 여기서는 my-awx로 지정했습니다.

  # ingressType: Ingress를 사용하여 Kubernetes Ingress를 통해 AWX에 접근하도록 설정합니다.
  # K3s는 기본적으로 Traefik Ingress Controller를 포함하고 있어 편리합니다.
  ingressType: Ingress
  # ingress_host: AWX에 접근할 호스트 이름을 지정합니다.
  # 실제 환경에서는 DNS에 이 호스트를 등록해야 합니다.
  ingress_host: awx.myhomelab.local
  
  # 기타 설정 (필요에 따라 주석 해제 및 수정)
  # postgres_storage_class: AWX 데이터베이스를 위한 Persistent Volume Claim(PVC)의 StorageClass를 지정합니다.
  # 홈랩 환경에서는 hostPath나 local-storage 등을 사용할 수 있습니다.
  # postgres_storage_class: standard
  
  # web_extra_volume_mounts: AWX 웹 파드에 추가 볼륨을 마운트할 때 사용합니다.
  # e.g., 인증서 마운트 등
  # tasks_extra_volume_mounts: AWX 태스크 파드에 추가 볼륨을 마운트할 때 사용합니다.
  
  # image_version: 사용할 AWX 이미지 버전 (특정 버전을 고정할 경우)
  # image_version: "23.3.0"
  
  # resource_requirements: AWX 파드들의 리소스 요청/제한을 설정합니다.
  # 작은 환경에서는 이 부분을 적절히 조절해야 합니다.
  # web_resource_requirements:
  #   requests:
  #     cpu: 500m
  #     memory: 1Gi
  #   limits:
  #     cpu: 1000m
  #     memory: 2Gi

이 파일을 저장하고 kubectl apply -f awx.yaml 명령어를 실행하면 AWX Operator가 AWX 인스턴스에 필요한 Deployment(디플로이먼트), Service(서비스), Ingress(인그레스), Persistent Volume Claim(PVC) 등을 자동으로 생성하기 시작합니다.

AWX 웹 UI의 로그인 화면 또는 kubectl get pods -n awx 명령어를 실행했을 때 AWX 관련 파드들이 모두 Running 상태인 것을 보여주는 스크린샷입니다.

⚠️ 삽질 경험과 트러블슈팅

제가 이 과정을 진행하면서 겪었던 몇 가지 삽질 경험과 해결 방법을 공유합니다. 여러분은 저처럼 헤매지 않으시길 바라요! 😂

1. 리소스 부족 문제

K3s는 가볍지만, AWX는 생각보다 많은 리소스를 필요로 합니다. 특히 데이터베이스(PostgreSQL)와 웹, 태스크 파드들이 동시에 돌아가기 때문에, 2GB RAM 이하의 시스템에서는 버벅이거나 파드가 계속 재시작되는 문제가 발생할 수 있어요. 최소 4GB RAM, 2코어 CPU 이상을 권장합니다. 저도 처음엔 라즈베리 파이 4(4GB 모델)에서 돌렸는데, 다른 서비스들과 함께 돌리니 정말 아슬아슬하더라고요. 결국 8GB 모델로 업그레이드하거나, AWX 전용 노드를 따로 두는 것을 고려하게 됐습니다.

해결책: awx.yaml 파일의 resource_requirements 섹션을 통해 각 파드의 리소스 요청(requests)과 제한(limits)을 조절할 수 있습니다. 하지만 너무 낮추면 성능 문제가 발생하니, 하드웨어 사양을 충분히 확보하는 것이 최고의 방법입니다.

2. Persistent Volume(영구 볼륨) 설정

AWX는 데이터베이스(PostgreSQL)와 작업 실행 로그 등을 저장하기 위해 Persistent Volume(PV, 영구 볼륨)이 필요합니다. K3s는 기본적으로 local-path-provisioner(로컬 패스 프로비저너)를 내장하고 있어서 별도의 StorageClass(스토리지 클래스) 설정 없이도 PVC(Persistent Volume Claim)를 생성하면 자동으로 PV가 프로비저닝(Provisioning)됩니다. 하지만 이 방식은 특정 노드에 데이터가 종속되기 때문에 노드 장애 시 데이터 손실 위험이 있습니다.

해결책: 홈랩 환경에서는 간단하게 hostPath 타입을 사용하여 특정 경로에 데이터를 저장할 수 있지만, 좀 더 안정적인 환경을 원한다면 NFS(네트워크 파일 시스템) 서버를 구축하고 NFS CSI Driver(드라이버)를 설치하여 공유 스토리지를 사용하는 것이 좋습니다. 저도 NFS를 사용해서 여러 노드에서 AWX 파드들이 유연하게 움직일 수 있도록 구성했거든요.

3. Ingress(인그레스) 접근 문제

ingress_host를 설정했지만, 웹 브라우저에서 접속이 안 되는 경우가 있었습니다. K3s는 기본적으로 Traefik(트래픽) Ingress Controller(인그레스 컨트롤러)를 내장하고 있어 편리합니다. 하지만 제 경우에는 다음과 같은 문제가 있었습니다.

• DNS 설정: awx.myhomelab.local과 같은 호스트 이름을 사용하려면, 홈랩 내 DNS 서버에 해당 호스트를 등록하거나, 접속하려는 PC의 /etc/hosts (Linux/macOS) 또는 C:\Windows\System32\drivers\etc\hosts (Windows) 파일에 IP 주소와 호스트 이름을 직접 매핑해주어야 합니다.

  # /etc/hosts 예시
  192.168.1.100 awx.myhomelab.local # K3s 마스터 노드의 IP 주소

• Traefik 설정: 가끔 Traefik이 외부 트래픽을 제대로 라우팅(Routing)하지 못하는 경우가 있는데, K3s 설치 시 Traefik 관련 옵션을 확인하거나, Traefik 대시보드(보통 http://<k3s_master_ip>:8080/dashboard/)에서 Ingress Route(인그레스 라우트)가 제대로 생성되었는지 확인해야 합니다.

해결책: 저는 /etc/hosts 파일을 수정하고, kubectl get ingress -n awx 명령어로 AWX Ingress 리소스가 정상적으로 생성되었는지 확인하면서 문제를 해결했습니다.

검증 및 결과: AWX로 K3s 자동화하기

여러 삽질 끝에 드디어 AWX가 K3s 클러스터 위에 성공적으로 배포되었습니다! 🎉 이제 웹 브라우저를 열고 설정했던 ingress_host로 접속하면 AWX 로그인 화면이 보일 겁니다. 초기 관리자 비밀번호는 AWX Operator가 Secret(시크릿)으로 생성해두는데, 다음 명령어로 확인할 수 있습니다.

kubectl get secret my-awx-admin-password -o jsonpath='{.data.password}' | base64 --decode

로그인 후, 저는 간단한 Ansible 플레이북을 만들어서 K3s 클러스터의 노드 목록을 조회하는 작업을 자동화해봤습니다. AWX에서 Project(프로젝트), Inventory(인벤토리), Credential(자격 증명)을 설정하고 Job Template(잡 템플릿)을 생성한 뒤 실행하니, 깔끔하게 K3s 노드 정보가 출력되는 것을 확인할 수 있었습니다. 이 화면을 보는 순간, 그동안의 고생이 눈 녹듯 사라지더라고요! 정말 뿌듯했어요. 😄

AWX 웹 UI에서 Ansible 플레이북이 성공적으로 실행되어 K3s 클러스터의 노드 목록을 출력하는 잡 실행 결과 화면 스크린샷입니다. 초록색 성공 메시지와 함께 결과가 표시됩니다.

마무리: 경량 Kubernetes 자동화, 여러분도 해보세요!

K3s와 AWX를 통합하여 경량 Kubernetes 환경에서 자동화 워크플로우를 구축한 경험은 저에게 정말 값진 시간이었습니다. 비록 중간중간 삽질도 많이 했지만, 그 과정에서 얻은 지식과 해결 능력은 어떤 책에서도 배울 수 없는 것이었거든요.

주요 배운 점:

• K3s는 가볍지만, AWX처럼 리소스를 많이 쓰는 애플리케이션을 올릴 때는 충분한 하드웨어 리소스 계획이 필요하다는 것.
• Persistent Volume 설정은 안정적인 운영을 위한 핵심이라는 것. (홈랩이라도 NFS는 정말 중요합니다.)
• Kubernetes Ingress와 DNS 설정은 항상 꼼꼼하게 확인해야 한다는 것.
• AWX Operator를 사용하면 복잡한 AWX 배포를 Kubernetes 스타일로 정말 간단하게 할 수 있다는 것.

이 조합은 특히 저처럼 홈랩을 운영하거나, 소규모 팀에서 효율적인 인프라 자동화를 목표로 할 때 정말 강력한 솔루션이 될 수 있다고 확신합니다. 여러분도 직접 K3s와 AWX를 설치하고 이것저것 만져보면서 자신만의 자동화 워크플로우를 구축해보시길 강력히 추천합니다. 직접 해보면서 얻는 경험만큼 값진 건 없으니까요! 💪

다음 글에서는 AWX를 이용한 좀 더 복잡한 GitOps(깃옵스) 파이프라인 구축에 대해 더 깊이 다뤄볼 예정입니다. 기대해주세요! 😄

K3s와 AWX 통합의 주요 장점 (예: 리소스 효율성, 중앙 집중식 자동화, 빠른 배포, 간편한 관리)을 시각적으로 요약한 인포그래픽입니다.

📚 함께 읽으면 좋은 글

• Kubernetes Operator 활용 사례: 데이터베이스 관리 자동화로 운영 효율 높이기
• Helm 차트 관리의 진화: GitOps 시대의 베스트 프랙티스 분석
• AWX로 쿠버네티스 워크플로우 자동화: 실전 가이드