13개 작업 묶음(P1–P13)의 W2 커밋을 합치고 전체 게이트로 검증했다. - 묶음별 정합성 수정(notification dispatch·recovery, object storage staged publication, fileserver 복구·정리, gRPC 플랫폼, Redis 분류·lease TTL, JPA outbox claim 순서·durable operation HTTP, web 요청 id·category 필수, graphql 에러 mapper, Mongo profile 바인딩, build 소스 보존 게이트·compose smoke info 확인) - 통합 때 드러난 3건 수정: outbox claim 테스트 fixture의 가짜 envelope hash, sample scan이 새 operation controller를 등록하던 문제, SpotBugs aux classpath 파일이 truncate되지 않아 로컬에서 ".jar.jar"로 실패하던 문제 - 현황표: 묶음 결과 반영, 소유자 결정 21–27, 후속 발견 결함 47행, 요약 갱신 - docs/capability-status.md 「제거된 코드」에 85행 추가 - 묶음 결과 파일·에이전트 지시·스크립트를 docs로 옮기고 desktop 재개 프롬프트 추가 검증: check, ci verifyDependencyLocks, mainCheck, architecture/public path/env keys/config contract, bootstrap·sample integration/system, build-logic·build-tools test, optional-platforms ci, qualificationBootJar 통과. integrationCheck는 이번 작업 전에도 실패하던 lane(Redis topology 모드 인자, httpclient failure injection, AWS 보호 lane)만 실패. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
259 lines
13 KiB
Markdown
259 lines
13 KiB
Markdown
# 설정 레퍼런스
|
|
|
|
> **Prefix.** Every property below binds under `app.messaging`, which is the prefix the deployed
|
|
> runtime and the `APP_MESSAGING_*` environment variables already use. Earlier revisions of this
|
|
> page documented a bare `messaging` prefix and the starter bound `backend.messaging`; neither
|
|
> bound what this page describes, so a deployment configured from it changed nothing. A key under
|
|
> either of the old prefixes now fails startup with a message naming the key — see
|
|
> `MessagingPrefixMigrationValidator`.
|
|
|
|
> **이 페이지는 실행된다.** 아래 YAML 블록은 `MessagingConfigurationBindingTest`가 이 파일에서 직접
|
|
> 읽어 컨텍스트에 올린다. 문서가 설명하는 모양이 곧 바인딩되는 모양이라는 뜻이고, 문서를 고치면서
|
|
> 코드를 고치지 않으면 테스트가 깨진다. 이전 판은 destination·broker·security 세 섹션을 설명했지만
|
|
> 어떤 binder도 그것을 읽지 않았다 — 문서대로 설정한 배포는 아무것도 바뀌지 않았고 아무 말도 듣지
|
|
> 못했다 (MSG-008).
|
|
|
|
## Application publish bridge identity
|
|
|
|
Application의 canonical integration event를 platform publish pipeline으로 보낼 때는
|
|
`app.messaging.producer-id`를 명시한다. 같은 값의 환경변수 이름은
|
|
`APP_MESSAGING_PRODUCER_ID`다. 이 값은 host/pod 이름이 아니라 배포와 무관하게 유지되는 논리적
|
|
producing-service identity다.
|
|
|
|
값이 없으면 `IntegrationEventPublishPort` bridge 자체를 만들지 않는다. `spring.application.name`이나
|
|
현재 process 이름으로 추론하지 않는다. 기존 legacy `OutboxEvent`/realtime 경로는 별도 cutover가
|
|
끝날 때까지 `app.messaging.broker` 경로를 유지한다.
|
|
|
|
## Outbox canonical transport-only cutover
|
|
|
|
`APP_OUTBOX_CANONICAL_TRANSPORT_ENABLED` / `ca-skeleton.outbox.canonical-transport-enabled`은
|
|
기존 `outbox_event` writer/claim/status authority를 유지한 채 canonical row의 **transport만** platform
|
|
publish path로 보내는 compatibility gate다. 기본값은 `false`이며 두 번째 relay를 만들지 않는다.
|
|
|
|
`true`일 때는 `OutboxAppendPort`가 `ValidatedIntegrationEvent`의 exact envelope bytes와 canonical
|
|
metadata를 기존 outbox row에 저장하고, claim된 canonical row는 `IntegrationEventPublishPort`로 간다.
|
|
legacy row는 계속 `MessageBroker`를 사용한다. 따라서 mixed-row compatibility 기간에는 relay가 켜져
|
|
있다면 `app.messaging.broker`도 계속 필요하며, canonical path를 위해 `IntegrationEventPublishPort`도
|
|
추가로 필요하다. legacy backlog가 0이라는 별도 증거 없이 broker 요구를 제거하지 않는다.
|
|
|
|
## Destination profile
|
|
|
|
```yaml
|
|
app:
|
|
messaging:
|
|
destinations:
|
|
order-events:
|
|
broker: kafka-primary
|
|
kind: EVENT_STREAM # ASYNC_COMMAND | DOMAIN_EVENT | INTEGRATION_EVENT
|
|
# | WORK_QUEUE | PUBLISH_SUBSCRIBE | EVENT_STREAM | REQUEST_REPLY
|
|
tier: M1 # M1 | M2 | M3
|
|
physical:
|
|
topic: order.events.v1
|
|
schema:
|
|
codec: application/json
|
|
compatibility: BACKWARD_TRANSITIVE
|
|
message-types: [order.created]
|
|
guarantees:
|
|
delivery: AT_LEAST_ONCE # AT_MOST_ONCE | AT_LEAST_ONCE
|
|
ordering: KEY # NONE | DESTINATION | PARTITION | KEY
|
|
external-side-effect: INBOX_TRANSACTIONAL
|
|
producer:
|
|
confirmation: REPLICATION_OR_PERSISTENCE_ACK
|
|
timeout: 5s
|
|
mandatory-routing: true
|
|
idempotent: true
|
|
consumer:
|
|
group: order-projection
|
|
concurrency: 1 # DESTINATION 순서를 요구하면 1이어야 한다
|
|
max-in-flight-per-ordering-unit: 1
|
|
prefetch: 16
|
|
handler-timeout: 30s
|
|
manual-settlement: false
|
|
retry:
|
|
mode: PAUSE_PARTITION # NONE | INLINE | BLOCKING | PAUSE_PARTITION
|
|
# | RETRY_DESTINATION | BROKER_DELAYED
|
|
max-attempts: 3
|
|
initial-delay: 200ms
|
|
max-delay: 2s
|
|
multiplier: 2.0
|
|
jitter: true
|
|
ordering-impact: PRESERVE # PRESERVE | ALLOW_REORDER
|
|
dlq:
|
|
destination: order-events-dlq
|
|
max-redrive-count: 1
|
|
payload:
|
|
max-bytes: 1048576
|
|
claim-check-threshold-bytes: 1048576
|
|
key-resolver-configured: true
|
|
production: false
|
|
topology-auto-create: false
|
|
order-events-dlq:
|
|
broker: kafka-primary
|
|
kind: WORK_QUEUE
|
|
guarantees:
|
|
delivery: AT_MOST_ONCE # terminal DLQ: another DLQ is not required
|
|
physical:
|
|
topic: order.events.v1.dlt
|
|
schema:
|
|
message-types: [order.created]
|
|
```
|
|
|
|
`dlq.destination`이 가리키는 destination도 선언되어야 한다. 선언되지 않은 이름은 부팅 실패이며,
|
|
메시지가 갈 곳 없는 DLQ 설정이 조용히 통과하지 않는다. `retry.destination`과 `dlq.destination`이
|
|
섞여 만드는 순환(A의 retry가 B로, B의 dlq가 A로)도 하나의 그래프로 검사되어 경로와 함께 거절된다.
|
|
|
|
## 기본값
|
|
|
|
| 설정 | 기본값 | 근거 |
|
|
|---|---:|---|
|
|
| logical payload 최대 | 1,048,576 bytes | portability. 초과는 Claim Check |
|
|
| global hard 최대 | 8,388,608 bytes | 어떤 destination도 넘을 수 없는 상한 |
|
|
| header 총 크기 | 32,768 bytes | |
|
|
| header 개수 | 64 | |
|
|
| header key | 128 bytes | metric tag 안전 |
|
|
| header value | 4,096 bytes | |
|
|
| publish timeout | 5s | |
|
|
| handler timeout | 30s | |
|
|
| graceful shutdown drain | 30s | |
|
|
| 일반 destination retry | 0회 | 자동 retry는 opt-in |
|
|
| DLQ redrive batch | 100 | 한 번의 작업이 source를 덮치지 않게 |
|
|
| Outbox relay batch | 100 | |
|
|
| Outbox lease | 30s | |
|
|
| Outbox polling | 500ms | |
|
|
| metric dimension 상한 | 200 | cardinality 폭발 방지 |
|
|
|
|
`schema.codec`은 `application/json`, `schema.compatibility`는 `BACKWARD_TRANSITIVE`,
|
|
|
|
> **현재 강제 범위:** `schema.compatibility` 값은 현재 정책 선언이며 runtime/CI에서 schema registry를
|
|
> 조회해 호환성을 차단하지 않는다. Avro 비교기는 독립 utility/test로만 존재한다. 따라서 이 값을
|
|
> 설정했다고 breaking schema가 자동 거부된다고 해석하면 안 된다. 실제 registry gate가 wiring되기
|
|
> 전까지 호환성은 adopter의 schema CI가 소유한다.
|
|
|
|
`guarantees.delivery`는 `AT_LEAST_ONCE`, `retry.mode`는 `NONE`이 기본값이다. 자동 retry가 기본으로
|
|
꺼져 있는 이유는 순서를 흐트러뜨리거나 비멱등 side effect를 두 번 실행하는 retry가 눈에 보이는
|
|
실패보다 나쁘기 때문이다.
|
|
|
|
## Broker profile
|
|
|
|
브로커는 `app.messaging.brokers` 아래에 한 번만 기술한다. `type`은 `kafka`만 받는다 — transport가
|
|
있는 계열이 Kafka 하나뿐이다. RabbitMQ 키(`addresses`, `prefetch`, `quorum-queues` 등)와
|
|
`type: rabbitmq`는 2026-09-25에 설정 모델에서 삭제됐다. 연결할 transport 없이 바인딩만 되던 키라,
|
|
지금은 무시되지 않고 키 이름을 담아 부팅 실패로 거절된다.
|
|
|
|
### Kafka
|
|
|
|
```yaml
|
|
app:
|
|
messaging:
|
|
brokers:
|
|
kafka-primary:
|
|
type: kafka
|
|
stable: true
|
|
production: false
|
|
bootstrap-servers: [broker-1:9093, broker-2:9093]
|
|
enable-idempotence: true # stable에서 필수
|
|
acks: all # stable에서 필수
|
|
max-in-flight-requests-per-connection: 5 # 최대 5
|
|
delivery-timeout: 30s
|
|
enable-auto-commit: false # 항상 금지
|
|
consumer-group: order-projection
|
|
tls-enabled: false # production이면 필수
|
|
authentication-enabled: false # production이면 필수
|
|
```
|
|
|
|
`production: true`인 Kafka 브로커는 `tls-enabled`와 `authentication-enabled`가 모두 참이어야 하고,
|
|
그렇지 않으면 `KafkaProfileValidator`가 부팅을 거절한다. `app.messaging.broker`로 고를 수 있는 값은
|
|
`kafka`뿐이다. 위 예시가
|
|
`production: false`인 것은 이 페이지가 그대로 실행되는 fixture이기 때문이며, 실 배포는 셋 다 참이다.
|
|
|
|
Kafka producer는 이 항목 하나로 만든다. `bootstrap-servers`, `acks`, `enable-idempotence`,
|
|
`max-in-flight-requests-per-connection`, `delivery-timeout`이 그대로 client 설정이 된다.
|
|
`spring.kafka.bootstrap-servers`는 읽지 않는다. type이 `kafka`인 항목이 정확히 하나가 아니면 기동에
|
|
실패한다. `send()`가 metadata를 기다리며 호출 스레드를 막는 시간(`max.block.ms`)은 기본 publish
|
|
timeout(5s)이다.
|
|
|
|
## 보안
|
|
|
|
```yaml
|
|
app:
|
|
messaging:
|
|
security:
|
|
kafka-primary:
|
|
producer: { type: SASL_SCRAM, credential-id: kafka-producer }
|
|
consumer: { type: SASL_SCRAM, credential-id: kafka-consumer }
|
|
# admin은 application runtime에 설정하지 않는다
|
|
hostname-verification: true
|
|
# 사설 CA로 서명된 TLS 브로커면(tls-enabled: true일 때만):
|
|
# trust-store: { location: /etc/kafka/ca.p12, type: PKCS12, password-credential-id: kafka-truststore }
|
|
access:
|
|
publishable: [order-events]
|
|
consumable: []
|
|
administrable: []
|
|
```
|
|
|
|
키는 `app.messaging.brokers`에 선언된 브로커 이름과 같아야 한다. `tls-enabled`와 `production`은
|
|
브로커 쪽에만 있고 여기에 중복되지 않는다 — 하나의 브로커가 두 곳에서 기술되면 두 값이 어긋나는
|
|
날이 오고, 어느 쪽이 이기는지는 아무도 모른다.
|
|
|
|
`credential-id`는 이름일 뿐이고 자격 증명 자체가 아니다. 실제 재료는 `CredentialProvider`가
|
|
연결 시점에 해석하므로, 설정 덤프나 힙 덤프에서 나오는 것은 이름뿐이다. producer와 consumer는
|
|
서로 다른 `credential-id`를 써야 하며, 같으면 부팅에 실패한다.
|
|
|
|
`SASL_SCRAM`·`USERNAME_PASSWORD`의 사용자 이름은 `CredentialProvider.username(credentialId)`가
|
|
준다. credential id를 사용자 이름으로 보내지 않는다. 비밀번호와 사용자 이름은 JAAS 문자열에 들어가지
|
|
않고, 연결이 인증할 때마다 provider에서 읽힌다. 그래서 provider가 만료 시각을 주는 credential은
|
|
재기동 없이 rotation된다(`security.md`).
|
|
|
|
`MUTUAL_TLS`는 클라이언트 인증서를 key store로 제출한다. `credential-id`는 key store 비밀번호를
|
|
가리킨다.
|
|
|
|
```text
|
|
producer:
|
|
type: MUTUAL_TLS
|
|
credential-id: kafka-producer-tls # key store 비밀번호
|
|
key-store: { location: /etc/kafka/producer.p12, type: PKCS12 }
|
|
```
|
|
|
|
`trust-store`를 생략하면 JVM 기본 trust store를 쓴다. 사설 CA 브로커는 `trust-store.location`
|
|
(PKCS12·JKS·PEM)과, 잠긴 store면 `password-credential-id`를 준다.
|
|
|
|
Kafka producer는 이 항목을 실제 클라이언트 설정(`security.protocol`, `sasl.mechanism`,
|
|
`sasl.jaas.config`, `sasl.client.callback.handler.class`, `ssl.truststore.*`, `ssl.keystore.*`,
|
|
`ssl.enabled.protocols=TLSv1.3,TLSv1.2`, hostname 검증)으로 옮긴다. 평문으로 조용히 넘어가지
|
|
않도록 다음 경우 부팅에 실패한다: 브로커가 `tls-enabled`나 `authentication-enabled`를 켰는데
|
|
`app.messaging.security.<broker>`가 없을 때, security 항목은 있는데 `CredentialProvider` bean이 없을
|
|
때, 같은 브로커에 맞는 항목이 둘 이상일 때, provider가 SASL 사용자 이름을 주지 않을 때,
|
|
`MUTUAL_TLS`인데 `key-store`가 없거나 `tls-enabled`가 꺼져 있을 때, `trust-store`를 줬는데
|
|
`tls-enabled`가 꺼져 있을 때, store 파일을 열 수 없을 때.
|
|
|
|
`access.publishable`은 강제된다. security 항목이 있는 브로커의 destination은 이 목록에 있어야
|
|
publish된다. 목록 밖 publish는 `REJECTED`(`PUBLISH_FORBIDDEN`)이고, 빈 목록이면 아무것도 publish되지
|
|
않는다.
|
|
|
|
## Backpressure
|
|
|
|
```yaml
|
|
app:
|
|
messaging:
|
|
backpressure:
|
|
global-limit: 512
|
|
per-destination-limit: 64 # global-limit 이하여야 한다
|
|
```
|
|
|
|
`per-destination-limit > global-limit`이면 global limit이 limit이 아니게 되므로 부팅에 실패한다.
|
|
|
|
## 바인딩되지 않는 키
|
|
|
|
섹션은 바인딩되는데 그 안의 키 하나가 오타인 경우는 접두사 오타와 달리 조용하다 — 섹션은 붙고,
|
|
플랫폼은 뜨고, 바꾸러 온 그 설정만 적용되지 않는다. `MessagingConfigurationKeyValidator`가
|
|
`app.messaging.destinations|brokers|security` 아래의 모든 키를 settings 레코드에서 파생한 목록과
|
|
대조하고, 없는 키는 그 키 이름을 담아 부팅을 거절한다.
|
|
|
|
허용 키 목록은 이 문서가 아니라 레코드에서 나온다. 문서에 목록을 적으면 필드가 추가된 날 그
|
|
목록이 틀리고, 오타를 잡으라고 만든 검사가 정상 필드를 거절하게 된다.
|
|
|
|
환경변수(`APP_MESSAGING_...`)는 이 검사의 대상이 아니다. `APP_MESSAGING_DESTINATIONS_ORDER_EVENTS_
|
|
CONSUMER_PREFETCH`에서 entry 이름과 leaf를 가르는 밑줄은 둘 안에 있는 밑줄과 구별되지 않으므로,
|
|
되돌려 쪼개려면 추측해야 한다. 여기서의 추측은 정상 배포를 거절하는 쪽으로 틀리며, 그것은 배포
|
|
매니페스트에 손으로 적어야 하는 변수에서 오타 하나를 놓치는 것보다 나쁘다.
|