NGINX Ingress Controller Documentation

GlobalConfiguration 리소스

GlobalConfiguration 리소스를 사용하면 Ingress Controller의 Global Configuration 매개변수를 정의할 수 있습니다. 리소스는 사용자 정의 리소스로 구현됩니다.

리소스는 TCP 및 UDP Load Balancing을 위한 Listener 구성을 지원합니다. Listener는 TransportServer 리소스에 필요합니다.

목차

1. 전제 조건
2. GlobalConfiguration 사양
 2-1. Listener
3. GlobalConfiguration 사용
3-1. 검증
3-2. 구조 검증
3-3. 포괄적 검증

1. 전제 조건

Ingress Controller를 설치할 때 -global-configuration Command-line Argument에서 GlobalConfiguration 리소스를 참조해야 합니다. Ingress Controller에는 하나의 GlobalConfiguration 리소스만 필요합니다.

2. GlobalConfiguration 사양

GlobalConfiguration 리소스는 Ingress Controller의 전역 구성 매개변수를 정의합니다. 아래는 예입니다.

apiVersion: k8s.nginx.org/v1alpha1
kind: GlobalConfiguration 
metadata:
  name: nginx-configuration
  namespace: nginx-ingress
spec:
  listeners:
  - name: dns-udp
    port: 5353
    protocol: UDP
  - name: dns-tcp
    port: 5353
    protocol: TCP
Field설명TypeRequired
listenerslisteners의 목록[]listenerNo

2-1. Listener

Listener는 NGINX가 TransportServer에 대한 트래픽을 허용하는 데 사용할 Listener(프로토콜과 포트의 조합)를 정의합니다.

name: dns-tcp
port: 5353
protocol: TCP
Field설명TypeRequired
nameListener의 이름입니다. RFC 1035에 정의된 유효한 DNS Label이어야 합니다. 예를 들어 hello 및 listener-123은 유효합니다. 이름은 모든 Listener에서 고유해야 합니다. tls-passthrough라는 이름은 기본 제공 TLS Passthrough Listener용으로 예약되어 있으며 사용할 수 없습니다.stringYes
portListener의 포트입니다. 포트는 80, 443, Status 포트, Prometheus 측정항목 포트를 제외하고 1~65535 범위에 속해야 합니다. 모든 Listener 중에서 포트 프로토콜의 단일 조합만 허용됩니다.intYes
protocolListener의 프로토콜입니다. 지원되는 값: TCP 및 UDP.stringYes

3. GlobalConfiguration 사용

일반적인 kubectl 명령을 사용하여 GlobalConfiguration 리소스로 작업할 수 있습니다.

예를 들어 다음 명령은 global-configuration.yaml에 정의된 nginx-configuration이라는 이름의 GlobalConfiguration 리소스를 생성합니다.

$ kubectl apply -f global-configuration.yaml
globalconfiguration.k8s.nginx.org/nginx-configuration created

리소스의 Namespace가 nginx-ingress라고 가정하면 다음을 실행하여 리소스를 가져올 수 있습니다.

$ kubectl get globalconfiguration nginx-configuration -n nginx-ingress
NAME                  AGE
nginx-configuration   13s

kubectl get 및 유사한 명령에서 globalconfiguration 대신 짧은 이름 gc를 사용할 수도 있습니다.

3-1. 검증

GlobalConfiguration 리소스에 대해 두 가지 유형의 유효성 검사를 사용할 수 있습니다.

  • kubectl 및 Kubernetes API 서버에 의한 구조 검증.
  • Ingress Controller에 의한 종합적인 검증.

3-2. 구조 검증

GlobalConfiguration에 대한 사용자 정의 리소스 정의에는 리소스의 모든 필드 유형을 설명하는 구조적 OpenAPI 스키마가 포함됩니다.

구조적 스키마를 위반하는 리소스를 생성(또는 업데이트)하려고 하면(예: Listener의 포트 필드에 문자열 값 사용) kubectl 및 Kubernetes API 서버는 이러한 리소스를 거부합니다.

kubectl 유효성 검사의 예:

$ kubectl apply -f global-configuration.yaml
error: error validating "global-configuration.yaml": error validating data: ValidationError(GlobalConfiguration.spec.listeners[0].port): invalid type for org.nginx.k8s.v1alpha1.GlobalConfiguration.spec.listeners.port: got "string", expected "integer"; if you choose to ignore these errors, turn validation off with --validate=false

Kubernetes API 서버 유효성 검사의 예:

$ kubectl apply -f global-configuration.yaml --validate=false
  The GlobalConfiguration "nginx-configuration" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list:
  spec.listeners.port in body must be of type integer: "string"

리소스가 거부되지 않으면(구조적 스키마를 위반하지 않음) Ingress Controller가 추가로 유효성을 검사합니다.

3-3. 포괄적 검증

Ingress Controller는 GlobalConfiguration 리소스의 필드를 검증합니다. 리소스가 유효하지 않으면 Ingress Controller러는 리소스를 사용하지 않습니다. 다음 두 가지 경우를 고려하십시오.

1. Ingress Controller pod가 시작될 때 GlobalConfiguration 리소스가 유효하지 않으면 Ingress Controller가 시작되지 않고 오류와 함께 종료됩니다.

2. Ingress Controller가 실행 중일 때 GlobalConfiguration 리소스가 유효하지 않게 되면 Ingress Controller는 새 버전을 무시합니다. 오류를 보고하고 이전 버전을 계속 사용합니다. 리소스가 다시 유효해지면 Ingress Controller가 리소스를 사용하기 시작합니다.

Note: Ingress Controller가 실행되는 동안 GlobalConfiguration이 삭제되면 Controller는 이전 버전의 리소스를 계속 사용합니다.

Ingress Controller가 GlobalConfiguration에 대한 구성을 성공적으로 적용했는지 확인할 수 있습니다. nginx 구성의 GlobalConfiguration의 경우 다음을 실행할 수 있습니다.

$ kubectl describe gc nginx-configuration -n nginx-ingress
. . .
Events:
  Type     Reason    Age   From                      Message
  ----     ------    ----  ----                      -------
  Normal   Updated   11s   nginx-ingress-controller  GlobalConfiguration nginx-ingress/nginx-configuration was updated

이벤트 섹션에 구성이 성공적으로 적용되었음을 알리는 작업이 업데이트된 이유와 함께 일반 이벤트가 포함된 방법을 확인하십시오.

잘못된 리소스를 생성하면 Ingress Controller 가 이를 거부하고 Rejected 이벤트를 내보냅니다. 예를 들어, 동일한 프로토콜 UDP 및 포트 53이 있는 두 개 이상의 Listener로 GlobalConfiguration nginx-configuration을 생성하면 다음과 같은 결과를 얻게 됩니다.

$ kubectl describe gc nginx-configuration -n nginx-ingress
. . .
Events:
  Type     Reason    Age   From                      Message
  ----     ------    ----  ----                      -------
  Normal   Updated   55s   nginx-ingress-controller  GlobalConfiguration nginx-ingress/nginx-configuration was updated
  Warning  Rejected  6s    nginx-ingress-controller  GlobalConfiguration nginx-ingress/nginx-configuration is invalid and was rejected: spec.listeners: Duplicate value: "Duplicated port/protocol combination 53/UDP"

이벤트 섹션에 Rejected 이유가 포함된 경고 이벤트가 어떻게 포함되어 있는지 확인하십시오.