이 문서는 연구실 운영 클러스터에 처음 들어오는 사람이 k3s, 쿠버네티스 리소스, GitOps 배포 흐름이 어떻게 연결되는지 빠르게 잡기 위한 입문 가이드다.
k3s 기반 쿠버네티스 클러스터 위에서 동작한다.namespace, deployment, service, ingress, secret 같은 쿠버네티스 리소스로 표현된다.gitops 레포이고, ArgoCD가 그 레포를 읽어 클러스터를 원하는 상태로 수렴시킨다.즉 초보자가 먼저 잡아야 하는 순서는 클러스터 구조 -> GitOps 반영 단위 -> 인프라 계층 -> 서비스 계층이다.
이 문서는 입문자가 아래 질문에 답할 수 있게 만드는 것이 목적이다.
k3s와 쿠버네티스는 이 운영 환경에서 어떤 관계인가ArgoCD app, namespace, overlay, base는 각각 무엇을 뜻하는가실제 접속, 명령 실행, 배포 확인, 되돌리기 같은 절차는 Manual에서 관리한다.
ArgoCD app으로 관리된다.overlays/prod 같은 위치가 최종 반영 기준이 된다.| 헷갈리는 것 | 실제 의미 |
|---|---|
ArgoCD app 이름 |
GitOps 동기화 단위다 |
namespace 이름 |
쿠버네티스 리소스가 실제로 실행되는 위치다 |
overlay |
환경별 최종 조합이다 |
base |
환경 공통 리소스다 |
OutOfSync |
Git 기준과 live 리소스가 다르다는 뜻이지 즉시 장애라는 뜻은 아니다 |
Degraded |
현재 live 상태가 기대한 상태로 수렴하지 않았다는 신호다 |
앱 문제가 보여도 초보자는 바로 애플리케이션 코드부터 보지 않는 편이 좋다.
먼저 아래 순서로 구조를 본다.
이 순서가 중요한 이유는, 많은 장애가 애플리케이션 코드보다 배포 계층이나 실행 의존성 계층에서 먼저 드러나기 때문이다.
GitOps 레포는 현재 운영이 어떤 상태로 선언돼 있는지 확인하는 기준이다.
초보자가 레포를 볼 때는 아래 수준만 먼저 이해하면 충분하다.
| 경로 축 | 의미 |
|---|---|
terraform/cluster |
클러스터 생성과 초기 bootstrap 관점 |
k8s/bootstrap/argocd |
ArgoCD가 어디서 시작되는지 보는 관점 |
k8s/clusters/... |
특정 클러스터에 어떤 애플리케이션을 올릴지 보는 관점 |
k8s/infra/... |
ingress, monitoring, infisical, observability 같은 공통 인프라 관점 |
k8s/apps/... |
서비스별 매니페스트와 overlay 관점 |
즉 서비스 하나를 이해하려면 보통 clusters에서 app을 찾고, 거기서 apps/.../overlays/...로 내려가는 흐름을 따르면 된다.
서비스는 보통 아래 단위로 이해하면 된다.
따라서 서비스 이름 -> ArgoCD app -> namespace -> overlay 순서로 관계를 잡아두면 이후 문서를 읽기 쉬워진다.
초보자 기준 최소한 아래 정도의 역할 구분은 알고 시작하면 된다.
| 스택 | 왜 필요한가 |
|---|---|
| ingress-nginx | 외부 HTTP 요청을 클러스터 서비스로 보낸다 |
| monitoring | 메트릭과 대시보드를 본다 |
| infisical | 운영 시크릿을 중앙에서 관리한다 |
| infisical-operator | 시크릿을 쿠버네티스 실행 환경으로 전달한다 |
| observability | 로그와 트레이스를 수집하고 조회한다 |
각 스택의 세부 구조와 운영 관점은 해당 가이드 문서에서 따로 읽는 편이 좋다.
입문자는 보통 아래 순서로 이어서 보면 된다.
k3s와 쿠버네티스의 관계를 먼저 이해한다.GitOps와 ArgoCD가 어떤 단위로 상태를 맞추는지 본다.Infisical, Monitoring, Observability처럼 공통 인프라 역할을 본다.즉 이 문서는 "지도를 펴는 문서"이고, 실제 작업 문서는 별도 가이드와 매뉴얼에서 이어진다.