- 결정 16: `ca-skeleton.*`·`backend.graphql` 등 → `app.*`(APP_* env 키 이름 유지), selector 키 상수 하나(`CapabilitySelectors`), 바인딩만 되던 `streaming-idle` 삭제 - `StrictSettingsBinder`가 env 오타까지 거부 — 모든 capability(graphql·websocket·mongo는 edge 제약으로 파일만 strict), httpclient 리플렉션 `HttpClientEnvironmentKeys` 삭제 - persistence-jpa가 `APP_DATASOURCE_PASSWORD` secret 요구를 기여(bootstrap이 JPA 스위치를 읽지 않음), Redis ACL fixture에서 pub/sub 권한 제거 - 결함 수정: SMTP 설정 env 이름 충돌(P20-new-1), `bindExcept`가 system env까지 filter(P20-new-2), graphql 빈 deployment-mode 메시지(P20-new-6) - 통합: P30과 충돌 11건(P30의 명시적 bean 구조 유지), P30 코드의 옛 키를 app.*로, persistence-jpa 포맷 - 현황표: 소유자 결정 36(persistence-jpa 설정은 플랫폼 키만 app.persistence-jpa.*로, 공유 기능 트리 예외), 재개 문서에 일시 정지 상태 Wave 3 종료 검증: check · ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck · architectureCheck verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest · integrationCheck · -p build-logic test · -p optional-platforms ci · :app-bootstrap:qualificationBootJar releaseCheck 통과 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
255 lines
13 KiB
Markdown
255 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 이름으로 추론하지 않는다. 모든 발행(outbox relay 포함)이 이 bridge를 지나므로 messaging
|
|
모듈이 켜진 상태에서 값이 없으면 기동이 거부된다.
|
|
|
|
## Outbox
|
|
|
|
outbox는 canonical 하나다(2026-09-28). use case가 `IntegrationEventEncoderPort`로 만든
|
|
`ValidatedIntegrationEvent`를 `OutboxAppendPort`로 append하고, relay는 claim한 row의 exact envelope
|
|
bytes를 `IntegrationEventPublishPort`로 보낸다. 예전의 `app.outbox.canonical-transport-enabled`
|
|
gate와 legacy `MessageBroker → KafkaSender` 경로는 삭제됐다. 발행할 contract의 logical destination마다
|
|
아래 destination profile을 선언한다(템플릿의 durable operation event는 `durable-operations`).
|
|
|
|
## 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를 가르는 밑줄은 둘 안에 있는 밑줄과 구별되지 않으므로,
|
|
되돌려 쪼개려면 추측해야 한다. 여기서의 추측은 정상 배포를 거절하는 쪽으로 틀리며, 그것은 배포
|
|
매니페스트에 손으로 적어야 하는 변수에서 오타 하나를 놓치는 것보다 나쁘다.
|