NGINX Ingress Controller Documentation

Snippets을 사용한 고급 구성

Snippets 을 사용하면 Ingress Controller가 생성하는 NGINX 구성의 다른 Context에 Raw NGINX 구성을 삽입할 수 있습니다. 이는 Annotations과 ConfigMap 항목이 도움이 되지 않는 경우 최후의 수단으로 사용해야 합니다. Snippets은 생성된 NGINX 구성을 더 많이 제어해야 하는 고급 NGINX 사용자를 위한 것입니다.

Snippets은 ConfigMap을 통해서도 사용할 수 있습니다. Annotations은 ConfigMap보다 우선합니다.

목차

1. Snippets 사용
2. Snippets
3. Snippets 사용의 단점
4. Troubleshooting

1. Snippets 사용

아래 예는 Snippets을 사용하여 Annotations을 사용하여 NGINX 구성 템플릿을 사용자 정의하는 방법을 보여줍니다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress-with-snippets
  annotations:
    nginx.org/server-snippets: |
      location / {
          return 302 /coffee;
      }      
    nginx.org/location-snippets: |
            add_header my-test-header test-value;
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

생성된 NGINX 구성:

server {
    listen 80;


    location / {
        return 302 /coffee;
    }


    location /coffee {
        proxy_http_version 1.1;


        add_header my-test-header test-value;
        ...
        proxy_pass http://default-cafe-ingress-with-snippets-cafe.example.com-coffee-svc-80;
    }

    location /tea {
        proxy_http_version 1.1;

        add_header my-test-header test-value;
        ...
        proxy_pass http://default-cafe-ingress-with-snippets-cafe.example.com-tea-svc-80;
    }
}

Note: 예제의 명확성을 위해 생성된 구성이 생략되었습니다.

2. Snippets

자세한 내용은 Snippets 주석 문서를 참조하세요. 그러나 아래에 설명된 단점 때문에 Snippets은 기본적으로 비활성화되어 있습니다. Snippets을 사용하려면 enable-snippets Command-Line Arguments를 설정합니다.

3. Snippets 사용의 단점

Snippets에는 다음과 같은 단점이 있습니다:

  • 복잡성(Complexity). Snippets을 사용하려면 다음을 수행해야 합니다.
    • NGINX 구성 기본 요소를 이해하고 올바른 NGINX 구성을 구현합니다.
    • Snippets이 구성의 다른 기능을 방해하지 않도록 IC가 NGINX 구성을 생성하는 방법을 이해합니다.
  • 견고성(Robustness) 감소. 잘못된 Snippets은 NGINX 구성을 무효화하여 Reload 실패를 일으킵니다. 이렇게 하면 Snippets이 수정될 때까지 다른 Ingress 리소스에 대한 업데이트를 포함하여 새로운 구성 업데이트가 방지됩니다.
  • 보안에 영향을 미칩니다. Snippets은 NGINX 구성 기본 요소에 액세스할 수 있으며 이러한 기본 요소는 Ingress Controller에서 검증되지 않습니다. 예를 들어, 입력 리소스에 대한 TLS Termination에 사용되는 TLS 인증서 및 Key를 제공하도록 NGINX를 구성할 수 있습니다.

Note: NGINX 구성에 잘못된 Snippets이 포함된 경우 NGINX는 유효한 최신 구성으로 계속 작동합니다.

4. Troubleshooting

Snippets에 잘못된 NGINX 구성이 포함된 경우 Ingress Controller가 NGINX를 Reload하지 못합니다. 오류는 Ingress Controller 로그에 보고되고 오류가 발생한 이벤트는 Ingress 리소스와 연결됩니다.

오류 로그의 예:

[emerg] 31#31: unknown directive "badd_header" in /etc/nginx/conf.d/default-cafe-ingress-with-snippets.conf:54
Event(v1.ObjectReference{Kind:"Ingress", Namespace:"default", Name:"cafe-ingress-with-snippets", UID:"f9656dc9-63a6-41dd-a499-525b0e0309bb", APIVersion:"extensions/v1beta1", ResourceVersion:"2322030", FieldPath:""}): type: 'Warning' reason: 'AddedOrUpdatedWithError' Configuration for default/cafe-ingress-with-snippets was added or updated, but not applied: Error reloading NGINX for default/cafe-ingress-with-snippets: nginx reload failed: Command /usr/sbin/nginx -s reload stdout: ""
stderr: "nginx: [emerg] unknown directive \"badd_header\" in /etc/nginx/conf.d/default-cafe-ingress-with-snippets.conf:54\n"
finished with error: exit status 1

오류가 있는 이벤트의 예(kubectl describe -n nginx-ingress ingress nginx-ingress를 실행하여 Ingress와 관련된 이벤트를 볼 수 있음):

Events:
Type     Reason                   Age                From                      Message
----     ------                   ----               ----                      -------
Normal   AddedOrUpdated           52m (x3 over 61m)  nginx-ingress-controller  Configuration for default/cafe-ingress-with-snippets was added or updated
finished with error: exit status 1
Warning  AddedOrUpdatedWithError  54s (x2 over 89s)  nginx-ingress-controller  Configuration for default/cafe-ingress-with-snippets was added or updated, but not applied: Error reloading NGINX for default/cafe-ingress-with-snippets: nginx reload failed: Command /usr/sbin/nginx -s reload stdout: ""
stderr: "nginx: [emerg] unknown directive \"badd_header\" in /etc/nginx/conf.d/default-cafe-ingress-with-snippets.conf:54\n"
finished with error: exit status 1

또한 Snippets 문제 해결을 돕기 위해 많은 Prometheus 지표이 실패한 Reload에 대한 통계( controller_nginx_last_reload_status 및 controller_nginx_reload_errors_total)를 표시합니다.