UptimeKuma를 활용한 서비스 대시보드
March 2025 (538 Words, 3 Minutes)
홈서버 규모가 점점 커지고, 사용중인 서비스들이 많아졌습니다.
하나씩 다 차근차근 공개할 예정이지만, 우선 올라가있는 서비스들 중, 직접 외부에서 도메인 기반으로 접근 가능한 서비스들을 정리해보기로 했습니다.
Uptime Kuma
해당 프로젝트는 주기적으로 등록된 곳을 향해 헬스체크를 수행하면서 서비스의 상태를 모니터링 할 수 있는 서비스입니다. 웹서비스라면 특정 도메인에 대한 HealthCheck를 통해 서비스 다운여부를 확인할 수 있는
github status 홈페이지랑 비슷하다고 보시면 될것같습니다.
프로젝트에 소개 된 이미지입니다. 관리자 페이지에서는 헬스체크 이력 및 레이턴시 (응답속도) 를 확인 할 수 있습니다. 간단한 프로젝트여서 대단한 기능은없지만, 보기 깔끔하다는 특징이 있네요.
Helm Chart 깎기
공식 document에는 도커 컨테이너 실행까지밖에없는데,
언제나 그러하듯 쿠버네티스 위에 올려봐야죠. 컨테이너를 직접 예쁘게 말아서 yaml화 하는건 누군가가 먼저 해놨을거라 생각합니다 (실제로 그러하구요)
오픈톡방에서 추천받은 helm chart 인데 꽤 쓰기 편하게 되어있습니다.
helm 을 매번 깎으면서 파라미터를 하나씩 설명하기엔 내용이 너무 길어지는게 아닐까 싶었지만, 최대한 단순하게 설명해보겠습니다.
image:
repository: "art.montkim.com/proxy_cache/louislam/uptime-kuma"
tag: "2.0.0-beta.1"
ingress:
enabled: true
className: "nginx"
annotations:
cert-manager.io/cluster-issuer: mont-prod
hosts:
- host: status.montkim.com
paths:
- path: /
pathType: Prefix
tls:
- secretName: kuma-status-tls
hosts:
- status.montkim.com
volume:
enabled: true
accessMode: ReadWriteOnce
size: 4Gi
storageClassName: node-c-1
제 클러스터 환경에 맞는 파라미터는 다음과 같습니다.
image
- Dockerhub 의 이미지 정책변경으로 로컬 이미지 레지스트리에 프록시를 하는 기능을 활성화했습니다.
도메인 설정
제 도메인에서는 cert manager 를 이용한 도메인 인증서를 쿠버네티스 애드온으로 발급, 관리합니다. mont-prod라는 파라미터를 줄경우 해당 설정에 따라 유기적으로 발급절차를 거칩니다.
tls 에 해당 도메인에 대한 설정 및 관리할 secret 이름을 지정할경우 인증서를 Kubernetes 에서 발급합니다만, 해당 애드온을 쓰지않는다면 (그 앞에서 인증서를 관리, 부여해주는 구조의 아키텍처라면) 사용하지 않아도 됩니다.
개인적으로 Ingress 도메인 노출은 Prefix 형태로 노출하는것을 좋아하여 prefix 로 설정했습니다. PathType 에 대한 쿠버네티스 공식 Document 의 설명은 다음과 같습니다.
인그레스의 각 경로에는 해당 경로 유형이 있어야 한다. 명시적 pathType 을 포함하지 않는 경로는 유효성 검사에 실패한다. 지원되는 경로 유형은 세 가지이다.
-
ImplementationSpecific: 이 경로 유형의 일치 여부는 IngressClass에 따라 달라진다. 이를 구현할 때 별도pathType으로 처리하거나,Prefix또는Exact경로 유형과 같이 동일하게 처리할 수 있다. -
Exact: URL 경로의 대소문자를 엄격하게 일치시킨다. -
Prefix: URL 경로의 접두사를/를 기준으로 분리한 값과 일치시킨다. 일치는 대소문자를 구분하고, 요소별로 경로 요소에 대해 수행한다. 모든 p 가 요청 경로의 요소별 접두사가 p 인 경우 요청은 p 경로에 일치한다.
볼륨 설정
Pod 의 종료에도, 언제나 데이터를 유지해주는 볼륨설정입니다.
storageClass 설정만 해주면 상관없습니다.
제 개인환경에서는 NFS / iSCSI 볼륨 사용이 가능한 시놀로지가 한대 쿠버네티스 노드에 들어간 스토리지들을 엮어주는 내부 스토리지 서비스 OpenEBS 가 존재합니다.
- 여기서 2개의 서로다른 스토리지에 복제본을 유지시켜주는 형태의 Storage를 생성해뒀습니다.
emptyDir만 아니라면 어떤 형태의 볼륨을 StorageClass로 선언해서 붙이면 될거같습니다.
시..실제로 이걸 올린 쿠버네티스 자체가 망가진다면 외부에서 이 대시보드를 볼 수 없다는
SPOF 같은 상황이 오기도 하겠지만, 인프라는 꽤나 한정적이니 이만한것으로 만족하고 넘어가겠습니다
helm repo add uptime-kuma https://helm.irsigler.cloud
helm upgrade uptime-kuma uptime-kuma/uptime-kuma --install --namespace monitoring -f cvalues.yaml
이런 명령어로 제가 설정한 옵션을 file 에 파라미터로 지정하여 설치를 진행했습니다.
ArgoCD에서 Helm 형태로 지정하여 배포했다면 다른 형태로 저장/배포가 되겠지만 간단한 테스트용이니 여기까지만 다루겠습니다.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: kuma
namespace: argocd
spec:
project: mont-helm
destination:
server: https://kubernetes.default.svc
namespace: monitoring
sources:
# (1) OCI 기반 Uptime Kuma Helm 차트 소스
- repoURL: 'https://helm.irsigler.cloud'
chart: uptime-kuma
targetRevision: '2.21.2'
helm:
releaseName: kuma
valueFiles:
- '$values/kuma/cvalues.yaml'
# (2) custom values 파일을 포함하는 Git 리포 소스
- repoURL: 'https://github.com/@.git'
targetRevision: HEAD
ref: values
syncPolicy:
automated:
prune: true
selfHeal: true
사실은 하나 깎았습니다. Argo Project 밑에있는 Helm Chart에 해당 Chart 를 신규로 배포했습니다.
서비스 등록
처음 접속하면 SQLite 혹은 임베디드 MariaDB를 이용가능하다고 뜨네요.
이용 가능한 형태의 Healthcheck들은 다양합니다만, 기본적인 응답만 보도록 하겠습니다.
제가 쿠버네티스 위에 올린 웹서비드들은, 정상이라면 Ingress Controller에서 정상적인 응답을 하겠죠?
해당 http/s 요청에 대해서 정상적인 응답만을 받으면 웹서비스 까지의 상태는 모두 정상으로 보아도 괜찮을것 같습니다.
이런 설정으로 등록을한다면 서비스 자체가 응답은 정상적으로 한다고 볼 수 있겠네요.
물론 저게 웹서비스가 아주 정상적으로 동작한다랑은 다른 이야기지만
도메인 -> 집 인터넷 -> 홈서버 -> 내부 웹서비스
정도의 상태를 직관적으로 이해, 표시하기에 적합한것같습니다.
별도의 “내부 웹서비스” 안에서 동작하는 것들에 대한 헬스체크 등은 별도로 구성해야겠지만, 이건 해당 대시보드에서의 역할은 아닌것으로 생각이 되어서요.
물론 prometheus에 promql문을 질의하여 메트릭 모니터링과도 연관을 할 수 있지만, 이 대시보드에서 할 수 있는것이 그렇게 크진않아 기능을 분리하는것이 낫겠다는 생각을 해봅니다.