VirtualServer 및 VirtualServerRoute 리소스

VirtualServer 및 VirtualServerRoute 리소스는 Ingress 리소스의 대안으로 권장되는 Load Balancing 구성입니다.

릴리스 1.5에 도입된 VirtualServer 및 VirtualServerRoute 리소스는 트래픽 분할 및 고급 콘텐츠 기반 라우팅과 같이 Ingress 리소스에서 지원되지 않는 사용 사례를 지원합니다. 리소스는 사용자 정의 리소스로 구현됩니다.

이 문서는 리소스에 대한 참조 문서입니다. 특정 사용 사례에 리소스를 사용하는 추가 예제를 보려면 GitHub Repo의 examples/custom-resources 폴더로 이동하세요.

목차

1. VirtualServer 사양
1-1. VirtualServer.TLS
1-2. VirtualServer.TLS.Redirect
1-3. VirtualServer.TLS.CertManager
1-4. VirtualServer.ExternalDNS
1-5. VirtualServer.ExternalDNS.ProviderSpecific
1-6. VirtualServer.Policy
1-7. VirtualServer.Route
2. VirtualServerRoute 사양
2-1. VirtualServerRoute.Subroute
3. VirtualServer 및 VirtualServerRoute의 공통 부분
3-1. Upstream
3-2. Upstream.Buffers
3-3. Upstream.TLS
3-4. Upstream.Queue
3-5. Upstream.Healthcheck
3-6. Upstream.SessionCookie
3-7. Header
3-8. Action
3-9. Action.Redirect
3-10. Action.Return
3-11. Action.Proxy
3-12. Action.Proxy.RequestHeaders
3-13. Action.Proxy.RequestHeaders.Set.Header
3-14. Action.Proxy.ResponseHeaders
3-15. AddHeader
3-16. Split
3-17. Match
3-18. Condition
3-19. ErrorPage
3-20. ErrorPage.Redirect
3-21. ErrorPage.Return
3-22. ErrorPage.Return.Header
4.VirtualServer 및 VirtualServerRoute 사용
4-1. Snippets 사용
4-2. 검증
4-3. 구조 검증
4-4. 포괄적 검증
5.ConfigMap을 통한 사용자 정의

1. VirtualServer 사양

VirtualServer 리소스는 example.com과 같은 도메인 이름에 대한 Load Balancing 구성을 정의합니다. 다음은 이러한 구성의 예입니다.

apiVersion: k8s.nginx.org/v1
kind: VirtualServer
metadata:
  name: cafe
spec:
  host: cafe.example.com
  tls:
    secret: cafe-secret
  upstreams:
  - name: tea
    service: tea-svc
    port: 80
  - name: coffee
    service: coffee-svc
    port: 80
  routes:
  - path: /tea
    action:
      pass: tea
  - path: /coffee
    action:
      pass: coffee
  - path: ~ ^/decaf/.*\\.jpg$
    action:
      pass: coffee
  - path: = /green/tea
    action:
      pass: tea

Field	설명	Type	Required
host	서버의 호스트(도메인 이름)입니다. my-app 또는 hello.example.com과 같이 RFC 1123에 정의된 유효한 하위 도메인이어야 합니다. *.example.com과 같은 와일드 카드 도메인을 사용하는 경우 도메인을 큰따옴표로 묶어야 합니다. host 값은 모든 Ingress 및 VirtualServer 리소스에서 고유해야 합니다. 호스트 및 Listener 충돌 처리도 참조하세요.	string	Yes
tls	TLS termination 구성.	tls	No
externalDNS	VirtualServer의 externalDNS 구성입니다.	externalDNS	No
dos	DosProtectedResource에 대한 참조로 설정하면 VirtualServer의 DOS 보호가 활성화됩니다.	string	No
policies	정책 목록입니다.	[]policy	No
upstreams	Upstream 목록입니다.	[]upstream	No
routes	루트 목록입니다.	[]route	No
ingressClassName	VirtualServer 리소스를 처리해야 하는 Ingress Controller를 지정합니다.	string	No
http-snippets	http Context에서 사용자 정의 snippet을 설정합니다.	string	No
server-snippets	server Context에서 사용자 정의 snippet을 설정합니다. server-snippets ConfigMap Key를 재정의합니다.	string	No

1-1. VirtualServer.TLS

tls 필드는 VirtualServer에 대한 TLS 구성을 정의합니다. 예:

secret: cafe-secret
redirect:
  enable: true

Field	설명	Type	Required
secret	TLS 인증서 및 Key가 있는 Secret의 이름입니다. Secret는 VirtualServer와 동일한 Namespace에 속해야 합니다. 보안 Secret은 kubernetes.io/tls 유형이어야 하며 여기에 설명된 인증서와 개인 Key를 포함하는 tls.crt 및 tls.key라는 Key를 포함해야 합니다. Secret이 존재하지 않거나 유효하지 않은 경우 NGINX는 VirtualServer의 호스트에 대한 TLS 연결을 설정하려는 모든 시도를 중단합니다. Secret가 지정되지 않았지만 wildcard TLS secret가 구성된 경우 NGINX는 TLS Termination에 와일드 카드 Secret를 사용합니다.	string	No
redirect	VirtualServer에 대한 TLS의 리다이렉션 구성입니다.	tls.redirect	No
cert-manager	VirtualServer에 대한 TLS의 cert-manager 구성입니다.	tls.cert-manager	No

1-2. VirtualServer.TLS.Redirect

Redirect 필드는 VirtualServer에 대한 TLS Redirect을 구성합니다.

enable: true
code: 301
basedOn: scheme

Field	설	Type	Required
enable	VirtualServer에 대한 TLS 리다이렉션을 활성화합니다. 기본값은 False입니다.	boolean	No
code	리다이렉션의 상태 코드입니다. 허용되는 값은 301 , 302 , 307 , 308입니다. 기본값은 301입니다.	int	No
basedOn	NGINX가 리다이렉션을 전송하기 위해 평가할 요청의 속성입니다. 허용되는 값은 scheme(요청의 scheme) 또는 x-forwarded-proto(요청의 X-Forwarded-Proto 헤더)입니다. 기본값은 scheme입니다.	string	No

1-3. VirtualServer.TLS.CertManager

cert-manager 필드는 cert-manager(cert-manager.io)를 사용하여 VirtualServer 리소스에 대한 x509 자동 인증서 관리를 구성합니다. 발급자 배포 및 구성에 대한 자세한 내용은 cert-manager 구성 설명서를 참조하세요. 예:

cert-manager:
  cluster-issuer: "my-issuer-name"

Field	Description	Type	Required
issuer	Issuer의 이름. Issuer는 인증서에 서명할 수 있는 인증 기관을 설명하는 인증서 관리자 리소스입니다. Issuer는 VirtualServer 리소스와 동일한 Namespace에 있어야 합니다. issuer 및 cluster-issuer 중 하나가 필요하지만 상호 배타적이므로 하나만 정의해야 합니다.	string	No
cluster-issuer	ClusterIssuer의 이름. ClusterIssuer는 인증서에 서명할 수 있는 인증 기관을 설명하는 인증서 관리자 리소스입니다. ClusterIssuer는 Namespace가 없는 리소스이므로 VirtualServer가 상주하는 Namespace는 중요하지 않습니다. issuer 및 cluster-issuer 중 하나가 필요하지만 상호 배타적이므로 하나만 정의해야 합니다.	string	No
issuer-kind	외부 Issuer 리소스의 종류(예: AWSPCAIssuer)입니다. 이는 트리 외부 Issuer에게만 필요합니다. cluster-issuer도 정의된 경우에는 정의할 수 없습니다.	string	No
issuer-group	외부 Issuer Controller의 API 그룹(예: awspca.cert-manager.io)입니다. 이는 트리 외부 Issuer에게만 필요합니다. cluster-issuer도 정의된 경우에는 정의할 수 없습니다.	string	No
common-name	이 필드를 사용하면 생성할 인증서에 대한 spec.commonName을 구성할 수 있습니다. 이 구성은 x509 인증서에 CN을 추가합니다.	string	No
duration	이 필드에서는 생성할 인증서에 대한 spec.duration 필드를 구성할 수 있습니다. Go time.Duration 문자열 형식을 사용하여 지정해야 하며 d(일) 접미사를 허용하지 않습니다. 대신 s, m 및 h 접미사를 사용하여 이러한 값을 지정해야 합니다.	string	No
renew-before	이 Annotation을 사용하면 생성할 인증서에 대한 spec.renewBefore 필드를 구성할 수 있습니다. Go time.Duration 문자열 형식을 사용하여 지정해야 하며 d(일) 접미사를 허용하지 않습니다. 대신 s, m 및 h 접미사를 사용하여 이러한 값을 지정해야 합니다.	string	No
usages	이 필드를 사용하면 생성할 인증서에 대한 spec.usages 필드를 구성할 수 있습니다. 쉼표로 구분된 값(예: key agreement, digital signature, server auth)이 있는 문자열을 전달합니다. 지원되는 Key 사용의 전체 목록은 cert-manager api 문서에서 찾을 수 있습니다.	string	No

1-4. VirtualServer.ExternalDNS

externalDNS 필드는 ExternalDNS를 사용하여 VirtualServer 리소스에 대해 DNS 레코드를 동적으로 제어하도록 구성합니다. ExternalDNS 및 공급자 배포 및 구성에 대한 자세한 내용은 ExternalDNS 구성 설명서를 참조하십시오. 예시:

enable: true

Field	설명	Type	Required
enable	VirtualServer 리소스에 대한 ExternalDNS 통합을 활성화합니다. 기본값은 false입니다.	string	No
labels	ExternalDNS에서 사용할 Endpoint 리소스에 적용할 Label을 구성합니다.	map[string]string	No
providerSpecific	개별 DNS 공급자에 특정한 구성의 이름과 값을 보유하는 공급자별 속성을 구성합니다.	[]ProviderSpecific	No
recordTTL	DNS 레코드용 TTL입니다. 정의되지 않은 경우 기본값은 0입니다. 업체별 기본값은 ExternalDNS TTL 문서를 참조하세요.	int64	No
recordType	생성해야 하는 레코드 유형입니다. 예: “A”, “AAAA”, “CNAME”. 정의되지 않은 경우 외부 Endpoint를 기반으로 자동으로 계산됩니다.	string	No

1-5. VirtualServer.ExternalDNS.ProviderSpecific

externalDNS 블록의 providerSpecific 필드를 사용하면 개별 DNS 제공자에 고유한 구성의 Key Value 쌍 목록인 제공자 특정 속성을 지정할 수 있습니다. 예:

- name: my-name
  value: my-value
- name: my-name2
  value: my-value2

Field	설명	Type	Required
name	Key Value 쌍의 name입니다.	string	Yes
value	Key Value 쌍의 value입니다.	string	Yes

1-6. VirtualServer.Policy

policy 필드는 이름과 선택적 Namespace로 정책 리소스를 참조합니다. 예:

name: access-control

Field	설명	Type	Required
name	정책의 이름입니다. 정책이 존재하지 않거나 유효하지 않은 경우 NGINX는 500 상태 코드가 포함된 오류 응답으로 응답합니다.	string	Yes
namespace	정책의 Namespace입니다. 지정하지 않으면 VirtualServer 리소스의 Namespace가 사용됩니다.	string	No

1-7. VirtualServer.Route

Route는 요청을 Upstream에 전달하는 것과 같은 작업에 클라이언트 요청을 일치시키는 규칙을 정의합니다. 예:

  path: /tea
  action:
    pass: tea

Field	설명	Type	Required
path	route의 경로입니다. NGINX는 요청의 URI와 일치시킵니다. 가능한 값은 다음과 같습니다. 접두사( / , /path ), 정확한 일치( =/exact/match ), 대소문자를 구분하지 않는 정규식(~*^/Bar.*\.jpg ) 또는 대소문자를 구분하는 정규식(~^/foo.*\.jpg ). 접두사(/로 시작해야 함) 또는 정확히 일치(=로 시작해야 함)의 경우 경로에 공백 문자({ , } 또는 ;)가 포함되어서는 안 됩니다. 정규식 일치의 경우 모든 큰따옴표는 " 이스케이프되어야 하며 일치는 이스케이프 처리되지 않은 백슬래시 \로 끝날 수 없습니다. 경로는 VirtualServer의 모든 경로 경로 중에서 고유해야 합니다. 자세한 내용은 location 지시문을 확인하세요. .	string	Yes
policies	정책 목록입니다. 정책은 VirtualServer의 spec에 정의된 동일한 유형의 정책을 재정의합니다. 자세한 내용은 정책 적용을 참조하세요.	[]policy	No
action	요청에 대해 수행할 기본 작업입니다.	action	No
dos	DosProtectedResource에 대한 참조로 설정하면 VirtualServer 경로의 DOS 보호가 활성화됩니다.	string	No
splits	트래픽 분할을 위한 기본 분할 구성입니다. 최소 2개의 분할을 포함해야 합니다.	[]split	No
matches	고급 콘텐츠 기반 라우팅을 위한 일치 규칙입니다. 기본 action  또는 splits이 필요합니다. 일치하지 않는 요청은 기본 action  또는 splits로 처리됩니다.	matches	No
route	이 경로를 정의하는 VirtualServerRoute 리소스의 이름입니다. VirtualServerRoute가 VirtualServer와 다른 Namespace에 속하는 경우 Namespace를 포함해야 합니다. 예: tea-namespace/tea.	string	No
errorPages	오류 코드에 대한 사용자 정의 응답입니다. NGINX는 Upstream 서버의 오류 응답이나 NGINX에서 생성한 기본 응답을 반환하는 대신 해당 응답을 사용합니다. 사용자 정의 응답은 리다이렉션 또는 미리 준비된 응답일 수 있습니다. 예를 들어 Upstream 서버가 404 상태 코드로 응답한 경우 다른 URL로 리다이렉션합니다.	[]errorPage	No
location-snippets	location Context에서 맞춤 Snippet을 설정합니다. location-snippets ConfigMap Key를 재정의합니다.	string	No

* – 경로에는 action, splits 또는 route 중 하나를 정확히 포함해야 합니다.

2. VirtualServerRoute 사양

VirtualServerRoute 리소스는 VirtualServer에 대한 경로를 정의합니다. 하나 또는 여러 하위 경로로 구성될 수 있습니다. VirtualServerRoute는 Mergeable Ingress Type의 대안입니다.

아래 예에서 Namespace cafe-ns의 VirtualServer cafa는 경로 /coffee가 있는 경로를 정의하며, 이는 Namespace coffee-ns의 VirtualServerRoute coffee에서 추가로 정의됩니다.

VirtualServer:

apiVersion: k8s.nginx.org/v1
kind: VirtualServer
metadata:
  name: cafe
  namespace: cafe-ns
spec:
  host: cafe.example.com
  upstreams:
  - name: tea
    service: tea-svc
    port: 80
  routes:
  - path: /tea
    action:
      pass: tea
  - path: /coffee
    route: coffee-ns/coffee

VirtualServerRoute:

apiVersion: k8s.nginx.org/v1
kind: VirtualServerRoute
metadata:
  name: coffee
  namespace: coffee-ns
spec:
  host: cafe.example.com
  upstreams:
  - name: latte
    service: latte-svc
    port: 80
  - name: espresso
    service: espresso-svc
    port: 80
  subroutes:
  - path: /coffee/latte
    action:
      pass: latte
  - path: /coffee/espresso
    action:
      pass: espresso

각 하위 path에는 VirtualServer의 경로에 정의된 동일한 접두사(여기서는 /coffee)로 시작하는 Route가 있어야 합니다. 또한 VirtualServerRoute의 host는 VirtualServer의 host와 동일해야 합니다.

Field	설명	Type	Required
host	서버의 호스트(도메인 이름)입니다. my-app 또는 hello.example.com과 같이 RFC 1123에 정의된 유효한 하위 도메인이어야 합니다. *.example.com과 같은 와일드 카드 도메인을 사용하는 경우 도메인을 큰따옴표로 묶어야 합니다. 이 리소스를 참조하는 VirtualServer의 host와 동일해야 합니다.	string	Yes
upstreams	Upstreams 목록입니다.	[]upstream	No
subroutes	하위 경로 목록입니다.	[]subroute	No
ingressClassName	VirtualServerRoute 리소스를 처리해야 하는 Ingress Controller를 지정합니다. 이 리소스를 참조하는 VirtualServer의 ingressClassName과 동일해야 합니다.	string_	No

2-1. VirtualServerRoute.Subroute

하위 경로는 클라이언트 요청을 Upstream에 전달하는 것과 같은 작업에 일치시키는 규칙을 정의합니다. 예:

path: /coffee
action:
  pass: coffee

Field	설명	Type	Required
path	subroute의 path입니다. NGINX는 요청의 URI와 일치시킵니다. 가능한 값은 다음과 같습니다. 접두사( / , /path ), 정확한 일치( =/exact/match ), 대소문자를 구분하지 않는 정규식(  ~*^/Bar.*\.jp ) 또는 대소문자를 구분하는 정규식( ~^/foo.*\.jpg ). 접두사의 경우 경로는 이 리소스를 참조하는 VirtualServer의 route path와 동일한 path로 시작해야 합니다. 정확한 일치 또는 정규식 일치의 경우 경로는 이 리소스를 참조하는 VirtualServer의 route path와 동일해야 합니다. 접두사 또는 정확히 일치하는 경우 path에 공백 문자({ , } 또는 ;)가 포함되어서는 안 됩니다. 정규식 일치의 경우 모든 큰따옴표 " 는 이스케이프되어야 하며 일치는 이스케이프 처리되지 않은 백슬래시 \로 끝날 수 없습니다. path는 VirtualServerRoute의 모든 하위 path에서 고유해야 합니다.	string	Yes
policies	정책 목록입니다. 정책은 이 리소스를 참조하는 VirtualServer의 경로에 정의된 모든 정책을 재정의합니다. 정책은 또한 VirtualServer의 spec에 정의된 동일한 유형의 정책을 재정의합니다. 자세한 내용은 정책 적용을 참조하세요.	[]policy	No
action	요청에 대해 수행할 기본 작업입니다.	action	No
dos	DosProtectedResource에 대한 참조로 이를 설정하면 VirtualServerRoute 하위 경로의 DOS 보호가 활성화됩니다.	string	No
splits	트래픽 분할을 위한 기본 분할 구성입니다. 최소 2개의 분할을 포함해야 합니다.	[]split	No
matches	고급 콘텐츠 기반 라우팅을 위한 일치 규칙입니다. 기본 action 또는 splits이 필요합니다. 일치하지 않는 요청은 기본 action 또는 splits로 처리됩니다.	matches	No
errorPages	오류 코드에 대한 사용자 정의 응답입니다. NGINX는 Upstream 서버의 오류 응답이나 NGINX에서 생성한 기본 응답을 반환하는 대신 해당 응답을 사용합니다. 사용자 정의 응답은 리다이렉션 또는 미리 준비된 응답일 수 있습니다. 예를 들어 Upstream 서버가 404 상태 코드로 응답한 경우 다른 URL로 리다이렉션합니다.	[]errorPage	No
location-snippets	위치 Context에서 맞춤 Snippet을 설정합니다. VirtualServer(설정된 경우)의 location-snippets 또는 location-snippets ConfigMap Key를 재정의합니다.	string	No

* – 하위 경로는 action 또는 splits 중 하나를 포함해야 합니다.

3. VirtualServer 및 VirtualServerRoute의 공통 부분

3-1. Upstream

Upstream은 라우팅 구성의 대상을 정의합니다. 예:

name: tea
service: tea-svc
subselector:
  version: canary
port: 80
lb-method: round_robin
fail-timeout: 10s
max-fails: 1
max-conns: 32
keepalive: 32
connect-timeout: 30s
read-timeout: 30s
send-timeout: 30s
next-upstream: "error timeout non_idempotent"
next-upstream-timeout: 5s
next-upstream-tries: 10
client-max-body-size: 2m
tls:
  enable: true

Note: WebSocket 프로토콜은 추가 구성 없이 지원됩니다.

Field	Description	Type	Required
name	Upstream의 이름입니다. RFC 1035에 정의된 유효한 DNS Label이어야 합니다. 예를 들어 hello 및 upstream-123은 유효합니다. 이름은 리소스의 모든 Upstream에서 고유해야 합니다.	string	Yes
service	서비스의 이름입니다. 서비스는 리소스와 동일한 Namespace에 속해야 합니다. 서비스가 존재하지 않는 경우 NGINX는 서비스에 Endpoint가 없다고 가정하고 이 Upstream에 대한 요청에 대해 502 응답을 반환합니다. NGINX Plus의 경우에만 ExternalName 유형의 서비스도 지원됩니다(전제 조건 확인).	string	Yes
subselector	Label Key와 값을 사용하여 서비스 내의 Pod를 선택합니다. 기본적으로 서비스의 모든 Pod가 선택됩니다. Note: 지정된 Label은 생성될 때 Pod에 있어야 합니다. Pod Label이 업데이트되면 Ingress Controller는 Pod 수가 변경될 때까지 해당 변경 사항을 확인하지 않습니다.	map[string]string	No
use-cluster-ip	Pod의 IP 및 포트를 사용하는 기본 동작 대신 서비스의 클러스터 IP 및 포트를 사용하도록 설정합니다. 이 필드가 활성화되면 Ingress Controller가 서비스 클러스터 IP와 일치하는 하나의 Upstream 서버로만 NGINX를 구성하므로 여러 Upstream 서버와 관련된 NGINX 동작을 구성하는 필드(예: lb-method 및 next-upstream)는 영향을 미치지 않습니다.	boolean	No
port	서비스의 포트입니다. 서비스가 해당 포트를 정의하지 않으면 NGINX는 서비스에 Endpoint가 없다고 가정하고 이 Upstream에 대한 요청에 대해 502 응답을 반환합니다. 포트는 1..65535 범위에 속해야 합니다.	uint16	Yes
lb-method	Load Balancing 매서드입니다. 라운드 로빈 방법을 사용하려면 round_robin을 지정하세요. 기본값은 lb-method ConfigMap Key에 지정됩니다.	string	No
fail-timeout	서버를 사용할 수 없는 것으로 간주하기 위해 Upstream 서버와의 통신을 시도하는데 지정된 횟수만큼 실패한 시간입니다. sever 지시문의 fail_timeout 매개변수를 참조하세요. 기본값은 fail-timeout ConfigMap Key에 설정되어 있습니다.	string	No
max-fails	서버를 사용할 수 없다고 간주하기 위해 fail-timeout 에서 설정한 기간 내에 발생해야 하는 Pustream 서버와의 통신 시도 실패 횟수입니다. server 지시문의 max_fails 매개변수를 참조하세요. 기본값은 max-fails ConfigMap Key에 설정되어 있습니다.	int	No
max-conns	Upstream 서버에 대한 최대 동시 활성 연결 수입니다. server 지시문의 max_conns 매개변수를 참조하세요. 기본적으로 제한이 없습니다. Note: keepalive 연결이 활성화된 경우 Upstream 서버에 대한 총 활성 및 유휴 keepalive 연결 수가 max_conns 값을 초과할 수 있습니다.	int	No
keepalive	Upstream 서버에 연결하기 위한 캐시를 구성합니다. 캐시 값을 0으로 사용하지 않도록 설정합니다. keepalive 지시문을 참조하세요. 기본값은 Keepailive ConfigMap Key에 설정되어 있습니다.	int	No
connect-timeout	Upstream 서버와의 연결을 설정하기 위한 제한 시간입니다. proxy_connect_timeout 지시문을 참조하세요. 기본값은 proxy-connect-timeout ConfigMap Key에 지정됩니다.	string	No
read-timeout	Upstream 서버에서 응답을 읽기 위한 제한 시간입니다. proxy_read_timeout 지시문을 참조하세요. 기본값은 proxy-read-timeout ConfigMap Key에 지정됩니다.	string	No
send-timeout	Upstream 서버로 요청을 전송하기 위한 제한 시간입니다. proxy_send_timeout 지시문을 참조하세요. 기본값은 proxy-send-timeout ConfigMap Key에 지정됩니다.	string	No
next-upstream	요청을 다음 Upstream 서버로 전달할 경우를 지정합니다. proxy_next_upstream 지시문을 참조하세요. 기본값은 error timeout입니다.	string	No
next-upstream-timeout	요청이 다음 Upstream 서버로 전달될 수 있는 시간입니다. proxy_next_upstream_timeout 지시문을 참조하세요. 0 값은 시간 제한을 끕니다. 기본값은 0입니다.	string	No
next-upstream-tries	요청을 다음 Upstream 서버로 전달하기 위한 가능한 시도 횟수입니다. proxy_next_upstream_tries 지시문을 참조하세요. 0 값은 이 제한을 끕니다. 기본값은 0입니다.	int	No
client-max-body-size	클라이언트 요청 본문의 최대 허용 크기를 설정합니다. client_max_body_size 지시문을 참조하세요. 기본값은 client-max-body-size ConfigMap 키에 설정되어 있습니다.	string	No
tls	Upstream에 대한 TLS 구성입니다.	tls	No
healthCheck	Upstream에 대한 Health Check 구성입니다. health_check 지시문을 참조하세요. Note: 이 기능은 NGINX Plus에서만 지원됩니다.	healthcheck	No
slow-start	Slow Start을 사용하면 Upstream 서버가 복구되거나 사용 가능해진 후 또는 서버가 사용 불가능한 것으로 간주된 일정 기간 후에 사용 가능해지면 가중치를 0에서 공칭 값으로 점진적으로 복구할 수 있습니다. 기본적으로 Slow Start은 비활성화되어 있습니다. server 지시문의 slow_start 매개변수를 참조하세요. Note: 이 매개변수는 random, hash 또는 ip_hash 부하 분산 방법과 함께 사용할 수 없으며 무시됩니다.	string	No
queue	Upstream에 대한 을 구성합니다. 요청을 처리하는 동안 Upstream 서버를 즉시 선택할 수 없는 경우 클라이언트 요청이 에 배치됩니다. 기본적으로 은 구성되지 않습니다. Note: 이 기능은 NGINX Plus에서만 지원됩니다.	queue	No
buffering	Upstream 서버의 응답 버퍼링을 활성화합니다. proxy_buffering 지시문을 참조하세요. 기본값은 proxy_buffering ConfigMap 키에 설정되어 있습니다.	boolean	No
buffers	단일 연결에 대한 Upstream 서버에서 응답을 읽는 데 사용되는 버퍼를 구성합니다.	buffers	No
buffer-size	Upstream 서버에서 받은 응답의 첫 번째 부분을 읽는 데 사용되는 버퍼 크기를 설정합니다. proxy_buffer_size 지시문을 참조하세요. 기본값은 proxy-buffer-size ConfigMap 키에 설정됩니다.	string	No
ntlm	NTLM 인증으로 Proxy 요청을 허용합니다. ntlm 지시문을 참조하세요. NTLM 인증이 작동하려면 keepalive 필드를 사용하여 Upstream 서버에 대한 keepalive 연결을 활성화해야 합니다. Note: 이 기능은 NGINX Plus에서만 지원됩니다.	boolean	No
type	Upstream의 유형입니다. 지원되는 값은 http 및 grpc입니다. 기본값은 http입니다. gRPC의 경우 ConfigMap에서 HTTP/2를 사용 설정하고 VirtualServer에서 TLS 종료를 구성해야 합니다.	string	No

3-2. Upstream.Buffers

buffers 필드는 단일 연결에 대한 Upstream 서버의 응답을 읽는 데 사용되는 Buffers를 구성합니다.

number: 4
size: 8K

자세한 내용은 proxy_buffers 지침을 참조하십시오.

Field	설명	Type	Required
number	버퍼 수를 구성합니다. 기본값은 proxy-buffers ConfigMap Key에 설정되어 있습니다.	int	Yes
size	버퍼의 크기를 구성합니다. 기본값은 proxy-buffers ConfigMap Key에 설정되어 있습니다.	string	Yes

3-3. Upstream.TLS

Field	설명	Type	Required
enable	Upstream 서버에 대한 요청에 대해 HTTPS를 활성화합니다. 기본값은 False 이며 HTTP가 사용됨을 의미합니다. Note: 기본적으로 NGINX는 Upstream 서버 인증서를 확인하지 않습니다. 확인을 활성화하려면 EgressMTLS 정책을 구성하십시오.	boolean	No

3-4. Upstream.Queue

queue 필드는 Queue을 구성합니다. 요청을 처리하는 동안 Upstream 서버를 즉시 선택할 수 없는 경우 클라이언트 요청이 Queue에 배치됩니다.

size: 10
timeout: 60s

자세한 내용은 Queue 지시문을 참조하십시오.

Note: 이 기능은 NGINX Plus에서만 지원됩니다.

Field	설명	Type	Required
size	큐(Queue)의 크기입니다.	int	Yes
timeout	큐(Queue)의 제한시간입니다. 제한 시간보다 긴 기간 동안 요청을 대기할 수 없습니다. 기본값은 60초입니다.	string	No

3-5. Upstream.Healthcheck

Healthcheck는 Active Health Check를 정의합니다. 아래 예에서는 Upstream에 대한 Health Check을 활성화하고 Mandatory 및 Persistent와 결합된 Slow-Start 매개변수를 포함하여 사용 가능한 모든 매개변수를 구성합니다.

name: tea
service: tea-svc
port: 80
slow-start: 30s
healthCheck:
  enable: true
  path: /healthz
  interval: 20s
  jitter: 3s
  fails: 5
  passes: 5
  port: 8080
  tls:
    enable: true
  connect-timeout: 10s
  read-timeout: 10s
  send-timeout: 10s
  headers:
  - name: Host
    value: my.service
  statusMatch: "! 500"
  mandatory: true
  persistent: true

Note: 이 기능은 NGINX Plus에서만 지원됩니다.

Field	설명	Type	Required
enable	Upstream 서버에 대한 상태 확인을 활성화합니다. 기본값은 false입니다.	boolean	No
path	Health Check 요청에 사용되는 경로입니다. 기본값은 /입니다. 이것은 gRPC 유형 Upstream에 대해 구성할 수 없습니다.	string	No
interval	연속된 두 Health Check 사이의 간격입니다. 기본값은 5s입니다.	string	No
jitter	각 Health Check가 임의로 지연되는 시간입니다. 기본적으로 지연은 없습니다.	string	No
fails	이 서버가 비정상으로 간주된 후 특정 Upstream 서버의 Health Check에 연속으로 실패한 횟수입니다. 기본값은 1입니다.	integer	No
passes	서버가 정상 상태로 간주될 때까지 특정 Upstream 서버에 대해 연속적으로 통과된 Health Check 수입니다. 기본값은 1입니다.	integer	No
port	Health Check 요청에 사용되는 포트입니다. 기본적으로 server port가 사용됩니다. 참고: Upstream의 포트와 달리 이 포트는 서비스 포트가 아니라 Pod의 포트입니다.	integer	No
tls	Health Check 요청에 사용되는 TLS 구성입니다. 기본적으로 Upstream의 tls 필드가 사용됩니다.	upstream.tls	No
connect-timeout	Upstream 서버와의 연결을 설정하기 위한 제한 시간입니다. 기본적으로 Upstream의 connect-timeout이 사용됩니다.	string	No
read-timeout	Upstream 서버에서 응답을 읽기 위한 제한 시간입니다. 기본적으로 Upstream의 read-timeout이 사용됩니다.	string	No
send-timeout	Upstream 서버로 요청을 전송하기 위한 제한 시간입니다. 기본적으로 Upstream의 send-timeout이 사용됩니다.	string	No
headers	Health Check 요청에 사용되는 요청 헤더입니다. NGINX Plus는 항상 Health Check 요청을 위해 Host, 사용자 User-Agent 및 Connection 헤더를 설정합니다.	[]header	No
statusMatch	Health Check의 예상 응답 상태 코드입니다. 기본적으로 응답에는 상태 코드 2xx 또는 3xx가 있어야 합니다. 예: '200' , '! 500' , '301-303 307'. match 지시어 문서를 참조하세요. gRPC 유형 Upstream에는 지원되지 않습니다.	string	No
grpcStatus	Check method에 대한 Upstream 서버 응답의 예상 gRPC status code입니다. gRPC 서비스가 gRPC Health Check 프로토콜을 구현하지 않는 경우에만 이 필드를 구성하십시오. 예를 들어 Upstream 서버가 12(UNIMPLEMENTED) 상태 코드로 응답하는 경우 12를 구성합니다. gRPC 유형 Upstream에서만 유효합니다.	int	No
grpcService	Upstream 서버에서 모니터링할 gRPC 서비스입니다. gRPC 유형 Upstream에서만 유효합니다.	string	No
mandatory	NGINX Plus가 트래픽을 전송하기 전에 새로 추가된 모든 서버가 구성된 모든 Health Check을 통과해야 합니다. 이를 지정하지 않거나 false로 설정하면 처음에는 서버가 정상으로 간주됩니다. Slow-Start과 결합하면 새 서버가 데이터베이스에 연결하고 전체 트래픽 공유를 처리하라는 요청을 받기 전에 “Warm Up”할 수 있는 더 많은 시간을 제공합니다.	bool	No
persistent	Reload하기 전에 서버가 정상으로 간주된 경우 Reload한 후 서버에 대한 초기 “Up” 상태를 설정합니다. 영구적으로 사용을 설정하려면 필수 매개변수도 true로 설정해야 합니다.	bool	No

3-6. Upstream.SessionCookie

SessionCookie 필드는 동일한 클라이언트의 요청이 동일한 Upstream 서버로 전달될 수 있도록 하는 세션 지속성을 구성합니다. 지정된 Upstream 서버에 대한 정보는 NGINX Plus에서 생성된 세션 Cookie에 전달됩니다.

아래 예에서는 Upstream에 대한 세션 Cookie를 사용하여 세션 지속성을 구성하고 사용 가능한 모든 매개변수를 구성합니다.

name: tea
service: tea-svc
port: 80
sessionCookie:
  enable: true
  name: srv_id
  path: /
  expires: 1h
  domain: .example.com
  httpOnly: false
  secure: true

추가 정보는 sticky 지시문을 참조하십시오. Session Cookie는 sticky cookie 방법에 해당합니다.

Note: 이 기능은 NGINX Plus에서만 지원됩니다.

Field	설명	Type	Required
enable	Upstream 서버에 대한 세션 Cookie로 세션 지속성을 활성화합니다. 기본값은 false입니다.	boolean	No
name	Cookie의 이름입니다.	string	Yes
path	Cookie가 설정된 경로입니다.	string	No
expires	브라우저가 Cookie를 보관해야 하는 시간입니다. Cookie가 2037년 12월 31일 23:55:55 GMT에 만료되도록 하는 특수 값 max로 설정할 수 있습니다.	string	No
domain	Cookie가 설정된 도메인입니다.	string	No
httpOnly	Cookie에 HttpOnly 특성을 추가합니다.	boolean	No
secure	Cookie에 Secure 특성을 추가합니다.	boolean	No

3-7. Header

header는 HTTP Header를 정의합니다:

name: Host
value: example.com

Field	Description	Type	Required
name	헤더의 이름입니다.	string	Yes
value	헤더의 값입니다.	string	No

3-8. Action

action은 요청에 대해 Action 작업을 정의합니다.

아래 예에서 클라이언트 요청은 Upstream coffe로 전달됩니다.

 path: /coffee
 action:
  pass: coffee

Field	설명	Type	Required
pass	요청을 Upstream으로 전달합니다. 해당 이름의 Upstream을 리소스에 정의해야 합니다.	string	No
redirect	요청을 제공된 URL로 리다이렉션합니다.	action.redirect	No
return	미리 구성된 응답을 반환합니다.	action.return	No
proxy	요청/응답을 수정할 수 있는 기능(예: URI 재작성 또는 헤더 수정)을 사용하여 요청을 Upstream으로 전달합니다.	action.proxy	No

* – 작업에는 pass, redirect, return 또는 proxy 중 하나가 정확히 포함되어야 합니다.

3-9. Action.Redirect

redirect 작업은 요청에 대해 반환할 Redirect을 정의합니다.

아래 예에서는 클라이언트 요청이 http://www.nginx.com URL로 전달됩니다:

redirect:
  url: http://www.nginx.com
  code: 301

Field	설	Type	Required
url	요청을 리다이렉션할 URL입니다. 지원되는 NGINX 변수: $scheme , $http_x_forwarded_proto , $request_uri , $host 변수는 중괄호로 묶어야 합니다. 예: ${host}${request_uri}.	string	Yes
code	리다이렉션의 상태 코드입니다. 허용되는 값은 301, 302, 307, 308입니다. 기본값은 301입니다.	int	No

3-10. Action.Return

return 작업은 요청에 대해 미리 구성된 응답을 정의합니다.

아래 예에서 NGINX는 모든 요청에 대해 사전 구성된 응답으로 응답합니다:

return:
  code: 200
  type: text/plain
  body: "Hello World\n"

Field	설명	Type	Required
code	응답의 상태 코드입니다. 허용되는 값은 2XX, 4XX 또는 5XX입니다. 기본값은 200입니다.	int	No
type	응답의 MIME 유형입니다. 기본값은 text/plain입니다.	string	No
body	응답의 본문입니다. NGINX 변수*를 지원합니다. 변수는 중괄호로 묶어야 합니다. 예: 요청은 ${request_uri}\n입니다.	string	Yes

* – 지원되는 NGINX 변수: $request_uri, $request_method, $request_body, $http_, $args, $args, $arg_, $cookie_, $host, $request_time, $request_length, $nginx_vers, $pid, $remote_addr, $remote_port, $time_iso8601, $time_local, $readdr, $re, $readdr, $servers_connection, $connections_writing 및 $connections_delays.

3-11. Action.Proxy

proxy 작업은 요청/응답을 수정할 수 있는 기능(예: URI Rewrite 또는 헤더 수정)을 사용하여 요청을 Upstream으로 전달합니다.

아래 예제에서는 요청 URI가 /로 다시 작성되고 요청 및 응답 헤더가 수정됩니다:

proxy:
  upstream: coffee
  requestHeaders:
    pass: true
    set:
    - name: My-Header
      value: Value
    - name: Client-Cert
      value: ${ssl_client_escaped_cert}
  responseHeaders:
    add:
    - name: My-Header
      value: Value
    - name: IC-Nginx-Version
      value: ${nginx_version}
      always: true
    hide:
    - x-internal-version
    ignore:
    - Expires
    - Set-Cookie
    pass:
    - Server
  rewritePath: /

Field	설명	Type	Required
upstream	요청이 Proxy될 Upstream의 이름입니다. 해당 이름의 Upstream이 리소스에 정의되어 있어야 합니다.	string	Yes
requestHeaders	요청 헤더 수정 사항입니다.	action.Proxy.RequestHeaders	No
responseHeaders	응답 헤더 수정 사항입니다.	action.Proxy.ResponseHeaders	No
rewritePath	재작성된 URI입니다. 루트 경로가 ~로 시작하는 정규식인 경우, rewritePath에는 $1-9의 캡처 그룹이 포함될 수 있습니다. 예를 들어 첫 번째 그룹에 $1 등이 있습니다. 자세한 내용은 다시 쓰기 예제를 확인하십시오.	string	No

3-12. Action.Proxy.RequestHeaders

RequestHeaders 필드는 Proxy Upstream 서버에 대한 요청 헤더를 수정합니다.

Field	설명	Type	Required
pass	원래 요청 헤더를 Proxy Upstream 서버로 전달합니다. 자세한 내용은 proxy_pass_request_header 지시문을 참조하세요. 기본값은 true입니다.	bool	No
set	Proxy Upstream 서버로 전달된 요청 헤더를 표시하기 위해 필드를 재정의하거나 추가할 수 있습니다. 자세한 내용은 proxy_set_header 지시문를 참조하세요.	[]header	No

3-13. Action.Proxy.RequestHeaders.Set.Header

header는 HTTP Header를 정의합니다:

name: My-Header
value: My-Value

Ingress Controller가 $host로 설정하는 Host 헤더의 기본값을 재정의할 수 있습니다.

name: Host
value: example.com

Field	설명	Type	Required
name	헤더의 이름입니다.	string	Yes
value	헤더의 값입니다. NGINX 변수*를 지원합니다. 변수는 중괄호로 묶어야 합니다. 예: ${scheme}.	string	No

* – 지원되는 NGINX 변수: $request_uri, $request_method, $request_body, $http_, $args, $args, $arg_, $cookie_, $host, $request_time, $request_length, $nginx_vers, $pid, $remote_addr, $remote_port, $time_iso8601, $time_local, $readdr, $re, $readdr, $servers_connection, $connections_writing, $connections_dn, $ssl_dn, $ssl_client_cert, $ssl_client_dn, $ssl_client_dn_fingerprint, $ssl_client_writing, $ssl_client_dn, $ssl_client_dn_dn, $ssl_client_dn_dn_dn, $ssl_client_dn, $ssl_dn_client_dn_client_dn, $ssl_dn_dn, $ss, $ssl_curves, $ssl_early_data, $ssl_protocol, $ssl_server_name, $ssl_session_id, $ssl_session_reuse, $jwt_claim_(NGINX Plus 전용) 및 $jwt_header_(NGINX Plus 전용).

3-14. Action.Proxy.ResponseHeaders

ResponseHeaders 필드는 클라이언트에 대한 응답의 헤더를 수정합니다.

Field	설명	Type	Required
hide	Proxy Upstream 서버에서 클라이언트에 대한 응답으로 전달되지 않는* 헤더입니다. 자세한 내용은 proxy_hide_header 지시문을 참조하세요.	[]string	No
pass	Proxy Upstream 서버에서 클라이언트로 숨겨진 헤더 필드*를 전달할 수 있습니다. 자세한 내용은 proxy_pass_header 지시문을 참조하세요.	[]string	No
ignore	Proxy Uptream 서버에서 클라이언트로의 특정 헤더** 처리를 비활성화합니다. 자세한 내용은 proxy_ignore_headers 지시문을 참조하세요.	[]string	No
add	클라이언트에 대한 응답에 헤더를 추가합니다.	[]addHeader	No

* – 기본 숨김 헤더: Date, Server, X-Pad 및 X-Accel-… 등.

** – 무시할 수 있는 필드는 X-Acel-Redirect, X-Acel-Expires, X-Acel-Limit-Rate, X-Acel-Buffering, X-Acel-Charset, Expires, Cache-Control, Set-Cookie 및 Vari입니다.

3-15. AddHeader

addHeader는 선택적 always 필드가 있는 HTTP 헤더를 정의합니다.

name: My-Header
value: My-Value
always: true

Field	설명	Type	Required
name	헤더의 이름입니다.	string	Yes
value	헤더의 값입니다. NGINX 변수*를 지원합니다. 변수는 중괄호로 묶어야 합니다. 예: ${scheme}.	string	No
always	true로 설정하면 응답 상태 코드**에 관계없이 헤더를 추가합니다. 기본값은 false입니다. 자세한 내용은 add_header 지시어를 참조하십시오.	bool	No

* – 지원되는 NGINX 변수: $request_uri, $request_method, $request_body, $http_, $args, $args, $arg_, $cookie_, $host, $request_time, $request_length, $nginx_vers, $pid, $remote_addr, $remote_port, $time_iso8601, $time_local, $readdr, $re, $readdr, $servers_connection, $connections_writing, $connections_dn, $ssl_dn, $ssl_client_cert, $ssl_client_dn, $ssl_client_dn_fingerprint, $ssl_client_writing, $ssl_client_dn, $ssl_client_dn_dn, $ssl_client_dn_dn_dn, $ssl_client_dn, $ssl_dn_client_dn_client_dn, $ssl_dn_dn, $ss, $ssl_curves, $ssl_early_data, $ssl_protocol, $ssl_server_name, $ssl_session_id, $ssl_session_reuse, $jwt_claim_(NGINX Plus 전용) 및 $jwt_header_(NGINX Plus 전용).

** – always가 false이면 응답 상태 코드가 200, 201, 204, 206, 301, 302, 303, 304, 307 또는 308인 경우에만 응답 헤더가 추가됩니다.

3-16. Split

split은 Split 구성의 일부로 작업에 대한 가중치를 정의합니다.

아래 예에서 NGINX는 요청의 80%를 Upstream coffee-v1에 전달하고 나머지 20%를 coffee-v2에 전달합니다.

splits:
- weight: 80
  action:
    pass: coffee-v1
- weight: 20
  action:
    pass: coffee-v2

Field	설명	Type	Required
weight	작업의 무게입니다. 1..99 범위에 속해야 합니다. 모든 분할 가중치의 합은 100이어야 합니다.	int	Yes
action	요청에 대해 수행할 작업입니다.	action	Yes

3-17. Match

match는 조건과 작업 또는 Split 간의 일치를 정의합니다.

아래 예에서 NGINX는 Cookie user의 값에 따라 /coffee 경로가 있는 요청을 다른 Upstream으로 라우팅합니다.

user=john -> coffee-future

user=bob -> coffee-deprecated

Cookie가 설정되지 않았거나 john 또는 bob과 같지 않은 경우 NGINX는 coffee-stable로 라우팅합니다.

path: /coffee
matches:
- conditions:
  - cookie: user
    value: john
  action:
    pass: coffee-future
- conditions:
  - cookie: user
    value: bob
  action:
    pass: coffee-deprecated
action:
  pass: coffee-stable

다음 예에서 NGINX는 요청의 HTTP 메서드를 나타내는 기본 제공 $request_method 변수의 값을 기반으로 요청을 라우팅합니다.

모든 POST 요청 -> coffee-post

모든 non-POST 요 -> coffee

path: /coffee
matches:
- conditions:
  - variable: $request_method
    value: POST
  action:
    pass: coffee-post
action:
  pass: coffee

Field	설명	Type	Required
conditions	조건 목록입니다. 조건을 1개 이상 포함해야 합니다.	[]condition	Yes
action	요청에 대해 수행할 작업입니다.	action	No
splits	트래픽 분할을 위한 분할 구성입니다. 최소 2개의 분할을 포함해야 합니다.	[]split	No

* – Match에는 action 또는 splits 중 정확히 하나가 포함되어야 합니다.

3-18. Condition

condition은 일치 Condition의 조건을 정의합니다.

Field	설	Type	Required
header	헤더의 이름입니다. 영숫자 또는 -로 구성되어야 합니다.	string	No
cookie	Cookie의 이름입니다. 영숫자 문자 또는 _로 구성되어야 합니다.	string	No
argument	Argument의 이름입니다. 영숫자 문자 또는 _로 구성되어야 합니다.	string	No
variable	NGINX 변수의 이름입니다. $로 시작해야 합니다. 표 아래에서 지원되는 변수 목록을 참조하십시오.	string	No
value	조건과 일치하는 값입니다. 값을 정의하는 방법은 표 아래에 나와 있습니다.	string	Yes

* – 조건은 header, cookie, argument 또는 variable 중 하나를 정확하게 포함해야 합니다.

지원되는 NGINX 변수: $args, $http2, $https, $remote_addr, $remote_port, $query_string, $request, $request_body, $request_uri, $request_method, $scheme. 여기에서 각 변수에 대한 설명서를 확인하십시오.

이 값은 두 가지 유형의 Matching를 지원합니다:

• 대소문자를 구분하지 않는 문자열 비교. 예:
  • john – 문자열(예: john, John, JOHN)에 대해 대소문자를 구분하지 않는 일치.
  • !john – bob, anything, ' '(빈 문자열)과 같은 문자열에 대해 john에 대한 대소문자 구분 일치를 부정합니다.
• 정규식과 일치합니다. NGINX는 PCRE(Perl 프로그래밍 언어)에서 사용하는 것과 호환되는 정규식을 지원합니다. 예를 들어:
  • ~^yes – yes로 시작하는 모든 문자열과 일치하는 대소문자를 구분하는 정규식입니다. 예를 들어 yes, yes123입니다.
  • !~^yes – YES, Yes123, noyes와 같은 문자열에 대해 성공하는 이전 정규식의 부정. (부정 메커니즘은 PCRE 구문의 일부가 아닙니다.).
  • ~*no$ – no로 끝나는 모든 문자열과 일치하는 대소문자를 구분하지 않는 정규식입니다. 예: no, 123no, 123NO.

Note: 값에는 이스케이프 처리되지 않은 큰따옴표(")가 포함되어서는 안 되며 이스케이프 처리되지 않은 백슬래시(\)로 끝나지 않아야 합니다. 예를 들어 다음은 유효하지 않은 값입니다. some"value, somevalue\.

3-19. ErrorPage

errorPage는 Upstream 서버가 오류 상태 코드로 응답(또는 NGINX가 생성)하는 경우 경로에 대한 사용자 정의 응답을 정의합니다. 사용자 정의 응답은 리다이렉션 또는 미리 준비된 응답일 수 있습니다. 자세한 내용은 error_page 지시문을 참조하십시오.

path: /coffee
errorPages:
- codes: [502, 503]
  redirect:
    code: 301
    url: https://nginx.org
- codes: [404]
  return:
    code: 200
    body: "Original resource not found, but success!"

Field	설명	Type	Required
codes	오류 상태 코드 목록입니다.	[]int	Yes
redirect	지정된 상태 코드에 대한 리다이렉션 작업입니다.	errorPage.Redirect	No
return	지정된 상태 코드에 대한 미리 준비된 응답 작업입니다.	errorPage.Return	No

* – errorPage는 다음 중 하나를 정확히 포함해야 합니다: return 또는 redirect.

3-20. ErrorPage.Redirect

redirect은 errorPage에 대한 Redirect을 정의합니다.

아래 예에서 NGINX는 Upstream 서버의 응답에 404 상태 코드가 있을 때 리다이렉션으로 응답합니다.

codes: [404]
redirect:
  code: 301
  url: ${scheme}://cafe.example.com/error.html

Field	설명	Type	Required
code	리디렉션의 상태 코드입니다. 허용되는 값은 301, 302, 307, 308입니다. 기본값은 301입니다.	int	No
url	요청을 리다이렉션할 URL입니다. 지원되는 NGINX 변수: $scheme 및 $http_x_forwarded_proto 변수는 중괄호로 묶어야 합니다. 예: ${scheme}.	string	Yes

3-21. ErrorPage.Return

반환은 errorPage에 대한 미리 준비된 응답을 정의합니다.

아래 예에서 NGINX는 Upstream 서버의 응답에 401 또는 403 상태 코드가 있을 때 준비된 응답으로 응답합니다.

codes: [401, 403]
return:
  code: 200
  type: application/json
  body: |
        {\"msg\": \"You don't have permission to do this\"}
  headers:
  - name: x-debug-original-statuses
    value: ${upstream_status}

Field	설	Type	Required
code	응답의 상태 코드입니다. 기본값은 원래 응답의 상태 코드입니다.	int	No
type	응답의 MIME 유형입니다. 기본값은 text/html입니다.	string	No
body	응답의 본문입니다. 지원되는 NGINX 변수: $upstream_status . 변수는 중괄호로 묶어야 합니다. 예: ${upstream_status}.	string	Yes
headers	응답의 사용자 정의 헤더입니다.	errorPage.Return.Header	No

3-22. ErrorPage.Return.Header

헤더는 errorPage에서 검색된 응답에 대한 HTTP 헤더를 정의합니다:

name: x-debug-original-statuses
value: ${upstream_status}

Field	설명	Type	Required
name	헤더의 이름입니다.	string	Yes
value	헤더의 값입니다. 지원되는 NGINX 변수: $upstream_status . 변수는 중괄호로 묶어야 합니다. 예: ${upstream_status}.	string	No

4. VirtualServer 및 VirtualServerRoute 사용

일반적인 kubectl 명령을 사용하여 Ingress 리소스와 유사한 VirtualServer 및 VirtualServerRoute 리소스로 사용할 수 있습니다.

예를 들어 다음 명령은 cafe-virtual-server.yaml에 이름이 cafe인 VirtualServer 리소스를 생성합니다.

$ kubectl apply -f cafe-virtual-server.yaml
virtualserver.k8s.nginx.org "cafe" created

다음을 실행하여 리소스를 가져올 수 있습니다:

$ kubectl get virtualserver cafe
NAME   STATE   HOST                   IP            PORTS      AGE
cafe   Valid   cafe.example.com       12.13.23.123  [80,443]   3m

kubectl get 및 유사한 명령에서 virtualserver 대신 vs라는 짧은 이름을 사용할 수도 있습니다.

VirtualServerRoute 리소스 작업은 유사합니다. kubectl 명령에서 virtualserverroute 또는 단축 이름 vsr을 사용합니다.

4-1. Snippets 사용

Snippets을 사용하면 Raw NGINX 구성을 다른 NGINX 구성 Context에 삽입할 수 있습니다. 아래 예에서는 Snippets을 사용하여 VirtualServer에서 여러 NGINX 기능을 구성합니다.

apiVersion: k8s.nginx.org/v1
kind: VirtualServer
metadata:
  name: cafe
  namespace: cafe
spec:
  http-snippets: |
    limit_req_zone $binary_remote_addr zone=mylimit:10m rate=1r/s;
    proxy_cache_path /tmp keys_zone=one:10m;    
  host: cafe.example.com
  tls:
    secret: cafe-secret
  server-snippets: |
        limit_req zone=mylimit burst=20;
  upstreams:
  - name: tea
    service: tea-svc
    port: 80
  - name: coffee
    service: coffee-svc
    port: 80
  routes:
  - path: /tea
    location-snippets: |
      proxy_cache one;
      proxy_cache_valid 200 10m;      
    action:
      pass: tea
  - path: /coffee
    action:
      pass: coffee

Snippets은 생성된 NGINX 구성에 대해 더 많은 제어가 필요한 고급 NGINX 사용자가 사용하기 위한 것입니다.

그러나 아래에 설명된 단점 때문에 Snippets은 기본적으로 비활성화되어 있습니다. Snippets을 사용하려면 enable-snippets Command-line를 설정합니다.

Snippets 사용의 단점:

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

Snippets을 사용할 때 오류를 감지할 수 있도록 Ingress Controller는 로그뿐 아니라 VirtualServer 및 VirtualServerRoute 리소스의 이벤트 및 상태 필드에 구성 Reload 오류를 보고합니다. 또한 다수의 Prometeus 메트릭은 실패한 Reload에 대한 통계(controller_nginx_last_reload_status 및 controller_nginx_reload_errors_total)를 보여줍니다.

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

4-2. 검증

VirtualServer 및 VirtualServerRoute 리소스에 대해 두 가지 유형의 유효성 검증을 사용할 수 있습니다.

• Kubectl 및 Kubernetes API 서버에 의한 구조 검증.
• Ingress Controller에 의한 포괄적인 검증.

4-3. 구조 검증

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

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

kubectl 검증의 예:

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

Kubernetes API 서버 검증의 예:

$ kubectl apply -f cafe-virtual-server.yaml --validate=false
  The VirtualServer "cafe" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list:
  spec.upstreams.port in body must be of type integer: "string"

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

4-4. 포괄적 검증

Ingress Controller는 VirtualServer 및 VirtualServerRoute 리소스의 필드 유효성을 검사합니다. 리소스가 유요하지 않은 경우 Ingress Controller가 리소스를 거부합니다. 리소스는 클러스터에 계속 존재하지만 Ingress Controller는 이를 무시합니다.

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

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

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

잘못된 리소스를 생성하면 Ingress Controller가 이를 거부하고 Rejected 이벤트를 내보냅니다. 예를 들어, 같은 이름의 tea를 가진 두 개의 Upstream이 있는 VirtualServer cafe를 만들면 다음과 같은 결과를 얻게 됩니다.

$ kubectl describe vs cafe
. . .
Events:
  Type     Reason    Age   From                      Message
  ----     ------    ----  ----                      -------
  Warning  Rejected  12s   nginx-ingress-controller  VirtualServer default/cafe is invalid and was rejected: spec.upstreams[1].name: Duplicate value: "tea"

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

또한 이 정보는 VirtualServer 리소스의 status 필드에서도 사용할 수 있습니다. VirtualServer의 상태 섹션에 유의하십시오.

$ kubectl describe vs cafe
. . .
Status:
  External Endpoints:
    Ip:        12.13.23.123
    Ports:     [80,443]
  Message:  VirtualServer default/cafe is invalid and was rejected: spec.upstreams[1].name: Duplicate value: "tea"
  Reason:   Rejected
  State:    Invalid

Ingress Controller는 유사한 방식으로 VirtualServerRoute 리소스의 유효성을 검사합니다.

Note: 기존 리소스를 유효하지 않게 만들면 Ingress Controller는 이를 거부하고 NGINX에서 해당 구성을 제거합니다.

5. ConfigMap을 통한 사용자 정의

ConfigMap을 사용하여 VirtualServer 및 VirtualServerRoutes 리소스에 대한 NGINX 구성을 사용자 정의할 수 있습니다. 다음을 제외하고 대부분의 ConfigMap Key가 지원됩니다.

• proxy-hide-headers
• proxy-pass-headers
• hsts
• hsts-max-age
• hsts-include-subdomains
• hsts-behind-proxy
• redirect-to-https
• ssl-redirect