# 설정 레퍼런스 > **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 application의 발행 경로는 하나다(2026-09-28): `outbox_event` 표와 `composition:outbox-relay`. vendored platform의 `messaging_outbox`(`outbox-inbox.md`)는 이 경로에 쓰이지 않는다 — 두 모델의 상태 대응은 `outbox-inbox.md` 머리의 표에 있다. 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.`가 없을 때, 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를 가르는 밑줄은 둘 안에 있는 밑줄과 구별되지 않으므로, 되돌려 쪼개려면 추측해야 한다. 여기서의 추측은 정상 배포를 거절하는 쪽으로 틀리며, 그것은 배포 매니페스트에 손으로 적어야 하는 변수에서 오타 하나를 놓치는 것보다 나쁘다.