이 문서는 연구실 운영 클러스터에 처음 들어오는 사람이 k3s, 쿠버네티스 리소스, GitOps 배포 흐름이 어떻게 연결되는지 빠르게 잡기 위한 입문 가이드다.

운영용 비밀번호, 시크릿 값, 개인 접속 정보는 이 문서에 적지 않는다. 민감한 값은 별도 보안 채널에서 관리하고, 여기에는 구조와 확인 관점만 남긴다.

먼저 잡을 그림

연구실 서비스는 k3s 기반 쿠버네티스 클러스터 위에서 동작한다.
클러스터 상태는 namespace, deployment, service, ingress, secret 같은 쿠버네티스 리소스로 표현된다.
실제 반영 기준은 gitops 레포이고, ArgoCD가 그 레포를 읽어 클러스터를 원하는 상태로 수렴시킨다.
인프라 계층은 ingress, 모니터링, 시크릿 관리, 관측성을 먼저 올리고, 그 위에 서비스가 각 namespace에서 동작한다.

즉 초보자가 먼저 잡아야 하는 순서는 클러스터 구조 -> GitOps 반영 단위 -> 인프라 계층 -> 서비스 계층이다.

이 문서의 역할

이 문서는 입문자가 아래 질문에 답할 수 있게 만드는 것이 목적이다.

실제 접속, 명령 실행, 배포 확인, 되돌리기 같은 절차는 Manual에서 관리한다.

헷갈리는 것	실제 의미
`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 순서로 관계를 잡아두면 이후 문서를 읽기 쉬워진다.

초보자 기준 최소한 아래 정도의 역할 구분은 알고 시작하면 된다.

각 스택의 세부 구조와 운영 관점은 해당 가이드 문서에서 따로 읽는 편이 좋다.

입문자는 보통 아래 순서로 이어서 보면 된다.

즉 이 문서는 "지도를 펴는 문서"이고, 실제 작업 문서는 별도 가이드와 매뉴얼에서 이어진다.