[IT-방법] 인그레스 설정 방법 및 설치 가이드 – 실습 환경 구성부터 검증까지

인그레스가 없던 시절의 혼란과 도입의 필요성

클러스터에 서비스를 하나씩 추가할 때마다 클라우드 콘솔에서 새로운 로드밸런서를 생성하던 기억이 나시나요? 서비스가 10개, 20개로 늘어날수록 매달 청구되는 비용은 눈덩이처럼 불어나고, 각 서비스마다 고유한 외부 IP를 관리하는 일은 그야말로 재앙에 가까워요. 개발자는 코드 작성보다 인프라 비용 계산과 IP 관리 목록을 정리하는 데 더 많은 시간을 쓰게 되곤 합니다.

이런 비효율적인 상황을 해결하기 위해 등장한 것이 바로 인그레스(Ingress)예요. 인그레스는 클러스터 외부에서 내부 서비스로 들어오는 HTTP와 HTTPS 요청을 관리하는 똑똑한 문지기 역할을 수행합니다. 단 하나의 로드밸런서만 사용하여 여러 서비스를 호스트 이름이나 경로에 따라 효율적으로 분배할 수 있게 도와주죠.

단순히 비용을 아끼는 차원을 넘어, 인그레스는 보안 인증서(SSL/TLS)를 한곳에서 통합 관리하거나, 특정 경로로 들어오는 요청을 특정 서비스로 넘겨주는 정교한 라우팅을 가능하게 합니다. 만약 여러분이 지금 서비스 규모가 커지면서 네트워크 설정이 복잡해지고 있다면, 이제는 인그레스 설정 방법을 제대로 익혀야 할 타이밍이에요.

이 글을 끝까지 읽고 나면 다음 내용들을 완벽하게 이해하고 실행할 수 있어요.

• 클러스터 환경에 맞는 인그레스 컨트롤러 선택 기준
• 헬름(Helm)을 이용한 인그레스 컨트롤러 설치 실습
• 경로와 호스트 기반의 세부 인그레스 설정 방법
• 설정 적용 후 실제 동작을 검증하는 프로세스
• 설치 과정에서 마주하는 흔한 오류 해결법

인그레스 설정을 위한 사전 준비와 선택 기준

인그레스를 본격적으로 설치하기 전에 반드시 갖춰야 할 밑바탕이 있어요. 준비 없이 명령어를 입력했다가는 설정이 꼬이거나 클러스터 통신이 끊기는 낭패를 볼 수 있습니다. 우선 쿠버네티스 클러스터가 정상적으로 작동 중인지 확인해야 하며, 클러스터에 명령을 내릴 수 있는 kubectl 도구가 로컬 환경에 세팅되어 있어야 해요.

또한, 인그레스는 그 자체로는 규칙만 담고 있는 설정 파일일 뿐이고, 실제로 그 규칙을 읽어서 트래픽을 전달하는 인그레스 컨트롤러(Ingress Controller)가 반드시 별도로 설치되어 있어야 합니다. 마치 법전(인그레스)이 있어도 이를 집행할 판사(컨트롤러)가 없으면 아무 일도 일어나지 않는 것과 같아요. 따라서 어떤 컨트롤러를 사용할지 결정하는 것이 첫 번째 과제입니다.

컨트롤러 선택을 위한 비교 가이드

시중에는 다양한 컨트롤러가 존재하지만, 실무에서는 주로 다음과 같은 기준에 따라 선택을 진행해요. 여러분의 프로젝트 규모와 요구사항에 맞춰 가장 적합한 도구를 골라보세요.

준비물을 모두 챙겼다면 이제 클러스터에 접속하여 컨트롤러를 설치할 준비가 끝난 거예요. 다음 단계에서는 가장 표준적인 방식인 헬름(Helm)을 활용해 실제 설치 과정을 진행해 볼게요.

인그레스 설치 및 단계별 환경 구성 실습

이제 본격적으로 실무에서 사용하는 인그레스 설치 절차를 밟아볼게요. 우리는 가장 안정적인 Nginx 인그레스 컨트롤러를 기준으로, 패키지 매니저인 헬름(Helm)을 사용하여 설치를 진행할 거예요. 이 과정을 따라오시면 복잡한 설정 파일을 직접 작성하지 않고도 단 몇 분 만에 문지기를 세울 수 있습니다.

STEP 1. 헬름을 이용한 컨트롤러 설치하기

먼저 헬름 저장소를 추가하고 컨트롤러를 설치해야 해요. 터미널에서 다음의 논리적 단계를 따라주세요. 첫째, 엔진엑스 공식 차트 저장소를 헬름에 등록합니다. 둘째, 설치 명령어를 통해 클러스터에 컨트롤러 파드(Pod)를 생성해요. 이때 컨트롤러는 별도의 네임스페이스(Namespace)에 격리하여 설치하는 것이 관리 측면에서 매우 유리합니다.

설치가 완료되면 kubectl get pods -n ingress-nginx 명령어를 통해 컨트롤러가 ‘Running’ 상태인지 꼭 확인하세요. 만약 파드가 생성되지 않는다면 클러스터의 노드 자원이 부족하거나 네트워크 플러그인 설정에 문제가 있을 가능성이 커요.

STEP 2. 테스트용 애플리케이션과 서비스 배포하기

인그레스가 제대로 작동하는지 확인하려면 트래픽을 받아줄 대상이 필요하겠죠? 간단한 웹 서버를 배포해 봅시다. 우선 Deployment를 생성하여 Nginx 웹 서버를 띄우고, 이를 외부로 노출하기 위한 Service를 생성합니다. 여기서 중요한 점은 서비스의 타입(Type)을 ClusterIP로 설정하는 것이에요. 인그레스가 내부에서 트래픽을 전달해 줄 것이기 때문에, 굳이 비싼 비용을 들여 서비스를 LoadBalancer 타입으로 만들 필요가 전혀 없답니다.

서비스가 생성되면 해당 서비스의 이름을 정확히 기억해 두세요. 나중에 인그레스 설정 파일에서 이 이름을 호출해야 하기 때문이에요. 서비스의 포트 번호(예: 80)도 함께 메모해 두는 습관을 들이는 것이 좋습니다.

STEP 3. 인그레스 리소스 작성 및 경로 설정

이제 가장 핵심인 인그레스 초기 구성 단계예요. YAML 파일을 작성하여 어떤 경로로 들어온 요청을 어떤 서비스로 보낼지 정의해야 합니다. 예를 들어, `example.com/app1`으로 들어오면 `app1-service`로, `example.com/app2`로 들어오면 `app2-service`로 보내도록 설정할 수 있어요.

설정 파일 작성 시 주의할 점은 `pathType` 설정이에요. 보통 Prefix 방식을 가장 많이 사용하는데, 이는 지정한 경로로 시작하는 모든 하위 경로를 포함하겠다는 의미입니다. 만약 `ImplementationSpecific`을 사용하면 컨트롤러의 특성에 따라 동작이 달라질 수 있으니 초보자라면 Prefix를 권장해요.

STEP 4. 호스트 기반 라우팅 적용하기

경로 기반 라우팅뿐만 아니라, 도메인 이름(Host)에 따라 다른 서비스를 보여주는 방법도 알아두어야 합니다. `api.example.com`은 API 서버로, `web.example.com`은 프론트엔드 서비스로 연결하는 식이죠. 이렇게 하면 하나의 IP 주소만으로도 마치 여러 개의 독립된 웹사이트를 운영하는 것과 같은 효과를 누릴 수 있습니다.

이 과정을 수행할 때는 로컬 PC의 `hosts` 파일을 수정하여 테스트 도메인이 클러스터의 인그레스 컨트롤러 IP를 바라보도록 설정해야 실제 웹 브라우저에서 접속 테스트가 가능합니다. 이 단계를 건너뛰면 도메인이 어디를 가리키는지 몰라 헤매게 될 거예요.

STEP 5. SSL/TLS 보안 연결 구성하기

마지막으로 실제 서비스라면 반드시 갖춰야 할 HTTPS 설정을 해볼까요? 인그레스의 가장 큰 장점 중 하나는 각 서비스마다 인증서를 설치할 필요 없이, 인그레스 계층에서 통합적으로 SSL을 관리할 수 있다는 점이에요. Secret 오브젝트를 생성하여 SSL 인증서 파일을 저장한 뒤, 인그레스 설정의 `tls` 섹션에 해당 Secret 이름을 적어주기만 하면 됩니다.

이렇게 설정하면 클라이언트와 인그레스 사이의 통신은 암호화되고, 인그레스와 내부 서비스 사이의 통신은 트래픽 부하를 줄이기 위해 일반 HTTP로 처리하는 효율적인 구조를 완성할 수 있습니다.

자주 하는 실수와 해결법 및 자주 묻는 질문

인그레스 설정을 마치고 나면 생각보다 많은 분이 예상치 못한 벽에 부딪히곤 해요. 이론적으로는 완벽해 보이는데 왜 접속이 안 되는 걸까요? 가장 빈번하게 발생하는 문제들을 정리해 보았습니다.

자주 하는 실수와 해결법

❌ 404 Not Found 에러가 발생해요
왜 발생하는가: 인그레스의 경로(Path) 설정과 서비스의 경로가 일치하지 않거나, 인그레스 컨트롤러가 해당 인그레스 리소스를 인식하지 못할 때 발생합니다.
✅ 해결법: 인그레스 설정의 `path` 값과 서비스의 포트가 정확한지 확인하세요. 또한, 인그레스 리소스의 `ingressClassName`이 설치한 컨트롤러의 이름과 일치하는지도 반드시 체크해야 합니다.

❌ 외부 IP(ADDRESS)가 표시되지 않아요
왜 발생하는가: 인그레스 컨트롤러가 로드밸런서를 생성하지 못했거나, 클라우드 환경이 아닌 로컬(Minikube 등) 환경에서 설정을 누락했을 때 나타납니다.
✅ 해결법: Minikube를 사용 중이라면 `minikube tunnel` 명령어를 실행하여 네트워크 통로를 열어주어야 합니다. 클라우드 환경이라면 컨트롤러의 Service 타입이 `LoadBalancer`인지 확인하세요.

❌ SSL 접속 시 인증서 오류가 떠요
왜 발생하는가: Secret 오브젝트에 인증서 파일이 제대로 저장되지 않았거나, 인그레스 설정에서 Secret 이름을 잘못 입력한 경우입니다.
✅ 해결법: `kubectl get secret` 명령어로 인증서가 존재하는지 확인하고, YAML 파일의 `tls.secretName`이 해당 이름과 토씨 하나 틀리지 않고 일치하는지 검토하세요.

❌ 서비스로 트래픽이 전달되지 않아요
왜 발생하는가: 인그레스가 가리키는 서비스 이름이나 네임스페이스가 틀렸을 확률이 매우 높습니다.
✅ 해결법: 인그레스 리소스와 대상 서비스가 반드시 동일한 네임스페이스에 있어야 합니다. 네임스페이스가 다르다면 인그레스는 서비스를 찾을 수 없습니다.

❌ 경로 기반 라우팅이 꼬여요
왜 발생하는가: 경로의 우선순위 문제입니다. 예를 들어 `/` 경로가 `/api` 경로보다 먼저 정의되어 있으면 모든 요청이 `/`로 쏠릴 수 있습니다.
✅ 해결법: 더 구체적인 경로(예: `/api/v1`)를 먼저 정의하거나, 인그레스 컨트롤러의 우선순위 설정 옵션을 확인해야 합니다.

자주 묻는 질문

Q. 인그레스와 로드밸런서 서비스의 차이점은 무엇인가요?

로드밸런서 서비스는 클라우드 공급자가 제공하는 물리적인/가상 로드밸런서를 직접 사용하는 방식이라 서비스마다 비용이 발생합니다. 반면 인그레스는 하나의 로드밸런서 위에 소프트웨어적으로 여러 서비스를 올리는 방식이라 비용 효율성이 훨씬 높습니다.

Q. 하나의 클러스터에 여러 개의 인그레스 컨트롤러를 설치할 수 있나요?
네, 가능합니다. 예를 들어, 외부 트래픽용 Nginx 컨트롤러와 내부 관리용 Traefik 컨트롤러를 각각 다른 네임스페이스에 설치하여 분리 운영할 수 있습니다.

Q. 인그레스 설정 변경 시 서비스가 중단되나요?
아니요, 인그레스 리소스를 수정하고 적용(apply)하면 컨트롤러가 변경 사항을 감지하여 실시간으로 반영합니다. 아주 짧은 순간의 설정 적용 시간 외에는 서비스 중단 없이 운영이 가능해요.

Q. 인증서 관리는 어떻게 하는 게 가장 편할까요?
실무에서는 Cert-Manager이라는 도구를 인그레스와 함께 사용합니다. Let’s Encrypt 같은 무료 인증서를 자동으로 발급하고 갱신까지 해 주기 때문에 운영 부담이 획기적으로 줄어듭니다.