Nginx Ingress annotations

 

Nginx Ingress에서는 주석( annotations)을 특정 Ingress 객체에 추가하여 사용자가 원하는 동작을 지정할 수 있다.

 

Nginx Ingress에서는 2가지 방식으로 설정이 가능하다.

 

• ConfigMap : Nginx Ingress Controller 에서는 configmap 으로 전역 설정을 할 수 있도록 환경 구성을 한다. 예를 들어 아래와 같이 설정한다.

data:
  allow-snippet-annotations: "true"
  client-max-body-size: 1000m
  enable-sticky-sessions: "true"
  proxy-read-timeout: "300"
  proxy-send-timeout: "300"
  ...

• annotation : Ingress 객체에 주석을 설정하여 domain별로 작동방식을 다르게 할 수 있다.

동일한 기능의 설정이 annotation과 configmap 양쪽에 있으면 annotation이 우선 작동하도록 된다.

 

configmap 설정 방법은 아래를 참고한다.

https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/

ConfigMap - NGINX Ingress Controller

 

annotations 설정 방법은 아래를 참고한다.

https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/

Annotations - NGINX Ingress Controller

 

이번에는 이 중 많이 사용되는 annotation에 대해 알아보자.

 

Timeout

Nginx ingress는 다양한 timeout 설정값이 있다. 대용량 파일 upload나 download 서비스 일때 timeout에 의해 중단 될 수 있다. 이 때는 해당 서비스에 timeout을 조종하여 서비스를 할 수 있다.

• proxy-connect-timeout : 프록시 서버와의 연결을 설정하기 위한 시간 초과를 정의
• proxy-send-timeout : 프록시 서버에 요청을 전송하기 위한 시간 초과를 설정. 시간 초과는 전체 요청의 전송이 아니라 두 개의 연속 쓰기 작업 사이에만 설정된다. 프록시 서버가 이 시간 내에 아무 것도 수신하지 않으면 연결이 닫힌다.
• proxy-read-timeout : 프록시 서버에서 응답을 읽기 위한 시간 초과를 정의. 타임아웃은 전체 응답의 전송이 아니라 두 개의 연속적인 읽기 작업 사이에서만 설정된다. 프록시 서버가 이 시간 내에 아무 것도 전송하지 않으면 연결이 닫힌다.

nginx.ingress.kubernetes.io/proxy-connect-timeout: "10"
nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
nginx.ingress.kubernetes.io/proxy-read-timeout: "300"

 

SSL Redirect

기본적으로 컨트롤러는 해당 수신에 대해 TLS가 활성화된 경우 HTTPS로 리디렉션(308)한다. 다음의 규칙을 추가하여 redirect를 비활성화 할 수 있다.

nginx.ingress.kubernetes.io/ssl-redirect: "false"

클러스터 외부에서 SSL 오프로딩을 사용할 때(예: AWS ELB) 사용 가능한 TLS 인증서가 없는 경우에도 HTTPS로 리디렉션하는 것이 유용할 수 있다. 이때에는 아래의 설정을 할 수 있다.

nginx.ingress.kubernetes.io/force-ssl-redirect: "true"

 

Max body size

NGINX의 경우 요청의 크기가 클라이언트 요청 본문의 최대 허용 크기를 초과하면 413 오류가 클라이언트에 반환된다.

다음 설정으로 수정을 할 수 있다.

nginx.ingress.kubernetes.io/proxy-body-size: 8m

 

Sticky Sessions

Affinity 설정은 최초 요청한 서버로 동일한 요청이 갈 수 있도록 해준다. 설정 유형 값은 cookie가 유일하다. 

nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "route"
nginx.ingress.kubernetes.io/session-cookie-hash: "sha1"

다양한 추가 옵션은 다음을 참고한다.

https://kubernetes.github.io/ingress-nginx/examples/affinity/cookie/

Sticky Sessions - NGINX Ingress Controller

 

Rewrite target

일부 시나리오에서는 백엔드 서비스의 노출된 URL이 수신 규칙의 지정된 경로와 다를 수 있다. 이 때 rewrite-target 설정을 서비스에서 예상하는 경로로 설정할 수 있다.

nginx.ingress.kubernetes.io/rewrite-target: /

이와 유사하게 "/" context를 호출 시 다른 애플리케이션 루트로 이동하려면 다음을 설정한다.

nginx.ingress.kubernetes.io/app-root: "/test"

 

Server snippet

Nginx 서버  구성 블록에 사용자 정의 구성을 추가할 수 있다.

우선 snippet annotation을 설정하려면 아래의 설정이 configmap에 설정되어 있어야 한다.

allow-snippet-annotations: "true"

server snippet설정은 다음과 같다.

nginx.ingress.kubernetes.io/server-snippet: |
      proxy_intercept_errors on;
      error_page 400 500 502 503 504 404 /custom_error.html;
      location = /custom_error.html {
        default_type application/json;
        return 400 '{"code":"400", "message": "bad request"}';
      }

만약 5xx대 에러페이지를 특정 사이트로 이동하려면 아래와 같이 할 수 있다.

nginx.ingress.kubernetes.io/server-snippet: |
    error_page 400 500 502 503 504 404 "http://www.errorpage.com/";

 

White Source

Ingress에 접속 가능한 클라이언트 IP 소스 범위를 지정할 수 있다.

nginx.ingress.kubernetes.io/whitelist-source-range: "10.20.0.0/16, 10.10.0.100"

nginx ingress 가 NodePort 서비스 등의 환경이면 Client IP가 아닌 kube-proxy 서버의 IP가 넘어올 수 있다. 이 때는 externalTrafficPolicy=Local 로 설정하여야만 Client IP를 제대로 가지고 올 수 있다.

 

Default backend

Nginx Ingress에 알 수 없는 페이지를 요청하는 경우 기본으로 제공되는 default-http 에러페이지가 반환된다. 이 문제를 해결하려면 다음과 같이 설정가능하다.

nginx.ingress.kubernetes.io/default-backend: <svc name>

 

CORS

Ingress 규칙에서 CORS(Cross-Origin Resource Sharing)를 활성화하려면 다음의 주석을 추가한다.

nginx.ingress.kubernetes.io/enable-cors: "true"

CORS는 다음 주석으로 제어할 수 있다.

• nginx.ingress.kubernetes.io/cors-allow-methods: 허용되는 방법을 제어한다. ','로 구분된 다중 값 필드이며 문자(대소문자)만 허용한다.
  • 기본:GET, PUT, POST, DELETE, PATCH, OPTIONS
  • 예시:nginx.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"
• nginx.ingress.kubernetes.io/cors-allow-headers: 허용되는 헤더를 제어한다. ','로 구분된 다중값 필드이며 문자, 숫자, _ 및 -를 사용할 수 있다.
  • 기본:DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization
  • 예시:nginx.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For, X-app123-XPTO"

• nginx.ingress.kubernetes.io/cors-expose-headers: 응답에 노출되는 헤더를 제어한다. ','로 구분된 다중값 필드이며 문자, 숫자, _, - 및 *를 사용할 수 있습니다.
  • 기본값: 비어 있음
  • 예시:nginx.ingress.kubernetes.io/cors-expose-headers: "*, X-CustomResponseHeader"

• nginx.ingress.kubernetes.io/cors-allow-origin: CORS에 대해 허용되는 Origin을 제어한다. ','로 구분된 다중값 필드
  • 기본:*
  • 예시:nginx.ingress.kubernetes.io/cors-allow-origin: "https://origin-site.com:4443, http://origin-site.com, https://example.org:1199"
• nginx.ingress.kubernetes.io/cors-allow-credentials: CORS 작업 중에 자격 증명을 전달할 수 있는지 여부를 제어한다.
  • 기본:true
  • 예시:nginx.ingress.kubernetes.io/cors-allow-credentials: "false"
• nginx.ingress.kubernetes.io/cors-max-age: 실행 전 요청을 캐시할 수 있는 기간을 제어한다.
  • 기본:1728000
  • 예시:nginx.ingress.kubernetes.io/cors-max-age: 600

 

속도 제한

연결 및 전송 속도에 대한 제한할 수 있다. DDoS 공격을 완화하는데 사용할 수 있다.

nginx.ingress.kubernetes.io/limit-rps: "20" 
nginx.ingress.kubernetes.io/limit-connections: "5"

• nginx.ingress.kubernetes.io/limit-connections: 단일 IP 주소에서 허용되는 동시 연결 수. 이 제한을 초과하면 503 오류가 반환된다.
• nginx.ingress.kubernetes.io/limit-rps: 초당 주어진 IP에서 수락된 요청 수. 버스트 제한은 버스트 승수를 곱한 이 제한으로 설정되며 기본 승수는 5이다. 클라이언트가 이 제한을 초과하면 limit-req-status-code 기본값인 503이 반환된다.
• nginx.ingress.kubernetes.io/limit-rpm: 지정된 IP에서 분당 수락된 요청 수. 버스트 제한은 버스트 승수를 곱한 이 제한으로 설정되며 기본 승수는 5이다. 클라이언트가 이 제한을 초과하면 limit-req-status-code 기본값인 503이 반환된다.
• nginx.ingress.kubernetes.io/limit-burst-multiplier: 버스트 크기에 대한 제한 속도의 승수. 기본 버스트 승수는 5이며 이 주석은 기본 승수를 재정의한다. 클라이언트가 이 제한을 초과하면 limit-req-status-code 기본값인 503이 반환된다.
• nginx.ingress.kubernetes.io/limit-rate-after: 주어진 연결에 대한 응답의 추가 전송이 속도가 제한되는 초기 킬로바이트 수. 이 기능은 프록시 버퍼링이 활성화 된 상태에서 사용해야 한다.
• nginx.ingress.kubernetes.io/limit-rate: 주어진 연결에 보낼 수 있는 초당 킬로바이트 수. 0 값은 속도 제한을 비활성화한다. 이 기능은 프록시 버퍼링이 활성화 된 상태에서 사용해야 한다 .
• nginx.ingress.kubernetes.io/limit-whitelist: 속도 제한에서 제외할 클라이언트 IP 소스 범위. 값은 쉼표로 구분된 CIDR 목록이다.