ArgoCD를 라즈베리파이 k3s 클러스터에 설치하고 운영하기

이번 학습에서는 ArgoCD를 라즈베리파이 k3s 클러스터에 설치하고, GitOps 워크플로우를 통해 애플리케이션을 배포하는 과정을 실습했습니다. SSH 터널링, kubectl 포트 포워딩, 서비스 라우팅 등 여러 네트워킹 개념과 함께 ArgoCD의 핵심 원리를 파악할 수 있었습니다.

학습 주제

• 공부 주제: ArgoCD 설치 및 GitOps 기반 애플리케이션 배포
• 대화 제목: ArgoCD 실습_SSH 터널링_kubectl 포트 포워딩_svc 라우팅
• 학습 날짜: 2026년 2월 15일

질문과 탐구

학습은 실제 환경 구축부터 시작했습니다. 라즈베리파이에 이미 설치된 k3s 클러스터를 기반으로 ArgoCD를 설치하고, Git 저장소와 연동하여 애플리케이션을 배포하는 과정을 진행하며 다음과 같은 질문과 탐구를 이어갔습니다.

• ArgoCD를 로컬 환경(라즈베리파이 k3s)에 설치하는 방법은 무엇인가?
• SSH 터널링과 kubectl 포트 포워딩은 어떻게 작동하며, 왜 필요한가?
• ArgoCD는 Git 저장소의 매니페스트를 어떻게 인식하고 클러스터에 적용하는가?
• Kustomize는 무엇이며, ArgoCD와 어떻게 연동되는가?
• --dest-server, --dest-namespace 등의 옵션은 어떤 역할을 하는가?
• 포트 번호(8081, 443, 8080, 8083)가 어떻게 연결되고 트래픽이 흐르는가?
• Service, Pod, CRD는 무엇인가?

핵심 학습 내용

1. ArgoCD 설치 및 기본 설정

• 라즈베리파이 k3s 클러스터 준비: SSH로 라즈베리파이에 접속하여 k3s 클러스터 상태를 확인하고, ArgoCD 설치를 위한 argocd 네임스페이스를 생성했습니다.
• ArgoCD 컴포넌트 설치: kubectl apply 명령어를 사용하여 ArgoCD의 다양한 컴포넌트(server, controller, repo-server 등)를 클러스터에 배포했습니다. 이 과정에서 CustomResourceDefinition(CRD)이 생성되어 ArgoCD의 Application 리소스를 쿠버네티스에서 관리할 수 있게 됩니다.
• 초기 관리자 암호 획득: argocd-initial-admin-secret에서 초기 관리자 암호를 추출하여 admin 계정으로 로그인할 준비를 했습니다.
• ArgoCD CLI 설치: 라즈베리파이의 ARM 아키텍처에 맞는 argocd-linux-arm64 바이너리를 다운로드하여 CLI 환경을 구축했습니다.

2. GitOps 워크플로우 구현

• Git 저장소 연결: 공개 GitHub 리포지토리(k8s-manifests)를 ArgoCD에 연결했습니다. base 디렉토리를 경로로 지정하여 기본적인 쿠버네티스 매니페스트를 사용했습니다.
• Kustomize 자동 감지: base 디렉토리에 kustomization.yaml 파일이 존재하는 것을 ArgoCD가 자동으로 감지하여 Kustomize 빌드를 수행했습니다.
• 애플리케이션 생성 및 동기화: argocd app create 명령어로 애플리케이션 리소스를 생성하고, argocd app sync 명령어로 Git 저장소의 상태를 클러스터에 동기화했습니다. 이 과정에서 OutOfSync 상태가 Synced 상태로 변경되는 것을 확인했습니다.
• 프로덕션 환경 배포: overlays/prod-blog 디렉토리를 사용하여 별도의 Application 리소스를 생성했습니다. 이 과정에서 namespace: production, namePrefix: prod-, replicas, images 등의 Kustomize 규칙이 적용되어 기본 매니페스트와는 다른 설정으로 배포되는 것을 확인했습니다.

3. 네트워킹 및 포트 이해

• Port-forwarding: kubectl port-forward 명령어를 사용하여 ArgoCD 서버의 내부 포트(8080 또는 8083)를 라즈베리파이의 외부 노출 포트(8081)로 매핑했습니다.
• SSH 터널링: ssh -L 옵션을 사용하여 외부 노트북과 라즈베리파이 간의 안전한 터널을 구축했습니다. 이 터널을 통해 노트북의 8081 포트로 들어오는 요청이 라즈베리파이의 8081 포트로 전달되도록 했습니다.
• 트래픽 흐름: 사용자 노트북의 8081 포트 → SSH 터널 → 라즈파이의 8081 포트 → kubectl port-forward → Service의 443 포트 → Service의 내부 라우팅(443/80 → 8080/8083) → ArgoCD Pod의 8080 또는 8083 포트 순서로 트래픽이 흐르는 것을 이해했습니다.

이해한 내용

• GitOps 핵심: Git 저장소가 "단일 진실의 원천(Single Source of Truth)"이 되며, ArgoCD는 Git의 상태를 클러스터에 지속적으로 적용하는 역할을 합니다.
• Kustomize의 유연성: Base 매니페스트를 두고 overlays를 통해 환경별(dev, prod 등) 설정을 분기하여 관리하는 것이 매우 효율적임을 알게 되었습니다.
• 네트워킹의 중요성: 클러스터 외부에서 내부 Pod에 접근하기 위해 port-forward와 SSH 터널링의 조합이 필수적이며, 각 단계별 포트와 프로토콜의 역할을 명확히 이해하게 되었습니다.
• CRD의 역할: ArgoCD가 Application이라는 새로운 리소스를 정의하기 위해 CRD를 사용하는 방식을 이해했습니다.

실전 적용

• 다중 환경 관리: overlays 기능을 활용하여 개발, 스테이징, 프로덕션 환경별로 다른 설정을 적용하는 애플리케이션을 배포할 수 있습니다.
• 자동화된 CI/CD 파이프라인 구축: Git push 이벤트에 ArgoCD의 Auto-sync 또는 Webhook 기능을 연동하여 완전 자동화된 배포 파이프라인을 구축할 수 있습니다.
• 클러스터 간 배포: --dest-server 옵션을 활용하여 여러 쿠버네티스 클러스터에 동일한 애플리케이션을 배포하고 관리할 수 있습니다.
• 기존 Git Repo 활용: 이미 운영 중인 프로젝트의 쿠버네티스 매니페스트를 ArgoCD에 연결하여 GitOps 워크플로우로 전환할 수 있습니다.

추가 학습 계획

• Auto-Sync 및 Self-Heal: Git 변경 시 자동으로 동기화되는 Auto-Sync 기능과, 수동으로 변경된 리소스를 자동으로 복구하는 Self-Heal 기능에 대해 더 깊이 학습하고 적용해볼 계획입니다.
• ApplicationSet: 여러 애플리케이션을 동시에 관리하고 프로비저닝하는 ApplicationSet에 대해 알아보고 실습할 예정입니다.
• Sync Strategies: Blue/Green, Canary 등 고급 동기화 전략을 적용하여 서비스 무중단 배포를 구현하는 방법을 공부하고 싶습니다.
• ArgoCD 보안: RBAC, SSO 연동 등 ArgoCD의 보안 설정을 강화하는 방법을 학습할 계획입니다.

참고 자료

• Argo CD 공식 문서: ArgoCD의 모든 기능과 설정에 대한 상세한 정보를 제공합니다.
• Kubernetes 공식 문서: Kubernetes의 Service, Pod, CRD 등 기본 개념에 대한 이해를 돕습니다.