콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

Keycloak 스택 — 모듈로 구성된 데이터베이스 기반 ID 서버

이 예제는 Developer가 작성한 하나의 Aggregate에서 작지만 실제적인 스택인 데이터베이스 기반 ID 서버를 합성된 Kubernetes 매니페스트로 컴파일합니다.

ID 서버는 단일 컴포넌트가 아닙니다. 이는 모듈, 즉 단일 워크로드 컴포넌트 두 개를 구성하는 재사용 가능한 하위 aggregate입니다.

  • HTTP 포트에서 계정 콘솔과 토큰 엔드포인트를 제공하며 로컬 상태를 보유하지 않는 서버, 그리고
  • 서버의 realm, 클라이언트, 사용자를 보유하고 이를 볼륨에 영구 저장하는 백엔드인 PostgreSQL.

모듈은 서버에서 백엔드로 향하는 자체 내부 엣지를 연결하고 서버를 공개 엔드포인트 http로 내보냅니다. 최상위 Aggregate는 모듈을 이름으로 가져와 구성된 스택을 렌더링하며, 운영자는 Release에서 모듈의 내부 컴포넌트 크기를 지정합니다.

파일

파일역할
aggregate.yamlDeveloper 의도: ID 서버 모듈(core/keycloak)을 가져옵니다.
manifest-helm-synth.yaml서버 및 백엔드 유형을 해당 synth helm Recipes에 매핑하고, 모듈이 연결하는 자격 증명 Feature를 모듈의 자격 증명 매개변수로부터 Secret을 생성하는 구현에 매핑합니다.
release-helm-synth.yamlKubernetes 대상에 대한 운영자 레코드입니다. 모듈 범위 ID로 모듈의 내부 컴포넌트 크기를 지정하며, 스키마 기본값에 맡긴 항목은 자체 완결적으로 렌더링됩니다.

보여 주는 내용

  • 모듈로서의 구성. 다중 워크로드 기능, 즉 실제로는 서버와 구성 데이터베이스로 이루어진 ID 서버는 하나의 모놀리식 컴포넌트가 아니라 단일 워크로드 컴포넌트 두 개를 구성하는 하위 aggregate로 패키징됩니다. 모듈은 이름으로 가져오며 ID 서버가 필요한 곳 어디에서나 재사용됩니다.
  • 모듈 내부의 엣지. 서버는 백엔드 사용을 선언하며, 백엔드 Recipe의 provides 호스트, 포트, 사용자, 데이터베이스가 서버로 전달되어 데이터베이스 연결로 구성됩니다. 컴파일러는 문자열을 해석하지 않고 라우팅합니다.
  • 공개 엔드포인트. 모듈은 서버를 http로 내보냅니다. 이는 소비자가 연결하는 안정적인 공개 이름으로, 모듈의 내부 컴포넌트 이름과 분리되어 있습니다.
  • 내부 컴포넌트에 대한 운영자의 크기 지정. Release는 모듈 범위 ID(server.backend, server.server)로 모듈의 내부 컴포넌트를 지정하여 컴퓨팅을 설정하며, 개발자의 Aggregate가 물리적 크기를 다시 명시할 필요가 없습니다.
  • 자체 마이그레이션 스키마. 서버는 시작 시 백엔드에 대해 자체 스키마를 프로비저닝하고 마이그레이션하므로, 별도의 마이그레이션 단계 없이 준비된 스키마로 시작합니다.
  • 참조로 받는 공유 자격 증명. 서버는 PostgreSQL 백엔드에 인증하므로 두 워크로드가 하나의 비밀번호를 공유합니다. 모듈은 이를 매개변수 db_password로 받고, core/referenced-secret 자격 증명 Feature를 이 값으로 두 번 연결합니다. 한 번은 백엔드 자체의 자격 증명 슬롯에, 다른 한 번은 서버가 백엔드에 연결할 때의 credential로, 즉 서버가 이 비밀번호를 제시하는 연결에 연결합니다. 각 워크로드는 비밀번호를 인라인으로 가지지 않고 Secret에서 읽으며, 부트스트랩 관리자 계정의 비밀번호는 두 번째 매개변수 admin_password입니다. 모듈이 해당 Feature를 연결하므로 Manifest가 이를 매핑합니다. 이 예제는 두 매개변수를 모듈의 개발용 기본값으로 두고 Feature를 k8s-secret-from-parameter에 매핑합니다. 이는 각 값을 담은 Secret을 생성하므로 스택이 자체 완결적으로 실행됩니다. 실제 트래픽을 처리하는 Release의 경우, Aggregate가 자체 매개변수를 선언하여 aggregates.server.parameters를 통해 하위로 전달하고, Release가 이를 채우며, Manifest는 Feature를 k8s-existing-secret에 매핑합니다. 이는 각 매개변수를 네임스페이스에 이미 존재하는 Secret의 이름으로 읽습니다.
  • 재현 가능한 이미지. 서버와 백엔드 모두 명시적인 이미지 태그를 고정하므로, 렌더링된 매니페스트는 안정적인 이미지를 참조합니다.

예제 생성하기

아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.

예제 이름을 딴 새 폴더에 예제를 씁니다:

Terminal window
aggrega scaffold --example keycloak-stack

그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:

Terminal window
cd keycloak-stack

빌드

이 워크스페이스에는 .aggrega-config.yaml이 없으므로 표준 라이브러리 엔터티는 허브 레지스트리 hub.aggrega.ai에서 해석되며 카탈로그 플래그가 필요하지 않습니다. --auto-pull은 새 클론에 없는 lockfile을 빌드 중에 기록합니다.

Terminal window
aggrega build --release release-helm-synth.yaml --auto-pull

렌더링된 아티팩트는 dist/ 아래에 생성됩니다. Kubernetes 대상은 오프라인으로 일반 매니페스트를 렌더링하므로 차트를 가져올 필요가 없습니다.

AI 어시스턴트 사용

Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.

Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 작업 공간 폴더에 아직 `keycloak-stack` 폴더가 없으면 `example`에 `keycloak-stack` 값을 지정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 예제가 새 `keycloak-stack` 폴더에 작성됩니다. 그런 다음 `workspace_root` 값은 `keycloak-stack`, `release` 값은 `release-helm-synth.yaml`, `auto_pull` 값은 true, `write` 값은 true로 설정하여 `build` 도구를 호출하십시오. 빌드가 작성한 파일을 알려 주십시오. 파일은 `keycloak-stack/dist/` 아래에 있습니다.

구성된 스택의 모습

서버는 상태 비저장 Deployment와 HTTP 포트의 ClusterIP Service로 렌더링됩니다. 컨테이너에는 백엔드 엣지에서 구성된 연결(백엔드의 클러스터 내 Service 이름, 사용자, 데이터베이스)과 자체 완결적인 HTTP 설정, 활성화되어 관리 포트에서 제공되는 상태 엔드포인트, 부트스트랩 관리자 계정이 포함되며, 두 비밀번호는 모두 Secret에서 읽습니다.

env:
- name: KC_DB_PASSWORD
valueFrom:
secretKeyRef:
name: server-zdserver-db.credential
key: db-password
- name: KC_BOOTSTRAP_ADMIN_PASSWORD
valueFrom:
secretKeyRef:
name: server-zdserver-admin-password
key: admin-password
- name: KC_DB
value: postgres
- name: KC_DB_URL_HOST
value: server-zdbackend-default
- name: KC_DB_URL_PORT
value: "5432"
- name: KC_DB_URL_DATABASE
value: keycloak
- name: KC_DB_USERNAME
value: keycloak
- name: KC_HTTP_ENABLED
value: "true"
- name: KC_HOSTNAME_STRICT
value: "false"
- name: KC_HEALTH_ENABLED
value: "true"
- name: KC_HTTP_MANAGEMENT_PORT
value: "9000"
- name: KC_BOOTSTRAP_ADMIN_USERNAME
value: admin

컨테이너는 HTTP 포트 옆에 관리 포트 9000을 선언하며, Deployment는 그곳에서 서버를 프로브합니다. /health/started의 시작 프로브는 서버가 부팅되는 동안 다른 프로브를 보류하고, /health/ready의 준비 상태 프로브는 서버가 응답할 때까지 트래픽을 차단하며, /health/live의 활성 상태 프로브는 서버가 멈추면 재시작합니다. Service는 여전히 HTTP 포트만 전달합니다.

백엔드는 /var/lib/postgresql/data에 마운트된 영구 볼륨을 가진 StatefulSet과 ClusterIP Service 및 헤드리스 Service로 렌더링됩니다. 백엔드의 POSTGRES_PASSWORD는 자체 Secret인 server-zdbackend-password에서 동일한 데이터베이스 비밀번호를 읽습니다. 세 개의 Secret은 워크로드 옆에 생성되며, 모듈이 연결하는 자격 증명마다 하나씩, 각각 모듈의 개발용 기본값을 담습니다.