버전: 1.0.4

4.9. S2I 환경 변수

어떨 때 보는가

빌드나 배포에 환경 변수를 넣어야 할 때
넣은 값이 반영되지 않는 이유를 찾을 때
어떤 값을 넣을 수 있는지 목록으로 볼 때

빌드를 만드는 절차는 402 콘솔에서 빌드하기, 배포는 408 배포 전략 을 참고하십시오. 이 장은 어떤 값을 넣을 수 있는지 를 모아 둔 레퍼런스입니다.

설치가 만들어 두는 S2I 예제 (openmaru-war-example)

설치할 때 동작하는 S2I 예제 하나가 함께 만들어집니다. 처음부터 BuildConfig 를 쓰지 않고 이미 도는 것을 보고 고쳐 쓰라는 뜻입니다.

항목	값
이름	`openmaru-war-example`
네임스페이스	전자정부 샘플과 같은 네임스페이스(`egov_project_name`)
소스	설치가 GitLab 에 만들어 둔 `openmaru-war-example` 저장소 (`main` 브랜치)
빌더 이미지	`tomcat9-jdk8-ubi8-s2i-openmaru:9.0`
접근 시크릿	`openmaru-git`

WAR 예제라 Tomcat 9 + JDK 8 빌더를 씁니다. 빌드 산출물은 플랫폼 반입물(images)과 섞이지 않도록 별도 Harbor 프로젝트로 올라갑니다.

함께 골격 Deployment 도 만들어집니다. 빌드가 끝나면 그 이미지를 바라보도록 되어 있어, 빌드 → 배포까지의 흐름을 한 번에 볼 수 있습니다.

# BuildConfig 와 골격 Deployment 확인
kubectl get buildconfig,deployment -n <전자정부 네임스페이스> | grep openmaru-war-example

COP Console 의 빌드 화면에서도 같은 것을 볼 수 있습니다. 자신의 애플리케이션으로 바꾸려면 저장소 주소와 빌더 이미지만 고치면 됩니다.

커스텀 빌드 스크립트

# .s2i/bin/assemble
#!/bin/bash
/usr/libexec/s2i/assemble
echo "Running custom build steps..."
npm run build
npm prune --production

# .s2i/bin/run
#!/bin/bash
export NODE_ENV=production
exec npm run start:prod

환경 변수를 어디에 넣는가

S2I(Source-to-Image, 소스에서 이미지로) 빌더 이미지의 환경 변수는 넣는 자리가 세 곳이고, 자리마다 적용되는 시점이 다릅니다. 자리를 잘못 고르면 오류 없이 값이 무시되므로 먼저 구분합니다.

경로	적용 시점	어디에 넣나	대표 변수
① 빌드	소스를 이미지로 만드는 동안만	BuildConfig `spec.strategy.sourceStrategy.env`, 콘솔 [빌드 설정] 폼의 환경 변수 행, `s2i build -e`	`MAVEN_MIRROR_URL`, `MAVEN_ARGS_APPEND`, `S2I_SOURCE_DEPLOYMENTS_FILTER`
② `.s2i/environment`	빌드와 런타임 양쪽	소스 저장소에 두는 표준 파일	빌드·실행에 공통으로 필요한 값
③ 런타임	컨테이너가 뜰 때	Deployment `spec.template.spec.containers[].env`, 콘솔 배포 화면의 환경 변수	`TOMCAT_`, `JWS_HTTPS_`, `JWS_REALM_*`, `RESOURCES`, `CATALINA_OPTS_APPEND`

자리를 잘못 고르면 오류 없이 무시됩니다. 런타임 변수인 TOMCAT_MAX_THREADS 를 빌드(①)에 넣으면 빌드는 성공하지만 값은 버려지고 실행 중인 컨테이너에는 반영되지 않습니다. 반대로 빌드 변수인 MAVEN_MIRROR_URL 을 런타임(③)에 넣어도 빌드에는 쓰이지 않습니다. 아래 각 표의 적용 시점 칸으로 자리를 확인하십시오.

빌드 변수 예시 (BuildConfig):

spec:
  strategy:
    sourceStrategy:
      env:
        - name: MAVEN_MIRROR_URL
          value: "https://nexus.<도메인>/repository/maven-public/"

런타임 변수 예시 (Deployment):

spec:
  template:
    spec:
      containers:
        - name: app
          env:
            - name: TOMCAT_MAX_THREADS
              value: "300"

콘솔을 쓰는 경우 빌드 변수는 [빌드 설정] 폼의 환경 변수 행에, 런타임 변수는 배포 화면의 환경 변수에 넣습니다 (콘솔 사용 절차는 402 콘솔에서 빌드하기 를 참고하십시오).

OpenJDK/Tomcat 공통 (JVM·가비지 컬렉션·빌드 도구·프록시)

정보성 변수 (읽기 전용):

변수	값	설명
`JAVA_HOME`	`/usr/lib/jvm/java-{version}`	JDK 설치 디렉터리
`JAVA_VERSION`	`1.8.0`, `11`, `17`, `21`	OpenJDK 버전
`JAVA_VENDOR`	`openjdk`	Java 배포 유형
`HOME`	`/home/jboss` (UBI8 계열), `/home/default` (UBI9 계열)	기본 사용자 홈 디렉터리
`USER`	`jboss` (UBI8 계열), `default` (UBI9 계열)	컨테이너 사용자. 이름은 계열마다 다르지만 UID 는 둘 다 185 입니다
`JAVA_DATA_DIR`	`/deployments/data`	애플리케이션 데이터 디렉터리
`MAVEN_VERSION`	`3.8` (UBI8 계열), `3.9` (UBI9 계열)	번들된 Maven 버전
`GRADLE_VERSION`	`8.14.5` (UBI8 계열), `9.7.1` (UBI9 계열)	번들된 Gradle 버전

JVM 메모리 및 GC 설정:

변수	기본값	설명
`JAVA_MAX_MEM_RATIO`	`70` (Tomcat 이미지는 `50`)	사용 가능한 메모리 대비 최대 힙 비율 (%). `0` 을 주면 힙 크기를 지정하지 않고 JVM 기본값에 맡깁니다. 기본값이 이미지 계열에 따라 다릅니다 — 아래 설명을 참고하십시오
`JAVA_INITIAL_MEM_RATIO`	-	초기 힙 할당 비율 (%)
`JAVA_UNBOUNDED_HEAP`	`4096m`	컨테이너에 메모리 제한이 없을 때 적용할 힙 크기. 아래 설명을 참고하십시오
`GC_CONTAINER_OPTIONS`	자동 선택 (아래 참고)	가비지 컬렉터 유형. 값을 주면 자동 선택을 쓰지 않고 그 값을 씁니다
`GC_MIN_HEAP_FREE_RATIO`	`10`	가비지 컬렉션 후 남길 여유 공간의 최소 비율 (%). 아래 설명을 참고하십시오
`GC_MAX_HEAP_FREE_RATIO`	`20`	가비지 컬렉션 후 남길 여유 공간의 최대 비율 (%). 아래 설명을 참고하십시오
`GC_TIME_RATIO`	`4`	가비지 컬렉션에 쓸 수 있는 시간의 역수. 아래 설명을 참고하십시오
`GC_ADAPTIVE_SIZE_POLICY_WEIGHT`	`90`	힙 크기 조정에서 최근 관측에 두는 가중치 (%). 아래 설명을 참고하십시오
`GC_METASPACE_SIZE`	`20`	초기 메타스페이스 크기 (MB)
`GC_MAX_METASPACE_SIZE`	`100`	최대 메타스페이스 크기 (MB)
`ENABLE_GC_LOG`	`false`	`true` 로 주면 가비지 컬렉션 로그를 표준 출력으로 내보냅니다. JDK 8 이미지에는 적용되지 않습니다
`ENABLE_HEAP_DUMP`	`false`	`true` 로 주면 메모리 부족 오류가 났을 때 힙 덤프를 남깁니다
`HEAP_DUMP_PATH`	`/deployments/data`	힙 덤프를 쓸 디렉터리

JAVA_MAX_MEM_RATIO 는 비율이라 기준이 되는 메모리 크기가 필요합니다. 파드에 메모리 제한 (resources.limits.memory)이 있으면 그 값이 기준이 되므로 힙은 제한 안에 머무릅니다.

제한이 없으면 기준이 노드 전체 메모리가 됩니다. 메모리 31 기가바이트 노드에서 비율 70 퍼센트면 힙 최대치가 약 22 기가바이트로 잡혀, 파드 하나가 노드 메모리를 대부분 예약합니다. JAVA_UNBOUNDED_HEAP 은 이 경우에만 적용되어 힙을 고정 크기로 잡습니다 (기본 4096 메가바이트, 초기 힙과 최대 힙을 같은 값으로 설정). 파드에 메모리 제한이 있으면 이 값은 쓰이지 않고 비율이 그대로 적용됩니다.

메모리 제한을 지정하는 것을 권장합니다. JAVA_UNBOUNDED_HEAP 은 제한을 깜빡했을 때 노드 전체를 잡지 않게 하는 안전장치이며, 제한을 대신하지는 않습니다.

기본 힙 비율은 이미지 계열에 따라 다릅니다.

이미지 계열	`JAVA_MAX_MEM_RATIO` 기본값	메모리 2 기가바이트 파드의 최대 힙
OpenJDK (`openjdk*-s2i`)	70	약 1.4 기가바이트
Tomcat (`tomcat9-*-s2i`)	50	약 1 기가바이트

힙은 컨테이너 메모리의 일부만 씁니다. 나머지는 메타스페이스, 코드 캐시, 스레드 스택, 직접 버퍼 등 힙 밖에서 쓰이며, 스레드가 많은 웹 애플리케이션은 이 영역이 200 메가바이트를 넘습니다. Tomcat 이미지의 기본값이 더 낮은 것은 애플리케이션 서버가 힙 밖을 특히 많이 쓰기 때문입니다.

메모리 1 기가바이트 이하 파드에서는 기본값으로도 힙 밖 공간이 빠듯할 수 있습니다. 애플리케이션이 메모리 부족으로 종료된다면 파드 메모리를 늘리거나 JAVA_MAX_MEM_RATIO 를 더 낮추십시오.

힙이 예상보다 작게 잡힌다면 이 기본값을 먼저 확인하십시오. 메모리 2 기가바이트를 할당했는데 OpenJDK 이미지에서 힙이 1.4 기가바이트, Tomcat 이미지에서 1 기가바이트로 잡히는 것은 정상 동작입니다. 값을 바꾸려면 JAVA_MAX_MEM_RATIO 를 직접 지정하십시오.

스레드 스택 크기(-Xss)는 별도로 지정하지 않으며 JVM 기본값 1024 킬로바이트를 사용합니다. 바꾸려면 JAVA_OPTS_APPEND (Tomcat 이미지는 CATALINA_OPTS_APPEND) 에 -Xss 를 넣으십시오.

가비지 컬렉터 자동 선택

가비지 컬렉터는 파드에 할당된 메모리와 CPU 를 보고 정합니다. GC_CONTAINER_OPTIONS 에 값을 지정하면 자동 선택을 쓰지 않고 그 값이 적용됩니다.

조건	적용되는 컬렉터
메모리 제한 1792 메비바이트 이상이고 CPU 2 코어 이상 (JDK 11 이상)	JVM 이 자체 판단합니다. 대부분 G1 을 고릅니다
그 밖의 경우	Parallel
JDK 8 이미지	Parallel (조건과 무관)

기준이 되는 1792 메비바이트와 2 코어는 JVM 이 서버급 장비를 판별할 때 쓰는 값과 같습니다. 자원이 그보다 적으면 JVM 은 Serial 을 고르는데, Parallel 이 더 나은 선택이라 명시적으로 지정합니다. 자원이 그 이상이면 JVM 의 판단이 더 정확하므로 맡깁니다.

JDK 8 을 제외하는 것은 그 버전의 JVM 이 G1 을 자동으로 고르지 않기 때문입니다.

힙 크기 조절 변수 (GC_MIN_HEAP_FREE_RATIO · GC_MAX_HEAP_FREE_RATIO · GC_TIME_RATIO · GC_ADAPTIVE_SIZE_POLICY_WEIGHT)

이 네 값은 JVM 이 힙을 얼마나 크게 유지할지 정할 때 씁니다. 기본값은 메모리를 아끼는 대신 가비지 컬렉션을 더 자주 수행하는 쪽으로 맞춰져 있으며, Parallel 컬렉터를 전제로 정해졌습니다.

컬렉터 선택을 JVM 에 맡기는 구간(메모리 제한 1792 메비바이트 이상이고 CPU 2 코어 이상, JDK 11 이상)에서는 이 네 값을 지정하지 않습니다. 컬렉터를 JVM 이 고르는데 다른 컬렉터를 전제로 한 조절값을 함께 주면 두 설정이 어긋나기 때문입니다. 이 구간에서는 JVM 기본값 (각각 40 · 70 · 12 · 10)이 적용됩니다.

조건	적용되는 값
컬렉터를 JVM 에 맡기는 구간	JVM 기본값 (40 · 70 · 12 · 10)
그 밖의 경우 (Parallel 컬렉터)	표의 기본값 (10 · 20 · 4 · 90)
환경 변수를 지정한 경우	지정한 값 (구간과 무관)

메모리 사용량이 늘어날 수 있습니다. JVM 기본값은 힙을 더 크게 유지하므로, 컬렉터를 JVM 에 맡기는 구간의 파드는 실제 메모리 사용량이 이전보다 증가합니다. 메모리 제한 (resources.limits.memory) 안에서 늘어나므로 파드가 강제 종료되지는 않지만, 한 노드에 여러 파드를 촘촘히 배치했다면 노드 메모리 여유를 확인하십시오.

이전 동작으로 되돌리려면 네 환경 변수에 표의 기본값을 직접 지정하십시오. 환경 변수로 지정한 값은 구간과 무관하게 그대로 적용됩니다.

가비지 컬렉션 로그

성능 문제를 분석할 때 ENABLE_GC_LOG 를 true 로 지정하십시오. 로그는 파일이 아니라 표준 출력으로 나가므로 클러스터의 로그 수집기가 그대로 가져갑니다.

env:
  - name: ENABLE_GC_LOG
    value: "true"

애플리케이션 수에 비례해 로그가 늘어납니다. 필요한 기간에만 켜고, 로그 수집기의 저장 용량을 함께 확인하십시오.

JDK 8 이미지에는 적용되지 않습니다. 로그 옵션의 형식이 JDK 9 부터 바뀌어, JDK 8 에 그 형식을 넣으면 컨테이너가 기동하지 않기 때문입니다.

힙 덤프

메모리 부족 오류의 원인을 분석하려면 ENABLE_HEAP_DUMP 를 true 로 지정하십시오. 기본값은 false 입니다.

힙 덤프를 켤 때는 볼륨을 함께 지정하십시오. 볼륨이 없으면 덤프가 컨테이너 안에 쓰이고, 컨테이너가 다시 시작되면서 사라집니다. 파일은 남지 않는데 노드 디스크만 차지합니다.

spec:
  securityContext:
    fsGroup: 0
  containers:
    - name: myapp
      env:
        - name: ENABLE_HEAP_DUMP
          value: "true"
      volumeMounts:
        - name: heapdump
          mountPath: /deployments/data
  volumes:
    - name: heapdump
      emptyDir:
        sizeLimit: 2Gi

각 항목의 이유는 다음과 같습니다.

fsGroup — 지정하지 않으면 볼륨을 컨테이너 사용자가 쓸 수 없어 덤프 생성이 실패합니다.
sizeLimit — 덤프 파일은 재시작마다 새로 쌓입니다. 상한을 두지 않으면 애플리케이션이 반복해서 재시작될 때 노드 디스크를 채우고, 같은 노드의 다른 파드까지 영향을 받습니다.
emptyDir — 파드가 살아 있는 동안 유지되므로 컨테이너 재시작을 견딥니다. 파드가 다른 노드로 옮겨가면 사라지므로, 오래 보관하려면 persistentVolumeClaim 을 쓰십시오.

덤프를 쓰는 데 걸리는 시간은 힙 크기에 비례하며 8 초에서 20 초 정도입니다. 그동안 컨테이너가 종료되지 않으므로, 활성 상태 검사(livenessProbe)의 대기 시간이 그보다 짧으면 덤프가 중간에 잘릴 수 있습니다.

메모리 부족 오류 중에서도 힙이 아니라 스레드나 파일 디스크립터가 모자라 발생한 경우에는 덤프가 생성되지 않습니다.

애플리케이션 런타임:

변수	설명
`JAVA_OPTS`	JVM 옵션. 지정하지 마십시오 — 아래 설명을 참고하십시오
`JAVA_OPTS_APPEND`	추가 JVM 인수 (기본값에 추가)
`JAVA_APP_DIR`	애플리케이션 디렉터리 위치
`JAVA_MAIN_CLASS`	Java 실행 진입점 클래스 (예: `com.example.MainClass`)
`JAVA_APP_NAME`	사용자 정의 프로세스 이름
`JAVA_ARGS`	Java 애플리케이션에 전달할 인수
`JAVA_CLASSPATH`	사용자 정의 클래스패스

JAVA_OPTS 를 지정하지 마십시오. 이 변수를 설정하면 이미지가 만들어 주는 옵션이 모두 사라집니다. 힙 크기 제한(JAVA_MAX_MEM_RATIO), 가비지 컬렉터 선택, 메모리 부족 시 종료 설정이 함께 없어집니다. 그 결과 JVM 이 파드의 메모리 제한을 무시하고 노드 전체 메모리를 기준으로 힙을 잡아, 파드가 OOMKilled 로 종료될 수 있습니다.

빈 문자열("")을 지정해도 같습니다. 값이 없더라도 "지정됨" 으로 판단하기 때문입니다.

옵션을 더하려면 JAVA_OPTS_APPEND (Tomcat 이미지는 CATALINA_OPTS_APPEND) 를 쓰십시오. 기존 옵션 뒤에 덧붙으며, 같은 옵션이 중복되면 나중 값이 적용됩니다.

Maven 빌드 설정:

변수	기본값	설명
`MAVEN_ARGS`	-	Maven 빌드 인수
`MAVEN_LOCAL_REPO`	-	로컬 Maven 저장소 경로
`MAVEN_MIRROR_URL`	-	Maven 미러 저장소 URL
`MAVEN_MIRRORS`	-	다중 미러 저장소 지원
`MAVEN_S2I_ARTIFACT_DIRS`	`target`	빌드 결과물 디렉터리
`MAVEN_S2I_GOALS`	`package`	Maven 실행 목표
`S2I_SOURCE_DEPLOYMENTS_DIR`	-	소스 배포 디렉터리
`S2I_ENABLE_INCREMENTAL_BUILDS`	`true`	증분 빌드 활성화 (아티팩트 보존)

Gradle 빌드 설정:

참고: COP 의 S2I 이미지는 Gradle 빌드를 지원합니다. build.gradle 파일이 있으면 자동으로 Gradle 빌드가 실행됩니다.

변수	기본값	설명
`GRADLE_USER_HOME`	`/tmp/artifacts/gradle`	Gradle 사용자 홈 디렉터리 (캐시 위치)
`BUILDER_ARGS`	`build -x test --no-daemon`	Gradle 빌드 인수
`BUILDER_ARGS_APPEND`	-	추가 Gradle 빌드 인수
`SCRIPT_DEBUG`	`false`	`true` 설정 시 스크립트 디버그 모드 활성화

Gradle 빌드 동작:

빌드 결과물은 build/libs/에서 /deployments/로 자동 복사됩니다
-plain 접미사가 붙은 JAR 파일은 제외됩니다
Gradle Wrapper(gradlew)가 있으면 Wrapper를 사용하고, 없으면 번들된 Gradle을 사용합니다

디버깅 및 모니터링:

변수	기본값	설명
`JAVA_DEBUG`	`false`	원격 디버깅 활성화
`JAVA_DEBUG_PORT`	`5005`	디버그 연결 포트
`JAVA_DIAGNOSTICS`	`false`	진단 출력 활성화

프록시 설정:

변수	설명
`HTTP_PROXY` / `http_proxy`	HTTP 프록시 서버 URL
`HTTPS_PROXY` / `https_proxy`	HTTPS 프록시 서버 URL
`NO_PROXY` / `no_proxy`	프록시를 우회할 호스트/도메인 (쉼표 구분). 런타임 JVM 프록시 모듈은 소문자 `no_proxy` 를 읽습니다

Tomcat 커넥터·동시 처리

아래 변수는 Tomcat 커넥터(요청을 받는 8080·8443 포트)의 동시 처리 한계를 정합니다. 모두 런타임(경로 ③)에 넣으며, tomcat9-* 계열 이미지에만 적용됩니다(OpenJDK 계열에는 없습니다). 환경 변수 하나가 HTTP(8080)와 HTTPS(8443) 커넥터 양쪽에 같은 값으로 걸립니다.

변수	기본값	설명
`TOMCAT_MAX_THREADS`	`300`	동시에 요청을 처리하는 최대 스레드 수. 동시 요청이 많아 대기가 생길 때 올립니다. 스레드 하나가 스택 1 메가바이트를 힙 밖에서 쓰므로 컨테이너 메모리와 데이터베이스 커넥션 풀을 함께 보고 정합니다
`TOMCAT_MIN_SPARE_THREADS`	`25`	미리 만들어 두는 최소 여유 스레드 수
`TOMCAT_MAX_CONNECTIONS`	`8192`	동시에 받아들이는 최대 연결 수. NIO(논블로킹 입출력) 커넥터는 연결 수용과 요청 처리가 분리되므로, 동시 접속을 늘리려면 이 값을 봅니다
`TOMCAT_ACCEPT_COUNT`	`200`	`TOMCAT_MAX_CONNECTIONS` 까지 찼을 때 운영체제 대기 큐에 더 쌓을 수 있는 연결 수
`TOMCAT_CONNECTION_TIMEOUT`	`10000`	연결 후 요청이 오기까지 기다리는 시간(밀리초). Tomcat 기본값 20000 보다 짧게 두어, 느린 연결이 스레드를 오래 붙잡는 것을 줄입니다
`TOMCAT_MAX_KEEPALIVE_REQUESTS`	`200`	하나의 연결에서 처리할 요청 수 상한
`TOMCAT_MAX_POST_SIZE`	`104857600`	폼 본문의 최대 크기(바이트, 기본 100 메가바이트). `application/x-www-form-urlencoded` 요청에만 적용되며, 멀티파트 파일 업로드 크기는 여기에 걸리지 않습니다
`TOMCAT_MAX_PARAMETER_COUNT`	`10000`	요청 하나가 담을 수 있는 파라미터 수 상한. 파라미터를 대량으로 보내 서버 자원을 소모시키는 요청을 막습니다

TOMCAT_MAX_THREADS 를 400~500 으로 크게 올리는 것은 권장하지 않습니다. 스레드가 늘면 스택 메모리가 함께 늘어 컨테이너 메모리 제한에 부딪히고, 각 스레드가 데이터베이스 연결을 잡으면 파드 수 × 스레드 수만큼 연결이 열려 데이터베이스의 최대 연결 수가 먼저 고갈됩니다. 늘려야 한다면 병목이 스레드인지 힙인지 데이터베이스 대기인지 먼저 확인하고, CPU·메모리와 데이터베이스 연결 수를 함께 올린 뒤 한 단계씩 측정하며 조정하십시오.

설정 예시 (Deployment 런타임 환경 변수):

env:
  - name: TOMCAT_MAX_THREADS
    value: "300"
  - name: TOMCAT_MAX_CONNECTIONS
    value: "8192"
  - name: TOMCAT_MAX_POST_SIZE
    value: "104857600"

Tomcat HTTPS·종료 포트·로그·디버그

tomcat9-* 계열 이미지 전용이며 모두 런타임(경로 ③)에 넣습니다.

HTTPS 커넥터 — 아래 세 변수(_DIR·_CERTIFICATE·_CERTIFICATE_KEY)를 모두 함께 주면 8443 포트에 HTTPS 커넥터가 구성됩니다. 하나라도 빠지면 HTTPS 는 구성되지 않습니다.

변수	기본값	설명
`JWS_HTTPS_CERTIFICATE_DIR`	없음	인증서 파일이 들어 있는 디렉터리 경로
`JWS_HTTPS_CERTIFICATE`	없음	서버 인증서 파일 이름 (디렉터리 기준 상대 경로)
`JWS_HTTPS_CERTIFICATE_KEY`	없음	서버 개인 키 파일 이름
`JWS_HTTPS_CERTIFICATE_PASSWORD`	없음	개인 키의 암호 (설정한 경우)
`JWS_HTTPS_CACERTIFICATE`	없음	인증서 체인(중간 CA) 파일 이름 (설정한 경우)

인증서 관련 값은 시크릿으로 넣으십시오. 개인 키 암호(JWS_HTTPS_CERTIFICATE_PASSWORD)를 평문으로 두지 말고 시크릿을 참조합니다.

env:
  - name: JWS_HTTPS_CERTIFICATE_DIR
    value: "/etc/tls"
  - name: JWS_HTTPS_CERTIFICATE
    value: "tls.crt"
  - name: JWS_HTTPS_CERTIFICATE_KEY
    value: "tls.key"
  - name: JWS_HTTPS_CERTIFICATE_PASSWORD
    valueFrom:
      secretKeyRef:
        name: tls-key-password
        key: password        # 값: *****

종료 포트·로그·디버그

변수	기본값	설명
`TOMCAT_SHUTDOWN_PORT`	`-1`	Tomcat 종료 명령 포트. 기본값 `-1` 은 포트를 열지 않습니다. 이 이미지는 종료를 SIGTERM 신호로 처리하므로 이 포트가 필요하지 않습니다. 되살려야 할 때만 포트 번호를 지정합니다
`TOMCAT_SHUTDOWN`	기동마다 난수	종료 명령 문자열. 지정하지 않으면 컨테이너가 뜰 때마다 무작위 값으로 정해집니다. 종료 포트를 켠 경우에만 의미가 있습니다
`ENABLE_ACCESS_LOG`	`false`	`true` 로 주면 접근 로그(AccessLogValve)를 표준 출력으로 내보냅니다
`DISABLE_REMOTE_IP_VALVE`	없음(사용)	프록시 뒤에서 원래 클라이언트 주소를 복원하는 RemoteIpValve 를 끕니다
`DEBUG`	없음	`true` 로 주면 기동 스크립트의 디버그 로그를 출력하고, Tomcat 오류 페이지에 상세 정보(스택 추적·서버 버전)를 함께 노출합니다. 운영 환경에서는 켜지 마십시오
`JWS_SERVER_NAME`	없음	커넥터의 `server` 속성값. 응답 헤더에 노출되는 서버 이름을 지정한 값으로 바꿉니다

Tomcat 데이터베이스 연동 (JNDI·Realm)

tomcat9-* 계열 이미지 전용, 런타임(경로 ③)입니다. 애플리케이션이 JNDI(Java Naming and Directory Interface)로 데이터베이스에 접근하거나, Tomcat 이 데이터베이스로 사용자 인증(Realm)을 할 때 씁니다.

JNDI 데이터소스 — 두 가지 방법이 있습니다.

RESOURCES 에 접두어를 쉼표로 나열하고, 접두어별로 아래 값을 각각 지정합니다.

변수 (접두어 `<P>`)	설명
`RESOURCES`	데이터소스 접두어 목록 (예: `DB1,DB2`)
`<P>_NAME`	JNDI 이름 (예: `jdbc/mydb`)
`<P>_DRIVER`	JDBC 드라이버 클래스
`<P>_URL`	접속 URL
`<P>_USERNAME`	사용자 이름
`<P>_PASSWORD`	비밀번호 — 시크릿으로 넣습니다
`<P>_TYPE`	자원 유형 (기본 `javax.sql.DataSource`)
`<P>_MIN_POOL_SIZE` / `<P>_MAX_POOL_SIZE`	커넥션 풀 최소·최대 크기 (선택)

env:
  - name: RESOURCES
    value: "DB1"
  - name: DB1_NAME
    value: "jdbc/mydb"
  - name: DB1_DRIVER
    value: "org.mariadb.jdbc.Driver"
  - name: DB1_URL
    value: "jdbc:mariadb://mariadb:3306/appdb"
  - name: DB1_USERNAME
    value: "appuser"
  - name: DB1_PASSWORD
    valueFrom:
      secretKeyRef:
        name: db1-secret
        key: password        # 값: *****

DB_SERVICE_PREFIX_MAPPING 은 쿠버네티스 서비스 환경 변수를 이용해 데이터소스를 자동으로 구성하는 방법입니다. 형식은 <서비스명>=<접두어> 이며, 해당 서비스의 _SERVICE_HOST· _SERVICE_PORT 를 함께 참고합니다.

데이터베이스 기반 인증 (DataSourceRealm) — 아래 다섯 변수를 모두 함께 주면 Tomcat 이 지정한 데이터소스를 통해 사용자 인증을 수행합니다. 하나라도 빠지면 Realm 은 구성되지 않습니다.

변수	기본값	설명
`JWS_REALM_DATASOURCE_NAME`	`jdbc/auth`	인증에 사용할 JNDI 데이터소스 이름
`JWS_REALM_USERTABLE`	없음	사용자 테이블 이름
`JWS_REALM_USERNAME_COL`	없음	사용자 이름 컬럼
`JWS_REALM_USERCRED_COL`	없음	비밀번호(자격 증명) 컬럼
`JWS_REALM_USERROLE_TABLE`	없음	사용자-역할 매핑 테이블
`JWS_REALM_ROLENAME_COL`	없음	역할 이름 컬럼

인증 정보가 담긴 테이블·컬럼 값은 그대로 노출해도 되지만, 데이터소스가 참조하는 데이터베이스 비밀번호는 위 RESOURCES 예시처럼 시크릿으로 넣습니다.

Node.js

참고: Node.js S2I 컨테이너 이미지 환경 변수 상세:

Node.js 20

Node.js 22

런타임 설정:

변수	기본값	설명
`NODE_ENV`	`production`	Node.js 런타임 모드 (`production` / `development`)
`NPM_RUN`	`start`	실행할 npm 스크립트 (`package.json`의 scripts 섹션)
`NODE_CMD`	-	npm start 대신 사용할 사용자 정의 시작 명령
`INIT_WRAPPER`	`false`	`true` 설정 시 init-wrapper 스크립트로 애플리케이션 시작

빌드 설정:

변수	기본값	설명
`NPM_BUILD`	`build`	빌드 시 실행할 npm 스크립트 (`package.json`의 scripts 섹션)
`NPM_MIRROR`	-	npm 패키지 다운로드용 사용자 정의 레지스트리 미러 URL
`npm_config_loglevel`	-	npm install 시 로그 출력 레벨

개발 모드:

변수	기본값	설명
`DEV_MODE`	`false`	`true` 설정 시 nodemon으로 서버 자동 재시작 활성화
`DEBUG_PORT`	`5858`	디버그 포트 (`DEV_MODE=true`일 때만 유효)

참고: DEV_MODE=true 설정 시 NODE_ENV가 명시적으로 설정되지 않으면 자동으로 development로 변경됩니다.

프록시 설정:

변수	설명
`HTTP_PROXY`	빌드 시 npm 프록시 URL
`HTTPS_PROXY`	빌드 시 npm 프록시 URL (HTTPS)

Python

참고: Python S2I 컨테이너 이미지 환경 변수 상세:

Python 3.9

Python 3.11

Python 3.12

애플리케이션 실행 설정:

변수	기본값	설명
`APP_SCRIPT`	`app.sh`	애플리케이션 시작 스크립트 경로
`APP_FILE`	`app.py`	Python 인터프리터에 전달할 Python 파일 경로
`APP_MODULE`	`application`	WSGI callable 패턴 (`MODULE_NAME:VARIABLE_NAME`)
`APP_HOME`	`.` (루트)	`wsgi.py` 또는 `manage.py`가 있는 서브디렉터리
`APP_CONFIG`	-	Gunicorn 설정 파일 경로
`PORT`	`8080`	HTTP 리스닝 포트

Gunicorn 설정:

변수	기본값	설명
`WEB_CONCURRENCY`	`(코어 수 × 2)`, 최대 12	Gunicorn 워커 수

Django 설정:

변수	기본값	설명
`DISABLE_MIGRATE`	`false`	`true` 설정 시 `manage.py migrate` 실행 건너뜀
`DISABLE_COLLECTSTATIC`	`false`	`true` 설정 시 `manage.py collectstatic` 실행 건너뜀

의존성 관리:

변수	기본값	설명
`ENABLE_PIPENV`	`false`	`true` 설정 시 Pipenv로 의존성 관리
`PIN_PIPENV_VERSION`	-	특정 Pipenv 버전 지정 (예: `2018.11.26`)
`ENABLE_MICROPIPENV`	`false`	`true` 설정 시 micropipenv 래퍼 사용 (requirements.txt, Pipenv, Poetry 지원)
`PIP_INDEX_URL`	PyPI	사용자 정의 PyPI 인덱스 또는 미러 URL
`UPGRADE_PIP_TO_LATEST`	`false`	`true` 설정 시 pip, setuptools, wheel 최신 버전으로 업그레이드

빌드 옵션:

변수	기본값	설명
`DISABLE_SETUP_PY_PROCESSING`	`false`	`true` 설정 시 setup.py 처리 건너뜀
`ENABLE_INIT_WRAPPER`	`false`	`true` 설정 시 좀비 프로세스 정리용 init wrapper 활성화

PHP

참고: PHP S2I 컨테이너 이미지 환경 변수 상세:

PHP 8.2

PHP 8.3

PHP 기본 설정:

변수	기본값	설명
`PHP_MEMORY_LIMIT`	`128M`	PHP 메모리 제한
`DOCUMENTROOT`	`/`	DocumentRoot 경로 (예: `/public`)
`INCLUDE_PATH`	`.:/opt/app-root/src:/usr/share/pear`	PHP 소스 파일 경로
`SHORT_OPEN_TAG`	`OFF`	`<? ?>` 단축 태그 인식 여부
`PHP_CLEAR_ENV`	`ON`	FPM 워커에서 환경 변수 초기화

에러 처리:

변수	기본값	설명
`ERROR_REPORTING`	`E_ALL & ~E_NOTICE`	PHP 에러 리포팅 레벨
`DISPLAY_ERRORS`	`ON`	에러, 경고, 알림 출력 여부
`DISPLAY_STARTUP_ERRORS`	`OFF`	PHP 시작 시 에러 표시
`HTML_ERRORS`	`ON`	에러를 문서 링크와 연결

세션 설정:

변수	기본값	설명
`SESSION_NAME`	`PHPSESSID`	세션 이름
`SESSION_HANDLER`	`files`	세션 저장 방식
`SESSION_PATH`	`/tmp/sessions`	세션 데이터 파일 위치
`SESSION_COOKIE_DOMAIN`	-	쿠키 유효 도메인
`SESSION_COOKIE_HTTPONLY`	`0`	httpOnly 플래그 추가 여부
`SESSION_COOKIE_SECURE`	`Off`	HTTPS 전용 쿠키 여부

OPcache 설정:

변수	기본값	설명
`OPCACHE_MEMORY_CONSUMPTION`	`128`	OPcache 공유 메모리 크기 (MB)
`OPCACHE_REVALIDATE_FREQ`	`2`	스크립트 타임스탬프 확인 주기 (초)
`OPCACHE_MAX_FILES`	`4000`	OPcache 해시 테이블 최대 키(스크립트) 수

Apache MPM 설정:

변수	기본값	설명
`HTTPD_START_SERVERS`	`8`	시작 시 생성할 자식 서버 프로세스 수
`HTTPD_MAX_REQUEST_WORKERS`	`256`	동시 요청 처리 최대 수
`HTTPD_MAX_REQUESTS_PER_CHILD`	`4000`	개별 자식 프로세스당 처리할 최대 연결 수
`HTTPD_MAX_KEEPALIVE_REQUESTS`	`100`	연결당 허용되는 최대 요청 수

Composer 설정:

변수	기본값	설명
`COMPOSER_MIRROR`	-	사용자 정의 Composer 저장소 미러 URL
`COMPOSER_INSTALLER`	-	Composer 다운로드 URL 덮어쓰기
`COMPOSER_VERSION`	-	설치할 Composer 버전 지정
`COMPOSER_ARGS`	-	`composer install` 명령에 추가할 인수

PHP 설정 덮어쓰기:

변수	설명
`PHPRC`	php.ini 파일 경로
`PHP_INI_SCAN_DIR`	추가 ini 설정 파일 스캔 경로

Ruby

참고: Ruby S2I 컨테이너 이미지 환경 변수 상세:

Ruby 3.3

애플리케이션 환경:

변수	기본값	설명
`RACK_ENV`	-	배포 환경 지정 (`production`, `development`, `test`)
`RAILS_ENV`	-	Rails 애플리케이션 환경 (Hot Deploy 시 `development` 설정)
`DISABLE_ASSET_COMPILATION`	-	`true` 설정 시 에셋 컴파일 건너뜀 (프로덕션 환경에만 적용)

참고: production 환경에서만 에셋 컴파일이 수행됩니다. 개발 환경에서 Hot Deploy를 사용하려면 RAILS_ENV=development 또는 RACK_ENV=development로 설정하세요.

Puma 웹 서버 설정:

변수	기본값	설명
`PUMA_MIN_THREADS`	-	Puma 스레드 풀 최소 스레드 수
`PUMA_MAX_THREADS`	-	Puma 스레드 풀 최대 스레드 수
`PUMA_WORKERS`	CPU 코어 수	클러스터 모드에서 실행할 워커 프로세스 수

패키지 관리:

변수	기본값	설명
`RUBYGEM_MIRROR`	-	RubyGems 미러 URL (빌드 시 gem 다운로드용)

Nginx

참고: Nginx 컨테이너 이미지 환경 변수 상세:

Nginx 1.26

변수	기본값	설명
`NGINX_LOG_TO_VOLUME`	-	설정 시 로그를 `/var/log/nginx/`에 기록 (기본: stdout/stderr)

참고: Nginx 설정은 주로 환경 변수가 아닌 설정 파일을 통해 구성됩니다:

./nginx.conf - 메인 설정 파일

./nginx-cfg/*.conf - 추가 nginx 설정

./nginx-default-cfg/*.conf - 기본 서버 블록 스니펫

./nginx-start/*.sh - nginx 시작 전 실행할 쉘 스크립트

httpd

참고: Apache httpd 컨테이너 이미지 환경 변수 상세:

httpd 2.4

변수	기본값	설명
`HTTPD_LOG_TO_VOLUME`	-	설정 시 로그를 `/var/log/httpd24`에 기록 (기본: stdout)
`HTTPD_MPM`	`prefork`	Multi-Processing Module 설정 (`event`, `prefork`, `worker`)

참고: httpd 설정은 주로 설정 파일을 통해 구성됩니다:

./httpd-cfg/*.conf - 추가 httpd 설정

./httpd-pre-init/*.sh - httpd 시작 전 실행할 쉘 스크립트

./httpd-ssl/certs/ - SSL 인증서 디렉터리

./httpd-ssl/private/ - SSL 개인키 디렉터리

Varnish

참고: Varnish 컨테이너 이미지 상세:

Varnish 6

Varnish 컨테이너는 주로 VCL(Varnish Configuration Language) 파일로 구성하며, 아래 두 환경 변수를 함께 지원합니다. 모두 런타임(경로 ③)에 넣습니다.

변수	기본값	설명
`VARNISH_VCL`	`/etc/varnish/default.vcl`	Varnish 가 읽을 VCL 파일 경로. 다른 위치의 VCL 을 쓰려면 이 값을 바꿉니다
`VARNISH_TTL`	`120`	기본 캐시 보관 시간(초). VCL 에서 별도로 지정하지 않은 응답에 적용됩니다

VCL 설정 방법:

S2I 빌드 시 소스 디렉터리에 default.vcl 파일을 포함하여 Varnish 설정을 정의합니다:

# default.vcl 예시
vcl 4.0;

backend default {
    .host = "backend-service";
    .port = "8080";
}

sub vcl_recv {
    # 요청 처리 로직
}

sub vcl_backend_response {
    # 백엔드 응답 처리 로직
}

참고: Varnish 로그는 기본적으로 stdout으로 출력되며, podman logs 또는 kubectl logs 명령으로 확인할 수 있습니다.

MariaDB

참고: MariaDB 컨테이너 이미지 환경 변수 상세:

MariaDB 10.11

비밀번호는 시크릿으로 넣으십시오. 아래 MYSQL_PASSWORD·MYSQL_ROOT_PASSWORD 를 비롯한 데이터베이스 계열(MariaDB·MySQL·PostgreSQL·Redis)의 비밀번호 변수는 Deployment env 에 평문으로 두지 말고 valueFrom.secretKeyRef 로 시크릿을 참조합니다(예시는 Tomcat 데이터베이스 연동 절 참고).

필수 환경 변수:

변수	설명
`MYSQL_USER`	생성할 데이터베이스 사용자 이름
`MYSQL_PASSWORD`	데이터베이스 사용자 비밀번호
`MYSQL_DATABASE`	생성할 데이터베이스 이름

선택 환경 변수:

변수	기본값	설명
`MYSQL_ROOT_PASSWORD`	-	root 사용자 비밀번호 (원격 접속 허용 시 필요)
`MYSQL_CHARSET`	`utf8`	기본 문자셋
`MYSQL_COLLATION`	`utf8_general_ci`	기본 콜레이션

성능 튜닝:

변수	기본값	설명
`MYSQL_MAX_CONNECTIONS`	`151`	최대 동시 클라이언트 연결 수
`MYSQL_MAX_ALLOWED_PACKET`	`200M`	패킷 또는 생성된 문자열 최대 크기
`MYSQL_TABLE_OPEN_CACHE`	`400`	모든 스레드의 오픈 테이블 캐시 수
`MYSQL_KEY_BUFFER_SIZE`	`32M` 또는 메모리 10%	인덱스 블록 버퍼 크기
`MYSQL_SORT_BUFFER_SIZE`	`256K`	정렬 작업 버퍼 크기
`MYSQL_READ_BUFFER_SIZE`	`8M` 또는 메모리 5%	순차 스캔 버퍼 크기
`MYSQL_INNODB_BUFFER_POOL_SIZE`	`32M` 또는 메모리 50%	InnoDB 테이블/인덱스 캐시 버퍼
`MYSQL_INNODB_LOG_FILE_SIZE`	`8M` 또는 메모리 15%	각 로그 파일 크기
`MYSQL_INNODB_LOG_BUFFER_SIZE`	`8M` 또는 메모리 15%	InnoDB 디스크 로그 쓰기 버퍼

전문 검색 설정:

변수	기본값	설명
`MYSQL_FT_MIN_WORD_LEN`	`4`	FULLTEXT 인덱스 최소 단어 길이
`MYSQL_FT_MAX_WORD_LEN`	`20`	FULLTEXT 인덱스 최대 단어 길이

고급 설정:

변수	기본값	설명
`MYSQL_LOWER_CASE_TABLE_NAMES`	`0`	테이블 이름 대소문자 구분 제어
`MYSQL_AIO`	`1`	`innodb_use_native_aio` 설정
`MYSQL_BINLOG_FORMAT`	`statement`	복제 로그 형식 (`row`, `statement`)
`MYSQL_LOG_QUERIES_ENABLED`	`0`	`1` 설정 시 쿼리 로깅 활성화
`MYSQL_DEFAULTS_FILE`	`/etc/my.cnf`	대체 설정 파일 경로
`MYSQL_DATADIR_ACTION`	`upgrade-warn`	업그레이드 동작 (`upgrade-auto`, `upgrade-force`, `optimize`, `analyze`, `disable`)

데이터 디렉터리:

컨테이너의 데이터 디렉터리는 /var/lib/mysql/data입니다. 영구 저장을 위해 볼륨을 마운트하세요.

MySQL

참고: MySQL 컨테이너 이미지 환경 변수 상세:

MySQL 8.4

필수 환경 변수:

변수	설명
`MYSQL_USER`	생성할 데이터베이스 사용자 이름
`MYSQL_PASSWORD`	데이터베이스 사용자 비밀번호
`MYSQL_DATABASE`	생성할 데이터베이스 이름

선택 환경 변수:

변수	기본값	설명
`MYSQL_ROOT_PASSWORD`	-	root 사용자 비밀번호 (원격 접속 허용 시 필요)
`MYSQL_CHARSET`	`utf8mb4`	기본 문자셋
`MYSQL_COLLATION`	`utf8mb4_0900_ai_ci`	기본 콜레이션

인증 설정 (MySQL 8.x 전용):

변수	기본값	설명
`MYSQL_AUTHENTICATION_POLICY`	`caching_sha2_password,,`	인증 정책 설정
`MYSQL_DEFAULT_AUTHENTICATION_PLUGIN`	`caching_sha2_password`	기본 인증 플러그인 (`mysql_native_password`, `caching_sha2_password`) - deprecated

참고: MySQL 8.x는 기본 인증 플러그인으로 caching_sha2_password를 사용합니다. 레거시 클라이언트 호환성이 필요한 경우 mysql_native_password로 변경하세요.

성능 튜닝:

변수	기본값	설명
`MYSQL_MAX_CONNECTIONS`	`151`	최대 동시 클라이언트 연결 수
`MYSQL_MAX_ALLOWED_PACKET`	`200M`	패킷 또는 생성된 문자열 최대 크기
`MYSQL_TABLE_OPEN_CACHE`	`400`	모든 스레드의 오픈 테이블 캐시 수
`MYSQL_KEY_BUFFER_SIZE`	`32M` 또는 메모리 10%	인덱스 블록 버퍼 크기
`MYSQL_SORT_BUFFER_SIZE`	`256K`	정렬 작업 버퍼 크기
`MYSQL_READ_BUFFER_SIZE`	`8M` 또는 메모리 5%	순차 스캔 버퍼 크기
`MYSQL_INNODB_BUFFER_POOL_SIZE`	`32M` 또는 메모리 50%	InnoDB 테이블/인덱스 캐시 버퍼
`MYSQL_INNODB_LOG_FILE_SIZE`	`8M` 또는 메모리 15%	각 로그 파일 크기
`MYSQL_INNODB_LOG_BUFFER_SIZE`	`8M` 또는 메모리 15%	InnoDB 디스크 로그 쓰기 버퍼

전문 검색 설정:

변수	기본값	설명
`MYSQL_FT_MIN_WORD_LEN`	`4`	FULLTEXT 인덱스 최소 단어 길이
`MYSQL_FT_MAX_WORD_LEN`	`20`	FULLTEXT 인덱스 최대 단어 길이

고급 설정:

변수	기본값	설명
`MYSQL_LOWER_CASE_TABLE_NAMES`	`0`	테이블 이름 대소문자 구분 제어
`MYSQL_AIO`	`1`	`innodb_use_native_aio` 설정
`MYSQL_BINLOG_FORMAT`	`statement`	복제 로그 형식 (`row`, `statement`)
`MYSQL_LOG_QUERIES_ENABLED`	`0`	`1` 설정 시 쿼리 로깅 활성화
`MYSQL_DEFAULTS_FILE`	`/etc/my.cnf`	대체 설정 파일 경로
`MYSQL_DATADIR_ACTION`	-	데이터 디렉터리 작업 (`optimize`, `analyze` - 쉼표로 구분)

데이터 디렉터리:

컨테이너의 데이터 디렉터리는 /var/lib/mysql/data입니다. 영구 저장을 위해 볼륨을 마운트하세요.

PostgreSQL

참고: PostgreSQL 컨테이너 이미지 환경 변수 상세:

PostgreSQL 16

필수 환경 변수:

변수	설명
`POSTGRESQL_USER`	생성할 데이터베이스 사용자 이름
`POSTGRESQL_PASSWORD`	데이터베이스 사용자 비밀번호
`POSTGRESQL_DATABASE`	생성할 데이터베이스 이름

선택 환경 변수:

변수	기본값	설명
`POSTGRESQL_ADMIN_PASSWORD`	-	postgres 관리자 계정 비밀번호

성능 튜닝:

변수	기본값	설명
`POSTGRESQL_MAX_CONNECTIONS`	`100`	최대 클라이언트 연결 수
`POSTGRESQL_MAX_PREPARED_TRANSACTIONS`	`0`	prepared 상태의 최대 트랜잭션 수
`POSTGRESQL_SHARED_BUFFERS`	메모리 1/4 또는 `32M`	데이터 캐싱용 공유 메모리
`POSTGRESQL_EFFECTIVE_CACHE_SIZE`	메모리 1/2 또는 `128M`	디스크 캐시 예상 사용 가능 메모리

로깅 및 확장:

변수	기본값	설명
`POSTGRESQL_LOG_DESTINATION`	`/var/lib/pgsql/data/userdata/log/`	에러 로그 저장 위치
`POSTGRESQL_LIBRARIES`	-	`shared_preload_libraries`에 로드할 라이브러리 (쉼표 구분)
`POSTGRESQL_EXTENSIONS`	-	서버 시작 시 생성할 확장 목록 (공백 구분)

데이터 마이그레이션:

변수	기본값	설명
`POSTGRESQL_MIGRATION_REMOTE_HOST`	-	마이그레이션 소스 호스트명/IP
`POSTGRESQL_MIGRATION_ADMIN_PASSWORD`	-	원격 postgres 관리자 비밀번호
`POSTGRESQL_MIGRATION_IGNORE_ERRORS`	`no`	`yes` 설정 시 SQL 가져오기 오류 무시

데이터베이스 업그레이드:

변수	설명
`POSTGRESQL_UPGRADE`	PostgreSQL 15에서 업그레이드 (`copy` 또는 `hardlink`)

데이터 디렉터리:

컨테이너의 데이터 디렉터리는 /var/lib/pgsql/data입니다. 영구 저장을 위해 볼륨을 마운트하세요.

Redis

참고: Redis 컨테이너 이미지 환경 변수 상세:

Redis 7

환경 변수:

변수	기본값	설명
`REDIS_PASSWORD`	-	Redis 서버 접근 비밀번호 (선택)

보안 참고: Redis는 초당 약 150,000개의 비밀번호를 처리할 수 있으므로, 추측하기 어려운 긴 비밀번호를 쓰십시오.

데이터 디렉터리:

컨테이너의 데이터 디렉터리는 /var/lib/redis/data입니다. 영구 저장을 위해 볼륨을 마운트하세요.

Redis 설정 커스터마이징: 추가 Redis 설정이 필요한 경우 설정 파일을 마운트하여 사용할 수 있습니다.

Tomcat S2I 이미지의 보안 설정

tomcat9-*-s2i 이미지에는 아래 보안 설정이 이미 적용되어 있습니다. 다섯 이미지 (tomcat9-jdk8-ubi8-s2i · tomcat9-jdk11-ubi8-s2i · tomcat9-jdk17-ubi8-s2i · tomcat9-jdk17-ubi9-s2i · tomcat9-jdk21-ubi9-s2i)가 모두 같습니다.

취약점 분석·평가에서 근거 자료로 제시할 수 있도록 한자리에 정리했습니다. 각 항목을 바꾸는 환경 변수는 앞의 OpenJDK/Tomcat 공통 절과 Tomcat HTTPS·종료 포트·로그·디버그 절에 있습니다.

항목	적용 내용	되돌리면
비root 실행	컨테이너를 UID 185로 실행합니다	별도 설정으로 바꾸지 마십시오
관리·예제 웹앱 제거	`manager` · `host-manager` · `docs` · `examples` · `ROOT` 를 이미지에서 삭제했습니다	—
종료 포트	열지 않습니다 (`TOMCAT_SHUTDOWN_PORT` 기본값 `-1`)	포트를 지정하면 그 포트로 종료 명령을 받습니다
종료 명령 문자열	기동할 때마다 무작위로 정합니다	`TOMCAT_SHUTDOWN` 을 지정하면 그 값으로 고정됩니다
AJP 커넥터	사용하지 않습니다 (8009 포트를 열지 않습니다)	—
오류 페이지	스택 추적과 Tomcat 버전을 표시하지 않습니다	`DEBUG=true` 를 주면 둘 다 표시됩니다
세션 쿠키	`HttpOnly` 속성을 붙여 스크립트가 읽지 못하게 합니다	—
웹 애플리케이션 권한	컨테이너 내부 API 에 접근하지 못하게 합니다 (`privileged="false"`)	—
클라이언트 주소	프록시 뒤에서 원래 주소를 복원합니다 (`RemoteIpValve`)	`DISABLE_REMOTE_IP_VALVE` 로 끕니다

관리 웹앱을 제거한 이유

Tomcat 의 manager 와 host-manager 는 원격으로 애플리케이션을 배포하고 서버를 관리하는 웹앱입니다. 컨테이너 환경에서는 배포를 S2I 빌드와 파드 재시작으로 처리하므로 필요하지 않고, 남겨 두면 인증만 뚫리면 임의의 애플리케이션을 올릴 수 있는 경로가 됩니다. examples 는 세션과 쿠키를 조작하는 예제를, docs 는 Tomcat 버전 정보를 포함합니다.

이미지에서는 이 다섯 개를 삭제한 뒤 webapps 디렉터리를 /deployments 로 연결하므로, 실행 중인 컨테이너의 웹앱은 S2I 빌드로 넣은 애플리케이션뿐입니다.

DEBUG 환경 변수 주의

🚨 DEBUG=true 는 로그만 늘리는 설정이 아닙니다. Tomcat 오류 페이지에 스택 추적과 서버 버전을 함께 노출합니다. 운영 환경에서는 켜지 마십시오. 문제를 재현할 때만 일시적으로 켜고, 확인이 끝나면 되돌립니다.

HTTPS 는 기본으로 구성되지 않습니다

⚠️ 이미지가 8443 포트를 선언하고 있지만 기본 상태에서는 그 포트로 듣지 않습니다. Tomcat HTTPS·종료 포트·로그·디버그 절의 인증서 환경 변수 세 개(JWS_HTTPS_CERTIFICATE_DIR · JWS_HTTPS_CERTIFICATE · JWS_HTTPS_CERTIFICATE_KEY)를 모두 주었을 때만 HTTPS 커넥터가 만들어집니다. 하나라도 빠지면 구성되지 않습니다.

클러스터 안에서는 보통 Ingress 가 TLS 를 처리하므로 컨테이너까지 HTTPS 를 내릴 필요가 없습니다. 컨테이너에서 직접 TLS 를 끝내야 하는 경우에만 설정하고, 개인 키 암호(JWS_HTTPS_CERTIFICATE_PASSWORD)는 평문으로 두지 말고 시크릿을 참조합니다.

UID 185 와 그룹 0

파드의 securityContext 에 runAsUser: 185 와 함께 runAsGroup: 0 을 쓰기를 권장합니다. 이유는 다음과 같습니다.

이미지의 파일은 185:0 소유이고, 그룹에 소유자와 같은 권한을 부여해 두었습니다. 그래서 파드에 다른 UID 가 배정되어도 그 프로세스가 그룹 0에 속하면 애플리케이션 디렉터리를 그대로 읽고 쓸 수 있습니다. 보안 정책상 UID 를 지정해야 하는 환경에서 runAsUser 를 185가 아닌 값으로 바꾸어도 동작하도록 하기 위한 구성입니다.

runAsGroup: 0 은 컨테이너 프로세스를 root 사용자로 실행한다는 뜻이 아닙니다. 사용자는 runAsNonRoot: true 와 runAsUser 로 지정한 비root 사용자입니다.

적용하지 않은 항목

항목	상태
Tomcat 보안 리스너(`SecurityListener`)	적용하지 않았습니다. 이 리스너는 root 실행을 막고 `umask` 를 검사하는데, 이미지가 UID 185로 실행되므로 같은 목적이 달성됩니다
`TRACE` 메서드	Tomcat 기본 설정에 따라 허용하지 않습니다
`X-Powered-By` 응답 헤더	Tomcat 기본 설정에 따라 내보내지 않습니다

어떨 때 보는가​

설치가 만들어 두는 S2I 예제 (openmaru-war-example)​

커스텀 빌드 스크립트​

환경 변수를 어디에 넣는가​

OpenJDK/Tomcat 공통 (JVM·가비지 컬렉션·빌드 도구·프록시)​

Tomcat 커넥터·동시 처리​

Tomcat HTTPS·종료 포트·로그·디버그​

Tomcat 데이터베이스 연동 (JNDI·Realm)​

Node.js​

Python​

PHP​

Ruby​

Nginx​

httpd​

Varnish​

MariaDB​

MySQL​

PostgreSQL​

Redis​

Tomcat S2I 이미지의 보안 설정​

어떨 때 보는가

설치가 만들어 두는 S2I 예제 (openmaru-war-example)

커스텀 빌드 스크립트

환경 변수를 어디에 넣는가

OpenJDK/Tomcat 공통 (JVM·가비지 컬렉션·빌드 도구·프록시)

Tomcat 커넥터·동시 처리

Tomcat HTTPS·종료 포트·로그·디버그

Tomcat 데이터베이스 연동 (JNDI·Realm)

Node.js

Python

PHP

Ruby

Nginx

httpd

Varnish

MariaDB

MySQL

PostgreSQL

Redis

Tomcat S2I 이미지의 보안 설정