SHIELD Mail Proxy 상세 설정 및 검증 가이드

문서 버전: 1.0
작성일: 2025-10-27
대상: DevOps, 네트워크 관리자, 고급 트러블슈팅
상태: Production Ready

개요

SHIELD Mail은 아웃바운드 트래픽을 프록시를 통해 관리할 수 있습니다. 이 문서는 프록시 설정의 상세 내용과 운영 방법을 다룹니다.

기능 설명

외부 통신 (프록시 경유)

인터넷 API 호출
클라우드 서비스 호출

내부 통신 (프록시 우회)

Redis, RabbitMQ, Elasticsearch
클러스터 내부 서비스 (*.svc.cluster.local)

SMTP 통신 (프록시 미사용)

SMTP(25 포트)는 HTTP가 아니므로 프록시 설정과 무관
방화벽에서 SMTP 아웃바운드 별도 허용 필요

자동 프록시 감지 및 검증

HTTP_PROXY 환경변수만 설정하면 자동 적용
Go: net/http 기본 지원
JVM: 시스템 프로퍼티로 지원

자동 프록시 검증:

Go 컨테이너: 시작 시 HTTP_PROXY 설정 확인 후 자동 프록시 연결 테스트 실행
JVM 컨테이너: JAVA_TOOL_OPTIONS의 -Dhttp.proxyHost 설정 확인 후 자동 프록시 연결 테스트 실행

아키텍처

배포 구조

SHIELD Mail (shieldmail-0)
 ├─ Go Container: HTTP_PROXY/HTTPS_PROXY 설정
 ├─ JVM Container: JAVA_TOOL_OPTIONS 설정
 └─ 프록시 경유 → Squid Proxy (3128 포트) → 인터넷

트래픽 흐름

외부 통신 (프록시 경유):

SHIELD Mail → Squid Proxy → 인터넷

내부 통신 (프록시 우회):

SHIELD Mail → 내부 서비스 (Redis, RabbitMQ, Elasticsearch)

설정 방법

1. Squid Proxy 배포

# 1. Squid 프록시 배포
kubectl apply -f build/squid-proxy-deploy.yaml

# 2. 배포 확인
kubectl get pod -n dev -l app=squid-proxy
# 예상 결과: squid-proxy-XXXXX 1/1 Running

주요 리소스:

ConfigMap: squid-config (ACL, 캐시 설정)
Deployment: squid-proxy (1 replica)
Service: squid-proxy (ClusterIP 3128)
Service: squid-proxy-headless (DNS 조회용)

2. SHIELD Mail 프록시 설정

build/kube-deploy.yaml의 ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: shieldmail-config
  namespace: dev
data:
  # Go 컨테이너 프록시 설정
  HTTP_PROXY: "http://squid-proxy.dev.svc.cluster.local:3128"
  HTTPS_PROXY: "http://squid-proxy.dev.svc.cluster.local:3128"
  NO_PROXY: "localhost,127.0.0.1,.svc.cluster.local,.cluster.local,10.42.0.0/16,10.43.0.0/16,redis-sentinel-ha-headless.dev.svc.cluster.local,security365-rabbitmq-headless.dev.svc.cluster.local,elasticsearch-cluster-data.elasticsearch.svc.cluster.local,cloud-oauth-service.dev.svc.cluster.local,cloud-idgp-resource-api.dev.svc.cluster.local,cloud-log-service.dev.svc.cluster.local,cloud-skms-service.dev.svc.cluster.local,squid-proxy.dev.svc.cluster.local"

  # JVM 컨테이너 프록시 설정
  JAVA_TOOL_OPTIONS: "-Dhttp.proxyHost=squid-proxy.dev.svc.cluster.local -Dhttp.proxyPort=3128 -Dhttps.proxyHost=squid-proxy.dev.svc.cluster.local -Dhttps.proxyPort=3128 -Dhttp.nonProxyHosts=localhost|127.0.0.1|*.svc.cluster.local|*.cluster.local|10.42.0.0/16|redis-sentinel-ha-headless|security365-rabbitmq-headless|elasticsearch-cluster-data|cloud-oauth-service|cloud-idgp-resource-api|cloud-log-service|cloud-skms-service|squid-proxy"

  # 프록시 인증이 필요한 경우 (선택사항)
  # Go: http://username:password@proxy.example.com:3128
  # JVM: -Dhttp.proxyUser=username -Dhttp.proxyPassword=password

3. StatefulSet 볼륨 설정 (JVM /tmp 지원)

volumes:
  - name: tmp
    emptyDir: {}          # /tmp 쓰기 권한 (Tomcat용)
  - name: tmp-app
    emptyDir: {}          # /opt/app/tmp

volumeMounts:
  - name: tmp
    mountPath: /tmp
  - name: tmp-app
    mountPath: /opt/app/tmp

4. 배포

# 설정 적용
kubectl apply -f build/kube-deploy.yaml

# 롤아웃 상태 확인
kubectl rollout status statefulset/shieldmail -n dev

프록시 검증 가이드

자동 검증 (Master 프로세스)

SHIELD Mail의 master 프로세스는 시작 시 자동으로 프록시 연결을 검증합니다.

검증 항목:

HTTP_PROXY 환경변수 설정 확인
Squid 프록시 포트(3128) 접근 가능성
외부 인터넷 통신 가능 여부
Via/X-Cache 헤더를 통한 프록시 경유 확인

1. 로그 기반 검증

# 실시간 로그 모니터링
kubectl logs -n dev shieldmail-0 -c shieldmail -f | grep "proxy"

# 배포 후 검증
kubectl logs -n dev shieldmail-0 -c shieldmail | grep -A 3 "proxy validation"

성공 로그 예시:

Starting HTTP proxy validation: http://squid-proxy.dev.svc.cluster.local:3128
Proxy validation response status: 200
Proxy validation success - Via header: 1.1 squid-proxy-75cccdb5f9-4dmjd (squid/3.5.27)
Proxy cache status - X-Cache: MISS from squid-proxy-75cccdb5f9-4dmjd
HTTP proxy validation completed successfully

2. 환경변수 검증

Go 컨테이너

kubectl exec -n dev shieldmail-0 -c shieldmail -- env | grep -i proxy

예상 결과:

HTTP_PROXY=http://squid-proxy.dev.svc.cluster.local:3128
HTTPS_PROXY=http://squid-proxy.dev.svc.cluster.local:3128
NO_PROXY=localhost,127.0.0.1,.svc.cluster.local,...

JVM 컨테이너

kubectl exec -n dev shieldmail-0 -c shieldmail-pep -- env | grep JAVA_TOOL_OPTIONS

예상 결과:

JAVA_TOOL_OPTIONS=-Dhttp.proxyHost=squid-proxy.dev.svc.cluster.local -Dhttp.proxyPort=3128 ...

3. 네트워크 연결 검증

# Squid 프록시 포트 접근 확인
kubectl exec -n dev shieldmail-0 -c shieldmail -- nc -zv squid-proxy.dev.svc.cluster.local 3128
# 성공 예시: (... open)

4. Squid 액세스 로그 확인

# 프록시를 통한 요청 로그 확인
kubectl logs -n dev deployment/squid-proxy | grep "httpbin.org"

# 실시간 모니터링
kubectl logs -n dev deployment/squid-proxy -f

운영 및 모니터링

프록시 상태 확인

# Squid Pod 상태 및 리소스 사용량
kubectl get pod -n dev -l app=squid-proxy
kubectl top pod -n dev -l app=squid-proxy

프록시 설정 변경

# ConfigMap 수정 후 재시작
kubectl edit configmap squid-config -n dev
kubectl rollout restart deployment squid-proxy -n dev

# SHIELD Mail 프록시 주소 변경
kubectl edit configmap shieldmail-config -n dev
kubectl rollout restart statefulset shieldmail -n dev

트러블슈팅

문제 1: Squid Pod이 Ready 상태가 아님

증상:

squid-proxy-XXXXX   0/1   CrashLoopBackOff

진단:

# 로그 확인
kubectl logs -n dev -l app=squid-proxy

# Pod 상태 확인
kubectl describe pod -n dev -l app=squid-proxy

# 이벤트 확인
kubectl get events -n dev --sort-by='.lastTimestamp' | tail -20

해결 방법:

로그에서 에러 메시지 확인
이미지 풀 가능성 확인: kubectl describe pod에서 ImagePullBackOff 확인
리소스 부족 확인: kubectl describe node
ConfigMap 문법 오류 확인: kubectl get configmap squid-config -o yaml

문제 2: SHIELD Mail에서 외부 연결 실패

증상:

curl: (7) Failed to connect to proxy

해결:

# Squid Pod 상태 확인
kubectl get pod -n dev -l app=squid-proxy

# 프록시 포트 접근 확인
kubectl exec -n dev shieldmail-0 -c shieldmail -- nc -zv squid-proxy.dev.svc.cluster.local 3128

# 환경변수 확인
kubectl exec -n dev shieldmail-0 -c shieldmail -- env | grep -i proxy

문제 3: 프록시는 연결되지만 외부 서비스 응답 없음 (502)

증상:

< HTTP/1.1 502 Bad Gateway

해결:

# Squid 로그 확인
kubectl logs -n dev deployment/squid-proxy | tail -50

# DNS 해석 확인
kubectl exec -n dev deployment/squid-proxy -- nslookup httpbin.org

원인:

Squid가 외부 서비스에 접근할 수 없음
네트워크 정책에서 TCP 80/443 아웃바운드 허용 확인 필요
DNS 해석 실패 가능성

문제 4: JVM 컨테이너의 /tmp 쓰기 오류

증상:

java.nio.file.FileSystemException: /tmp/tomcat-docbase.8080: Read-only file system

해결 방법: StatefulSet에 다음 설정 확인:

containers:
  - name: shieldmail-pep
    volumeMounts:
      - name: tmp
        mountPath: /tmp
      - name: tmp-app
        mountPath: /opt/app/tmp

volumes:
  - name: tmp
    emptyDir: {}
  - name: tmp-app
    emptyDir: {}

문제 4: SMTP 메일 전송 실패

증상:

fail to connect to MX=mail.example.com:25, connection timeout

원인: SMTP는 프록시 설정과 무관하며 직접 연결 사용

해결:

# 외부 SMTP 서버 연결 테스트
kubectl exec -n dev shieldmail-0 -c shieldmail -- nc -zv mail.example.com 25

조치:

방화벽/Azure NSG에서 SMTP(25 포트) 아웃바운드 허용
DNS 서버 정상 동작 확인

참고 자료

Go HTTP 프록시: net/http 기본 지원
Java 네트워크 설정: 시스템 프로퍼티로 지원
Squid: http://www.squid-cache.org/
Kubernetes: https://kubernetes.io/docs/concepts/services-networking/

배포 체크리스트

Squid 프록시 배포 완료 (1/1 Running)
SHIELD Mail ConfigMap 프록시 설정 추가
StatefulSet 볼륨 설정 (/tmp 쓰기 권한)
SHIELD Mail Pod 재배포 완료 (3/3 Running)
프록시 검증 로그 확인
SMTP(25 포트) 아웃바운드 허용 확인

버전 정보

항목	버전
SHIELD Mail	1.0.3.60+
Squid	3.5.27 (sameersbn/squid:latest)
Kubernetes	1.20+
문서 버전	1.0

문서 버전: 1.0
최종 수정일: 2025-10-29

목차​

개요​

기능 설명​

외부 통신 (프록시 경유)​

내부 통신 (프록시 우회)​

SMTP 통신 (프록시 미사용)​

자동 프록시 감지 및 검증​

아키텍처​

배포 구조​

트래픽 흐름​

설정 방법​

1. Squid Proxy 배포​

2. SHIELD Mail 프록시 설정​

3. StatefulSet 볼륨 설정 (JVM /tmp 지원)​

4. 배포​

프록시 검증 가이드​

자동 검증 (Master 프로세스)​

1. 로그 기반 검증​

2. 환경변수 검증​

Go 컨테이너​

JVM 컨테이너​

3. 네트워크 연결 검증​

4. Squid 액세스 로그 확인​

운영 및 모니터링​

프록시 상태 확인​

프록시 설정 변경​

트러블슈팅​

문제 1: Squid Pod이 Ready 상태가 아님​

문제 2: SHIELD Mail에서 외부 연결 실패​

문제 3: 프록시는 연결되지만 외부 서비스 응답 없음 (502)​

문제 4: JVM 컨테이너의 /tmp 쓰기 오류​

문제 4: SMTP 메일 전송 실패​

참고 자료​

배포 체크리스트​

버전 정보​

목차

개요

기능 설명

외부 통신 (프록시 경유)

내부 통신 (프록시 우회)

SMTP 통신 (프록시 미사용)

자동 프록시 감지 및 검증

아키텍처

배포 구조

트래픽 흐름

설정 방법

1. Squid Proxy 배포

2. SHIELD Mail 프록시 설정

3. StatefulSet 볼륨 설정 (JVM /tmp 지원)

4. 배포

프록시 검증 가이드

자동 검증 (Master 프로세스)

1. 로그 기반 검증

2. 환경변수 검증

Go 컨테이너

JVM 컨테이너

3. 네트워크 연결 검증

4. Squid 액세스 로그 확인

운영 및 모니터링

프록시 상태 확인

프록시 설정 변경

트러블슈팅

문제 1: Squid Pod이 Ready 상태가 아님

문제 2: SHIELD Mail에서 외부 연결 실패

문제 3: 프록시는 연결되지만 외부 서비스 응답 없음 (502)

문제 4: JVM 컨테이너의 /tmp 쓰기 오류

문제 4: SMTP 메일 전송 실패

참고 자료

배포 체크리스트

버전 정보