Skip to content

Commit 64965da

Browse files
Yoon-Hae-MinYoon-Hae-Min
committed
feat: Docker 컨테이너 관리 대시보드의 데이터 구조 및 개발 가이드라인 문서 추가, 기존 노드 및 서비스 배포 관련 코드 제거
1 parent 7cb52b9 commit 64965da

48 files changed

Lines changed: 1903 additions & 3717 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.cursor/rules/api-structor.mdc‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
# 🐳 Docker 컨테이너 관리 대시보드 - 데이터 구조 가이드
7+
8+
이 문서는 Docker Swarm 기반 컨테이너 관리 대시보드의 핵심 데이터 구조와 엔티티 간 관계를 정의합니다.
9+
10+
## 🏗️ 시스템 아키텍처 개요
11+
12+
```
13+
📦 클러스터 (Cluster)
14+
├── 🖥️ 노드 (Node) × N
15+
│ ├── 👑 매니저 노드 (Manager Node) - 클러스터 관리 및 오케스트레이션
16+
│ └── 👷 워커 노드 (Worker Node) - 컨테이너 실행 환경
17+
│
18+
├── 🚀 서비스 (Service) × N
19+
│ ├── 📋 배포 명세 (Deployment Spec)
20+
│ ├── 🔄 레플리카 설정 (Replica Configuration)
21+
│ └── 🌐 네트워크 구성 (Network Configuration)
22+
│
23+
└── 📦 컨테이너 (Container) × N
24+
├── 🏃 실행 인스턴스 (Running Instance)
25+
├── 📊 리소스 사용량 (Resource Usage)
26+
└── 🔌 포트 바인딩 (Port Binding)
27+
```
28+
29+
## 🔗 엔티티 관계 정의
30+
31+
### 1. 클러스터 (Cluster) - 최상위 관리 단위
32+
33+
**역할**: Docker Swarm 클러스터 전체를 관리하는 최상위 엔티티
34+
**관계**: 1개 클러스터 → N개 노드, N개 서비스
35+
36+
```typescript
37+
interface ClusterStatus {
38+
id: string; // 클러스터 고유 식별자
39+
swarmStatus: SwarmStatus; // 'active' | 'inactive' | 'pending' | 'error'
40+
nodes: NodeSummary; // 노드 통계 정보
41+
services: ServiceSummary; // 서비스 통계 정보
42+
version: ClusterVersion; // 클러스터 버전 정보
43+
}
44+
```
45+
46+
**책임**:
47+
- 전체 인프라 상태 관리
48+
- 노드 간 통신 조율
49+
- 서비스 배포 스케줄링
50+
- 클러스터 레벨 보안 정책
51+
52+
### 2. 노드 (Node) - 물리적 실행 환경
53+
54+
**역할**: 컨테이너가 실제로 실행되는 물리적/가상 서버
55+
**관계**: N개 노드 → 1개 클러스터, N개 컨테이너 호스팅
56+
57+
```typescript
58+
interface Node {
59+
id: string; // 노드 고유 식별자
60+
role: 'manager' | 'worker'; // 노드 역할
61+
status: NodeStatus; // 'active' | 'inactive' | 'draining' | 'unavailable'
62+
availability: NodeAvailability; // 'active' | 'pause' | 'drain'
63+
resources: NodeResources; // CPU, 메모리, 디스크 용량
64+
labels: Record<string, string>; // 배치 제약 조건용 라벨
65+
constraints: string[]; // 서비스 배치 제약
66+
}
67+
```
68+
69+
**노드 타입별 역할**:
70+
- **매니저 노드**: 클러스터 관리, API 엔드포인트, 스케줄링 결정
71+
- **워커 노드**: 컨테이너 실행, 태스크 수행
72+
73+
### 3. 서비스 (Service) - 애플리케이션 정의
74+
75+
**역할**: 배포할 애플리케이션의 명세와 실행 정책을 정의
76+
**관계**: N개 서비스 → 1개 클러스터, 1개 서비스 → N개 컨테이너 레플리카
77+
78+
```typescript
79+
interface Service {
80+
id: string; // 서비스 고유 식별자
81+
name: string; // 서비스 이름
82+
image: string; // 컨테이너 이미지
83+
mode: 'replicated' | 'global'; // 배포 모드
84+
replicas?: number; // 레플리카 수 (replicated 모드)
85+
status: ServiceStatus; // 서비스 상태
86+
constraints: string[]; // 노드 배치 제약 조건
87+
networks: string[]; // 연결된 네트워크
88+
resources: ServiceResources; // 리소스 요구사항/제한
89+
endpoint: ServiceEndpoint; // 네트워크 엔드포인트 정보
90+
}
91+
```
92+
93+
**서비스 배포 모드**:
94+
- **Replicated**: 지정된 수의 레플리카를 클러스터에 분산 배포
95+
- **Global**: 각 노드마다 하나씩 배포 (데몬셋과 유사)
96+
97+
### 4. 컨테이너 (Container) - 실행 인스턴스
98+
99+
**역할**: 서비스로부터 생성된 실제 실행 인스턴스
100+
**관계**: N개 컨테이너 → 1개 서비스, 1개 컨테이너 → 1개 노드
101+
102+
```typescript
103+
interface Container {
104+
id: string; // 컨테이너 고유 식별자
105+
name: string; // 컨테이너 이름
106+
serviceId?: string; // 소속 서비스 ID (서비스에서 생성된 경우)
107+
nodeId?: string; // 실행 중인 노드 ID
108+
image: string; // 컨테이너 이미지
109+
status: ContainerStatus; // 'running' | 'stopped' | 'paused' | 'failed'
110+
resources: ContainerResources; // 실제 리소스 사용량
111+
ports: PortBinding[]; // 포트 바인딩 정보
112+
health: HealthStatus; // 헬스체크 상태
113+
}
114+
```
115+
116+
**컨테이너 라이프사이클**:
117+
1. **Pending**: 스케줄링 대기
118+
2. **Pulling**: 이미지 다운로드
119+
3. **Starting**: 컨테이너 시작
120+
4. **Running**: 정상 실행
121+
5. **Failed**: 실행 실패
122+
123+
## 🌐 네트워크 및 통신 관계
124+
125+
### 서비스 간 통신
126+
127+
```typescript
128+
interface ServiceEndpoint {
129+
virtualIPs: VirtualIP[]; // 가상 IP 주소
130+
ports: ServicePort[]; // 노출된 포트
131+
loadBalancing: LoadBalancingConfig; // 로드 밸런싱 설정
132+
}
133+
134+
interface VirtualIP {
135+
networkID: string; // 네트워크 ID
136+
addr: string; // IP 주소 (CIDR 표기)
137+
}
138+
```
139+
140+
**통신 흐름**:
141+
1. **클라이언트** → **로드밸런서** (가상 IP)
142+
2. **로드밸런서** → **서비스 레플리카** (라운드로빈/가중치)
143+
3. **서비스 A** → **서비스 B** (서비스 디스커버리)
144+
145+
## 📊 리소스 관리 및 스케줄링
146+
147+
### 리소스 할당 흐름
148+
149+
```
150+
1. 서비스 리소스 요구사항 정의
151+
├── resources.limits (최대 사용량)
152+
└── resources.reservations (보장 사용량)
153+
154+
2. 노드 리소스 용량 확인
155+
├── node.resources.cpus
156+
├── node.resources.memory
157+
└── node.resources.disk
158+
159+
3. 스케줄링 알고리즘 적용
160+
├── 리소스 여유분 확인
161+
├── 배치 제약 조건 검증
162+
└── 최적 노드 선택
163+
164+
4. 컨테이너 배치 및 실행
165+
```
166+
167+
### 제약 조건(Constraints) 시스템
168+
169+
```typescript
170+
// 서비스 배치 제약 조건 예시
171+
service.constraints = [
172+
'node.role==worker', // 워커 노드에만 배치
173+
'node.labels.storage==ssd', // SSD 스토리지가 있는 노드
174+
'node.labels.zone!=us-west' // 특정 가용영역 제외
175+
];
176+
```
177+
178+
## 🔄 상태 관리 및 모니터링
179+
180+
### 헬스체크 및 자가 치유
181+
182+
```typescript
183+
interface HealthCheck {
184+
containerId: string;
185+
status: 'healthy' | 'unhealthy' | 'failed' | 'recovering';
186+
lastCheck: string;
187+
failureCount: number;
188+
restartPolicy: RestartPolicy;
189+
}
190+
191+
interface RestartPolicy {
192+
condition: 'none' | 'on-failure' | 'any';
193+
delay: string; // 재시작 간격
194+
maxAttempts: number; // 최대 재시작 횟수
195+
window: string; // 모니터링 윈도우
196+
}
197+
```
198+
199+
## 📋 데이터 일관성 규칙
200+
201+
1. **서비스 → 컨테이너**: 서비스의 `replicas` 수와 실제 실행 중인 컨테이너 수 일치
202+
2. **노드 → 컨테이너**: 노드의 리소스 사용량 = 해당 노드 내 모든 컨테이너 리소스 합
203+
3. **클러스터 → 서비스**: 클러스터 서비스 통계 = 모든 서비스 상태의 집계
204+
4. **네트워크 일관성**: 같은 네트워크의 서비스들은 서로 통신 가능
205+
206+
이 구조를 바탕으로 대시보드의 모든 기능은 이 엔티티 관계를 반영하여 구현되어야 합니다.

0 commit comments

Comments
 (0)