Infrastructure Configuration

분산 배포 활성화 (PoC / 엔터프라이즈 시연) — 분산 모드가 필요하면 contexa init --distributed 를 실행하세요. CLI 가 자동 처리합니다:

의존성 — spring-kafka, redisson 을 빌드 파일에 자동 추가
인프라 — docker-compose.yml 에 PostgreSQL + Ollama + Redis + Kafka + Zookeeper 정의
설정 — application.yml 의 Contexa 블록에 contexa.infrastructure.mode: DISTRIBUTED + Redis/Kafka 호스트 자동 추가

이 페이지의 속성들은 분산 모드 활성화 후 세부 튜닝에 사용합니다. 운영 배포는 Kubernetes + Helm 을 권장합니다.

Contexa 코어 속성 (요약)

최상위 ContexaProperties 클래스(접두사 contexa)는 인프라 모드, Redis, Kafka, 관측성의 마스터 스위치를 포함합니다. 이 속성들은 구성 개요 페이지에 완전히 문서화되어 있습니다. 인프라 관련 주요 항목은 다음과 같습니다:

속성	타입	기본값	설명
`contexa` (마스터)
`contexa.enabled`	`boolean`	`true`	Contexa 자동 구성 전체를 켜고 끄는 최상위 마스터 스위치입니다. `false` 면 모든 하위 모듈이 비활성화됩니다.
`contexa.infrastructure`
`.mode`	`enum`	`STANDALONE`	`STANDALONE` (인메모리) 또는 `DISTRIBUTED` (Redis/Kafka)
`.redis.enabled`	`boolean`	`true`	분산 캐싱 및 pub/sub을 위한 Redis 활성화
`.kafka.enabled`	`boolean`	`true`	Distributed 모드에서 이벤트 스트리밍을 위한 Kafka 활성화
`.observability.enabled`	`boolean`	`true`	관측 인프라 활성화
`.observability.open-telemetry-enabled`	`boolean`	`true`	분산 추적을 위한 OpenTelemetry 활성화

전체 ContexaProperties 참조는 구성 개요를 확인하세요.

캐시 속성

contexa.cache 아래의 속성으로, ContexaCacheProperties에 바인딩됩니다. Identity, 정책, 행동 데이터를 위해 Contexa 전반에서 사용되는 다중 계층 캐싱 하위 시스템을 제어합니다. 로컬(Caffeine), Redis, 하이브리드 캐싱 전략과 선택적 pub/sub 기반 캐시 무효화를 지원합니다.

일반 설정

속성	타입	기본값	설명
`contexa.cache`
`.type`	`CacheType`	`REDIS`	`LOCAL`, `REDIS`, 또는 `HYBRID` (L1 로컬 + L2 Redis)
`.local.max-size`	`int`	`1000`	로컬(L1) 캐시의 최대 항목 수
`.local.default-ttl-seconds`	`int`	`60`	로컬 캐시 항목의 기본 TTL (초)
`.redis.default-ttl-seconds`	`int`	`300`	Redis 캐시 항목의 기본 TTL (초)
`.redis.key-prefix`	`String`	`contexa:cache:`	모든 Redis 캐시 키의 접두사 (네임스페이스 격리)
`.pubsub.enabled`	`boolean`	`true`	클러스터 노드 간 pub/sub 캐시 무효화 활성화
`.pubsub.channel`	`String`	`contexa:cache:invalidation`	캐시 무효화 브로드캐스트를 위한 pub/sub 채널

도메인별 TTL

각 캐시 도메인은 로컬 및 Redis 계층에 대해 독립적인 TTL 값을 가질 수 있습니다. 이를 통해 세밀한 제어가 가능합니다 - 예를 들어, 자주 변경되는 정책 데이터는 짧은 TTL을 사용하고 안정적인 HCAD 기준선 데이터는 긴 TTL을 사용할 수 있습니다.

속성	타입	기본값	설명
`contexa.cache.domains`
`.users`	`TtlConfig`	`local: 3600 / redis: 3600`	사용자 Identity 및 프로필 데이터
`.roles`	`TtlConfig`	`local: 14400 / redis: 14400`	역할 정의 및 권한 매핑
`.permissions`	`TtlConfig`	`local: 28800 / redis: 28800`	권한 부여 및 접근 제어 항목
`.groups`	`TtlConfig`	`local: 14400 / redis: 14400`	그룹 멤버십 및 계층 데이터
`.policies`	`TtlConfig`	`local: 30 / redis: 300`	XACML/ABAC 정책 정의 (짧은 로컬 TTL)
`.soar`	`TtlConfig`	`local: 900 / redis: 900`	SOAR 플레이북 및 자동 응답 데이터
`.hcad`	`TtlConfig`	`local: 86400 / redis: 86400`	HCAD 행동 기준선 (장기 프로필)

각 도메인 항목은 local-ttl-seconds 및 redis-ttl-seconds 필드를 가진 TtlConfig 객체입니다. 각 도메인을 독립적으로 재정의할 수 있습니다:

YAML

contexa:
  cache:
    type: HYBRID
    local:
      max-size: 5000
      default-ttl-seconds: 120
    redis:
      default-ttl-seconds: 600
      key-prefix: "myapp:contexa:cache:"
    pubsub:
      enabled: true
      channel: "contexa:cache:invalidation"
    domains:
      users:
        local-ttl-seconds: 1800
        redis-ttl-seconds: 3600
      policies:
        local-ttl-seconds: 15
        redis-ttl-seconds: 60
      hcad:
        local-ttl-seconds: 43200
        redis-ttl-seconds: 86400

보안 Kafka 속성

security.kafka 아래의 속성으로, SecurityKafkaProperties에 바인딩됩니다. Contexa 보안 이벤트 파이프라인의 Kafka 토픽 이름을 구성합니다.

속성	타입	기본값	설명
`security.kafka.topic` (TopicSettings)
`.authorization`	`String`	`security-authorization-events`	인가 결정 이벤트 토픽.
`.authentication`	`String`	`auth-events`	인증 이벤트 토픽.
`.incident`	`String`	`security-incident-events`	보안 인시던트 이벤트 토픽.
`.threat`	`String`	`threat-indicators`	위협 지표 토픽.
`.audit`	`String`	`security-audit-events`	감사 이벤트 토픽.
`.general`	`String`	`security-events`	일반 보안 이벤트 토픽.
`.dlq`	`String`	`security-events-dlq`	실패한 이벤트 처리를 위한 dead-letter queue 토픽.
`.soar-action`	`String`	`soar-action-events`	SOAR action 이벤트 토픽.
`security.kafka.dlq` (DlqSettings)
`.max-retries`	`int`	`3`	DLQ 처리 시 최대 재시도 횟수.
`.retry-delay-ms`	`int`	`5000`	재시도 간 지연(ms).
`.alert-threshold`	`int`	`10`	DLQ 메시지가 이 임계값을 넘으면 알림.

YAML

security:
  kafka:
    topic:
      authorization: security-authorization-events
      authentication: auth-events
      incident: security-incident-events
      threat: threat-indicators
      audit: security-audit-events
      general: security-events
      dlq: security-events-dlq
      soar-action: soar-action-events
    dlq:
      max-retries: 3
      retry-delay-ms: 5000
      alert-threshold: 10

관련 문서: Zero Trust 보안 참조 | SOAR 자동화 참조

OpenTelemetry 속성

contexa.opentelemetry 아래의 속성으로, OpenTelemetryProperties에 바인딩됩니다. 분산 추적, 메트릭 내보내기, 관측성을 위한 OpenTelemetry 통합을 구성합니다.

속성	타입	기본값	설명
`contexa.opentelemetry`
`.enabled`	`boolean`	`true`	OpenTelemetry 추적 및 메트릭 내보내기 활성화
`.service-name`	`String`	`contexa-core`	추적 스팬 및 메트릭 라벨의 서비스 이름
`.exporter-endpoint`	`String`	`http://localhost:4317`	OTLP 내보내기 엔드포인트 (gRPC; HTTP는 4318)
`.sampling-probability`	`double`	`1.0`	샘플링 확률 (0.0-1.0); 프로덕션에서는 낮추기

YAML

contexa:
  opentelemetry:
    enabled: true
    service-name: "my-application"
    exporter-endpoint: "http://otel-collector.monitoring:4317"
    sampling-probability: 0.1

보안 Redis 속성

security.redis 아래의 속성으로, SecurityRedisProperties에 바인딩됩니다. Contexa 보안 이벤트의 Redis pub/sub 채널 이름, Redis stream 키, TTL, 메모리 임계값을 구성합니다.

속성	타입	기본값	설명
`security.redis.channel` (ChannelSettings)
`.authorization`	`String`	`security:authorization:events`	인가 이벤트 pub/sub 채널.
`.authentication`	`String`	`security:events`	인증 이벤트 pub/sub 채널.
`.incident`	`String`	`security:incidents`	인시던트 pub/sub 채널.
`.threat`	`String`	`security:threats`	위협 pub/sub 채널.
`.audit`	`String`	`security:audit:events`	감사 pub/sub 채널.
`.general`	`String`	`security:events`	일반 pub/sub 채널.
`security.redis.stream` (StreamSettings)
`.authorization`	`String`	`security:stream:authorization`	인가 Redis stream 키.
`.incident`	`String`	`security:stream:incident`	인시던트 Redis stream 키.
`.threat`	`String`	`security:stream:threat`	위협 Redis stream 키.
`.audit`	`String`	`security:stream:audit`	감사 Redis stream 키.
`.general`	`String`	`security:stream:general`	일반 Redis stream 키.
`.authentication`	`String`	`security:stream:authentication`	인증 Redis stream 키.
`.maxlen`	`int`	`10000`	Redis stream 최대 항목 수 (XADD MAXLEN).
`security.redis.ttl` (TtlSettings)
`.minutes`	`int`	`60`	이벤트 데이터의 기본 Redis TTL (분).
`security.redis.memory` (MemorySettings)
`.max-mb`	`int`	`1024`	Contexa 보안 이벤트가 사용 가능한 Redis 메모리 상한 (MB).
`.warning-threshold`	`double`	`0.8`	메모리 사용률 경고 임계값 (0.0~1.0).
`.critical-threshold`	`double`	`0.9`	메모리 사용률 critical 임계값 (0.0~1.0).

스케줄러 락 속성

contexa.scheduler.lock 아래의 속성으로, ContexaSchedulerLockProperties (record) 에 바인딩됩니다. 다중 JVM 환경에서 @Scheduled + @SchedulerLock 메서드의 단일 실행을 보장하는 ShedLock auto-configuration 을 제어합니다. 단일 인스턴스 배포에서도 기본값을 유지해도 됩니다 — 락은 항상 성공하고 오버헤드는 무시 가능합니다.

속성	타입	기본값	설명
`contexa.scheduler.lock`
`.enabled`	`boolean`	`true`	ShedLock auto-configuration 으로 `LockProvider` 빈 등록 여부. `false` 면 모든 `@SchedulerLock` 이 비활성화되고 각 `@Scheduled` 메서드는 단일 JVM 내 배타성만 보장합니다.
`.default-lock-at-most-for`	`Duration`	`5m`	특정 스케줄러가 `lockAtMostFor` 를 지정하지 않을 때 적용되는 fallback 상한입니다. JVM crash 후 락이 영구히 남는 것을 방지합니다.
`.use-database-time`	`boolean`	`true`	`true` 면 `JdbcTemplateLockProvider` 가 DB 의 `now()` 를 사용해 모든 인스턴스가 동일 시각을 봅니다. `false` 면 JVM 시계로 fallback (로컬 H2 테스트 단순화에 유용).

데이터소스 속성

contexa.datasource 아래의 속성으로, ContexaDataSourceProperties 에 바인딩됩니다. Contexa 가 자체 메타데이터(정책, 사용자, 감사 로그 등)를 저장하는 데이터베이스 연결을 정의합니다. 호스트 application 의 spring.datasource 와 격리할 수 있습니다.

속성	타입	기본값	설명
`contexa.datasource`
`.url`	`String`	`null`	JDBC URL. 비어 있으면 host application 의 `spring.datasource.url` 을 공유합니다 (격리 정책에 따라 다름).
`.username`	`String`	`null`	DB 사용자 이름.
`.password`	`String`	`null`	DB 비밀번호.
`.driver-class-name`	`String`	`null`	JDBC driver 클래스 이름. 비우면 URL 로부터 자동 탐지.
`contexa.datasource.isolation` (Isolation)
`.allow-shared-application-datasource`	`boolean`	`false`	호스트 application 의 datasource 를 공유 사용을 허용합니다. 기본값은 격리 (별도 connection pool).
`.shared-application-datasource-risk-accepted`	`boolean`	`false`	공유 datasource 사용에 따른 위험을 운영자가 명시 수락했음을 표시합니다.
`.contexa-owned-application`	`boolean`	`false`	이 application 자체가 Contexa 가 운영하는 application 임을 표시 (격리 검증 우회).

전체 구성 예제

Redis, Kafka, 외부 OpenTelemetry 수집기를 사용하는 분산 배포를 위한 프로덕션 준비 application.yml로 모든 인프라 속성을 결합한 것입니다.

YAML

# Infrastructure configuration for Contexa distributed deployment
contexa:
  enabled: true
  infrastructure:
    mode: DISTRIBUTED
    redis:
      enabled: true
    kafka:
      enabled: true
    observability:
      enabled: true
      open-telemetry-enabled: true

  # Multi-tier caching
  cache:
    type: HYBRID
    local:
      max-size: 5000
      default-ttl-seconds: 120
    redis:
      default-ttl-seconds: 600
      key-prefix: "contexa:cache:"
    pubsub:
      enabled: true
      channel: "contexa:cache:invalidation"
    domains:
      users:
        local-ttl-seconds: 1800
        redis-ttl-seconds: 3600
      roles:
        local-ttl-seconds: 7200
        redis-ttl-seconds: 14400
      permissions:
        local-ttl-seconds: 14400
        redis-ttl-seconds: 28800
      groups:
        local-ttl-seconds: 7200
        redis-ttl-seconds: 14400
      policies:
        local-ttl-seconds: 15
        redis-ttl-seconds: 120
      soar:
        local-ttl-seconds: 900
        redis-ttl-seconds: 900
      hcad:
        local-ttl-seconds: 86400
        redis-ttl-seconds: 86400

  # OpenTelemetry
  opentelemetry:
    enabled: true
    service-name: "contexa-production"
    exporter-endpoint: "http://otel-collector.monitoring:4317"
    sampling-probability: 0.1

# Security event infrastructure - Kafka
security:
  kafka:
    topic:
      dlq: "security-events-dlq"

인프라 구성

Contexa 코어 속성 (요약)

캐시 속성

일반 설정

도메인별 TTL

보안 Kafka 속성

OpenTelemetry 속성

보안 Redis 속성

스케줄러 락 속성

데이터소스 속성

전체 구성 예제