서비스 장애를 막기 위한 첫걸음
배포 버튼을 누른 직후, 갑자기 서비스 모니터링 대시보드에 붉은색 경고등이 들어옵니다. 사용자들은 접속이 안 된다고 항의하기 시작하고, 엔지니어는 당황하며 로그를 뒤지기 시작합니다. 분명히 이전 버전은 잘 작동했는데, 왜 이번 배포에서만 트래픽이 끊기는 걸까요? 대부분의 원인은 애플리케이션 코드 자체보다 쿠버네티스 서비스(Service) 설정의 사소한 실수에서 비롯됩니다.
클라우드 환경으로 전환하거나 대규모 마이그레이션을 진행할 때, 네트워크 설정 하나가 전체 시스템의 가용성을 결정짓습니다. 서비스는 단순히 포트를 열어주는 역할 그 이상을 수행하며, 파드(Pod) 간의 통신과 외부 트래픽의 통로 역할을 하기 때문입니다. 준비되지 않은 상태에서의 배포는 곧 서비스 중단으로 이어질 수 있습니다.
이 글에서는 실무에서 즉시 활용할 수 있는 서비스 체크리스트를 설계, 배포, 운영의 세 가지 관점에서 아주 상세하게 정리했습니다. 이 가이드를 따라 하나씩 검증한다면, 배포 시 발생하는 네트워크 통신 오류를 획기적으로 줄일 수 있습니다.
- 서비스 유형별 적합한 선택 기준과 설계 원칙
- 배포 전 반드시 확인해야 할 포트 및 셀렉터 설정
- 트래픽 유실을 방지하는 배포 직후 검증 절차
- 안정적인 운영을 위한 프로브(Probe) 및 보안 점검 항목
실패 없는 서비스를 위한 사전 준비
무작정 YAML 파일을 작성하기 전에, 우리 서비스가 어떤 방식으로 노출되어야 하는지 명확히 정의해야 합니다. 쿠버네티스는 다양한 서비스 타입을 제공하지만, 각 타입마다 동작 방식과 비용, 보안 수준이 완전히 다릅니다. 잘못된 타입을 선택하면 외부에서 접속이 안 되거나, 불필요하게 높은 비용이 발생할 수 있습니다.
가장 먼저 결정해야 할 것은 트래픽의 범위입니다. 클러스터 내부에서만 통신할 것인지, 아니면 실제 사용자가 접속할 수 있는 외부 경로를 열어줄 것인지에 따라 설계 방향이 완전히 달라집니다.
서비스 타입별 선택 기준 비교
| 서비스 타입 | 주요 용도 | 장점 | 주의점 |
|---|---|---|---|
| ClusterIP | 클러스터 내부 통신 | 가장 안전하고 효율적임 | 외부 접속 불가 |
| NodePort | 테스트 및 단순 외부 노출 | 설정이 매우 간편함 | 보안에 취약하고 포트 관리 어려움 |
| LoadBalancer | 실제 운영 환경 외부 노출 | 클라우드 통합 관리 가능 | 추가 비용 발생 |
| ExternalName | 외부 DNS 연결 | 외부 서비스를 내부처럼 사용 | 네트워크 라우팅 복잡도 증가 |
위 표를 기준으로 현재 인프라 상황과 예산을 고려하여 타입을 결정하세요. 예를 들어, 마이크로서비스 간의 API 통신에는 반드시 ClusterIP를 사용하여 보안을 강화해야 합니다. 반면, 웹 프론트엔드처럼 사용자가 직접 접속해야 하는 경우에는 클라우드 공급자의 로드밸런서를 활용하는 LoadBalancer 타입이 표준입니다.
NodePort를 운영 환경에서 직접 사용하는 것은 권장하지 않습니다. 특정 노드의 IP가 변경되거나 노드가 다운될 경우 서비스 접속이 끊길 위험이 크며, 포트 범위(30000-32767)를 관리하는 것도 매우 번거롭습니다.
준비 단계가 끝났다면, 이제 실제 설정 파일(YAML)에 담길 세부 항목들을 점검할 차례입니다. 다음 단계에서는 배포 과정에서 가장 실수가 많은 설정 항목들을 구체적으로 살펴보겠습니다.
단계별 실행: 서비스 배포 및 검증 가이드
서비스 설정은 작은 오타 하나로도 전체 트래픽을 차단할 수 있습니다. 단순히 코드를 작성하는 것에 그치지 않고, 각 단계에서 무엇을 어떻게 검증해야 하는지 아는 것이 중요합니다. 안정적인 서비스 점검을 위해 아래의 5단계 프로세스를 반드시 준수하세요.
STEP 1. 라벨(Label)과 셀렉터(Selector) 일치 여부 확인
쿠버네티스 서비스가 어떤 파드(Pod)로 트래픽을 보낼지 결정하는 핵심 메커니즘은 바로 라벨입니다. 서비스의 selector 항목에 적힌 값이 대상 파드의 labels와 단 한 글자라도 다르면, 서비스는 갈 곳을 잃고 방황하게 됩니다.
설계 단계에서는 반드시 파드의 템플릿 정의와 서비스의 셀렉터 정의를 나란히 놓고 대조해야 합니다. 가장 흔한 실수는 대소문자 구분 오류나 하이픈(-)과 언더바(_)의 혼용입니다. 배포 전에는 반드시 다음 명령어로 엔드포인트(Endpoints)가 정상적으로 생성되었는지 확인해야 합니다.
kubectl get endpoints [서비스명]
만약 결과값이
STEP 2. 포트(Port) 매핑 체계의 정밀 검증
서비스의 포트 설정은 세 가지 층위로 나뉩니다. 이 층위들을 정확히 구분하지 못하면 통신 오류가 발생합니다.
- Port: 서비스 자체가 외부(혹은 클러스터 내부)에서 듣는 포트입니다.
- TargetPort: 서비스가 트래픽을 전달할 실제 파드 내부의 컨테이너 포트입니다.
- NodePort: (NodePort 타입 사용 시) 모든 노드의 IP를 통해 접속할 수 있는 포트입니다.
배포 직전 확인 사항은 targetPort가 컨테이너 애플리케이션이 실제로 리스닝(Listening)하고 있는 포트와 일치하는지입니다. 예를 들어, 애플리케이션은 8080 포트로 떠 있는데 서비스의 targetPort를 80으로 설정했다면, 모든 연결 요청은 거부됩니다. 설정 파일에 명시된 포트 번호와 Dockerfile의 EXPOSE 명령어를 반드시 교차 검증하세요.
STEP 3. 배포 직후 엔드포인트 및 네트워크 흐름 테스트
배포가 완료되었다면, 논리적인 설정뿐만 아니라 실제 네트워크 패킷이 흐르는지 확인해야 합니다. 서비스가 생성되었다고 해서 트래픽이 목적지까지 도달하는 것은 아닙니다.
먼저 클러스터 내부의 다른 파드에서 curl 명령어를 사용하여 서비스 이름을 통해 접속을 시도해 보세요. 만약 내부 통신은 성공하는데 외부 통신만 안 된다면, 이는 서비스 설정 문제가 아니라 인프라 레벨의 로드밸런서나 보안 그룹(Security Group) 설정 문제일 가능성이 높습니다. 내부 통신까지 실패한다면 앞서 언급한 셀렉터나 포트 설정을 다시 점검해야 합니다.
STEP 4. 프로브(Probe) 설정을 통한 가용성 확보
운영 단계에서 가장 중요한 것은 서비스가 '준비된 파드'에만 트래픽을 보내도록 만드는 것입니다. 이를 위해 Readiness Probe와 Liveness Probe를 정교하게 설정해야 합니다.
Readiness Probe는 파드가 트래픽을 받을 준비가 되었는지 확인합니다. 애플리케이션이 부팅 중일 때 아직 DB 연결이 완료되지 않았다면, 이 프로브가 실패하도록 설정하여 서비스 엔드포인트에서 해당 파드를 일시적으로 제외해야 합니다. 만약 이 설정이 없다면, 부팅 중인 파드로 트래픽이 유입되어 사용자에게 502 Bad Gateway 에러를 보여주게 됩니다.
Liveness Probe는 파드가 살아있는지 확인하여 문제가 있으면 재시작시키고, Readiness Probe는 서비스에 포함할지를 결정합니다. 두 프로브를 혼동하여 잘못 설정하면, 애플리케이션이 정상적으로 부팅 중임에도 불구하고 계속해서 재시작되는 무한 루프에 빠질 수 있습니다.
STEP 5. 네트워크 정책(NetworkPolicy)과 보안 검토
마지막으로 보안을 점검해야 합니다. 쿠버네티스 클러스터 내부는 기본적으로 모든 파드 간 통신이 허용되어 있지만, 보안 규정이 엄격한 환경이라면 NetworkPolicy를 통해 트래픽을 제한해야 합니다. 서비스가 허용되지 않은 경로로부터의 접근을 막고 있는지, 필요한 포트만 열려 있는지 확인하는 것이 운영 점검 항목의 핵심입니다.
실제 점검 시나리오는 다음과 같습니다. kubectl describe networkpolicy 명령어를 통해 허용된 인그레스(Ingress) 규칙을 확인하고, 특정 네임스페이스나 라벨을 가진 파드만 접근할 수 있도록 제한되어 있는지 검토하세요.
실무 적용 예시: 서비스 배포 체크 시나리오
새로운 마이크로서비스 'order-api'를 배포할 때의 표준 절차입니다.
- 파드의 라벨이
app: order-api로 정확히 설정되었는지 확인합니다. - 서비스의 셀렉터가
app: order-api와 일치하는지 확인합니다. - 서비스 포트는 80, 타겟 포트는 컨테이너의 8080으로 설정되었는지 대조합니다.
kubectl get ep order-api를 실행하여 IP 목록이 나타나는지 확인합니다.- 내부 파드에서
curl order-api:80으로 응답을 받는지 테스트합니다. - Readiness Probe가 성공하여 서비스 엔드포인트에 파드가 등록되는지 모니터링합니다.
자주 하는 실수와 해결법 및 FAQ
현장에서 엔지니어들이 가장 빈번하게 겪는 실수들을 모았습니다. 문제를 해결하는 빠른 길을 확인하세요.
자주 하는 실수와 해결법
❌ 실수: 서비스는 생성되었는데 엔드포인트(Endpoints)가 비어 있음
왜 발생하는가: 서비스의 selector에 적힌 라벨이 파드의 labels와 일치하지 않기 때문입니다.
✅ 해결법: 파드의 상세 정보(kubectl get pod --show-labels)를 확인하여 라벨의 오타, 대소문자, 혹은 하이픈 사용 여부를 서비스 설정과 대조하세요.
❌ 실수: 연결 시 'Connection Refused' 에러 발생
왜 발생하는가: targetPort가 실제 컨테이너가 리스닝하는 포트와 다르거나, 애플리케이션이 아직 실행 중이지 않기 때문입니다.
✅ 해결법: 컨테이너 로그를 확인하여 애플리케이션이 정상적으로 시작되었는지 확인하고, targetPort 설정을 다시 검증하세요.
❌ 실수: 배포 후 파드가 무한 재시작됨
왜 발생하는가: Liveness Probe 설정이 너무 엄격하여, 애플리케이션이 준비되기도 전에 실패로 판단하고 재시작을 명령하기 때문입니다.
✅ 해결법: initialDelaySeconds 값을 늘려 애플리케이션이 충분히 준비될 시간을 확보해 주세요.
❌ 실수: 외부에서 접속이 안 되는데 내부에서는 잘 됨
왜 발생하는가: 클라우드 로드밸런서(LB) 설정이나 인그레스(Ingress) 컨트롤러, 혹은 네트워크 보안 그룹(SG) 설정 문제입니다.
✅ 해결법: 클라우드 콘솔에서 로드밸런서의 상태를 확인하고, 서비스 타입이 LoadBalancer인지, 혹은 인그레스 규칙이 올바른지 확인하세요.
❌ 실수: 서비스 업데이트 시 트래픽 끊김 현상 발생
왜 발생하는가: Readiness Probe가 설정되어 있지 않아, 새 파드가 준비되기도 전에 트래픽을 보내기 때문입니다.
✅ 해결법: 반드시 Readiness Probe를 설정하여 파드가 완벽히 준비된 상태에서만 서비스 엔드포인트에 추가되도록 하세요.
자주 묻는 질문
Q. ClusterIP와 LoadBalancer 중 무엇을 써야 할지 모르겠어요.
A. 서비스가 클러스터 내부의 다른 파드와 통신하기 위한 용도라면 무조건 ClusterIP를 사용하세요. 만약 실제 사용자가 인터넷을 통해 접속해야 한다면 LoadBalancer를 사용해야 합니다. 보안과 비용을 생각한다면 내부 통신은 최소한의 노출로 제한하는 것이 원칙입니다.
Q. 서비스 포트 설정 시 port와 targetPort의 차이가 정확히 무엇인가요?
P. port는 서비스라는 '문' 자체의 번호이고, targetPort는 그 문을 통과했을 때 도착할 '방(컨테이너)'의 번호입니다. 사용자는 서비스의 port로 접속하고, 쿠버네티스는 이를 컨테이너의 targetPort로 전달합니다.
Q. 엔드포인트가 왜 자꾸 사라졌다가 나타났다 하나요?
P. 파드의 상태가 불안정하기 때문입니다. 파드가 재시작되거나, Readiness Probe가 실패하면 쿠버네티스는 해당 파드를 서비스 엔드포인트에서 즉시 제거합니다. 파드의 리소스 제한(Limit) 설정이나 프로브 설정을 점검해 보세요.
Q. 서비스 배포 전 확인해야 할 가장 중요한 한 가지를 꼽는다면요?
P. 단연 셀렉터(Selector) 일치 여부입니다. 아무리 다른 설정이 완벽해도 셀렉터가 틀리면 트래픽은 어디로도 흐르지 못합니다.
안정적인 서비스를 위한 최종 요약
쿠버네티스 서비스 운영은 사소한 설정 하나로 성패가 갈리는 정밀한 작업입니다. 오늘 살펴본 내용을 바탕으로, 배포 전후에 반드시 수행해야 할 핵심 체크리스트를 다시 한번 정리해 드립니다.
- 라벨 검증: Service Selector와 Pod Label이 100% 일치하는가?
- 포트 매핑: port, targetPort, container port가 서로 유기적으로 연결되었는가?
- 프로브 설정: Readiness/Liveness Probe가 애플리케이션 특성에 맞게 설정되었는가?
- 엔드포인트 확인:
kubectl get endpoints로 IP 할당을 확인했는가? - 타입 결정: 보안과 비용을 고려해 적절한 Service Type을 선택했는가?
- 네트워크 보안: NetworkPolicy가 불필요한 트래픽을 잘 차단하고 있는가?
이제 이론은 충분합니다. 실제 운영 환경에 적용하기 전, 테스트 클러스터에서 위 항목들을 하나씩 직접 검증해 보시길 권장합니다. 특히 서비스 배포 전 확인 절차를 자동화(CI/CD 파이프라인에 포함)한다면 실수를 원천 차단할 수 있습니다.
오늘 정리한 운영 점검 항목들이 여러분의 장애 없는 클라우드 환경 구축에 도움이 되기를 바랍니다. 실습 환경에서 적용해 보시다가 설정이 꼬이거나 이해가 가지 않는 부분이 있다면 언제든 댓글로 질문을 남겨 주세요. 함께 고민하며 해결해 나가겠습니다.
함께 읽으면 좋은 글:
- 쿠버네티스 서비스 기본 개념과 작동 원리
- 클러스터 구축 및 초기 보안 설정 입문 가이드
