[IT-방법] 인그레스 YAML 설정 파일 작성법 총정리 – 필수 필드 해설과 실무 예제 포함

인그레스 설정 실패로 겪는 당혹스러운 순간들

새로운 서비스를 배포하고 설레는 마음으로 브라우저에 주소를 입력했는데, 화면에 뜬 것은 404 Not Found나 503 Service Unavailable 메시지뿐이었던 적이 있나요? 분명히 서비스(Service)와 파드(Pod)는 정상적으로 떠 있는데, 외부에서 접속하려고만 하면 벽에 막힌 기분이 들곤 해요. 온프레미스 환경을 운영하다 보면 네트워크 설정 하나하나가 생존과 직결되기에 이런 상황은 더욱 당혹스럽게 느껴져요.

대부분의 문제는 인그레스 컨트롤러가 설치되어 있음에도 불구하고, 정작 우리가 작성한 인그레스 YAML 설정 파일의 문법이 미세하게 어긋나거나 라우팅 규칙이 실제 트래픽 흐름과 맞지 않을 때 발생해요. YAML은 아주 작은 들여쓰기 하나만 틀려도 전체 설정이 무너지는 예민한 도구라 운영자에게는 늘 긴장을 늦출 수 없는 대상이에요.

단순히 문법을 맞추는 것을 넘어, 트래픽이 어떤 경로를 거쳐 백엔드 서비스로 전달되는지 그 흐름을 명확히 이해해야 해요. 이 글을 끝까지 읽고 나면, 복잡해 보이던 인그레스 매니페스트를 한 줄씩 뜯어보며 완벽하게 제어할 수 있는 자신감을 얻게 될 거예요. 실무에서 바로 활용할 수 있는 설정 예제와 검증 방법까지 모두 담았어요.

이 글에서 함께 살펴볼 내용은 다음과 같아요.

• 인그레스 매니페스트의 필수 구조와 필드별 상세 의미
• 바로 복사해서 사용할 수 있는 최소 기능 YAML 예제
• SSL/TLS 인증서 적용 및 어노테이션(Annotation) 활용법
• 실무에서 자주 발생하는 실수와 해결을 위한 검증 절차

인그레스 작성을 위한 사전 지식과 준비물

인그레스 설정을 시작하기 전에 반드시 짚고 넘어가야 할 개념이 있어요. 많은 분이 인그레스와 로드밸런서(LoadBalancer)를 혼동하곤 하는데, 이 둘은 계층과 역할이 완전히 달라요. 인그레스는 L7(애플리케이션 계층)에서 동작하며, HTTP/HTTPS 경로와 호스트 이름을 기준으로 트래픽을 분기해 주는 스마트한 규칙 집합이라고 생각하면 쉬워요.

성공적인 설정을 위해서는 클러스터 내에 트래픽을 실제로 처리할 인그레스 컨트롤러가 미리 구동 중이어야 해요. 규칙(Ingress Resource)만 만든다고 해서 갑자기 트래픽이 흐르는 것이 아니라, 그 규칙을 해석해서 실제 네트워크 경로를 열어줄 엔진이 필요하기 때문이에요. 온프레미스 환경이라면 NGINX나 HAProxy 기반의 컨트롤러를 직접 설치해 두었는지 꼭 확인하세요.

또한, 인그레스가 트래픽을 전달할 대상인 서비스(Service)와 그 서비스가 연결된 파드(Pod)가 준비되어 있어야 해요. 서비스의 포트 번호가 인그레스 설정과 일치하지 않으면 아무리 완벽한 YAML을 써도 연결이 되지 않아요.

서비스 노출 방식 비교

인그레스를 도입할지, 아니면 다른 방식을 쓸지 고민 중이라면 아래 표를 참고해 보세요. 운영 환경의 규모와 요구 사항에 따라 선택 기준이 달라져요.

온프레미스 운영자라면 비용과 자원 효율성을 고려했을 때 인그레스 방식이 가장 합리적이에요. 여러 개의 서비스에 대해 각각 로드밸런서를 할당하는 대신, 하나의 엔드포인트만 관리하면서 내부 규칙으로 트래픽을 쪼갤 수 있기 때문이에요.

인그레스 YAML 작성 단계별 가이드

이제 본격적으로 인그레스 설정 파일 작성을 시작해 볼게요. 이론적인 설명보다는 실제 코드를 보면서 구조를 파악하는 것이 훨씬 빨라요. 단계별로 차근차근 따라와 주세요.

STEP 1. 인그레스 매니페스트의 기본 뼈대 이해하기

모든 쿠버네티스 리소스와 마찬가지로 인그레스도 표준적인 구조를 가져요. 가장 먼저 정의해야 할 것은 이 리소스가 무엇인지 알려주는 API 버전과 종류예요. 현재 표준은 networking.k8s.io/v1을 사용하는 것이에요.

기본적인 구조는 다음과 같아요.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  namespace: default
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

여기서 metadata는 인그레스를 식별하는 이름과 네임스페이스를 정해요. spec 섹션이 가장 핵심인데, 여기에 어떤 호스트로 들어온 트래픽을 어떤 서비스로 보낼지에 대한 모든 규칙이 담겨요. spec.rules는 배열 형태라 여러 개의 규칙을 동시에 정의할 수 있어요.

STEP 2. 경로(Path)와 경로 타입(PathType) 설정하기

트래픽을 분기할 때 가장 중요한 것이 경로 설정이에요. 단순히 모든 트래픽을 보내는 것이 아니라, /api로 들어오면 API 서버로, /static으로 들어오면 이미지 서버로 보내는 식의 처리가 가능해요. 이때 반드시 pathType을 명시해야 해요.

• Prefix: 지정된 경로로 시작하는 모든 요청을 포함해요. (예: /api/v1, /api/v2 모두 매칭)
• Exact: 지정된 경로와 정확히 일치하는 요청만 처리해요.
• ImplementationSpecific: 컨트롤러에 따라 동작이 달라질 수 있어요.

실무에서는 대부분 Prefix를 사용해요. 하위 경로까지 모두 포함해야 하는 경우가 많기 때문이에요. 만약 Exact를 잘못 쓰면, 사용자가 경로 끝에 슬래시(/) 하나만 더 붙여도 접속이 안 되는 불상사가 생길 수 있으니 주의하세요.

STEP 3. 보안을 위한 TLS/SSL 인증서 적용하기

요즘 웹 서비스에서 HTTPS는 선택이 아닌 필수예요. 인그레스 매니페스트에 tls 섹션을 추가하면 아주 간단하게 SSL 인증서를 적용할 수 있어요. 단, 이 방법을 쓰려면 먼저 쿠버네티스 내부에 인증서 정보가 담긴 Secret이 생성되어 있어야 해요.

spec:
  tls:
  - hosts:
    - example.com
    secretName: my-tls-secret
  rules:
  - host: example.com
    http: ...

이렇게 설정하면 인그레스 컨트롤러가 my-tls-secret에 저장된 인증서를 가져와서 외부와의 통신을 암호화해요. 인증서 만료일이 다가오면 Secret만 업데이트해 주면 되니 관리가 매우 편리해요.

STEP 4. 어노테이션(Annotation)을 활용한 고급 기능 제어하기

인그레스의 진정한 강력함은 metadata.annotations에서 나와요. 인그레스 컨트롤러(특히 NGINX)는 수많은 특수 기능을 어노테이션을 통해 제공해요. 예를 들어, 특정 경로로 들어오는 요청을 다른 경로로 바꿔주는 Rewrite 기능이나, 요청의 최대 크기를 제한하는 기능 등이 있어요.

가장 자주 쓰이는 예시는 다음과 같아요.

• nginx.ingress.kubernetes.io/rewrite-target: /: 요청 경로를 재작성할 때 사용해요.
• nginx.ingress.kubernetes.io/proxy-body-size: 50m: 파일 업로드 용량 제한을 늘릴 때 유용해요.
• nginx.ingress.kubernetes.io/ssl-redirect:
  

  자주 하는 실수와 해결법

  인그레스를 운영하다 보면 분명히 설정은 맞는데 동작하지 않는 경우가 생겨요. 그럴 때 당황하지 말고 아래의 체크리스트를 확인해 보세요.

  ❌ 실수: 서비스의 포트 번호를 잘못 기입함
  왜 발생하는가: 서비스(Service) 객체에 정의된 port와 인그레스의 service.port.number를 혼동하는 경우가 많아요.
  ✅ 해결법: 서비스 YAML을 열어 spec.ports[].port 값을 정확히 확인하고 인그레스에 그대로 옮겨 적으세요.

  ❌ 실수: PathType을 지정하지 않거나 잘못 지정함
  왜 발생하는가: 구버전 쿠버네티스 문법을 사용하거나, Prefix와 Exact의 차이를 간과하기 때문이에요.
  ✅ 해결법: 경로의 유연성이 필요하다면 반드시 Prefix를 사용하세요.

  ❌ 실수: 인그레스 컨트롤러가 설치되어 있지 않음
  왜 발생하는가: 인그레스 리소스는 규칙일 뿐, 트래픽을 전달할 엔진이 없으면 아무 일도 일어나지 않아요.
  ✅ 해결법: kubectl get pods -A 명령어로 인그레스 컨트롤러 파드가 실행 중인지 먼저 확인하세요.

  ❌ 실수: TLS Secret의 이름이나 네임스페이스가 불일치함
  왜 발생하는가: 인증서가 담긴 Secret은 인그레스와 반드시 같은 네임스페이스에 있어야 해요.
  ✅ 해결법: Secret 생성 시 지정한 네임스페이스와 인그레스의 네임스페이스가 같은지 꼭 확인하세요.

  ❌ 실수: 어노테이션 오타 발생
  왜 발생하는가: 어노테이션은 키 값에 오타가 나면 에러를 내는 대신 그냥 무시되기 때문에 원인을 찾기 어려워요.
  ✅ 해결법: 공식 문서나 컨트롤러 가이드를 복사해서 사용하고, 적용 후 컨트롤러 로그를 확인하세요.

  자주 묻는 질문

  Q. 인그레스 하나에 여러 개의 서비스를 연결할 수 있나요?

  네, 당연히 가능해요. 하나의 인그레스 리소스 안에 여러 개의 rules를 넣거나, 하나의 호스트 아래에 여러 개의 paths를 정의하여 서비스들을 분기할 수 있어요.

  Q. 404 에러가 뜨는데 어디를 가장 먼저 봐야 할까요?
  먼저 pathType이 의도한 대로 설정되었는지, 그리고 인그레스가 바라보는 service.name과 port가 실제 서비스와 정확히 일치하는지 확인하는 것이 순서예요.

  Q. 도메인이 여러 개인데 IP를 여러 개 써야 하나요?
  아니요, 인그레스 컨트롤러가 사용하는 단일 IP(또는 로드밸런서 주소)만 있으면 돼요. 인그레스가 HTTP 헤더의 Host 값을 보고 어떤 규칙을 적용할지 스스로 판단하기 때문이에요.

  Q. SSL 인증서를 적용하면 성능이 떨어지나요?
  암호화/복호화 과정에서 약간의 CPU 부하가 발생할 수 있지만, 최신 서버와 컨트롤러 환경에서는 체감하기 어려운 수준이에요. 보안을 위해 적용하는 것을 강력히 권장해요.

  Q. 인그레스 컨트롤러를 교체할 수 있나요?
  네, 가능해요. 하지만 컨트롤러를 바꾸면 기존에 사용하던 어노테이션(Annotation)들이 작동하지 않을 수 있으니, 반드시 새로운 컨트롤러에 맞는 문법으로 YAML을 수정해야 해요.

  핵심 요약과 다음 단계

  오늘 살펴본 내용을 바탕으로 인그레스 설정을 완벽하게 마스터해 보세요. 인그레스는 한 번 제대로 구조를 잡아두면 클러스터 운영의 효율성을 극대화해 주는 아주 고마운 존재예요.

  ✅ 핵심 요약

  • 인그레스는 L7 라우팅을 담당하며 반드시 컨트롤러가 필요해요.
  • API 버전은 networking.k8s.io/v1을 사용하세요.
  • 경로 설정 시 pathType을 Prefix로 설정하는 것이 실무에서 유리해요.
  • 보안을 위해 tls 섹션과 Secret을 활용해 HTTPS를 적용하세요.
  • 고급 제어가 필요할 때는 annotations를 적극 활용하세요.
  • 설정 후에는 반드시 서비스 포트와 네임스페이스 일치 여부를 검증하세요.

  자, 이제 이론은 충분해요. 직접 실행해 볼 차례예요!

  • 오늘 할 일: 현재 운영 중인 서비스의 인그레스 YAML을 추출해서(kubectl get ingress -o yaml) 구조를 분석해 보세요.
  • 이번 주 할 일: 테스트 환경에서 TLS 인증서를 적용한 멀티 도메인 인그레스 매니페스트를 직접 배포해 보세요.
  • 실행 직전 할 일: 작성한 YAML 파일에 오타가 없는지, 서비스 포트가 맞는지 마지막으로 한 번 더 대조해 보세요.

  실습 환경에서 직접 적용해 보시고, 설정 과정에서 막히거나 예상치 못한 에러가 발생하면 언제든 댓글로 질문을 남겨 주세요. 함께 해결 방법을 찾아봐요!

  관련해서 더 깊이 있는 공부를 원하신다면 쿠버네티스 인그레스 기본 개념 글이나 클러스터 구축 입문 글을 함께 읽어보시는 것을 추천드려요.