NGINX Ingress Controller Documentation

Annotation이 포함된 고급 구성

이 문서는 Annotation 을 사용하여 고급 기능을 사용하는 방법을 설명합니다.

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

고급 기능을 사용하는 것 외에도 NGINX 동작을 사용자 정의하거나 미세 조정해야 하는 경우가 많습니다. 예를 들어 연결 시간 초과 값을 설정합니다.

Ingress 리소스에 적용된 Annotation을 사용하면 고급 NGINX 기능을 사용하고 해당 Ingress 리소스에 대한 NGINX 동작을 사용자 정의/미세 조정할 수 있습니다.

사용자 정의 및 미세 조정은 ConfigMap을 통해서도 가능합니다. Annotation은 ConfigMap보다 우선합니다.

목차

1. Annotation 사용
2. 검증
3. Annotation 요약
 3-1. 일반 사용자 정의
3-2. Request URI/Header Manipulation
3-3. 인증 및 SSL/TLS
3-4. Listeners
3-5. Backend Services (Upstreams)
3-6. Snippets and 사용자 정의 템플릿
3-7. App Protect
3-8. App Protect DoS

1. Annotation 사용

다음은 Annotation을 사용하여 특정 입력 리소스에 대한 구성을 사용자 정의하는 예입니다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress-with-annotations
  annotations:
    nginx.org/proxy-connect-timeout: "30s"
    nginx.org/proxy-read-timeout: "20s"
    nginx.org/client-max-body-size: "4m"
    nginx.org/server-snippets: |
      location / {
        return 302 /coffee;
      }      
spec:
  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

2. 검증

Ingress Controller는 Ingress 리소스의 Annotation을 검증합니다. Ingress가 유효하지 않은 경우 Ingress Controller는 이를 거부합니다. Ingress는 클러스터에 계속 존재하지만 Ingress Controller는 이를 무시합니다.

Ingress Controller가 Ingress에 대한 구성을 성공적으로 적용했는지 확인할 수 있습니다. 예시 cafe-ingress-with-annotations Ingress의 경우 다음을 실행할 수 있습니다.

$ kubectl describe ing cafe-ingress-with-annotations
. . .
Events:
  Type     Reason          Age   From                      Message
  ----     ------          ----  ----                      -------
  Normal   AddedOrUpdated  3s    nginx-ingress-controller  Configuration for default/cafe-ingress-with-annotations was added or updated

구성이 성공적으로 적용되었음을 알리는 AddedOrUpdated 이유가 있는 Normal 이벤트가 이벤트 섹션에 어떻게 포함되어 있는지 확인하십시오.

잘못된 Ingress를 생성하면 Ingress Controller가 이를 거부하고 Rejected 이벤트를 내보냅니다. 예를 들어 nginx.org/redirect-to-https Annotation이 true가 아닌 yes please로 설정된 Ingress cafe-ingress-with-annotations를 생성하면 다음과 같은 결과를 얻게 됩니다.

$ kubectl describe ing cafe-ingress-with-annotations
. . .
Events:
  Type     Reason    Age   From                      Message
  ----     ------    ----  ----                      -------
  Warning  Rejected  13s   nginx-ingress-controller  annotations.nginx.org/redirect-to-https: Invalid value: "yes please": must be a boolean

이벤트 섹션에 Rejected 이유가 포함된 경고 이벤트가 포함된 방식을 확인하십시오.

Note: 기존 Ingress을 무효화하면 Ingress Controller가 이를 거부하고 NGINX에서 해당 구성을 제거합니다.

다음 Ingress Annotation은 현재 검증이 제한되어 있습니다.

  • nginx.com/jwt-token.

3. Annotation 요약

아래 표에는 사용 가능한 Annotation이 요약되어 있습니다.

Note: nginx.com으로 시작하는 Annotation은 NGINX Plus에서만 지원됩니다.

3-1. 일반 사용자 정의

AnnotationConfigMap Key설명DefaultExample
nginx.org/proxy-connect-timeoutproxy-connect-timeoutproxy_connect_timeout 및 grpc_connect_timeout 지시문의 값을 설정합니다.60s
nginx.org/proxy-read-timeoutproxy-read-timeoutproxy_read_timeout 및 grpc_read_timeout 지시문의 값을 설정합니다.60s
nginx.org/proxy-send-timeoutproxy-send-timeoutproxy_send_timeout 및 grpc_send_timeout 지시문의 값을 설정합니다.60s
nginx.org/client-max-body-sizeclient-max-body-sizeclient_max_body_size 지시문의 값을 설정합니다.1m
nginx.org/proxy-bufferingproxy-bufferingProxy 서버의 buffering of responses을 활성화 또는 비활성화합니다.True
nginx.org/proxy-buffersproxy-buffersproxy_buffers 지시문의 값을 설정합니다.플랫폼에 따라 다릅니다.
nginx.org/proxy-buffer-sizeproxy-buffer-sizeproxy_buffer_size 및 grpc_buffer_size 지시문의 값을 설정합니다.플랫폼에 따라 다릅니다.
nginx.org/proxy-max-temp-file-sizeproxy-max-temp-file-sizeproxy_max_temp_file_size 지시문의 값을 설정합니다.1024m
nginx.org/server-tokensserver-tokensserver_tokens 지시문을 활성화하거나 비활성화합니다. 또한 NGINX Plus를 사용하여 빈 문자열 값을 포함한 사용자 정의 문자열 값을 지정할 수 있으며, 이로 인해 “Server” 필드가 실행 중지됩니다.True

3-2. Request URI/Header Manipulation

AnnotationConfigMap Key설명DefaultExample
nginx.org/proxy-hide-headersproxy-hide-headers하나 이상의 proxy_hide_header 지시문 값을 설정합니다. 예: "nginx.org/proxy-hide-headers": "header-a,header-b"N/A
nginx.org/proxy-pass-headersproxy-pass-headers하나 이상의 proxy_pass_header 지시문 값을 설정합니다. 예: "nginx.org/proxy-pass-headers": "header-a,header-b"N/A
nginx.org/rewritesN/Aproxy_pass 지시문을 사용하여 URI 재작성을 구성합니다.N/A재작성 지원.

3-3. 인증 및 SSL/TLS

AnnotationConfigMap Key설명DefaultExample
nginx.org/redirect-to-httpsredirect-to-https서버 블록의 http_x_forwarded_proto 헤더 값을 기반으로 301 리다이렉션 규칙을 설정하여 Ingress 트래픽이 HTTPS를 통과하도록 합니다. Ingress Controller 앞에 있는 Load Balancer에서 SSL Termination할 때 유용합니다. 115를 참조하세요.False
ingress.kubernetes.io/ssl-redirectssl-redirectIngress 트래픽이 HTTPS를 통해 강제 실행되도록 모든 Ingress HTTP 트래픽에 대해 무조건 301 리다이렉션 규칙을 설정합니다.True
nginx.org/hstshstsHTTP Strict Transport Security(HSTS) 사용 설정\ : HSTS 헤더가 Backend의 응답에 추가됩니다. Preload 지시문은 헤더에 포함되어 있습니다.False
nginx.org/hsts-max-agehsts-max-ageHSTS 헤더의 max-age 지시문 값을 설정합니다.2592000 (1 month)
nginx.org/hsts-include-subdomainshsts-include-subdomainsHSTS 헤더에 includeSubDomains 지시문을 추가합니다.False
nginx.org/hsts-behind-proxyhsts-behind-proxyhttp_x_forwarded_proto 요청 헤더의 값을 기반으로 HSTS를 활성화합니다. Ingress Controller 앞의 Load Balancer(Proxy)에서 TLS 종료가 구성된 경우에만 사용해야 합니다. 참고: HTTP에서 HTTPS로의 리다이렉션을 제어하려면 nginx.org/redirect-to-https Annotation을 구성하세요.False
nginx.org/basic-auth-secretN/AHTTP 기본 인증에 대한 사용자 목록이 있는 Secret 리소스를 지정합니다.N/A
nginx.org/basic-auth-realmN/ARealm을 지정합니다.N/A
nginx.com/jwt-keyN/AJWT(JSON Web Tokens)의 유효성을 검사하기 위한 Key가 있는 Secret 리소스를 지정합니다.N/AJSON Web Tokens (JWTs)을 지원합니다.
nginx.com/jwt-realmN/ARealm을 지정합니다.N/AJSON Web Tokens (JWTs)을 지원합니다.
nginx.com/jwt-tokenN/AJSON Web Tokens을 포함하는 변수를 지정합니다.기본적으로 Authorization 헤더에 Bearer Token으로 JWT가 필요합니다.JSON Web Tokens (JWTs)을 지원합니다.
nginx.com/jwt-login-urlN/AJWT가 잘못되었거나 누락된 경우 클라이언트가 리다이렉션되는 URL을 지정합니다.N/AJSON Web Tokens (JWTs)을 지원합니다.

3-4. Listeners

AnnotationConfigMap Key설명DefaultExample
nginx.org/listen-portsN/ANGINX가 Listen할 HTTP 포트를 구성합니다.[80]
nginx.org/listen-ports-sslN/ANGINX가 Listen할 HTTPS 포트를 구성합니다.[443]

3-5. Backend Services (Upstreams)

AnnotationConfigMap Key설명DefaultExample
nginx.org/lb-methodlb-methodLoad Balancing Method를 설정합니다. Round Robin을 사용하려면 "round_robin"을 지정합니다."random two least_conn"
nginx.org/ssl-servicesN/A서비스의 Endpoint에 연결할 때 SSL을 통한 HTTPS 또는 gRPC를 활성화합니다.N/ASSL 서비스 지원
nginx.org/grpc-servicesN/A서비스에 gRPC를 사용하도록 설정합니다. 참고: HTTP/2가 필요합니다(http2 ConfigMap 키 참조). TLS Termination가 활성화된 Ingress에서만 작동합니다.N/AGRPC 서비스 지원
nginx.org/websocket-servicesN/A서비스용 WebSocket을 활성화합니다.N/AWebSocket 서비스 지원
nginx.org/max-failsmax-failsserver 지시문의 max_fails 매개변수 값을 설정합니다.1
nginx.org/max-connsN\Aserver 지시문의 max_conns 매개변수 값을 설정합니다.0
nginx.org/upstream-zone-sizeupstream-zone-sizeUpstream에 대한 공유 메모리 zone의 크기를 설정합니다. NGINX의 경우 특수 값 0은 공유 메모리 영역을 비활성화합니다. NGINX Plus의 경우 공유 메모리 영역이 필요하며 비활성화할 수 없습니다. 특수 값 0은 무시됩니다.256K
nginx.org/fail-timeoutfail-timeoutserver 지시문의 fail_timeout 매개변수 값을 설정합니다.10s
nginx.com/sticky-cookie-servicesN/A세션 지속성을 구성합니다.N/A세션 지속성
nginx.org/keepalivekeepalivekeepalive 지시문의 값을 설정합니다. 값이 0보다 클 때 생성된 구성에 proxy_set_header Connection "";이 추가됩니다.0
nginx.com/health-checksN/AEnables active health checks.FalseActive Health Checks를 지원합니다.
nginx.com/health-checks-mandatoryN/AActive Health Checks를 실행합니다.FalseActive Health Checks를 지원합니다.
nginx.com/health-checks-mandatory-queueN/AActive Health Checks이 필수인 경우 NGINX Plus가 구성 Reload 후 Endpoint의 상태를 확인하는 동안 Ingress 요청이 임시로 저장되는 대기열을 생성합니다.0Active Health Checks를 지원합니다.
nginx.com/slow-startN/AUpstream 서버 Slow Start 기간을 설정합니다. 기본적으로 Slow Start는 서버가 사용 가능하거나 정상 상태가 된 후에 활성화됩니다. 새로 추가된 서버에 대해 Slow Start을 사용하려면 Active Health Checks를 구성하십시오."0s"

3-6. Snippets and 사용자 정의 템플릿

AnnotationConfigMap Key설명DefaultExample
nginx.org/location-snippetslocation-snippetslocation 지시문에서 사용자 정의 Snippet을 설정합니다.N/A
nginx.org/server-snippetsserver-snippetsserver 지시문에서 사용자 정의 Snippet을 설정합니다.N/A

3-7. App Protect

Note: App Protect Annotation은 App Protect WAF 모듈이 설치된 경우에만 작동합니다.

AnnotationConfigMap Key설명DefaultExample
appprotect.f5.com/app-protect-policyN/AIngress 리소스에 대한 애플리케이션 보호 정책의 이름입니다. 형식은 Namespace/Name 입니다. Namespace를 지정하지 않으면 Ingress 리소스의 동일한 Namespace가 사용됩니다. 지정되지 않았지만 appprotect.f5.com/app-protect-enable이 true이면 기본 정책 ID가 적용됩니다. 참조된 정책 리소스가 없거나 정책이 잘못된 경우 이 Annotation이 무시되고 기본 정책이 적용됩니다.N/AExample for App Protect.
appprotect.f5.com/app-protect-enableN/AIngress 리소스에 대해 App Protect를 활성화합니다.FalseExample for App Protect.
appprotect.f5.com/app-protect-security-log-enableN/AApp Protect용 보안 로그를 사용 설정합니다.FalseExample for App Protect.
appprotect.f5.com/app-protect-security-logN/AIngress 리소스에 대한 App Protect 로그 구성입니다. 형식은 namespace/name입니다. namespace를 지정하지 않으면 기본값(filter: illegal, format: default)이 사용됩니다. 쉼표로 구분된 목록에서 여러 구성을 지정할 수 있습니다. 로그 구성과 대상 목록(아래 참조)은 모두 길이가 같아야 합니다. 구성과 대상은 목록 인덱스에 의해 쌍으로 구성됩니다.N/AExample for App Protect.
appprotect.f5.com/app-protect-security-log-destinationN/A보안 로그의 대상입니다. 쉼표로 구분된 목록에서 여러 대상을 지정할 수 있습니다. 로그 구성과 대상 목록(위 참조)은 길이가 같아야 합니다. 구성 및 대상은 목록 인덱스로 쌍을 이룹니다.syslog:server=localhost:514Example for App Protect.

3-8. App Protect DoS

Note: App Protect DoS Annotation은 App Protect DoS 모듈이 설치된 경우에만 작동합니다.

AnnotationConfigMap Key설명DefaultExample
appprotectdos.f5.com/app-protect-dos-resourceN/ADosProtectedResource를 지정하여 Ingress 리소스에 대해 App Protect DoS를 활성화합니다.N/AExample for App Protect DoS.