Skip to content

API Documents

Jump to bottom
윤지원 edited this page Nov 16, 2025 · 4 revisions

KubeDev Auto System - API 문서

개요

K8s 기반 자동 개발 환경 프로비저닝 시스템의 API 명세서입니다.

기본 URL: http://localhost:8000/api/v1 Swagger UI: http://localhost:8000/docs ReDoc: http://localhost:8000/redoc

인증

모든 API 엔드포인트는 Bearer 토큰 인증을 사용합니다.

Authorization: Bearer <your-jwt-token>

로그인

POST /auth/login
{
  "email": "user@example.com",
  "password": "password123"
}

환경 관리 API

1. 새 환경 생성

POST /environments/
{
  "name": "My React Project",
  "template_id": 1,
  "git_repository": "https://github.com/user/project.git",
  "git_branch": "main",
  "expires_at": "2024-12-31T23:59:59Z"
}

2. 환경 목록 조회

GET /environments/
GET /environments/?status=running&user_id=1

3. 환경 제어

POST /environments/{id}/actions
{
  "action": "start"  // start, stop, restart, delete
}

4. 환경 로그 조회

GET /environments/{id}/logs?tail_lines=100

5. 환경 접속 정보

GET /environments/{id}/access-info

응답 예시:

{
  "environment_id": 1,
  "access_url": "http://env-my-react-project.kubdev.local",
  "status": "running",
  "ports": [8080]
}

템플릿 관리 API

1. 템플릿 생성

POST /templates/
{
  "name": "React + TypeScript Starter",
  "description": "React 18 + TypeScript + Vite 개발환경",
  "base_image": "codercom/code-server:latest",
  "stack_config": {
    "language": "javascript",
    "framework": "react",
    "version": "18"
  },
  "dependencies": ["nodejs", "npm", "git"],
  "resource_limits": {
    "cpu": "1000m",
    "memory": "2Gi",
    "storage": "10Gi"
  },
  "exposed_ports": [3000, 8080],
  "environment_variables": {
    "NODE_ENV": "development"
  }
}

2. 템플릿 목록

GET /templates/?status=active&organization_id=1

3. 템플릿 유효성 검증

POST /templates/{id}/validate

4. 템플릿 배포 테스트

POST /templates/{id}/test-deploy?timeout_seconds=300

모니터링 API

1. 실시간 클러스터 현황

GET /admin/overview

응답 예시:

{
  "cluster_overview": {
    "cluster_info": {
      "total_nodes": 3,
      "ready_nodes": 3,
      "total_pods": 25,
      "running_pods": 23
    },
    "kubdev_info": {
      "total_environments": 8,
      "active_environments": 6,
      "pending_environments": 2,
      "failed_environments": 0
    }
  }
}

2. 모든 환경 상태 조회 (Admin)

GET /admin/environments

** 핵심 기능**: K8s에서 실시간 상태를 조회하여 다음 정보 제공:

  • Pod 상태 (Running/Pending/Failed)
  • ResourceQuota 사용률 (CPU 65%, Memory 78% 등)
  • 네임스페이스별 리소스 현황
  • 컨테이너 Ready 상태

3. 특정 네임스페이스 상세 정보

GET /admin/namespace/{namespace}

4. 사용자별 환경 현황

GET /monitoring/user/{user_id}/environments

5. 리소스 메트릭 조회

GET /monitoring/environments/{id}/metrics?hours=24

6. 시스템 알림

GET /admin/alerts

알림 예시:

{
  "alerts": [
    {
      "type": "warning",
      "category": "high_resource_usage",
      "message": "High CPU usage in namespace 'lisa-project-a'",
      "cpu_usage": "85%",
      "memory_usage": "72%"
    }
  ]
}

Admin 대시보드 API

1. 전체 현황 요약

GET /admin/overview

2. 사용자 활동 현황

GET /admin/users-activity?limit=50

3. 템플릿 사용 통계

GET /admin/templates-usage

4. 만료된 환경 정리

POST /admin/cleanup/expired?dry_run=true

🔧 권한 관리

역할 체계

  • super_admin: 모든 권한
  • org_admin: 조직 내 모든 관리
  • team_leader: 팀 내 환경 관리
  • developer: 본인 환경만 관리

API 키 생성

POST /auth/api-keys
{
  "description": "CI/CD 파이프라인용 API 키"
}

자동화 플로우 예시

신입 개발자 온보딩 시나리오

  1. Admin: 템플릿 생성
POST /templates/
# "React 개발환경" 템플릿 생성
  1. 신입 개발자: 환경 생성 요청
POST /environments/
{
  "name": "Lisa의 첫 프로젝트",
  "template_id": 1,
  "git_repository": "https://github.com/company/onboarding-project"
}

  1. 백엔드 자동 처리:

    • ✅ lisa-project-a Namespace 생성
    • ✅ ResourceQuota 자동 적용 (CPU 1개, 메모리 2GB 제한)
    • ✅ Init Container가 Git 저장소 클론
    • ✅ VS Code Server 컨테이너 시작
    • ✅ Ingress로 외부 접속 URL 생성

  2. 결과:

    • Lisa는 http://env-lisa-project-a.kubdev.local로 즉시 접속
    • 웹 브라우저에서 VS Code 사용
    • 프로젝트 코드 미리 로드됨

  3. Admin 모니터링:

GET /admin/environments
# Lisa의 환경 상태 실시간 확인
# CPU 사용률: 45%, 메모리: 68% 등

K8s 자동화 확인 방법

kubectl 명령어로 확인

# 1. 환경 생성 전
kubectl get namespaces
# lisa-project-a 없음

# 2. 환경 생성 후
kubectl get namespaces
# lisa-project-a Active

kubectl get all -n lisa-project-a
# Deployment, Service, Pod 모두 Running

kubectl get resourcequota -n lisa-project-a
# CPU 1개, 메모리 2GB 제한 적용됨

K8s 대시보드 (Lens) 확인

  • Lens 연결 후 실시간으로 Namespace 생성 과정 시각적 확인
  • Pod 상태 변화: Pending → ContainerCreating → Running
  • ResourceQuota 제한 실시간 모니터링

📈 자원 관리 핵심 기능

1. 예방적 관리 (ResourceQuota)

  • 자동 생성: 환경 생성시 ResourceQuota 자동 적용
  • 과부하 방지: 무한루프 코드 실행해도 CPU 1개로 제한
  • 멀티테넌트: 사용자별 독립된 리소스 할당량

2. 실시간 모니터링

  • K8s API 연동: kubectl get 동급의 실시간 데이터
  • 사용률 추적: CPU 65%, 메모리 78% 등 정확한 수치
  • 알림 시스템: 임계값 초과시 자동 알림

3. Admin 대시보드

  • 통합 모니터링: 모든 환경 상태 한눈에 확인
  • 리소스 효율화: 비효율적 사용 패턴 식별
  • 자동 정리: 만료된 환경 자동 삭제

Dockerfile 자동 생성 API

1. 스택 설정으로 Dockerfile 자동 생성 및 이미지 빌드

POST /api/v1/templates/generate-dockerfile
Content-Type: application/json

{
  "stack_config": {
    "language": "node",
    "version": "18",
    "framework": "react",
    "dependencies": ["axios", "react-router-dom", "styled-components"],
    "exposed_ports": [3000],
    "environment_variables": {
      "NODE_ENV": "development",
      "REACT_APP_API_URL": "http://localhost:8000"
    }
  },
  "environment_id": "env-react-demo",
  "validate_only": false
}

응답 (성공):

{
  "status": "success",
  "dockerfile": "FROM node:18-alpine\n\n# Generated by KubeDev Auto System...",
  "image_tag": "kubdev/env-react-demo:latest",
  "environment_id": "env-react-demo",
  "stack_config": {...},
  "build_time": "2024-11-16T10:30:00Z"
}

지원 스택:

  • Node.js: React, Express, NestJS, Next.js
  • Python: Django, FastAPI, Flask, ML/Data Science
  • Java: Spring Boot, Maven, Gradle
  • Go: Gin, Fiber, Echo

2. 지원되는 스택 목록 조회

GET /api/v1/templates/supported-stacks

응답:

{
  "supported_stacks": {
    "languages": ["node", "python", "java", "go"],
    "frameworks": {
      "node": ["react", "express", "nest", "next"],
      "python": ["django", "fastapi", "flask", "ml"],
      "java": ["spring", "maven", "gradle"],
      "go": ["gin", "fiber", "echo"]
    },
    "base_images": {
      "node": {
        "16": "node:16-alpine",
        "18": "node:18-alpine",
        "20": "node:20-alpine"
      }
    }
  },
  "examples": {
    "node_react": {
      "language": "node",
      "version": "18",
      "framework": "react",
      "dependencies": ["axios", "react-router-dom"],
      "exposed_ports": [3000],
      "environment_variables": {
        "NODE_ENV": "development"
      }
    },
    "python_fastapi": {
      "language": "python",
      "version": "3.11",
      "framework": "fastapi",
      "dependencies": ["sqlalchemy", "pandas"],
      "exposed_ports": [8000],
      "environment_variables": {
        "PYTHONPATH": "/workspace"
      }
    }
  }
}

3. 기존 템플릿에서 커스텀 이미지 생성

POST /api/v1/templates/{template_id}/generate-custom-image?build_now=true

응답:

{
  "status": "success",
  "template_id": 1,
  "template_name": "React Development Environment",
  "dockerfile": "FROM node:18-alpine...",
  "image_tag": "kubdev/template-1-abc123:latest",
  "environment_id": "template-1-abc123",
  "build_time": "2024-11-16T10:35:00Z",
  "message": "Custom image built successfully"
}

일괄 사용자 생성 API (부트캠프용)

1. 대량 사용자 계정 생성 (최대 200명)

POST /api/v1/admin/users/batch
Content-Type: application/json

{
  "prefix": "camp2024",
  "count": 100,
  "template_id": 1,
  "organization_id": 1,
  "resource_quota": {
    "cpu": "1",
    "memory": "2Gi",
    "storage": "10Gi"
  }
}

응답 (실행 완료):

{
  "status": "completed",
  "created_count": 98,
  "failed_count": 2,
  "total_requested": 100,
  "users": [
    {
      "username": "camp2024-01",
      "email": "camp2024-01@kubdev.local",
      "password": "Kx9#mP2$vQ8!",
      "user_id": 101,
      "environment_id": 201,
      "namespace": "kubdev-camp2024-01",
      "access_url": "https://camp2024-01.ide.kubdev.io",
      "status": "creating",
      "expires_at": "2024-11-16T18:30:00Z",
      "created_at": "2024-11-16T10:30:00Z"
    },
    {
      "username": "camp2024-02",
      "email": "camp2024-02@kubdev.local",
      "password": "Qp7&nL5%rT3@",
      "user_id": 102,
      "environment_id": 202,
      "namespace": "kubdev-camp2024-02",
      "access_url": "https://camp2024-02.ide.kubdev.io",
      "status": "creating",
      "expires_at": "2024-11-16T18:30:00Z",
      "created_at": "2024-11-16T10:30:15Z"
    }
  ],
  "failures": [
    {
      "username": "camp2024-99",
      "error": "K8s resource creation failed: namespace already exists",
      "timestamp": "2024-11-16T10:32:00Z"
    },
    {
      "username": "camp2024-100",
      "error": "Database connection timeout",
      "timestamp": "2024-11-16T10:32:05Z"
    }
  ],
  "template_name": "React Development Environment",
  "resource_quota": {
    "cpu": "1",
    "memory": "2Gi",
    "storage": "10Gi"
  },
  "execution_time": "142.35s",
  "timestamp": "2024-11-16T10:32:30Z"
}

자동 생성되는 K8s 리소스:

  • ✅ Namespace: kubdev-{username}
  • ✅ ResourceQuota: CPU/메모리/스토리지 제한
  • ✅ Deployment: VS Code Server + 프로젝트 환경
  • ✅ Service: 내부 통신용
  • ✅ Ingress: 외부 접속 URL (https://{username}.ide.kubdev.io)
  • ✅ PVC: 개인 워크스페이스 (10GB)

2. 단일 사용자 + 환경 즉시 생성

POST /api/v1/admin/users/single
Content-Type: application/json

{
  "username": "newbie-alice",
  "template_id": 2,
  "password": "custom123!",
  "organization_id": 1,
  "resource_quota": {
    "cpu": "2",
    "memory": "4Gi",
    "storage": "20Gi"
  }
}

응답:

{
  "status": "success",
  "user": {
    "username": "newbie-alice",
    "email": "newbie-alice@kubdev.local",
    "password": "custom123!",
    "user_id": 203
  },
  "environment": {
    "environment_id": 301,
    "namespace": "kubdev-newbie-alice",
    "status": "creating",
    "expires_at": "2024-11-16T18:45:00Z"
  },
  "access_info": {
    "access_url": "https://newbie-alice.ide.kubdev.io",
    "username": "newbie-alice",
    "password": "custom123!"
  },
  "template_name": "Python FastAPI Environment",
  "timestamp": "2024-11-16T10:45:00Z"
}

3. 일괄 삭제 (prefix 기준)

DELETE /api/v1/admin/users/batch?prefix=camp2024&dry_run=false

응답:

{
  "status": "completed",
  "prefix": "camp2024",
  "users_found": 98,
  "deleted_count": 96,
  "failed_count": 2,
  "details": [
    {
      "user_id": 101,
      "username": "camp2024-01",
      "email": "camp2024-01@kubdev.local",
      "status": "deleted"
    },
    {
      "user_id": 150,
      "username": "camp2024-50",
      "email": "camp2024-50@kubdev.local",
      "status": "failed",
      "reason": "Active environment deletion failed"
    }
  ],
  "dry_run": false,
  "timestamp": "2024-11-16T11:00:00Z"
}

실제 사용 시나리오

시나리오 1: 신입 부트캠프 100명 온보딩

# 1단계: React 환경 템플릿 생성 (Dockerfile 자동생성)
curl -X POST "http://localhost:8000/api/v1/templates/generate-dockerfile" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stack_config": {
      "language": "node",
      "version": "18",
      "framework": "react",
      "dependencies": ["axios", "react-router-dom", "styled-components"],
      "exposed_ports": [3000],
      "environment_variables": {
        "NODE_ENV": "development"
      }
    },
    "environment_id": "bootcamp-react-2024",
    "validate_only": false
  }'

# 2단계: 100명 계정 일괄 생성
curl -X POST "http://localhost:8000/api/v1/admin/users/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prefix": "bootcamp2024",
    "count": 100,
    "template_id": 1,
    "resource_quota": {
      "cpu": "1",
      "memory": "2Gi",
      "storage": "10Gi"
    }
  }'

# 결과: 5-10분 내 100개 IDE 환경 완성
# - bootcamp2024-01.ide.kubdev.io
# - bootcamp2024-02.ide.kubdev.io
# - ...
# - bootcamp2024-100.ide.kubdev.io

시나리오 2: 개별 신입 개발자 온보딩

# Python FastAPI 환경 즉시 생성
curl -X POST "http://localhost:8000/api/v1/admin/users/single" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "junior-kim",
    "template_id": 3,
    "password": "welcome123!",
    "resource_quota": {
      "cpu": "2",
      "memory": "4Gi",
      "storage": "20Gi"
    }
  }'

# 결과: 3-5초 내 https://junior-kim.ide.kubdev.io 접속 가능

시나리오 3: 교육 종료 후 정리

# 1. 미리보기 (dry_run=true)
curl -X DELETE "http://localhost:8000/api/v1/admin/users/batch?prefix=bootcamp2024&dry_run=true" \
  -H "Authorization: Bearer $TOKEN"

# 2. 실제 삭제 (dry_run=false)
curl -X DELETE "http://localhost:8000/api/v1/admin/users/batch?prefix=bootcamp2024&dry_run=false" \
  -H "Authorization: Bearer $TOKEN"

# 결과: 모든 bootcamp2024-* 계정 및 K8s 리소스 정리

🔧 성능 지표

지표 성능
단일 환경 생성 시간 3-5초
대량 생성 (100명) 5-10분
동시 생성 제한 10개 (세마포어)
최대 일괄 생성 200명
자동 만료 시간 8시간 (설정 가능)
지원 언어 4개 (Node.js, Python, Java, Go)
지원 프레임워크 15+ 개

Clone this wiki locally