Actuator 상태 확인¶

spakky-actuator로 health, readiness, liveness, info 상태를 전송 방식과 독립적으로 모으는 방법을 설명합니다.

spakky-actuator는 애플리케이션 상태를 전송 방식과 독립적인 모델로 집계합니다. FastAPI와 Typer 플러그인은 같은 core result를 HTTP 엔드포인트나 CLI 명령으로 노출합니다.

의미 구분¶

표면	용도	실패 기준
`health`	운영자가 보는 전체 상태	필수 probe 중 하나라도 비정상이면 비정상
`readiness`	트래픽이나 작업을 받을 준비 여부	외부 의존성 등 준비 상태 probe 실패를 반영
`liveness`	프로세스와 프레임워크 기본 생존 여부	readiness와 분리되며 기본 probe가 없으면 정상 baseline
`info`	앱 버전, 빌드, 런타임 metadata	등록된 contributor payload를 결정적으로 병합

기본 health probe는 health와 readiness에만 참여합니다. liveness는 데이터베이스, 브로커, 외부 API 같은 의존성 readiness와 분리해야 합니다.

애플리케이션 등록¶

from spakky.actuator import (
    AbstractHealthProbe,
    ActuatorAggregationService,
    ActuatorEndpoint,
    ComponentHealthResult,
)
from spakky.core.application.application import SpakkyApplication
from spakky.core.application.application_context import ApplicationContext
from spakky.core.application.plugin import Plugin
from spakky.core.pod.annotations.pod import Pod


@Pod()
class DatabaseProbe(AbstractHealthProbe):
    @property
    def name(self) -> str:
        return "database"

    def check(self) -> ComponentHealthResult:
        return ComponentHealthResult.healthy(self.name)


@Pod()
class ProcessProbe(AbstractHealthProbe):
    @property
    def name(self) -> str:
        return "process"

    @property
    def endpoints(self) -> tuple[ActuatorEndpoint, ...]:
        return (ActuatorEndpoint.LIVENESS,)

    def check(self) -> ComponentHealthResult:
        return ComponentHealthResult.healthy(self.name)


app = (
    SpakkyApplication(ApplicationContext())
    .load_plugins(include={Plugin(name="spakky-actuator")})
    .add(DatabaseProbe)
    .add(ProcessProbe)
    .start()
)
service = app.container.get(type_=ActuatorAggregationService)
readiness = service.evaluate_readiness()
liveness = service.evaluate_liveness()

ComponentHealthResult.unhealthy(..., required=False)는 component 자체는 unhealthy로 보존하지만 aggregate status를 실패시키지 않습니다. SPAKKY_ACTUATOR_INCLUDE_DETAILS=false를 설정하면 component details 노출을 제한합니다.

DI 확장¶

애플리케이션에서는 probe와 info contributor를 Pod로 등록하면 됩니다. spakky-actuator plugin이 ActuatorExtensionPostProcessor를 등록하고, DI가 관리하는 extension을 ActuatorExtensionRegistry에 모읍니다.

from collections.abc import Mapping

from spakky.actuator import IInfoContributor
from spakky.core.pod.annotations.pod import Pod


@Pod()
class BuildInfo(IInfoContributor):
    @property
    def name(self) -> str:
        return "build"

    def contribute_info(self) -> Mapping[str, object]:
        return {"version": "1.0.0"}

비동기 probe와 비동기 info contributor도 지원합니다. 동기 평가 메서드에서 비동기 extension이 발견되면 명시적 actuator 에러가 발생하므로, 비동기 transport에서는 evaluate_*_async()를 사용하세요.

FastAPI 노출¶

spakky-actuator와 spakky-fastapi를 함께 로드하면 다음 route가 등록됩니다.

Route	정상	비정상
`GET /actuator/health`	`200 OK`	`503 Service Unavailable`
`GET /actuator/readiness`	`200 OK`	`503 Service Unavailable`
`GET /actuator/liveness`	`200 OK`	`503 Service Unavailable`
`GET /actuator/info`	`200 OK`	N/A

운영 환경 노출

FastAPI actuator route는 기본적으로 인증을 자동 적용하지 않습니다. 활성화하면 애플리케이션이 내부망, API 게이트웨이, 리버스 프록시 허용 목록, 또는 별도의 접근 제어 계층 뒤에 두지 않는 한 일반 공개 HTTP route입니다. 운영 환경에서는 필요 없는 endpoint를 끄고, base path를 내부 route 아래로 옮기며, 신뢰 경계 밖으로 actuator traffic을 노출하기 전에 SPAKKY_ACTUATOR_INCLUDE_DETAILS=false를 설정하세요.

FastAPIActuatorConfig는 spakky-fastapi 플러그인이 @Configuration Pod로 등록합니다. base path와 endpoint별 노출 여부는 환경변수로 조정합니다.

export SPAKKY_ACTUATOR_INCLUDE_DETAILS=false
export SPAKKY_FASTAPI_ACTUATOR_BASE_PATH=/internal/actuator
export SPAKKY_FASTAPI_ACTUATOR_READINESS_ENABLED=false

Typer 노출¶

spakky-actuator와 spakky-typer를 함께 로드하면 actuator 명령 그룹이 등록됩니다.

python main.py actuator health
python main.py actuator readiness
python main.py actuator liveness
python main.py actuator info

ActuatorTyperConfig는 spakky-typer 플러그인이 @Configuration Pod로 등록합니다. 다음 환경변수로 명령 노출을 제어합니다.

export SPAKKY_TYPER_ACTUATOR_COMMAND_ENABLED=false
export SPAKKY_TYPER_ACTUATOR_COMMAND_NAME=status

Backend 제공 Probe¶

Actuator core는 전송 방식과 독립적인 registry와 aggregation을 담당합니다. Backend plugin은 자신이 소유한 외부 의존 상태를 기본 probe/contributor로 등록할 수 있습니다.

spakky-redis는 RedisCacheHealthProbe와 RedisCacheMetricsInfoContributor를 등록하여 Redis 연결 상태와 cache metrics를 actuator health/info 표면에 노출합니다. SQLAlchemy, Kafka/RabbitMQ, Celery 같은 다른 backend도 같은 AbstractHealthProbe / IInfoContributor 계약으로 확장합니다.