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
234
README.md
234
README.md
@@ -1,114 +1,156 @@
|
|||||||
# cpu-reaper-operator
|
# CPU Reaper Operator
|
||||||
// TODO(user): Add simple overview of use/purpose
|
|
||||||
|
|
||||||
## Description
|
> Kubernetes Pod CPU 사용률을 실시간으로 감시하고,
|
||||||
// TODO(user): An in-depth paragraph about your project and overview of use
|
> 설정된 임계치를 초과한 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
|
**CPU Reaper Operator**는 Kubernetes 클러스터에서 실행 중인 Pod의
|
||||||
**Build and push your image to the location specified by `IMG`:**
|
CPU 사용량을 `metrics.k8s.io` 기반으로 주기적으로 확인하여,
|
||||||
|
|
||||||
```sh
|
- CPU 사용률이 설정한 임계치(%)를 초과하고
|
||||||
make docker-build docker-push IMG=<some-registry>/cpu-reaper-operator:tag
|
- 일정 시간 이상 지속될 경우
|
||||||
```
|
|
||||||
|
|
||||||
**NOTE:** This image ought to be published in the personal registry you specified.
|
해당 Pod를 **자동으로 삭제**하여
|
||||||
And it is required to have access to pull the image from the working environment.
|
Deployment / ReplicaSet에 의해 **Pod가 재생성되도록 유도**하는
|
||||||
Make sure you have the proper permission to the registry if the above commands don’t work.
|
**정책 기반(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 install
|
||||||
```
|
make run
|
||||||
|
|
||||||
**Deploy the Manager to the cluster with the image specified by `IMG`:**
|
📈 향후 개선 예정
|
||||||
|
|
||||||
```sh
|
HPA 연동
|
||||||
make deploy IMG=<some-registry>/cpu-reaper-operator:tag
|
|
||||||
```
|
|
||||||
|
|
||||||
> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin
|
CPU Throttling 기반 판단
|
||||||
privileges or be logged in as admin.
|
|
||||||
|
|
||||||
**Create instances of your solution**
|
Memory 정책 추가
|
||||||
You can apply the samples (examples) from the config/sample:
|
|
||||||
|
|
||||||
```sh
|
Prometheus / Alertmanager 연계
|
||||||
kubectl apply -k config/samples/
|
|
||||||
```
|
|
||||||
|
|
||||||
>**NOTE**: Ensure that the samples has default values to test it out.
|
Dry-Run 모드 지원
|
||||||
|
|
||||||
### To Uninstall
|
👨💻 작성자
|
||||||
**Delete the instances (CRs) from the cluster:**
|
|
||||||
|
|
||||||
```sh
|
GitHub: https://github.com/jominjun94
|
||||||
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=<some-registry>/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 <URL for YAML BUNDLE> to install the project, i.e.:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
kubectl apply -f https://raw.githubusercontent.com/<org>/cpu-reaper-operator/<tag or branch>/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.
|
|
||||||
|
|
||||||
|
Project: https://github.com/jominjun94/k8s-cpu-limit-check-operator
|
||||||
|
|||||||
Reference in New Issue
Block a user