52개 문서가 "adr" 태그에 분류되었습니다

2026년 3월 Aerospike CE Ecosystem 주요 의사결정 기록

Architecture Decision Record 작성을 위한 표준 템플릿. 새 ADR 작성 시 이 템플릿을 복사하여 사용.

aerospike-py에서 C FFI(CFFI) 대신 Rust/PyO3를 바인딩 기술로 선택한 아키텍처 결정 기록.

ACKO에서 Kubernetes Operator 프레임워크로 Kubebuilder v4와 controller-runtime을 선택한 아키텍처 결정 기록.

로컬 개발 환경의 컨테이너 런타임으로 Docker 대신 Podman을 선택한 아키텍처 결정 기록.

aerospike-py에서 레코드 결과를 dict 대신 NamedTuple로 반환하도록 선택한 아키텍처 결정 기록.

Cluster Manager에서 DaisyUI를 제거하고 Tailwind CSS 4 + Radix UI로 전환한 아키텍처 결정 기록.

aerospike-py에서 동시 요청 과부하 방지를 위한 Semaphore 기반 backpressure를 도입한 아키텍처 결정 기록.

ACKO에서 AerospikeClusterTemplate을 namespace-scoped에서 cluster-scoped로 변경한 아키텍처 결정 기록.

GitHub Issues에서 claude-code-action을 통해 AI 에이전트가 자동으로 코드를 생성하고 PR을 제출하는 IssueOps 워크플로우 도입 결정.

aerospike-py의 batch 연산 반환 타입을 BatchRecords NamedTuple로 통일하여 API 일관성과 per-record 에러 추적을 개선한 결정.

aerospike-py에 Logging(Rust tracing) + Metrics(Prometheus) + Tracing(OpenTelemetry) 3계층 관측성 스택을 도입한 아키텍처 결정.

AerospikeCECluster CRD를 AerospikeCluster로 리네이밍한 아키텍처 결정 기록. 중복된 CE 접두사 제거로 API 표면 단순화.

Aerospike 클러스터 메시 합류 및 마이그레이션 완료를 보장하기 위해 커스텀 Pod Readiness Gate(acko.io/aerospike-ready)를 도입한 아키텍처 결정 기록.

무한 reconciliation 루프 방지를 위해 5분 context timeout, 지수 백오프, 10회 연속 실패 시 circuit breaker를 도입한 아키텍처 결정 기록.

cluster-manager의 데이터베이스를 SQLite에서 PostgreSQL(asyncpg)로 마이그레이션하고, SQLite를 개발용 fallback으로 유지한 아키텍처 결정 기록.

ACKO에서 TCP probe 대신 asinfo 명령어 기반 liveness/readiness check를 도입하여 정확한 Aerospike 노드 상태를 감지하도록 한 아키텍처 결정 기록.

Cluster Manager에서 폴링 방식 대신 Server-Sent Events(SSE)를 도입하여 실시간 클러스터 상태 이벤트를 스트리밍하는 아키텍처 결정.

ACKO의 reconciliation circuit breaker 고정 임계값을 에러 유형별 차등 임계값으로 개선하는 제안에 대한 검토 결과. 운영 데이터 부재로 보류.

aerospike-py의 batch 작업 retry에 Full Jitter 패턴을 도입하여 thundering herd 문제를 방지하고 서버 부하를 분산하는 아키텍처 결정.

Cluster Manager에서 FastAPI OpenAPI 스키마를 기반으로 TypeScript 타입을 자동 생성하여 Backend↔Frontend 타입 동기화를 자동화하는 아키텍처 결정.

Cluster Manager 레코드 브라우저에 TanStack Virtual 기반 가상 스크롤을 도입하여 대용량 레코드 렌더링 성능을 개선하는 아키텍처 결정.

ACKO operator의 Pause/Resume 상태 전환 시 Status Condition 불일치 문제를 해결하기 위해 원자적 업데이트와 Resume condition 리셋을 도입하는 아키텍처 결정.

aerospike-py의 Tokio runtime worker thread 수를 CPU 코어 기반 heuristic으로 자동 결정하고, RuntimeMetrics를 Prometheus 메트릭으로 노출하는 아키텍처 결정.

Cluster Manager Backend에서 클라이언트 연결 끊김 시 장시간 실행 중인 비동기 연산(scan, query, K8s API)을 Graceful하게 취소하는 전략 도입.

Cluster Manager의 K8s 클러스터 목록 API에 Kubernetes 네이티브 cursor 기반 pagination과 namespace 필터링을 도입하여 대규모 환경 확장성을 확보하는 아키텍처 결정.

ACKO의 기존 ValidationError 타입을 활용하여 영구적 오류를 즉시 식별하고 Circuit Breaker를 즉시 활성화함으로써 불필요한 재시도를 방지하는 아키텍처 결정.

aerospike-py의 모든 AerospikeError 하위 예외에 result_code 정수 속성을 추가하여, 문자열 매칭 대신 안정적인 정수 코드 기반 에러 분류를 지원하는 아키텍처 결정.

Cluster Manager에서 개별 Aerospike info 호출을 세미콜론 구분자 기반 배치 호출로 통합하고 TTL 캐시를 도입하여 클러스터 Overview 응답 시간을 75% 단축하는 아키텍처 결정.

Cluster Manager에서 set object count 조회 실패 시 0 대신 None을 반환하여 "알 수 없음" 상태를 명시적으로 표현하고, 프론트엔드 pagination 정상 동작을 보장하는 아키텍처 결정.

ACKO의 동적 설정 변경 시 부분 적용을 방지하기 위해 Two-Phase Commit 패턴과 ConfigDegraded 상태 전환을 도입하는 전략

ACKO의 Pod readiness 확인을 10초 간격 polling에서 Kubernetes Informer watch로 전환하고, status enrichment의 Aerospike 노드 정보 수집을 병렬화하여 reconciliation 성능을 개선하는 아키텍처 결정.

ACKO webhook에 replication-factor, 포트 충돌, batch size 검증을 추가하여 런타임 오류를 admission 단계에서 차단하는 아키텍처 결정

aerospike-py AsyncClient에서 동시 connect() 호출 시 발생하는 연결 누수를 AtomicBool guard와 상태 머신으로 방지하고, close() 후 재연결 시 전체 상태를 초기화하는 아키텍처 결정.

Cluster Manager API에 JWT 기반 인증/인가(RBAC)를 도입하고 보안 헤더(HSTS, CORS 검증)를 강화하여 프로덕션 배포 가능성을 확보하는 아키텍처 결정.

ClientManager의 double-checked locking race condition을 per-connection-id AsyncLock으로 해결하고, string 기반 에러 감지를 구조화된 result_code 기반으로 전환하는 아키텍처 결정.

Cluster Manager 프론트엔드에서 폴링 메모리 누수, AbortController 미사용, 상태 초기화 누락, 에러 정보 미노출 문제를 해결하는 표준 패턴 도입.

Cluster Manager 초기 로딩 시 순차 health check를 병렬화하고, 연결 실패 시 에러 유형을 UI에 표시하여 디버깅 편의성을 개선

Kubernetes 외부 클라이언트가 ACKO로 배포된 Aerospike 클러스터에 접근할 수 있도록 per-pod LoadBalancer/NodePort 서비스, Seeds Finder LB, init container 기반 자동 LB IP 주입을 도입하는 아키텍처 결정.

ACKO의 E2E 테스트를 시나리오별 독립 테스트 스위트와 CI matrix 병렬 실행으로 확장하는 전략 결정.

ACKO의 CRD와 Operator를 독립된 Helm chart로 분리하고 GHCR OCI Registry를 통해 배포하는 버전 관리 체계에 대한 아키텍처 결정.

aerospike-py의 NumPy batch 연산에서 Owned Arrays를 기본 메모리 모델로 확정하고, API surface를 안정화하는 아키텍처 결정.

aerospike-py의 OTel Tracing을 완성하고 cluster-manager까지 trace context를 전파하는 아키텍처 결정. Metrics는 Prometheus 유지.

Project-hub의 ADR lifecycle을 AI 리뷰, cross-repo 디스패치, 상태 관리 3단계로 자동화하는 워크플로우 아키텍처를 문서화하고 표준화하는 결정.

Record 브라우저에서 대용량 데이터셋을 안정적으로 탐색하기 위해 가상 스크롤, cursor 기반 pagination, 3계층 timeout을 통합하는 상위 아키텍처 결정.

Core repo(aerospike-py, ACKO, cluster-manager)의 API/파일 변경이 plugin skill에 미치는 영향을 자동 감지하고 project-hub를 거쳐 plugins repo에 구현 이슈를 디스패치하는 cross-repo 파이프라인 도입 결정.

Cross-repo 변경 전파 시 의존성 체인 순서를 ADR로 공식화하고, 점진적 CI 검증을 도입하는 원칙을 정의합니다.

4개 core repo에서 매일 KST 09:00에 Conventional Commits 분석 기반 SemVer 자동 릴리스를 실행하는 daily-release 파이프라인의 아키텍처 결정 문서화.

에코시스템 5개 repo의 CI 워크플로우(agent-implement, pr-reviewer, issue-planner, daily-release, skill-impact-notify) 적용 범위를 표준화하고 공유 설정 관리 방식을 문서화하는 결정.

ACKO Helm chart를 multi-cluster 토폴로지(common + per-environment operator cluster)로 확장하고, FastAPI native JWT 검증 + Keycloak external IdP를 표준 인증 수단으로 채택하는 결정.

다수의 Aerospike Cluster Manager (ACM) 인스턴스가 노출하는 /mcp 엔드포인트를 단일 진입점으로 묶어 LLM 에이전트에게 한 번의 등록으로 노출하는 federation gateway 설계 결정.

Aerospike CE Ecosystem의 주요 아키텍처 결정 기록(ADR) 목록과 작성 가이드.