NGINX Ingress Controller Documentation

기본 구성

이 문서의 예는 Ingress 리소스 정의 및 기본 구성 을 보여줍니다.

아래 예시는 기본 Ingress 리소스 정의를 보여줍니다. 이는 cafe.example.com에서 호스팅되는 가상의 cafe 애플리케이션을 구성하는 두 가지 서비스(coffe와 tea)에 대한 요청의 Load Balancing합니다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
spec:
  tls:
  - hosts:
    - cafe.example.com
    secretName: cafe-secret
  rules:
  - host: cafe.example.com
    http:
      paths:
      - path: /tea
        pathType: Prefix
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      - path: /coffee
        pathType: Prefix
        backend:
          service:
            name: coffee-svc
            port:
              number: 80

다음은 이 Ingress 리소스 정의의 의미에 대한 분석입니다.

  • metadata.name 필드는 리소스 cafe‑ingress의 이름을 정의합니다
  • spec.tls 필드에서 SSL/TLS Termination를 설정합니다.
    • secretName에서 우리는 cafe‑secret이라는 이름으로 Secret 리소스를 참조합니다. Secret은 Ingress와 동일한 Namespace에 속해야 하며 kubernetes.io/tls 유형이어야 하며 여기에 설명된 대로 인증서와 개인 Key를 보유하는 tls.crt 및 tls.key라는 이름의 Key를 포함해야 합니다. Secret이 존재하지 않거나 유효하지 않은 경우 NGINX는 Secret이 적용되는 호스트에 대한 TLS 연결 설정 시도를 중단합니다.
    • hosts 필드에서 인증서와 Key를 cafe.example.com 호스트에 적용합니다.
  • spec.rules 필드에서 도메인 이름이 cafe.example.com인 호스트를 정의합니다.
  • paths 필드에서 두 가지 경로 기반 규칙을 정의합니다.
    • /tea 경로가 있는 규칙은 클러스터에서 이름이 tea‑svc로 배포된 tea 서비스의 Pod 간에 /tea URI가 있는 요청을 배포하도록 NGINX에 지시합니다.
    • /coffee 경로가 있는 규칙은 NGINX가 /coffee URI가 있는 요청을 클러스터에서 coffee‑svc라는 이름으로 배포된 Coffee 서비스의 Pod 간에 배포하도록 지시합니다.
    • 두 규칙 모두 NGINX가 해당 서비스의 포트 80(servicePort 필드)에 요청을 배포하도록 지시합니다.

클러스터에 Ingress 및 Secret 리소스를 배포하는 방법에 대한 전체 지침은 GitHub repo의 전체 예제를 참조하세요.

Ingress 리소스에 대해 자세히 알아보려면 Kubernetes 문서에서 Ingress 리소스 문서를 참조하십시오.

목차

1. Kubernetes 1.18 이상에서 사용할 수 있는 새로운 기능
2. 제한사항
3. 고급 구성

1. Kubernetes 1.18 이상에서 사용할 수 있는 새로운 기능

Kubernetes 1.18부터 다음과 같은 새로운 기능을 사용할 수 있습니다.

  • 호스트 필드는 *.example.com과 같은 와일드카드(Wildcard) 도메인 이름을 지원합니다.
  • 경로는 다음 값을 사용하는 새 필드 PathType을 사용하여 다양한 Matching 규칙을 지원합니다. Prefix-based Matching의 경우 Prefix, 정확한 Matching일 경우 Exact 및 기본 유형인 Prefix와 동일한 ImplementationSpecific 값을 사용합니다.
  - path: /tea
    pathType: Prefix
    backend:
      serviceName: tea-svc
      servicePort: 80
  - path: /tea/green
    pathType: Exact
    backend:
        service:
          name: tea-svc
          port:
            number: 80
  - path: /coffee
    pathType: ImplementationSpecific
    backend:
        service:
          name: coffee-svc
          port:
            number: 80
  • 이제 ingressClassName 필드가 지원됩니다.
  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    name: cafe-ingress
  spec:
    ingressClassName: nginx
    tls:
    - hosts:
      - cafe.example.com
      secretName: cafe-secret
    rules:
    - host: cafe.example.com
  . . .

이 필드를 사용할 때 해당 name으로 IngressClass 리소스를 생성해야 합니다. 공통 리소스 생성 섹션의 3단계 IngressClass 리소스 생성을 참조하십시오.

2. 제한사항

NGINX Ingress Controller는 Ingress 리소스에 다음과 같은 제한을 적용합니다.

  • Ingress 리소스를 정의할 때 host 필드는 필수입니다.
  • Ingress 리소스가 병합 가능한 최소값이 아닌 한 host 값은 모든 Ingress 및 VirtualServer 리소스 간에 고유해야 합니다. 호스트 및 Listener 충동 처리를 참조하십시오.
  • spec.rules[].http.paths[]의 path 필드는 필수입니다.

3. 고급 구성

Ingress 리소스는 기본 NGINX 기능(호스트 및 경로 기반 라우팅, TLS Termination)만 사용할 수 있도록 허용합니다. Request URI 재작성 또는 응답 헤더 추가 삽입과 같은 고급 기능은 Annotations을 통해 사용할 수 있습니다.

Ingress Controller는 구성 옵션이 포함된 템플릿 파일을 실행하여 NGINX 구성을 생성합니다. 이러한 옵션은 수신 리소스 및 Ingress Controller의 ConfigMap을 통해 설정됩니다. 생성된 NGINX 구성에 대해 더 많은 제어가 필요한 고급 NGINX 사용자는 Snippet을 사용하여 Raw NGINX 구성을 삽입할 수 있습니다. 자세한 내용은 스니펫을 사용한 고급 구성을 참조하십시오. 또한 템플릿을 사용자 정의할 수 있습니다. 지침은 사용자 정의 템플릿을 참조하십시오.