[Kubernetes Platform Lab] #1. Python/FastAPI 샘플 애플리케이션 구성

이전 글에서 전체 프로젝트의 목표 아키텍처와 구축 계획을 정리하였으며, 이번에는 Kubernetes에 배포할 FastAPI 샘플 애플리케이션을 구성합니다.

추후 Kubernetes의 Liveness/Readiness Probe와 연동할 Health Check API와 Pod별 응답을 확인하기 위한 애플리케이션 정보 API를 함께 구성합니다.

 

 

 

1. 프로젝트 구조

프로젝트는 애플리케이션 코드와 테스트 코드를 분리하여 다음과 같이 구성하였습니다.

k8s-platform-lab/
├── app/
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── health.py
│   │   └── info.py
│   ├── __init__.py
│   ├── config.py
│   └── main.py
│
├── tests/
│   ├── __init__.py
│   ├── test_health.py
│   └── test_info.py
│
├── .dockerignore
├── .gitignore
├── Dockerfile
├── README.md
└── requirements.txt

app 디렉토리에는 FastAPI 애플리케이션과 API Router를 구성하고, tests 디렉토리에는 각 API의 동작을 확인하기 위한 테스트 코드를 구성하였습니다.

Docker 관련 파일은 다음 단계에서 컨테이너 이미지를 생성하기 위해 프로젝트 Root 경로에 위치시켰습니다.

 

 

 

2. FastAPI 애플리케이션 구성

main.py를 애플리케이션의 Entry Point로 구성하고 Health Check와 애플리케이션 정보 API를 각각 Router로 분리하였습니다.

from fastapi import FastAPI

from app.routers import health, info

app = FastAPI(
    title="Kubernetes Platform Lab",
    description="Sample FastAPI application for Kubernetes platform lab",
    version="1.0.0",
)

app.include_router(health.router)
app.include_router(info.router)


@app.get("/")
def root():
    return {
        "message": "Kubernetes Platform Lab",
        "status": "running",
    }

 

 

 

현재 애플리케이션에서 제공하는 API는 다음과 같습니다.

Method	API	용도
GET	/	애플리케이션 기본 상태 확인
GET	/api/info	애플리케이션 및 실행 환경 확인
GET	/health/live	Liveness Check
GET	/health/ready	Readiness Check

애플리케이션 자체의 기능보다는 이후 Kubernetes 환경에서 배포 및 운영 상태를 확인하는 데 필요한 API 위주로 구성하였습니다.

 

 

 

 

 

3. Health Check API 구성

Kubernetes에서는 실행 중인 컨테이너의 상태를 확인하기 위해 Liveness Probe와 Readiness Probe를 사용할 수 있습니다.

추후 해당 기능과 연동하기 위해 /health/live, /health/ready API를 미리 구성하였습니다.

from fastapi import APIRouter

router = APIRouter(
    prefix="/health",
    tags=["Health"],
)


@router.get("/live")
def liveness():
    return {
        "status": "UP",
    }


@router.get("/ready")
def readiness():
    return {
        "status": "READY",
    }

 

 

 

두 API는 현재 단순한 상태 값만 반환하도록 구성하였으며, 이후 Kubernetes Deployment 구성 시 각각 livenessProbe, readinessProbe의 HTTP Endpoint로 사용할 예정입니다.

/health/live
      ↑
Liveness Probe


/health/ready
      ↑
Readiness Probe

 

 

 

 

4. 애플리케이션 정보 API 구성

여러 Pod가 실행되는 환경에서 어떤 Pod가 요청을 처리했는지 확인하기 위해 /api/info API를 추가하였습니다.

import socket

from fastapi import APIRouter

from app.config import APP_ENV, APP_NAME, APP_VERSION


router = APIRouter(
    prefix="/api",
    tags=["Application"],
)


@router.get("/info")
def application_info():
    return {
        "application": APP_NAME,
        "version": APP_VERSION,
        "environment": APP_ENV,
        "hostname": socket.gethostname(),
    }

 

응답에는 애플리케이션 이름과 버전, 실행 환경 및 Hostname을 포함합니다.

{
  "application": "k8s-platform-lab",
  "version": "1.0.0",
  "environment": "local",
  "hostname": "..."
}

 

 

특히 socket.gethostname()을 통해 현재 애플리케이션이 실행되고 있는 Hostname을 반환하도록 구성하였습니다.

추후 Kubernetes에서 Replica를 여러 개 구성한 후 Service를 통해 요청을 전달했을 때 각 요청을 처리한 Pod를 구분하는 데 활용할 예정입니다.

 

 

 

5. 환경별 설정 분리

애플리케이션 실행 환경에 따라 변경되는 값은 config.py에서 환경변수로 관리하도록 구성하였습니다.

 

import os


APP_NAME = os.getenv("APP_NAME", "k8s-platform-lab")
APP_VERSION = os.getenv("APP_VERSION", "1.0.0")
APP_ENV = os.getenv("APP_ENV", "local")

 

환경변수가 전달되지 않은 경우 기본값을 사용하고, 환경변수가 존재하는 경우 해당 값을 사용합니다.

현재는 로컬 환경에서 사용하지만 이후에는 다음과 같이 연결할 예정입니다.

 

 

Kubernetes ConfigMap
        ↓
   Environment
        ↓
   FastAPI Pod

 

이를 통해 애플리케이션 이미지를 환경별로 다시 생성하지 않고 설정값을 외부에서 전달할 수 있도록 구성합니다.

 

 

 

 

6. API 테스트 구성

작성한 API의 기본 동작을 확인하기 위해 pytest 기반 테스트 코드도 추가하였습니다.

Health Check API에서는 HTTP Status Code와 반환 값을 확인합니다.

def test_liveness():
    response = client.get("/health/live")

    assert response.status_code == 200
    assert response.json() == {
        "status": "UP",
    }

 

애플리케이션 정보 API에서는 기본 설정값과 Hostname 포함 여부를 확인합니다.

 

 

def test_application_info():
    response = client.get("/api/info")

    data = response.json()

    assert response.status_code == 200
    assert data["application"] == "k8s-platform-lab"
    assert data["version"] == "1.0.0"
    assert data["environment"] == "local"
    assert "hostname" in data

 

해당 테스트는 추후 Jenkins Pipeline의 테스트 단계에서도 동일하게 사용할 예정입니다.

 

 

GitHub
   ↓
Jenkins
   ↓
pytest
   ↓
Docker Build
   ↓
Image Push
   ↓
Kubernetes Deploy

 

테스트가 실패한 경우 컨테이너 이미지 빌드 및 배포 단계로 넘어가지 않도록 Pipeline을 구성할 예정입니다.

 

 

 

 

7. 로컬 실행 및 검증

 

FastAPI 애플리케이션을 실행합니다.

uvicorn app.main:app --reload

 

 

 

API별 동작은 다음 명령어를 통해 확인합니다.

curl http://localhost:8000/

curl http://localhost:8000/api/info

curl http://localhost:8000/health/live

curl http://localhost:8000/health/ready

 

 

 

 

✅ API 실행 결과

 

 

 

 

✅ 테스트 결과

pytest -v

 

 

 

 

✍️ 요약 및 회고

Kubernetes에 애플리케이션을 배포하기에 앞서 Python/FastAPI 기반의 간단한 샘플 애플리케이션을 구성하였습니다.

단순 API 실행뿐만 아니라 이후 Kubernetes 환경에서 활용할 수 있도록 Liveness/Readiness Check API와 실행 중인 인스턴스를 구분하기 위한 Hostname 정보를 함께 구성하였습니다.

또한 애플리케이션 설정값을 환경변수로 분리하여 이후 Kubernetes ConfigMap과 연결할 수 있도록 구성하고, Jenkins Pipeline에서 사용할 기본 테스트 코드도 함께 작성하였습니다.

 

 

다음 단계에서는 현재 로컬에서 실행 중인 FastAPI 애플리케이션을 Docker 이미지로 빌드하고 컨테이너 환경에서도 동일하게 동작하는지 확인해보겠습니다.