From b7c7ea2055fca1fa397a664e7c0cf04d290e806c Mon Sep 17 00:00:00 2001 From: JoMinJun <72008472+jominjun94@users.noreply.github.com> Date: Fri, 12 Dec 2025 17:01:59 +0900 Subject: [PATCH] Update README.md --- README.md | 152 +++++++++++++++++++----------------------------------- 1 file changed, 52 insertions(+), 100 deletions(-) diff --git a/README.md b/README.md index 0bf5259..1935b2f 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,52 @@ # CPU Reaper Operator -> Kubernetes Pod CPU 사용률을 실시간으로 감시하고, -> 설정된 임계치를 초과한 Pod를 자동으로 재기동(삭제)하는 Kubernetes Operator +CPU Reaper Operator는 Kubernetes 클러스터에서 실행 중인 Pod의 CPU 사용률을 +metrics.k8s.io API를 통해 주기적으로 확인하고, +설정된 임계치를 초과한 Pod를 자동으로 삭제하여 +Deployment, ReplicaSet 등에 의해 Pod가 재생성되도록 유도하는 Operator입니다. + +CPU limit은 컨테이너를 종료하지 않고 throttling만 수행하기 때문에 +CPU 과다 사용 상태에서도 Pod는 Running 상태로 유지될 수 있으며, +CPU Reaper Operator는 이러한 한계를 보완하기 위해 설계되었습니다. + --- -## 📌 프로젝트 개요 +## 주요 기능 -**CPU Reaper Operator**는 Kubernetes 클러스터에서 실행 중인 Pod의 -CPU 사용량을 `metrics.k8s.io` 기반으로 주기적으로 확인하여, - -- CPU 사용률이 설정한 임계치(%)를 초과하고 -- 일정 시간 이상 지속될 경우 - -해당 Pod를 **자동으로 삭제**하여 -Deployment / ReplicaSet에 의해 **Pod가 재생성되도록 유도**하는 -**정책 기반(Self-Healing) 오퍼레이터**입니다. - -운영 환경에서 다음과 같은 상황을 해결하는 것을 목표로 합니다: - -- CPU 폭주로 인한 서비스 성능 저하 -- 비정상 Pod의 수동 재기동 반복 -- HPA만으로 해결하기 어려운 순간적 CPU 스파이크 +- Pod CPU 사용률 모니터링 +- CPU Limit(또는 Request)을 기준으로 사용률 계산 +- 일정 시간 이상 임계치 초과 시 Pod 자동 삭제 +- Deployment / ReplicaSet 환경에서 자동 복구 유도 +- 정책(Custom Resource) 기반 설정 --- -## 🧠 아키텍처 개요 +## 동작 개요 -```text -CpuReaperPolicy (Custom Resource) - │ - ▼ -CPU Reaper Controller - │ - ├─ metrics.k8s.io (PodMetrics) - │ - ├─ CPU 사용률 계산 - │ - ├─ 임계치 초과 여부 판단 - │ - └─ 임계치 초과 시 Pod 삭제 - │ - └─ Deployment / ReplicaSet에 의해 Pod +1. 사용자가 `CpuReaperPolicy` 리소스를 생성합니다. +2. Controller는 주기적으로 정책을 Reconcile 합니다. +3. 지정된 Label Selector에 해당하는 Pod를 조회합니다. +4. `metrics.k8s.io` API를 통해 Pod의 CPU 사용량을 조회합니다. +5. Pod의 CPU Limit(없을 경우 Request) 대비 사용률을 계산합니다. +6. 사용률이 임계치를 초과한 상태가 일정 시간 이상 지속되면 Pod를 삭제합니다. +7. 상위 컨트롤러에 의해 Pod가 자동으로 재생성됩니다. -⚙️ 동작 방식 +--- -사용자가 CpuReaperPolicy CR을 생성 +## 사전 요구 사항 -Controller가 주기적으로 정책을 Reconcile +- Kubernetes 클러스터 +- metrics-server 설치 필수 +--- -Label Selector에 매칭되는 Pod 목록 조회 +## 설치 방법 +kubectl apply -f https://raw.githubusercontent.com/jominjun94/k8s-cpu-limit-check-operator/main/dist/install.yaml -metrics.k8s.io API를 통해 Pod CPU 사용량 조회 +--- -Pod의 CPU Limit(Request fallback) 대비 사용률 계산 - -임계치 초과 상태가 forSeconds 이상 지속되면 Pod 삭제 - -상위 컨트롤러(Deployment/RS)에 의해 Pod 자동 재생성 - -📦 필수 요구사항 - -Kubernetes v1.23+ - -metrics-server 설치 필수 -(PodMetrics API 사용) - -kubectl get apiservices | grep metrics.k8s.io - - -Go v1.21+ (개발 시) - -Docker / Podman (이미지 빌드 시) - -🧩 Custom Resource 정의 (CpuReaperPolicy) +## 정책 생성 (CpuReaperPolicy) +``` apiVersion: reaper.cpu.limit.check/v1alpha1 kind: CpuReaperPolicy metadata: @@ -83,11 +56,15 @@ spec: podSelector: matchLabels: app: stress - thresholdPercent: 100 # CPU 사용률 % - forSeconds: 30 # 초과 상태 유지 시간 - checkIntervalSeconds: 10 # 체크 주기 - -🔬 테스트용 CPU 부하 Deployment 예시 + thresholdPercent: 100 + forSeconds: 30 + checkIntervalSeconds: 10 +``` +--- +## 적용 +kubectl apply -f cpureaperpolicy.yaml +``` +테스트용 CPU 부하 Pod apiVersion: apps/v1 kind: Deployment metadata: @@ -116,41 +93,16 @@ spec: cpu: "100m" limits: cpu: "100m" - -🚀 설치 방법 (사용자 기준) -1️⃣ CRD 설치 -kubectl apply -f https://raw.githubusercontent.com/jominjun94/k8s-cpu-limit-check-operator/main/dist/install.yaml - -2️⃣ CpuReaperPolicy 생성 -kubectl apply -f cpureaperpolicy.yaml - -3️⃣ 동작 확인 +``` +--- +## 동작 확인 kubectl logs -n cpu-reaper-system deploy/cpu-reaper-operator-controller-manager -🐳 컨테이너 이미지 +--- +## 제거 +1. kubectl delete cpureaperpolicy cpu-reaper -n default +2. make undeploy +3. make uninstall +--- +## 컨테이너 이미지 jominjun/cpu-reaper-operator:v0.1.0 - - -Docker Hub 공개 이미지로 별도 인증 없이 Pull 가능 - -🧪 로컬 개발 모드 -make install -make run - -📈 향후 개선 예정 - -HPA 연동 - -CPU Throttling 기반 판단 - -Memory 정책 추가 - -Prometheus / Alertmanager 연계 - -Dry-Run 모드 지원 - -👨‍💻 작성자 - -GitHub: https://github.com/jominjun94 - -Project: https://github.com/jominjun94/k8s-cpu-limit-check-operator