From 65285709ac02053264eeee49d675aafb686d9a56 Mon Sep 17 00:00:00 2001 From: JoMinJun <72008472+jominjun94@users.noreply.github.com> Date: Fri, 12 Dec 2025 16:38:48 +0900 Subject: [PATCH] Update README.md --- README.md | 234 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 138 insertions(+), 96 deletions(-) diff --git a/README.md b/README.md index 419a7c8..0bf5259 100644 --- a/README.md +++ b/README.md @@ -1,114 +1,156 @@ -# cpu-reaper-operator -// TODO(user): Add simple overview of use/purpose +# CPU Reaper Operator -## Description -// TODO(user): An in-depth paragraph about your project and overview of use +> Kubernetes Pod CPU 사용률을 실시간으로 감시하고, +> 설정된 임계치를 초과한 Pod를 자동으로 재기동(삭제)하는 Kubernetes Operator -## Getting Started +--- -### Prerequisites -- go version v1.21.0+ -- docker version 17.03+. -- kubectl version v1.11.3+. -- Access to a Kubernetes v1.11.3+ cluster. +## 📌 프로젝트 개요 -### To Deploy on the cluster -**Build and push your image to the location specified by `IMG`:** +**CPU Reaper Operator**는 Kubernetes 클러스터에서 실행 중인 Pod의 +CPU 사용량을 `metrics.k8s.io` 기반으로 주기적으로 확인하여, -```sh -make docker-build docker-push IMG=/cpu-reaper-operator:tag -``` +- CPU 사용률이 설정한 임계치(%)를 초과하고 +- 일정 시간 이상 지속될 경우 -**NOTE:** This image ought to be published in the personal registry you specified. -And it is required to have access to pull the image from the working environment. -Make sure you have the proper permission to the registry if the above commands don’t work. +해당 Pod를 **자동으로 삭제**하여 +Deployment / ReplicaSet에 의해 **Pod가 재생성되도록 유도**하는 +**정책 기반(Self-Healing) 오퍼레이터**입니다. -**Install the CRDs into the cluster:** +운영 환경에서 다음과 같은 상황을 해결하는 것을 목표로 합니다: -```sh +- CPU 폭주로 인한 서비스 성능 저하 +- 비정상 Pod의 수동 재기동 반복 +- HPA만으로 해결하기 어려운 순간적 CPU 스파이크 + +--- + +## 🧠 아키텍처 개요 + +```text +CpuReaperPolicy (Custom Resource) + │ + ▼ +CPU Reaper Controller + │ + ├─ metrics.k8s.io (PodMetrics) + │ + ├─ CPU 사용률 계산 + │ + ├─ 임계치 초과 여부 판단 + │ + └─ 임계치 초과 시 Pod 삭제 + │ + └─ Deployment / ReplicaSet에 의해 Pod + +⚙️ 동작 방식 + +사용자가 CpuReaperPolicy CR을 생성 + +Controller가 주기적으로 정책을 Reconcile + +Label Selector에 매칭되는 Pod 목록 조회 + +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) +apiVersion: reaper.cpu.limit.check/v1alpha1 +kind: CpuReaperPolicy +metadata: + name: cpu-reaper + namespace: default +spec: + podSelector: + matchLabels: + app: stress + thresholdPercent: 100 # CPU 사용률 % + forSeconds: 30 # 초과 상태 유지 시간 + checkIntervalSeconds: 10 # 체크 주기 + +🔬 테스트용 CPU 부하 Deployment 예시 +apiVersion: apps/v1 +kind: Deployment +metadata: + name: cpu-stress + namespace: default +spec: + replicas: 1 + selector: + matchLabels: + app: stress + template: + metadata: + labels: + app: stress + spec: + containers: + - name: stress + image: busybox + command: + - sh + - -c + - | + while true; do :; done + resources: + requests: + 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 + +🐳 컨테이너 이미지 +jominjun/cpu-reaper-operator:v0.1.0 + + +Docker Hub 공개 이미지로 별도 인증 없이 Pull 가능 + +🧪 로컬 개발 모드 make install -``` +make run -**Deploy the Manager to the cluster with the image specified by `IMG`:** +📈 향후 개선 예정 -```sh -make deploy IMG=/cpu-reaper-operator:tag -``` +HPA 연동 -> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin -privileges or be logged in as admin. +CPU Throttling 기반 판단 -**Create instances of your solution** -You can apply the samples (examples) from the config/sample: +Memory 정책 추가 -```sh -kubectl apply -k config/samples/ -``` +Prometheus / Alertmanager 연계 ->**NOTE**: Ensure that the samples has default values to test it out. +Dry-Run 모드 지원 -### To Uninstall -**Delete the instances (CRs) from the cluster:** +👨‍💻 작성자 -```sh -kubectl delete -k config/samples/ -``` - -**Delete the APIs(CRDs) from the cluster:** - -```sh -make uninstall -``` - -**UnDeploy the controller from the cluster:** - -```sh -make undeploy -``` - -## Project Distribution - -Following are the steps to build the installer and distribute this project to users. - -1. Build the installer for the image built and published in the registry: - -```sh -make build-installer IMG=/cpu-reaper-operator:tag -``` - -NOTE: The makefile target mentioned above generates an 'install.yaml' -file in the dist directory. This file contains all the resources built -with Kustomize, which are necessary to install this project without -its dependencies. - -2. Using the installer - -Users can just run kubectl apply -f to install the project, i.e.: - -```sh -kubectl apply -f https://raw.githubusercontent.com//cpu-reaper-operator//dist/install.yaml -``` - -## Contributing -// TODO(user): Add detailed information on how you would like others to contribute to this project - -**NOTE:** Run `make help` for more information on all potential `make` targets - -More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html) - -## License - -Copyright 2025. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. +GitHub: https://github.com/jominjun94 +Project: https://github.com/jominjun94/k8s-cpu-limit-check-operator