mirror of
https://github.com/jominjun94/k8s-cpu-limit-check-operator.git
synced 2026-01-29 13:45:35 +00:00
Update README.md
This commit is contained in:
JoMinJun
152
README.md
152
README.md
@@ -1,79 +1,52 @@
|
|||||||
# CPU Reaper Operator
|
# CPU Reaper Operator
|
||||||
|
|
||||||
> Kubernetes Pod CPU 사용률을 실시간으로 감시하고,
|
CPU Reaper Operator는 Kubernetes 클러스터에서 실행 중인 Pod의 CPU 사용률을
|
||||||
> 설정된 임계치를 초과한 Pod를 자동으로 재기동(삭제)하는 Kubernetes Operator
|
metrics.k8s.io API를 통해 주기적으로 확인하고,
|
||||||
|
설정된 임계치를 초과한 Pod를 자동으로 삭제하여
|
||||||
|
Deployment, ReplicaSet 등에 의해 Pod가 재생성되도록 유도하는 Operator입니다.
|
||||||
|
|
||||||
|
CPU limit은 컨테이너를 종료하지 않고 throttling만 수행하기 때문에
|
||||||
|
CPU 과다 사용 상태에서도 Pod는 Running 상태로 유지될 수 있으며,
|
||||||
|
CPU Reaper Operator는 이러한 한계를 보완하기 위해 설계되었습니다.
|
||||||
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📌 프로젝트 개요
|
## 주요 기능
|
||||||
|
|
||||||
**CPU Reaper Operator**는 Kubernetes 클러스터에서 실행 중인 Pod의
|
- Pod CPU 사용률 모니터링
|
||||||
CPU 사용량을 `metrics.k8s.io` 기반으로 주기적으로 확인하여,
|
- CPU Limit(또는 Request)을 기준으로 사용률 계산
|
||||||
|
- 일정 시간 이상 임계치 초과 시 Pod 자동 삭제
|
||||||
- CPU 사용률이 설정한 임계치(%)를 초과하고
|
- Deployment / ReplicaSet 환경에서 자동 복구 유도
|
||||||
- 일정 시간 이상 지속될 경우
|
- 정책(Custom Resource) 기반 설정
|
||||||
|
|
||||||
해당 Pod를 **자동으로 삭제**하여
|
|
||||||
Deployment / ReplicaSet에 의해 **Pod가 재생성되도록 유도**하는
|
|
||||||
**정책 기반(Self-Healing) 오퍼레이터**입니다.
|
|
||||||
|
|
||||||
운영 환경에서 다음과 같은 상황을 해결하는 것을 목표로 합니다:
|
|
||||||
|
|
||||||
- CPU 폭주로 인한 서비스 성능 저하
|
|
||||||
- 비정상 Pod의 수동 재기동 반복
|
|
||||||
- HPA만으로 해결하기 어려운 순간적 CPU 스파이크
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🧠 아키텍처 개요
|
## 동작 개요
|
||||||
|
|
||||||
```text
|
1. 사용자가 `CpuReaperPolicy` 리소스를 생성합니다.
|
||||||
CpuReaperPolicy (Custom Resource)
|
2. Controller는 주기적으로 정책을 Reconcile 합니다.
|
||||||
│
|
3. 지정된 Label Selector에 해당하는 Pod를 조회합니다.
|
||||||
▼
|
4. `metrics.k8s.io` API를 통해 Pod의 CPU 사용량을 조회합니다.
|
||||||
CPU Reaper Controller
|
5. Pod의 CPU Limit(없을 경우 Request) 대비 사용률을 계산합니다.
|
||||||
│
|
6. 사용률이 임계치를 초과한 상태가 일정 시간 이상 지속되면 Pod를 삭제합니다.
|
||||||
├─ metrics.k8s.io (PodMetrics)
|
7. 상위 컨트롤러에 의해 Pod가 자동으로 재생성됩니다.
|
||||||
│
|
|
||||||
├─ CPU 사용률 계산
|
|
||||||
│
|
|
||||||
├─ 임계치 초과 여부 판단
|
|
||||||
│
|
|
||||||
└─ 임계치 초과 시 Pod 삭제
|
|
||||||
│
|
|
||||||
└─ Deployment / ReplicaSet에 의해 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) 대비 사용률 계산
|
## 정책 생성 (CpuReaperPolicy)
|
||||||
|
```
|
||||||
임계치 초과 상태가 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)
|
|
||||||
apiVersion: reaper.cpu.limit.check/v1alpha1
|
apiVersion: reaper.cpu.limit.check/v1alpha1
|
||||||
kind: CpuReaperPolicy
|
kind: CpuReaperPolicy
|
||||||
metadata:
|
metadata:
|
||||||
@@ -83,11 +56,15 @@ spec:
|
|||||||
podSelector:
|
podSelector:
|
||||||
matchLabels:
|
matchLabels:
|
||||||
app: stress
|
app: stress
|
||||||
thresholdPercent: 100 # CPU 사용률 %
|
thresholdPercent: 100
|
||||||
forSeconds: 30 # 초과 상태 유지 시간
|
forSeconds: 30
|
||||||
checkIntervalSeconds: 10 # 체크 주기
|
checkIntervalSeconds: 10
|
||||||
|
```
|
||||||
🔬 테스트용 CPU 부하 Deployment 예시
|
---
|
||||||
|
## 적용
|
||||||
|
kubectl apply -f cpureaperpolicy.yaml
|
||||||
|
```
|
||||||
|
테스트용 CPU 부하 Pod
|
||||||
apiVersion: apps/v1
|
apiVersion: apps/v1
|
||||||
kind: Deployment
|
kind: Deployment
|
||||||
metadata:
|
metadata:
|
||||||
@@ -116,41 +93,16 @@ spec:
|
|||||||
cpu: "100m"
|
cpu: "100m"
|
||||||
limits:
|
limits:
|
||||||
cpu: "100m"
|
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
|
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
|
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
|
|
||||||
|
|||||||
Reference in New Issue
Block a user