TransportServer 리소스
TransportServer 리소스 를 사용하면 TCP, UDP 및 TLS Passthrough Load Balancing을 구성할 수 있습니다. 리소스는 사용자 정의 리소스로 구현됩니다.
이 문서는 TransportServer 리소스에 대한 참조 문서입니다. 특정 사용 사례에 리소스를 사용하는 추가 예제를 보려면 GitHub Repo의 examples/custom-resources 폴더로 이동하세요.
목차
1. 전제 조건
2. TransportServer 사양
2-1. Listener
2-2. Upstream
2-3. Upstream.Healthcheck
2-4. Upstream.Healthcheck.Match
2-5. UpstreamParameters
2-6. 세션 매개변수
2-7. Action
3. TransportServer 사용
3-1. Snippet 사용
3-2. 검증
3-2-1. 구조 검증
3-2-2. 포괄적 검증
4. ConfigMap을 통한 사용자 정의
1. 전제 조건
TCP 및 UDP의 경우 TransportServer 리소스는 별도로 생성해야 하는 GlobalConfiguration 리소스와 함께 사용해야 합니다.
TLS Passthrough의 경우 Ingress Controller의 -enable-tls-passthrough command-line Argument를 활성화해야 합니다.
2. TransportServer 사양
TransportServer 리소스는 TCP, UDP 또는 TLS Passthrough 트래픽에 대한 Load Balancing 구성을 정의합니다. 다음은 몇 가지 예입니다.
TCP load balancing:
apiVersion: k8s.nginx.org/v1alpha1
kind: TransportServer
metadata:
name: dns-tcp
spec:
listener:
name: dns-tcp
protocol: TCP
upstreams:
- name: dns-app
service: dns-service
port: 5353
action:
pass: dns-appUDP load balancing:
apiVersion: k8s.nginx.org/v1alpha1
kind: TransportServer
metadata:
name: dns-udp
spec:
listener:
name: dns-udp
protocol: UDP
upstreams:
- name: dns-app
service: dns-service
port: 5353
upstreamParameters:
udpRequests: 1
udpResponses: 1
action:
pass: dns-appTLS passthrough load balancing:
apiVersion: k8s.nginx.org/v1alpha1
kind: TransportServer
metadata:
name: secure-app
spec:
listener:
name: tls-passthrough
protocol: TLS_PASSTHROUGH
host: app.example.com
upstreams:
- name: secure-app
service: secure-app
port: 8443
action:
pass: secure-app| Field | 설명 | Type | Required |
|---|---|---|---|
listener | 들어오는 connections/datagrams을 수락할 NGINX의 Listenrer입니다. | listener | Yes |
host | 서버의 호스트(도메인 이름)입니다. my-app 또는 hello.example.com과 같이 RFC 1123에 정의된 유효한 하위 도메인이어야 합니다. *.example.com과 같은 와일드카드 도메인은 허용되지 않습니다. TLS Passthrough Load Balancing에 필요합니다. | string | No |
upstreams | Upstream 목록입니다. | []upstream | Yes |
upstreamParameters | Upstream 매개변수 입니다. | upstreamParameters | No |
action | 클라이언트 connection/datagram에 대해 수행할 작업입니다. | action | Yes |
ingressClassName | TransportServer 리소스를 처리해야 하는 Ingress Controller를 지정합니다. | string | No |
streamSnippets | stream 지시문에서 사용자 정의 snippet을 설정합니다. | string | No |
serverSnippets | server 지시문에서 사용자 정의 snippet을 설정합니다. | string | No |
– TLSPassthrough 로드 밸런싱에 필요합니다.
2-1. Listener
Listener 필드는 NGINX가 TransportServer에 대한 Ingress 트래픽을 수락하는 데 사용할 Listener를 참조합니다. TCP 및 UDP의 경우 Listener는 GlobalConfiguration 리소스에서 정의되어야 합니다. Listener를 참조할 때 이름과 프로토콜이 모두 일치해야 합니다. TLS Passthrough의 경우 이름이 tls-passthrough이고 프로토콜이 TLS_PASSTHROUGH인 기본으로 제공하는 Listener를 사용합니다.
예:
listener:
name: dns-udp
protocol: UDP| Field | 설명 | Type | Required |
|---|---|---|---|
name | Listener의 이름입니다. | string | Yes |
protocol | Listener의 프로토콜입니다. | string | Yes |
2-2. Upstream
Upstream은 TransportServer의 목적지(Destination)를 정의합니다. 예를 들어:
name: secure-app
service: secure-app
port: 8443
maxFails: 3
maxConns: 100
failTimeout: 30s
loadBalancingMethod: least_conn| Field | 설명 | Type | Required |
|---|---|---|---|
name | Upstream의 이름입니다. RFC 1035에 정의된 유효한 DNS Label이어야 합니다. 예를 들어 hello 및 upstream-123이 유효합니다. 이름은 리소스의 모든 Upstream에서 고유해야 합니다. | string | Yes |
service | 서비스의 이름입니다. 서비스는 리소스와 동일한 Namespace에 속해야 합니다. 서비스가 존재하지 않으면 NGINX는 서비스에 Endpoint가 없다고 가정하고 클라이언트 연결을 닫거나 데이터그램을 무시합니다. | string | Yes |
port | 서비스의 포트입니다. 서비스가 해당 포트를 정의하지 않으면 NGINX는 서비스에 Endpoint가 없다고 가정하고 클라이언트 연결을 닫거나 데이터그램을 무시합니다. 포트는 1..65535 범위에 속해야 합니다. | int | Yes |
maxFails | 서버를 사용할 수 없다고 간주하기 위해 failTimeout 매개변수에서 설정한 기간 내에 발생해야 하는 서버와의 통신 시도 실패 횟수를 설정합니다. 기본값은 1입니다. | int | No |
maxConns | Proxy 서버에 대한 최대 연결 수를 설정합니다. 기본값은 0이며 0은 제한이 없음을 의미합니다. | int | No |
failTimeout | 서버를 사용할 수 없는 것으로 간주하기 위해 서버와의 통신에 실패한 지정된 횟수의 시도가 발생해야 하는 시간과 서버가 사용할 수 없는 것으로 간주되는 시간을 설정합니다. 기본값은 10초입니다. | string | No |
healthCheck | Upstream에 대한 상태 확인 구성입니다. health_check 지시문을 참조하세요. Note: 이 기능은 NGINX Plus에서만 지원됩니다. | healthcheck | No |
loadBalancingMethod | Upstream 서버의 Load Balancing하는 데 사용되는 방법입니다. 기본적으로 연결은 가중 라운드 로빈 Balancing 방법을 사용하여 서버 간에 분산됩니다. 사용 가능한 방법 및 세부정보는 Upstream 섹션을 참조하세요. | string | No |
2-3. Upstream.Healthcheck
Healthcheck는 Active Health Check를 정의합니다. 아래 예에서는 Upstream에 대한 Health Check을 활성화하고 사용 가능한 모든 매개변수를 구성합니다.
name: secure-app
service: secure-app
port: 8443
healthCheck:
enable: true
interval: 20s
timeout: 30s
jitter: 3s
fails: 5
passes: 5
port: 8080Note: 이 기능은 NGINX Plus에서만 지원됩니다.
| Field | 설명 | Type | Required |
|---|---|---|---|
enable | Upstream 서버에 대한 Health Check을 활성화합니다. 기본값은 false입니다. | boolean | No |
interval | 연속된 두 Health Check 사이의 간격입니다. 기본값은 5s입니다. | string | No |
timeout | 이는 Health Check을 위해 SessionParameters에서 설정한 proxy_timeout에서 설정한 시간 초과를 재정의합니다. 기본값은 5초입니다. | string | No |
jitter | 각 상태 확인이 임의로 지연되는 시간입니다. 기본적으로 지연이 없습니다. | string | No |
fails | 이 서버가 비정상으로 간주된 후 특정 Upstream 서버의 상태 확인에 연속으로 실패한 횟수입니다. 기본값은 1입니다. | integer | No |
passes | 특정 Upstream 서버의 상태 확인을 연속으로 통과한 후 서버가 정상으로 간주되는 횟수입니다. 기본값은 1입니다. | integer | No |
port | 상태 확인 요청에 사용되는 포트입니다. 기본적으로 서버 포트가 사용됩니다. Note: Upstream의 포트와 달리 이 포트는 서비스 포트가 아니라 Pod의 포트입니다. | integer | No |
match | 전송할 데이터와 Health Check에 대해 예상할 응답을 제어합니다. | match | No |
2-4. Upstream.Healthcheck.Match
일치는 전송할 데이터와 Health Check에 대해 예상되는 응답을 제어합니다.
match:
send: 'GET / HTTP/1.0\r\nHost: localhost\r\n\r\n'
expect: "~200 OK"send 및 expect 필드는 모두 접두사 \x 뒤에 두 개의 16진수가 오는 16진수 Literal을 포함할 수 있습니다(예: \x80).
자세한 내용은 match 지시문을 참조하십시오.
| Field | 설명 | Type | Required |
|---|---|---|---|
send | Upstream 서버로 보낼 문자열입니다. | string | No |
expect | 서버에서 얻은 데이터가 일치해야 하는 Literal 문자열 또는 정규식입니다. 정규 표현식은 앞의 ~* 수정자(대소문자를 구분하지 않는 일치의 경우) 또는 ~ 수정자(대소문자를 구분하는 일치의 경우)로 지정됩니다. Ingress Controller는 RE2 구문을 사용하여 정규식의 유효성을 검사합니다. | string | No |
2-5. UpstreamParameters
Upstream 매개변수는 Upstream에 대한 다양한 매개변수를 정의합니다.
upstreamParameters:
udpRequests: 1
udpResponses: 1
connectTimeout: 60s
nextUpstream: true
nextUpstreamTimeout: 50s
nextUpstreamTries: 1| Field | 설명 | Type | Required |
|---|---|---|---|
udpRequests | 동일한 클라이언트의 다음 데이터그램이 새 세션을 시작하는 데이터그램의 수입니다. proxy_requests 지시문을 참조하세요. 기본값은 0입니다. | int | No |
udpResponses | 클라이언트 데이터그램에 대한 응답으로 Proxy 서버에서 예상되는 데이터그램 수입니다. proxy_responses 지시문을 참조하세요. 기본적으로 데이터그램의 수는 제한되지 않습니다. | int | No |
connectTimeout | Proxy 서버와의 연결을 설정하기 위한 제한 시간입니다. proxy_connect_timeout 지시문을 참조하세요. 기본값은 60초입니다. | string | No |
nextUpstream | Proxy 서버에 대한 연결을 설정할 수 없는 경우 클라이언트 연결을 다음 서버로 전달할지 여부를 결정합니다. proxy_next_upstream 지시문을 참조하세요. 기본값은 true입니다. | bool | No |
nextUpstreamTries | 다음 서버로 연결을 전달하기 위한 시도 횟수입니다. proxy_next_upstream_tries 지시문을 참조하세요. 기본값은 0입니다. | int | No |
nextUpstreamTimeout | 다음 서버로 연결을 전달하는 데 허용되는 시간입니다. proxy_next_upstream_timeout 지시문을 참조하세요. 기본값은 0입니다. | string | No |
2-6. 세션 매개변수
세션 매개변수는 TCP 연결 및 UDP 세션에 대한 다양한 매개변수를 정의합니다.
sessionParameters:
timeout: 50s| Field | 설명 | Type | Required |
|---|---|---|---|
timeout | 클라이언트 또는 Proxy 서버 연결에 대한 두 개의 연속적인 읽기 또는 쓰기 작업 사이의 시간 제한입니다. proxy_timeout 지시문를 참조하십시오. 기본값은 10m입니다. | string | No |
2-7. Action
작업은 클라이언트 connection/datagram에 대해 수행할 작업을 정의합니다.
아래 예에서 클라이언트 connection/datagram은 Upstream dns-app에 전달됩니다.
action:
pass: dns-app| Field | 설명 | Type | Required |
|---|---|---|---|
pass | connection/datagram을 Upstream으로 전달합니다. 해당 이름의 Upstream이 리소스에 정의되어 있어야 합니다. | string | Yes |
3. TransportServer 사용
일반적인 kubectl 명령을 사용하여 Ingress 리소스와 유사한 TransportServer 리소스로 작업할 수 있습니다.
예를 들어 다음 명령은 이름이 secure-app인 transport-server-passthrough.yaml에 정의된 TransportServer 리소스를 생성합니다.
$ kubectl apply -f transport-server-passthrough.yaml
transportserver.k8s.nginx.org/secure-app created다음을 실행하여 리소스를 가져올 수 있습니다.
$ kubectl get transportserver secure-app
NAME AGE
secure-app 46smkubectl get 및 유사한 명령에서 transportserver 대신 짧은 이름 ts를 사용할 수도 있습니다.
3-1. Snippet 사용
Snippet 을 사용하면 Raw NGINX 구성을 다른 NGINX 구성 지시문에 삽입할 수 있습니다. 아래 예에서는 Snippet 을 사용하여 TransportServer에서 액세스 제어를 구성합니다.
apiVersion: k8s.nginx.org/v1alpha1
kind: TransportServer
metadata:
name: cafe
spec:
host: cafe.example.com
serverSnippets: |
deny 192.168.1.1;
allow 192.168.1.0/24;
upstreams:
- name: tea
service: tea-svc
port: 80Snippet은 Stream에 대해 지정할 수도 있습니다. 아래 예에서는 Snippet을 사용하여 연결 수를 제한합니다.
apiVersion: k8s.nginx.org/v1alpha1
kind: TransportServer
metadata:
name: cafe
spec:
host: cafe.example.com
streamSnippets: limit_conn_zone $binary_remote_addr zone=addr:10m;
serverSnippets: limit_conn addr 1;
upstreams:
- name: tea
service: tea-svc
port: 80Snippet은 생성된 NGINX 구성에 대해 더 많은 제어가 필요한 고급 NGINX 사용자가 사용하기 위한 것입니다.
그러나 아래에 설명된 단점 때문에 Snippet은 기본적으로 비활성화되어 있습니다. Snippet을 사용하려면 enable-snippets Command-Line Argument를 설정합니다.
Snippet 사용의 단점:
- 복잡성. Snippet을 사용하려면 다음을 수행해야 합니다.
- NGINX 구성 기본 요소를 이해하고 올바른 NGINX 구성을 구현합니다.
- Snippet이 구성의 다른 기능을 방해하지 않도록 IC가 NGINX 구성을 생성하는 방법을 이해합니다.
- 견고성 감소. 잘못된 Snippet은 NGINX 구성을 무효화하여 Reload에 실패하게 합니다. 이렇게 하면 Snippet이 수정될 때까지 다른 TransportServer 리소스에 대한 업데이트를 포함하여 새로운 구성 업데이트가 방지됩니다.
- 보안에 영향을 미칩니다. Snippet은 NGINX 구성 기본 요소에 액세스할 수 있으며 이러한 기본 요소는 Ingress Controller에서 검증되지 않습니다.
Note: NGINX 구성에 잘못된 Snippet이 포함된 기간 동안 NGINX는 유효한 최신 구성으로 계속 작동합니다.
Note: Stream 지시문에서 Snippet을 구성하려면 stream-snippets ConfigMap Key를 사용하십시오.
3-2. 검증
TransportServer 리소스에 대해 두 가지 유형의 유효성 검사를 사용할 수 있습니다.
kubectl및 Kubernetes API 서버에 의한 구조 검증.- Ingress Controller에 의한 포괄적인 검증.
3-2-1. 구조 검증
TransportServer에 대한 사용자 정의 리소스 정의에는 리소스의 모든 필드 유형을 설명하는 구조적 OpenAPI 스키마가 포함됩니다.
구조적 스키마를 위반하는 리소스를 생성(또는 업데이트)하려고 하면(예: Upstream의 포트 필드에 문자열 값 사용) kubectl 및 Kubernetes API 서버는 이러한 리소스를 거부합니다.
kubectl 유효성 검사의 예:
$ kubectl apply -f transport-server-passthrough.yaml
error: error validating "transport-server-passthrough.yaml": error validating data: ValidationError(TransportServer.spec.upstreams[0].port): invalid type for org.nginx.k8s.v1alpha1.TransportServer.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 transport-server-passthrough.yaml --validate=false
The TransportServer "secure-app" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list:
spec.upstreams.port in body must be of type integer: "string"리소스가 거부되지 않으면(구조적 스키마를 위반하지 않음) Ingress Controller가 추가로 유효성을 검사합니다.
3-2-2. 포괄적 검증
Ingress Controller는 TransportServer 리소스의 필드를 검증합니다. 리소스가 유효하지 않은 경우 Ingress Controller는 리소스를 거부합니다. 리소스는 클러스터에 계속 존재하지만 Ingress Controller는 이를 무시합니다.
Ingress Controller가 TransportServer에 대한 구성을 성공적으로 적용했는지 확인할 수 있습니다. 예제 secure-app TransportServer의 경우 다음을 실행할 수 있습니다.
$ kubectl describe ts secure-app
. . .
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 3s nginx-ingress-controller Configuration for default/secure-app was added or updated구성이 성공적으로 적용되었음을 알리는 AddedOrUpdated 이유가 있는 Normal 이벤트가 이벤트 섹션에 어떻게 포함되어 있는지 확인하십시오.
잘못된 리소스를 생성하면 Ingress Controller가 이를 거부하고 Rejected 이벤트를 내보냅니다. 예를 들어, 존재하지 않는 Upstream을 참조하는 패스 작업으로 TransportServer secure-app을 생성하면 다음을 얻게 됩니다.
$ kubectl describe ts secure-app
. . .
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning Rejected 2s nginx-ingress-controller TransportServer default/secure-app is invalid and was rejected: spec.action.pass: Not found: "some-app"이벤트 섹션에 Rejected 이유가 있는 경고 이벤트가 어떻게 포함되어 있는지 확인하십시오.
참고: 기존 리소스를 유효하지 않게 만들면 Ingress Controller는 이를 거부하고 NGINX에서 해당 구성을 제거합니다.
4. ConfigMap을 통한 사용자 정의
ConfigMap Key(stream-snippets, stream-log-format, resolver-addresses, resolver-ipv6, resolver-valid 및 resolver-timeout 제외)는 TransportServer 리소스에 영향을 주지 않습니다.
