FerretDB 스택 — 모듈로 구성된 문서 데이터베이스
이 예제는 작지만 실제로 동작하는 스택, 즉 MongoDB 와이어 프로토콜을 제공하는 문서 데이터베이스를
Developer가 작성한 하나의 Aggregate에서 합성된 Kubernetes 매니페스트로 컴파일합니다.
문서 데이터베이스는 단일 컴포넌트가 아닙니다. 이는 모듈, 즉 단일 워크로드 컴포넌트 두 개를 구성하는 재사용 가능한 하위 aggregate입니다.
- MongoDB 와이어 프로토콜을 사용하며 로컬 상태를 갖지 않는 프록시, 그리고
- 데이터를 볼륨에 영속적으로 저장하는, DocumentDB 확장이 적용된 PostgreSQL 17인 백엔드입니다.
모듈은 프록시에서 백엔드로 향하는 자체 내부 엣지를 연결하고, 프록시를 공개 엔드포인트 mongo로
내보냅니다. 최상위 Aggregate는 이름으로 모듈을 가져와 구성된 스택을 렌더링하며, 운영자는
Release에서 모듈의 내부 컴포넌트 크기를 지정합니다.
파일
| 파일 | 역할 |
|---|---|
aggregate.yaml | Developer 의도: 문서 데이터베이스 모듈(core/ferretdb)을 가져옵니다. |
manifest-helm-synth.yaml | 프록시 및 백엔드 타입을 해당 synth helm Recipes에 매핑합니다. |
release-helm-synth.yaml | Kubernetes 대상에 대한 운영자 레코드입니다. 모듈 범위 ID로 모듈의 내부 컴포넌트 크기를 지정하며, 스키마 기본값에 맡긴 항목은 자체 완결적으로 렌더링됩니다. |
보여 주는 내용
- 모듈로서의 구성. 다중 워크로드 기능, 즉 실제로는 프록시와 스토리지 백엔드로 이루어진 문서 데이터베이스를 하나의 단일 컴포넌트가 아니라 단일 워크로드 컴포넌트 두 개를 구성하는 하위 aggregate로 패키징합니다. 모듈은 이름으로 가져오며 문서 데이터베이스가 필요한 곳 어디서나 재사용됩니다.
- 모듈 내부의 엣지. 프록시는 백엔드 사용을 선언합니다. 백엔드 Recipe의
provides호스트, 포트, 사용자, 데이터베이스가 프록시로 전달되어 프록시의 PostgreSQL 연결로 구성됩니다. 컴파일러는 이 문자열을 해석하지 않고 라우팅합니다. - 공개 엔드포인트. 모듈은 프록시를
mongo로 내보냅니다. 이는 문서 데이터베이스 소비자가 연결하는 안정적인 공개 이름으로, 모듈의 내부 컴포넌트 이름과 분리되어 있습니다. - 운영자의 내부 컴포넌트 크기 지정. Release는 모듈 범위 ID(
database.backend,database.proxy)로 모듈의 내부 컴포넌트를 지정하여 컴퓨팅을 설정하며, 개발자의 Aggregate에서 물리적 크기를 다시 기술할 필요가 없습니다. - 공유 자격 증명. 프록시는 인증을 PostgreSQL 백엔드에 위임하므로 두 컴포넌트는 하나의 비밀번호를 공유합니다. 이 예제는 공유 인라인 개발용 기본값을 사용하므로 스택은 외부 시크릿 없이 자체 완결적으로 실행됩니다.
- 비밀번호 없는 연결 문자열. 프록시의 PostgreSQL 연결 URL은 비밀번호를 포함하지 않고
렌더링됩니다. 비밀번호는 표준 libpq
PGPASSWORD환경 변수로 별도 제공되며, 드라이버가 이를 연결에 병합합니다. 이렇게 하면 렌더링된 매니페스트의 연결 문자열에 자격 증명이 포함되지 않습니다. - 재현 가능한 이미지. 프록시와 백엔드 모두 명시적인 이미지 태그를 고정하므로, 렌더링된 매니페스트는 안정적인 이미지를 참조합니다.
예제 생성하기
아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.
예제 이름을 딴 새 폴더에 예제를 씁니다:
aggrega scaffold --example ferretdb-stack그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:
cd ferretdb-stack빌드
이 워크스페이스에는 .aggrega-config.yaml이 없으므로 표준 라이브러리 엔터티는 허브 레지스트리 hub.aggrega.ai에서 해석되며 카탈로그 플래그가 필요하지 않습니다. --auto-pull은 새 클론에 없는 lockfile을 빌드 중에 기록합니다.
aggrega build --release release-helm-synth.yaml --auto-pull렌더링된 아티팩트는 dist/ 아래에 생성됩니다. Kubernetes 대상은 오프라인으로
일반 매니페스트를 렌더링하므로 차트를 가져올 필요가 없습니다.
AI 어시스턴트 사용
Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고, 폴더는 직접 만들지 마십시오. 작업 영역 폴더에 아직 `ferretdb-stack` 폴더가 없으면 `example`을 `ferretdb-stack`으로 설정하고 `dir`은 지정하지 않은 채 `scaffold` 도구를 한 번 호출하십시오. 이 도구는 예제를 새 `ferretdb-stack` 폴더에 씁니다. 그런 다음 `workspace_root`를 `ferretdb-stack`으로, `release`를 `release-helm-synth.yaml`로, `auto_pull`을 true로, `write`를 true로 설정하여 `build` 도구를 호출하십시오. 빌드가 쓴 파일을 알려 주십시오. 파일은 `ferretdb-stack/dist/` 아래에 있습니다.구성된 스택의 모습
프록시는 상태 없는 Deployment와 와이어 포트의 ClusterIP Service로 렌더링됩니다. 컨테이너 환경에는 백엔드 엣지에서 구성된 연결, 즉 백엔드의 클러스터 내 Service 이름, 사용자, 데이터베이스가 URL에 비밀번호 없이 담기며, FerretDB의 디버그 리스너는 다른 파드가 접근할 수 없는 파드의 루프백 주소에 유지됩니다.
env: - name: FERRETDB_LISTEN_ADDR value: :27017 - name: FERRETDB_DEBUG_ADDR value: 127.0.0.1:8088 - name: FERRETDB_POSTGRESQL_URL value: postgres://postgres@database-zdbackend-default:5432/postgres - name: PGPASSWORD value: apppass두 프로브 모두 이 리스너가 필요하지 않습니다. 준비성 프로브는 컨테이너 안에서 ferretdb ping을
실행하는데, 이는 와이어 포트에 ping을 보내므로 백엔드 연결도 함께 확인합니다. 활성 프로브는 와이어
포트가 연결을 수락하는지만 확인하므로, 백엔드 장애 시 프록시는 재시작되지 않고 Service에서만
제외됩니다.
livenessProbe: tcpSocket: port: 27017readinessProbe: exec: command: - /ferretdb - ping백엔드는 /var/lib/postgresql/data에 영구 볼륨이 마운트된 StatefulSet과 ClusterIP Service,
헤드리스 Service로 렌더링됩니다.