[IT-방법] 인그레스 실전 예제 따라하기: 배포부터 검증까지 – 데브옵스 엔지니어를 위한 단계별 가이드

왜 지금 인그레스(Ingress)를 실습해야 할까요

클러스터를 운영하다 보면 예상치 못한 비용 문제에 직면하곤 해요. 서비스가 하나 늘어날 때마다 LoadBalancer 타입의 서비스를 생성하면 클라우드 환경에서는 그만큼의 비용이 계속해서 청구돼요. 서비스가 열 개, 스무 개로 늘어난다면 매달 날아오는 청구서를 보고 당황할 수밖에 없어요.

또한, 각 서비스마다 고유한 외부 IP를 할당받는 방식은 관리가 매우 까다로워요. 도메인 하나로 여러 서비스를 구분해서 호출하고 싶을 때, 혹은 SSL 인증서를 서비스마다 일일이 적용하기 버거울 때 우리는 결국 인그레스(Ingress)라는 해결책을 찾아야 해요.

단순히 이론만 아는 것과 실제 YAML 파일을 작성해서 트래픽이 흐르는 것을 확인하는 것은 천지 차이예요. 이번 인그레스 실전 예제를 통해 여러분은 서비스 노출의 효율성을 극대화하는 방법을 직접 체득하게 될 거예요.

이 글을 끝까지 따라오시면 다음과 같은 능력을 갖추게 돼요.

• 단일 엔드포인트로 여러 서비스를 라우팅하는 매니페스트 작성법
• 도메인 기반(Host-based) 및 경로 기반(Path-based) 라우팅 구현
• 인그레스 컨트롤러의 동작 원리 이해와 트래픽 흐름 검증
• 실제 장애 상황에서 로그를 통해 문제를 해결하는 디버깅 기술

실습 시작 전 꼭 확인해야 할 준비물

본격적인 인그레스 실습에 들어가기 전에 환경이 제대로 갖춰져 있는지 확인하는 과정이 필요해요. 아무런 준비 없이 명령어부터 입력하다가는 컨트롤러가 동작하지 않아 헛수고를 할 가능성이 높기 때문이에요.

가장 먼저 준비해야 할 것은 쿠버네티스 클러스터예요. 로컬 환경이라면 Minikube나 Kind를 사용하는 것을 추천해요. 클라우드 환경을 사용 중이라면 이미 생성된 클러스터에 접속할 수 있는 kubectl 설정이 완료되어 있어야 해요.

또한, 인그레스는 선언적인 규칙일 뿐이며, 이를 실제로 처리할 인그레스 컨트롤러(Ingress Controller)가 반드시 설치되어 있어야 해요. 가장 대중적으로 사용되는 것은 Nginx Ingress Controller예요. 컨트롤러가 없다면 인그레스 리소스를 아무리 잘 만들어도 외부 트래픽은 갈 곳을 잃게 돼요.

서비스 노출 방식을 선택할 때 어떤 기준을 가져야 할지 고민된다면 아래 비교 표를 참고해 보세요.

준비가 끝났다면 이제 실제 코드를 작성하고 배포할 준비가 된 거예요. 다음 단계에서 본격적인 실습을 시작할게요.

인그레스 실전 예제: 단계별 배포와 검증

이번 실습에서는 두 개의 서로 다른 웹 애플리케이션(app-a, app-b)을 하나의 도메인 아래에 배치하는 시나리오를 다뤄볼 거예요. 인그레스 예제를 통해 경로에 따라 트래픽이 어떻게 나뉘는지 눈으로 직접 확인할 수 있어요.

STEP 1. 테스트용 애플리케이션과 서비스 준비하기

먼저 인그레스가 바라볼 대상인 애플리케이션을 만들어야 해요. 복잡한 앱 대신, 응답 메시지만 다르게 출력하는 아주 가벼운 Nginx 컨테이너를 사용할게요. 이 과정은 네임스페이스를 생성하고, 디플로이먼트(Deployment)와 서비스(Service)를 만드는 과정으로 이루어져요.

아래 명령어를 통해 `demo-ns`라는 네임스페이스를 먼저 생성해 주세요.

kubectl create namespace demo-ns

그다음, `app-a` 서비스를 위한 매니페스트를 작성해요. 이 서비스는 `/app-a` 경로로 들어오는 요청을 처리할 거예요. 서비스의 타입은 인그레스가 내부에서 접근할 수 있도록 ClusterIP로 설정하는 것이 정석이에요.

이제 `app-b` 서비스도 동일한 방식으로 생성해 주세요. 두 서비스는 서로 다른 포트나 레이블을 사용하여 구분될 거예요. 서비스가 정상적으로 생성되었다면 kubectl get svc -n demo-ns 명령어로 IP가 할당되었는지 확인해 보세요.

STEP 2. 인그레스 규칙(Ingress Rule) 매니페스트 작성하기

이제 이번 실습의 핵심인 인그레스 리소스를 작성할 차례예요. 우리는 하나의 호스트(예: myapp.example.com)를 사용하면서, 경로(Path)에 따라 다른 서비스로 연결하는 인그레스 따라하기를 진행할 거예요.

아래는 작성해야 할 YAML 파일의 구조예요. 파일명을 ingress-rule.yaml로 저장해 주세요.


apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: demo-ingress
namespace: demo-ns
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
spec:
rules:
- host: myapp.example.com
http:
paths:
- path: /app-a
pathType: Prefix
backend:
service:
name: app-a-service
port:
number: 80
- path: /app-b
pathType: Prefix
backend:
service:
name: app-b-service
port:
number: 80


여기서 annotations 부분을 주의 깊게 봐주세요. rewrite-target: / 설정은 인그레스가 요청을 받을 때 경로를 재작성해 주는 아주 유용한 기능이에요. 예를 들어 사용자가 myapp.example.com/app-a로 접속하면, 실제 서비스에는 / 경로로 요청을 전달하여 앱이 경로 문제로 에러를 내지 않도록 도와줘요.

STEP 3. 리소스 배포 및 상태 확인

작성한 매니페스트를 클러스터에 적용할 시간이에요. 다음 명령어를 입력해 주세요.

kubectl apply -f ingress-rule.yaml

배포 후에는 인그레스가 제대로 생성되었는지, 그리고 외부에서 접속할 수 있는 Address가 할당되었는지 반드시 확인해야 해요. kubectl get ingress -n demo-ns를 입력했을 때 ADDRESS 열에 IP 주소나 도메인이 나타나야 성공이에요.

STEP 4. 경로 기반 라우팅 동작 검증하기

이제 모든 설정이 끝났으니 실제로 트래픽이 잘 흐르는지 테스트할 차례예요. 로컬 환경에서 테스트할 때는 /etc/hosts 파일을 수정하여 myapp.example.com이 방금 확인한 인그레스의 IP를 가리키도록 설정해야 해요.

설정이 완료되었다면 curl 명령어를 사용하여 다음 두 가지를 확인해 보세요.

1. curl http://myapp.example.com/app-a -> ‘Welcome to App A’ 응답 확인
2. curl http://myapp.example.com/app-b -> ‘Welcome to App B’ 응답 확인

만약 응답이 예상과 다르다면, pathType 설정이 Prefix인지 Exact인지 다시 한번 확인해 보세요. Prefix는 해당 경로로 시작하는 모든 요청을 포함하기 때문에 실무에서 가장 흔하게 쓰여요.

STEP 5. 보안 강화를 위한 TLS/SSL 설정 (심화)

실무 환경에서는 반드시 HTTPS를 사용해야 해요. 인그레스는 TLS 인증서를 아주 간편하게 관리할 수 있는 기능을 제공해요. 먼저 인증서가 담긴 Secret을 생성해야 해요.

kubectl create secret tls demo-tls-secret --cert=path/to/tls.crt --key=path/to/tls.key -n demo-ns

그다음 기존 인그레스 매니페스트의 spec 아래에 tls 섹션을 추가해 주세요.


spec:
tls:
- hosts:
- myapp.example.com
secretName: demo-tls-secret
rules:
... (기존 규칙) ...


이렇게 설정하면 인그레스 컨트롤러가 자동으로 443 포트를 열고, 요청이 들어오면 인증서를 사용해 암호화 통신을 수행하게 돼요. 이것이 바로 쿠버네티스 실습 예제를 통해 배우는 운영 환경의 핵심이에요.

자주 하는 실수와 해결법 + FAQ

자주 하는 실수와 해결법

실습 중에 가장 많이 겪게 되는 문제들을 정리했어요. 해결되지 않는다면 이 리스트를 먼저 살펴보세요.

❌ 404 Not Found 에러가 발생해요
왜 발생하는가: 인그레스의 path 설정과 실제 서비스의 경로가 일치하지 않거나, 인그레스 컨트롤러가 해당 규칙을 인식하지 못했을 때 발생해요.
✅ 해결법: pathType을 Prefix로 설정했는지 확인하고, annotations의 rewrite-target 설정을 다시 점검해 보세요.

❌ 503 Service Unavailable 에러가 떠요
왜 발생하는가: 인그레스는 정상 작동하지만, 뒤에 연결된 백엔드 서비스(Pod)가 죽어있거나 서비스(Service)의 포트 번호가 잘못 지정되었을 때 발생해요.
✅ 해결법: kubectl get pods -n demo-ns로 애플리케이션이 정상 실행 중인지 확인하고, 서비스의 targetPort와 port가 일치하는지 검토하세요.

❌ 인그레스의 ADDRESS가 계속 <pending> 상태예요
왜 발생하는가: 클러스터에 인그레스 컨트롤러(Nginx 등)가 설치되어 있지 않기 때문이에요.
✅ 해결법: 사용 중인 환경(Minikube, EKS, GKE 등)에 맞는 인그레스 컨트롤러 설치 가이드를 따라 컨트롤러를 먼저 배포하세요.

❌ 도메인 접속 시 SSL 인증서 경고가 나와요
왜 발생하는가: TLS Secret이 올바르지 않거나, 인증서의 도메인 이름이 인그레스의 host 설정과 일치하지 않기 때문이에요.
✅ 해결법: kubectl get secret -n demo-ns로 인증서가 잘 있는지 확인하고, 인증서 생성 시 입력한 도메인과 매니페스트의 도메인을 대조하세요.

❌ 특정 경로로 접속하면 페이지가 깨져요
왜 발생하는가: 정적 파일(이미지, CSS)을 불러오는 경로가 인그레스의 라우팅 규칙에 의해 잘못 전달되고 있을 가능성이 커요.
✅ 해결법: rewrite-target 어노테이션을 사용하여 경로 재작성이 올바르게 동작하는지 확인하세요.

자주 묻는 질문

Q. 인그레스 컨트롤러는 꼭 하나만 있어야 하나요?

기술적으로는 여러 개를 설치할 수 있지만, 관리 복잡성과 비용 문제로 인해 보통 하나의 컨트롤러를 설치하고 그 안에서 규칙(Rule)으로 서비스를 구분하는 방식을 사용해요.

Q. LoadBalancer 타입과 인그레스의 차이점은 무엇인가요?
LoadBalancer는 클러스터 외부에서 특정 서비스로 직접 연결하는 통로이고, 인그레스는 그 통로 하나를 통해 들어온 트래픽을 URL 경로에 따라 여러 서비스로 나누어주는 지능적인 관리자예요.

Q. 호스트 기반 라우팅(Host-based)은 어떻게 동작하나요?
app1.example.com과 app2.example.com처럼 도메인 자체를 다르게 설정하여, 동일한 IP를 사용하더라도 접속하는 주소에 따라 다른 서비스로 연결해 주는 방식이에요.

Q. 인그레스 규칙에 우선순위가 있나요?
네, 보통 더 구체적인 경로(예: /app/login)가 더 일반적인 경로(예: /app)보다 먼저 매칭되도록 설정해야 해요. 경로의 길이를 기준으로 판단하는 것이 일반적이에요.

Q. 인그레스 설정 변경 후 적용까지 시간이 걸리나요?
인그레스 컨트롤러가 설정 변경을 감지하는 데 약간의 시간이 걸릴 수 있어요. 보통 수 초 이내에 반영되지만, 대규모 클러스터에서는 약간의 지연이 있을 수 있습니다.

성공적인 인그레스 운영을 위한 마무리

지금까지 인그레스 실전 예제를 통해 실제 클러스터 환경에서 트래픽을 관리하는 전 과정을 살펴보았어요. 처음에는 YAML 파일의 복잡한 구조가 낯설 수 있지만, 한 번 익숙해지면 수십 개의 서비스를 아주 효율적으로 관리할 수 있는 강력한 무기가 될 거예요.

오늘 배운 내용을 토대로 다음 단계로 나아가 보세요.

• 오늘 할 일: 배운 매니페스트를 복사하여 로컬 Minikube 환경에 직접 배포해 보기
• 이번 주 할 일: Cert-manager를 연동하여 실제 Let’s Encrypt 인증서를 자동으로 발급받는 환경 구축하기
• 실행 직전 할 일: Helm 차트를 이용해 인그레스 컨트롤러를 명령 한 줄로 설치하는 방법 익히기

실습을 진행하다가 잘 풀리지 않거나 궁금한 점이 생기면 언제든 댓글로 질문을 남겨 주세요. 여러분의 시행착오를 함께 고민해 드릴게요!

함께 읽으면 좋은 글: 쿠버네티스 인그레스 기본 개념 글, 클러스터 구축 입문 글