TIL

Ingress

• 공식 문서 - Ingress
• 클러스터 외부의 HTTP/HTTPS 트래픽을 클러스터 내부 Service로 라우팅하는 L7 진입점
• 호스트 이름·URL 경로 기반 분기, TLS 종료, 단일 외부 IP 공유 같은 L7 기능을 선언적으로 정의
• Service만으로는 부족한 부분 — Service는 L4(TCP/UDP)까지만 다루고 호스트·경로 라우팅이나 TLS는 다루지 않음

Ingress가 필요한 이유

• 외부 노출 수단 비교
  • NodePort — Node IP·포트를 외부에 직접 노출. 운영에 부적합
  • LoadBalancer Service — 클라우드 L4 LB 자동 생성. Service 1개당 LB 1개가 필요해 비용·관리 부담
  • Ingress — 단일 외부 LB·진입점 위에서 호스트·경로 단위로 여러 Service를 다중화
• L7 기능을 한곳에서 처리
  • Host 기반 라우팅 — api.example.com은 backend Service, app.example.com은 frontend Service
  • Path 기반 라우팅 — /api는 API Service, /는 web Service
  • TLS 종료 — 인증서를 Ingress에서 한 번만 관리, 내부는 평문
  • 단일 IP·도메인 공유 — 여러 마이크로서비스를 하나의 진입점 뒤에 둠
• 결과적으로 외부에서 도메인을 붙이는 진입점은 보통 Ingress이고, 뒤쪽은 ClusterIP Service들이 받는 구조

Ingress Controller

• Ingress 리소스 자체는 정의일 뿐 — 실제 트래픽을 처리하는 컨트롤러가 별도로 떠 있어야 한다
• Ingress 리소스를 만들어도 컨트롤러가 없으면 아무 일도 일어나지 않음 (Service는 그렇지 않다는 점에서 다름)
• 컨트롤러가 하는 일
  • Ingress 리소스를 watch
  • 자기가 담당하는 IngressClass의 리소스를 골라 L7 프록시·LB의 설정으로 변환
  • 외부에서 들어온 HTTP 요청을 rule에 따라 적절한 Service로 전달
• 대표적인 컨트롤러
  • NGINX Ingress Controller — 가장 널리 쓰임, 클러스터 내부에 nginx 파드를 띄워 처리
  • GCE / GKE Ingress Controller — GKE 기본 제공, GCP HTTP(S) Load Balancer를 자동 프로비저닝
  • AWS Load Balancer Controller — AWS ALB로 매핑
  • Traefik / HAProxy / Contour / Istio Gateway 등
• 한 클러스터에 여러 컨트롤러를 동시에 띄울 수 있음 — 각 Ingress가 어느 컨트롤러를 쓸지 IngressClass로 지정

Ingress 리소스 정의

• 기본 구조 — ingressClassName, rules, (선택) defaultBackend, (선택) tls

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    name: minimal-ingress
    annotations:
      nginx.ingress.kubernetes.io/rewrite-target: /   # 컨트롤러별 동작 옵션
  spec:
    ingressClassName: nginx-example                   # 어느 컨트롤러가 처리할지
    rules:
      - host: foo.example.com
        http:
          paths:
            - path: /testpath
              pathType: Prefix
              backend:
                service:
                  name: test-service                  # 내부 ClusterIP Service
                  port:
                    number: 80
  

• 핵심 필드
  • spec.ingressClassName — 이 Ingress를 처리할 컨트롤러 선택 (기본 클래스가 있으면 생략 가능)
  • spec.rules — host·path 단위 라우팅 규칙 목록
  • spec.defaultBackend — 어떤 rule에도 매칭되지 않는 요청을 보낼 폴백 백엔드 (선택)
  • spec.tls — TLS 종료 설정 (선택, 별도 세션에서 정리)
• 필수 헤더 — apiVersion: networking.k8s.io/v1, kind: Ingress
• 어노테이션의 역할 — 표준 스펙으로 표현되지 않는 컨트롤러별 옵션은 metadata.annotations로 전달
  • ex) nginx.ingress.kubernetes.io/..., kubernetes.io/ingress.class (구버전)
  • 같은 어노테이션이라도 컨트롤러마다 해석이 다름 — 이식성이 떨어진다는 점에 주의

Rules 구조

• rules는 호스트별로 묶인 라우팅 규칙들의 목록
• 한 rule은 다음 세 요소로 구성
  • host — 매칭할 호스트 이름 (선택, 생략 시 모든 호스트 매칭)
  • http.paths — 그 호스트로 들어온 요청을 path 단위로 분기
  • 각 path — path + pathType + backend
• 예 — 같은 호스트에서 경로별로 다른 Service로 분배 ```yaml rules:
  • host: app.example.com http: paths: - path: /api pathType: Prefix backend: service: name: api-service port: number: 8080 - path: / pathType: Prefix backend: service: name: web-service port: number: 80 ```
• host를 생략하면 IP·임의 호스트로 들어오는 모든 요청에 적용
• 매칭 우선순위는 더 구체적인 path가 먼저 — /api/v2가 /api보다 먼저 평가됨

backend — 라우팅 대상

• 매칭된 요청을 어디로 보낼지 정의
• 두 가지 형태
  • service (대부분의 경우) — 클러스터 내부 Service로 전달

    backend:
      service:
        name: my-service
        port:
          number: 80         # 또는 name: http
    

  • resource — Service가 아닌 다른 리소스(예: 정적 파일을 담은 StorageBucket CR)로 전달, 컨트롤러가 지원해야 함
• service.port는 숫자 또는 Service에 정의된 포트 이름(name)으로 지정 가능

defaultBackend

• 어떤 rule의 host·path에도 매칭되지 않는 요청을 받는 폴백
• spec.defaultBackend로 Ingress 단위 설정 가능

  spec:
    defaultBackend:
      service:
        name: fallback-service
        port:
          number: 80
  

• Ingress 리소스에 정의하지 않으면 컨트롤러의 기본 동작(주로 404 반환)을 따름
• 사용처 — 404 페이지·유지보수 페이지를 별도 Service로 분리, 와일드카드성 처리

Path Types

• 각 path마다 pathType이 필수 — 같은 path 문자열이라도 매칭 방식이 달라짐
• 세 가지 값 — Exact / Prefix / ImplementationSpecific

Exact

• URL 경로가 정확히 일치할 때만 매칭, 대소문자 구분
• ex) path: /foo
  • /foo → 매칭
  • /foo/, /foo/bar → 매칭 안 됨
• 정적 엔드포인트 1개를 정확히 라우팅하고 싶을 때

Prefix

• URL 경로를 /로 분리한 element 단위로 prefix 비교
• ex) path: /foo
  • /foo, /foo/, /foo/bar → 매칭
  • /foobar → 매칭 안 됨 (element 경계가 다름)
• 일반적인 경로 기반 라우팅에 가장 흔히 쓰임 — /api, /admin 같은 prefix 매칭
• trailing slash는 무시 — /foo/로 적든 /foo로 적든 동일하게 동작

ImplementationSpecific

• 매칭 동작을 컨트롤러가 결정 — 정규식·glob 등 컨트롤러별 확장 문법을 허용
• nginx 컨트롤러는 정규식, GCE 컨트롤러는 자체 규칙처럼 구현체에 따라 다름
• 이식성이 떨어지므로 가능하면 Exact / Prefix를 쓰고, 정규식이 꼭 필요할 때만 사용

Path 매칭 우선순위

• 같은 host에서 여러 path가 매칭 가능하면 더 긴(구체적인) path가 우선
  • ex) /api/v2(Prefix) 와 /api(Prefix)가 둘 다 있으면 /api/v2 요청은 전자에 매칭
• Exact와 Prefix가 같은 path 문자열을 갖는 경우 — 보통 Exact가 우선
• 결국 컨트롤러 구현에 따라 미세하게 다를 수 있다 — 운영 전에 컨트롤러별 매칭 규칙을 한 번 확인하는 게 안전

매칭 예시

Path 정의	요청 경로	Exact	Prefix
/foo	/foo	⭕	⭕
/foo	/foo/	❌	⭕
/foo	/foo/bar	❌	⭕
/foo	/foobar	❌	❌
/foo/	/foo	❌	⭕

Hostname Wildcards

• host 값에 와일드카드(*)를 한 단계만 사용 가능
• 규칙
  • *은 가장 왼쪽 라벨에서 정확히 한 번만 — *.example.com ⭕
  • *이 중간이나 오른쪽에 오면 무효 — foo.*.com ❌
  • 한 라벨만 매칭 — *.example.com은 bar.example.com은 매칭하지만 bar.baz.example.com은 매칭 안 함
• 정의 예 ```yaml rules:
  • host: “*.example.com” # 한 단계 서브도메인 매칭 http: paths: - path: / pathType: Prefix backend: service: name: wildcard-service port: number: 80 ```
• 정확한 host 룰과 와일드카드 룰이 둘 다 있으면 정확한 host가 우선 — bar.example.com에 매칭되는 룰이 따로 있다면 그쪽으로 라우팅
• TLS 인증서도 같은 규칙으로 동작 — wildcard 인증서로 *.example.com을 한 번에 처리 가능

Resource Backend

• backend.resource로 Service가 아닌 임의 리소스를 백엔드로 지정 가능
• 동작은 컨트롤러가 해석 — 표준 스펙에는 메커니즘만 정의되어 있고, 처리 방법은 구현체 책임
• 정의 예 — 정적 자산을 담은 클러스터 외부 스토리지를 백엔드로 ```yaml rules:
  • http: paths: - path: /icons pathType: ImplementationSpecific backend: resource: apiGroup: k8s.example.com kind: StorageBucket name: icon-assets ```
• 사용 사례 — 정적 파일 서빙, 외부 오브젝트 스토리지 매핑, 컨트롤러 고유 추상화 연결
• 한 path는 backend.service와 backend.resource 중 하나만 가질 수 있음

IngressClass

• 한 클러스터에 여러 Ingress Controller가 공존할 수 있을 때, 어떤 Ingress를 어떤 컨트롤러가 처리할지 매핑
• 두 가지 객체가 협력
  • IngressClass 리소스 — 컨트롤러를 식별하는 클래스 정의
  • Ingress.spec.ingressClassName — 그 Ingress가 어느 클래스를 따를지 선택

IngressClass 정의

• 컨트롤러가 자기 클래스를 등록하기 위해 만드는 클러스터 스코프 리소스

  apiVersion: networking.k8s.io/v1
  kind: IngressClass
  metadata:
    name: external-lb                 # Ingress가 ingressClassName으로 참조할 이름
  spec:
    controller: example.com/ingress-controller   # 어떤 컨트롤러 구현이 처리할지
    parameters:                       # 컨트롤러별 추가 파라미터(선택)
      apiGroup: k8s.example.com
      kind: IngressParameters
      name: external-lb-params
  

• spec.controller — 컨트롤러 구현체를 식별하는 문자열. 컨트롤러는 자기와 일치하는 IngressClass의 Ingress만 처리
• spec.parameters — 컨트롤러 전용 설정을 담은 별도 CR을 가리킴 (예: 외부 LB 옵션, TLS 정책)

Default IngressClass

• IngressClass 중 하나에 어노테이션 ingressclass.kubernetes.io/is-default-class: "true"를 붙이면 기본 클래스가 됨

  metadata:
    name: default-class
    annotations:
      ingressclass.kubernetes.io/is-default-class: "true"
  

• Ingress.spec.ingressClassName이 비어 있으면 기본 클래스가 자동 적용
• 기본 클래스가 없는 클러스터에서 ingressClassName을 비워두면 어느 컨트롤러도 처리하지 않음
• 기본 클래스는 한 클러스터에 하나만 두는 게 권장 — 여러 개면 어떤 게 적용될지 비결정적

구버전과의 차이

• 예전엔 kubernetes.io/ingress.class 어노테이션으로 컨트롤러를 지정했음
• networking.k8s.io/v1부터는 spec.ingressClassName이 정식 — 어노테이션 방식은 deprecated
• 일부 컨트롤러는 호환을 위해 두 방식을 모두 인식하지만, 신규 작성은 ingressClassName 사용