수신

NCP는 TLS 규격을 사용하는 수신에 대해 하나의 계층 -7 로드 밸런서를 생성하고 TLS 규격을 사용하지 않는 수신에 대해 하나의 계층 -7 로드 밸런서를 생성합니다. CRD(CustomResourceDefinition)를 생성하여 수신 크기 조정을 처리할 수도 있습니다.

다음에 유의하십시오.

모든 수신에는 단일 IP 주소가 할당됩니다.
수신 리소스에는 ncp.ini의 [nsx_v3] 섹션에 있는 external_ip_pools 옵션에서 지정한 외부 IP 풀의 IP 주소가 할당됩니다. 로드 밸런서는 이 IP 주소와 HTTP 및 HTTPS 포트(80 및 443)를 사용합니다.
수신 리소스에는 ncp.ini의 [nsx_v3] 섹션에 있는 external_ip_pools_lb 옵션에서 지정한 외부 IP 풀의 IP 주소가 할당됩니다. external_ip_pools_lb 옵션이 없는 경우 external_ip_pools에서 지정한 풀이 사용됩니다. 로드 밸런서는 이 IP 주소와 HTTP 및 HTTPS 포트(80 및 443)를 사용합니다.
구성을 변경하고 NCP를 다시 시작하여 다른 IP 풀로 변경할 수 있습니다.
TLS에 대해 기본 인증서를 지정할 수 있습니다. 인증서를 생성하고 NCP 포드에 마운트하는 데 대한 내용은 아래를 참조하십시오.
TLS 규격을 사용하지 않는 수신은 HTTP 가상 서버(포트 80)에서 호스팅됩니다.
TLS 규격을 사용하는 수신은 HTTPS 가상 서버(포트 443)에서 호스팅됩니다. 로드 밸런서는 SSL 서버 역할을 하며 클라이언트 SSL 연결을 종료합니다.
TLS 섹션을 추가하거나 제거하여 수신을 수정하는 작업이 지원됩니다. 수신 규격에서 tls 키가 제거되면 HTTPS 가상 서버(포트 443)에서 HTTP 가상 서버(포트 80)로 수신 규칙이 전송됩니다. 마찬가지로 수신 규격에 tls 키가 추가되면 HTTP 가상 서버(포트 80)에서 HTTPS 가상 서버(포트 443)로 수신 규칙이 전송됩니다.
단일 클러스터에 대한 수신 정의에 중복된 규칙이 있는 경우 첫 번째 규칙만 적용됩니다. 중복 규칙이 있는 다른 수신에서 오류가 주석으로 추가됩니다. 예를 들어 동일한 host 및 path를 사용하는 두 개의 수신을 생성하며, 한 수신은 TLS이고 다른 수신은 TLS가 아니고, kubernetes.io/ingress.allow-http가 false이면 두 규칙이 다른 가상 서버에 생성되고 서로 충돌하지 않습니다. 그러나 kubernetes.io/ingress.allow-http가 true이면 나중에 적용되는 수신에 오류가 주석으로 추가됩니다. 자세한 내용은 아래의 “오류” 섹션을 참조하십시오.
각 클러스터당 기본 백엔드가 있는 하나의 수신만 지원됩니다. 수신 규칙과 일치하지 않는 트래픽은 기본 백엔드로 전달됩니다.
기본 백엔드가 있는 수신이 여러 개인 경우 첫 번째 수신만 구성됩니다. 다른 수신에는 오류 주석이 추가됩니다. 자세한 내용은 아래의 “오류” 섹션을 참조하십시오.
규칙은 다음 순서로 적용됩니다.
1. host 및 path가 모두 지정된 규칙
  1. Exact pathType에 해당하는 규칙
  2. Prefix pathType에 해당하는 규칙
  3. Regex pathType에 해당하는 규칙
2. host 또는 path가 지정된 규칙
  1. Exact pathType에 해당하는 규칙
  2. Prefix pathType에 해당하는 규칙
  3. Regex pathType에 해당하는 규칙
참고: 여러 경로가 요청과 일치하는 경우 일치하는 가장 긴 경로에 우선 순위가 지정됩니다.
pathType 정보:
- 이는 Kubernetes 1.19 pathType부터 필수입니다.
- use-regex가 설정된 경우 pathType이 ImplementationSpecific인 경우에만 적용됩니다.
- use-regex가 설정되지 않은 경우 ImplementationSpecific이 Exact와 동일하게 취급됩니다. pathType은 다른 NCP 주석보다 우선 적용됩니다.
- pathType이 서로 다른 두 개의 일치하는 경로가 공존할 수 있습니다.
- Prefix 유형의 경우 /foo는 /foo/bar, /foo/와 일치하지만 /foo 또는 /foobar와는 일치하지 않습니다. /foo를 일치시키려면 수신 규칙에 Exact 경로 /foo를 추가합니다.

호스트 이름 와일드카드

호스트 이름을 지정할 때 정확한 이름(예: abc.example.com)을 지정하거나 와일드카드(예: *.example.com)를 사용할 수 있습니다. 와일드카드는 하나 이상의 DNS 레이블과 일치합니다. 다음 표에는 *.example.com을 지정한 경우에 대한 일치 결과가 표시됩니다.

호스트 헤더	일치 결과
abc.example.com	일치
abc.def.example.com	일치
example.com	일치 항목 없음

(정책 모드를 사용하는 경우에 해당됩니다.) 기본 백엔드를 사용하여 TLS 수신을 생성한 경우에는 다음과 같은 이유로 HTTP 및 HTTPS 요청 모두에 응답하도록 기본 백엔드를 설정하는 것이 좋습니다.
- 요청의 호스트와 일치하는 호스트에서 TLS 수신(Kubernetes/TKGI 사용 사례용 클러스터 또는 Project Pacific 사용 사례용 동일한 네임스페이스)이 있는 경우 로드 밸런서는 TLS를 종료하고 기본 백엔드 서버로 HTTP 요청을 보냅니다.
- 요청의 호스트와 일치하는 호스트에서 TLS 수신(Kubernetes/TKGI 사용 사례용 클러스터 또는 Project Pacific 사용 사례용 동일한 네임스페이스)이 없는 경우 로드 밸런서는 HTTPS 요청을 다시 암호화한 후 백엔드 서버로 보냅니다.
IngressClass 리소스는 지원되지 않습니다.
pathType 특성이 지원됩니다.
JWT(JSON Web Token) 클라이언트 인증이 지원됩니다. 이 기능을 사용하려면 NSX 3.0.0 이상이 필요합니다.

Kubernetes 1.18부터는 kubernetes.io/ingress.class 주석이 사용되지 않으며 IngressClass 리소스로 대체됩니다. IngressClass 리소스에서 NSX를 수신 컨트롤러로 지정하려면 컨트롤러 매개 변수를 k8s.io/nsx로 설정합니다. 예:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nsx-lb
  annotations:
    ingressclass.kubernetes.io/is-default-class: true
spec:
  controller: k8s.io/nsx

타사의 수신 컨트롤러를 지정하려면 컨트롤러 매개 변수를 k8s.io/<controller name>으로 설정합니다. 예:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx-lb
  annotations:
    ingressclass.kubernetes.io/is-default-class: false
spec:
  controller: k8s.io/ingress-nginx

IngressClass를 클러스터에 대한 기본값으로 설정하려면 주석 ingressclass.kubernetes.io/is-default-class를 true로 설정합니다. 위의 예를 참조하십시오.

kubernetes.io/ingress.class 주석과 IngressClass 리소스를 모두 사용하지 말아야 합니다.

Endpoints 개체를 수동으로 구성하는 경우 targetRef 매개 변수를 설정해야 합니다. 이 값은 백엔드 포드의 UID여야 합니다. 예:

apiVersion: networking.k8s.io/v1
kind: Endpoints
metadata:
  name: tea-svc
subsets:
  - addresses:
    - ip: 172.26.0.2
      targetRef:
        uid: 4378e0ae-5837-49c6-a0b2-178dced8eb1e
...

기능 주석

다음 표에는 NCP에서 지원하는 주석이 나와 있습니다.

주석	설명	지원되는 값	기본값
kubernetes.io/ingress.allow-http	HTTPS 외에 HTTP 요청을 사용하도록 설정합니다.	true, false	true
ncp/use-regex	경로 패턴 일치 사용	true, false	false
ingress.kubernetes.io/rewrite-target	수신 요청의 경로를 다시 씁니다.	'/'로 시작하는 경로 정규식에 캡처된 그룹에 대해 번호가 매겨진 자리 표시자가 포함된 경로(예:/$1)	기본값은 없습니다.
ncp/http-redirect	HTTP 요청을 HTTPS로 리디렉션합니다.	true, false	false
kubernetes.io/ingress.class	이 수신을 담당하는 수신 컨트롤러를 나타냅니다.	nsx, nginx 등	nsx
nsx/loadbalancer	수신을 전용 로드 밸런서에 배치합니다.	LoadBalancer CRD의 이름	기본값은 없습니다.
ncp/allowed-source-range	요청 소스 IP의 수신 액세스를 제한합니다.	쉼표로 구분된 CIDR, IP 주소 또는 IP 범위 목록입니다.	기본값은 없습니다.
ncp/ssl-mode	수신의 모든 규칙에 대해 SSL 모드를 선택합니다.	오프로드, 다시 암호화, 패스스루	오프로드
ncp/jwt-alg	JWT 서명의 유효성을 검사하는 데 사용되는 알고리즘을 결정합니다. ncp/JWT 암호를 사용하여 설정한 경우 JWT 클라이언트 인증을 사용하도록 설정합니다.	HS256, RS256	기본값은 없습니다.
ncp/jwt-secret	서명 유효성 검사에 사용되는 JWT 비밀 또는 공용 키가 포함된 Kubernetes 암호의 이름을 지정합니다. ncp/jwt-alg를 사용하여 설정한 경우 JWT 클라이언트 인증을 사용하도록 설정합니다.	Kubernetes 암호의 이름	기본값은 없습니다.
ncp/jwt-token	HTTP 요청에서 JWT를 검색할 추가 위치입니다.	_arg_<param_name>, _cookie_<cookie_name>	기본값은 없습니다.
ncp/jwt-realm	인증이 실패했을 때 401과 함께 반환되는 영역 헤더를 지정합니다.	영역을 나타내는 문자열	수신 규칙의 호스트 이름
ncp/jwt-preserve	JWT를 보존하다가 성공적인 인증 후에 백엔드에 전달하는 옵션입니다.	true, false	true
ncp/connection_multiplexing_enabled	TCP 멀티플렉싱을 사용하도록 설정합니다.	true, false	false
ncp/connection_multiplexing_number	TCP 멀티플렉싱을 사용하도록 설정하면 사용 가능한 유휴 TCP 연결 수가 지정됩니다.	0 - 2147483647	6

주석에 대한 세부 정보:

경로 정규식 일치
- 주석 ncp/use-regex을 사용하여 수신 path(host 아님) 매개 변수의 정규식 일치를 사용하거나 사용하지 않도록 설정할 수 있습니다. false로 설정하면 equals 일치를 수행하여 정확한 경로 일치가 수행됩니다. true로 설정하면 전체 요청 URI가 패턴과 일치하도록 경로에 문자열 문자의 시작(^)과 문자열 문자의 끝($)을 추가하여 정규식 일치가 수행됩니다. OR 연산자(|)를 사용할 때는 항상 괄호로 범위를 지정하여 ^과 $가 모든 피연산자에 적용되도록 합니다. 예를 들면 path: /(tea|coffee|milk)와 같이 입력합니다. 수신 규격 예:
```
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
    kubernetes.io/ingress.class: "nsx"
    #/tea/cup will be served by tea-svc:80
    ncp/use-regex: "True"
spec:
  rules:
  - host: cafe.example.com
    http:
      paths:
      # for this tea and coffee NCP will configure regex rule
      - path: /tea/(.*)
        pathType: ImplementationSpecific
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      - path: /coffee/(.*)
        pathType: ImplementationSpecific
        backend:
          service:
            name: coffee-svc
            port:
              number: 80
      # for juice and alcohol NCP will configure Exact and Prefix rules
      - path: /juice
        pathType: Exact
        backend:
          service:
            name: juice-svc
            port:
              number: 80
      - path: /alcohol
        pathType: Prefix
        backend:
          service:
            name: bar
              number: 80
```
- NCP를 업그레이드하기 전에 수신 업데이트
  ‘.’ 및 ‘*’를 사용하는 모든 하위 경로 일치가 필요한 수신이 있는 경우에만 필요합니다.
  1. 주석 ncp/use-regex: true를 포함하도록 수신을 업데이트합니다.
  2. 모든 하위 경로 일치에 대해 /coffee/* 또는 /*와 같은 경로가 있는 경우 /coffee/.* 및 /.*로 변경합니다.
    /coffee/.*는 /coffee/, /coffee/a, /coffee/b, /coffee/a/b 등을 일치 항목으로 검색합니다. /.*는 /coffee, /tea, /coffee/a 등을 일치 항목으로 검색합니다. 경로를 생략하면 path: /.*와 동일한 동작이 생성됩니다.

주석 ingress.kubernetes.io/rewrite-target의 다음 예제에서 URL이 백엔드 서비스로 전송되기 전에 경로 /tea 및 /coffee가 /로 재작성됩니다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
    ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - host: cafe.example.com
    http:
      paths:
      - path: /tea
        pathType: ImplementationSpecific
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      - path: /coffee
        pathType: ImplementationSpecific
        backend:
          service:
            name: coffee-svc
            port:
              number: 80

정규식을 사용하여 path를 지정하면 캡처된 그룹은 $1, $2 등의 형식으로 번호가 매겨진 자리 표시자에 저장됩니다. 이러한 자리 표시자는 ingress.kubernetes.io/rewrite-target 주석에서 매개 변수로 사용할 수 있습니다. 명명된 캡처 그룹 및 명명된 자리 표시자는 지원되지 않습니다. 예를 들면 다음과 같습니다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
    kubernetes.io/ingress.class: "nsx"
    ncp/use-regex: "true"
    #/tea/cup will be rewritten to /cup before sending request to endpoint
    ingress.kubernetes.io/rewrite-target: /$1
spec:
  rules:
  - host: cafe.example.com
    http:
      paths:
      - path: /tea/(.*)
        pathType: ImplementationSpecific
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      - path: /coffee/(.*)
        pathType: ImplementationSpecific
        backend:
          service:
            name: coffee-svc
            port:
              number: 80

주석 kubernetes.io/ingress.allow-http 정보:
- 주석을 false로 설정하면 HTTPS 가상 서버에 대해 규칙이 생성됩니다.
- 주석을 true로 설정하거나 주석이 누락되면 HTTP 및 HTTPS 가상 서버 둘 다에 대해 규칙이 생성됩니다. 수신 규격에 TLS 섹션이 있는 경우에만 HTTPS 규칙이 생성됩니다.
주석 ncp/http-redirect 정보:
- 주석을 false로 설정하면 HTTP 가상 서버에 대한 수신 HTTP 트래픽(포트 80)이 HTTPS 가상 서버로 리디렉션되지 않습니다.
- 주석을 true로 설정하면 HTTP 가상 서버에 대한 수신 HTTP 트래픽(포트 80)이 HTTPS 가상 서버(포트 443)로 리디렉션됩니다.
이 주석은 TLS 섹션이 있는 경우에만 유효합니다. 이 주석은 kubernetes.io/ingress.allow-http보다 우선적으로 적용됩니다. true로 설정하면 kubernetes.io/ingress.allow-http가 설정된 방식에 관계없이 HTTP 트래픽이 HTTPS와 직접 일치됩니다.
주석 kubernetes.io/ingress.class 정보:
- 값이 nsx인 경우 이 수신은 NCP에서 처리됩니다. 다른 값을 지정하면 수신이 NCP에서 무시됩니다. 자세한 내용은 타사 수신 컨트롤러의 내용을 참조하십시오.
주석 nsx/loadbalancer에 대한 자세한 내용은 수신 크기 조정을 처리하기 위한 LoadBalancer CRD의 내용을 참조하십시오.

주석 ncp/allowed-source-range 정보:

정책 모드에서만 지원됩니다.
설정되면 수신 요청은 해당 소스 Ip가 이 주석에 포함된 경우에만 허용됩니다. 포함되지 않은 경우 트래픽이 삭제됩니다.
CIDR, IP 주소 및 IP 범위의 조합을 지정할 수 있습니다. 예: 1.1.1.1/24, 2.2.2.2, 3.3.3.3-4.4.4.4.

YAML 예:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
    kubernetes.io/ingress.class: "nsx"
    #Source IP addresses allowed to access ingress URL
    ncp/allowed-source-range: "192.168.128.0/17, 192.168.64.0-192.168.64.255, 192.168.16.32"
spec:
  tls:
  - hosts:
    - cafe.example.com
  rules:
  - host: cafe.example.com
    http:
      paths:
      - path: /tea
        pathType: ImplementationSpecific
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      - path: /coffee
        pathType: ImplementationSpecific
        backend:
          service:
            name: coffee-svc
            port:
              number: 80

주석 ncp/ssl-mode 정보:
- 정책 모드에서만 지원됩니다.
- 이 주석은 수신의 모든 규칙에 적용되며, 로드 밸런서는 이러한 규칙에 대해 선택된 SSL 모드에서 작동합니다.
  ncp/ssl-mode가 reencrypt 또는 passthrough로 설정되면 kubernetes.io/ingress.allow-http를 False로 설정해야 합니다. ingress.kubernetes.io/rewrite-target, ncp/use-regex 또는 ncp/allowed-source-range 주석이 설정된 경우 이 주석을 passthrough로 설정할 수 없습니다.
  ncp/ssl-mode를 passthrough로 설정하면 rules 규격의 path 특성이 지원되지 않습니다.
JWT 클라이언트 인증 정보:
- [수신] 아래의 모든 규칙에 대해 JWT 클라이언트 인증을 사용하도록 설정하려면 ncp/jwt-alg 및 ncp/jwt-secret 둘 다를 유효한 값으로 설정해야 합니다. 이 옵션을 사용하도록 설정하면 수신 HTTP 트래픽은 올바른 JSON 웹 토큰이 있는 경우에만 백엔드로 전달됩니다. 그러지 않으면 트래픽이 401 상태로 거부됩니다.
- 이 기능은 다음 주석과 호환되지 않습니다.
  - kubernetes.io/ingress.allow-http: true
  - ncp/http-redirect: true
  - ncp/ssl-mode: passthrough
- ncp/jwt-alg:
  - 지원되는 대칭형 알고리즘: HS256
  - 지원되는 비대칭 알고리즘: RS256
- ncp/jwt-secret:
  - 대칭 키 또는 공용 인증서는 수신과 동일한 네임스페이스에서 이 주석에 지정된 이름을 사용하여 Kubernetes 암호에서 구성해야 합니다.
  - 대칭 알고리즘의 경우 암호를 jwt.key 필드에 저장해야 합니다.
  - 비대칭 알고리즘의 경우 공용 인증서를 tls.crt 필드에 저장해야 합니다.
  - 대칭 암호 또는 공용 인증서가 위에 언급된 위치에 저장되어 있지 않거나 암호에 저장된 데이터가 유효하지 않은 경우 JWT 클라이언트 인증이 사용되지 않도록 설정됩니다.
- ncp/jwt-token:
  - 이 주석에는 하나의 항목만 구성할 수 있습니다.
  - _arg_<param_name>: URI 매개 변수로 전달된 JWT의 경우. JWT가 포함된 매개 변수 이름을 지정합니다.
  - _cookie_<cookie_name>: 쿠키로 변수로 전달된 JWT의 경우 JWT가 포함된 쿠키 이름을 지정합니다.

주석 ncp/connection_multiplxing_enabled 및 ncp/connection_multiplxing_number 정보:

TCP 멀티플렉싱은 HTTP NTLM과 공존할 수 없습니다. NSX에서 TCP 멀티플렉싱을 사용하도록 설정한 로드 밸런서 풀이 NTLM 지원 계층 7 서버에 바인딩된 경우 NTLM 구성이 TCP 멀티플렉싱보다 우선합니다.

YAML 예:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
    ncp/connection_multiplexing_enabled: "true"
    ncp/connection_multiplexing_number: 100
spec:
  tls:
  - hosts:
    - cafe.example.com
  rules:
  - host: cafe.example.com
    http:
      paths:
      - path: /tea
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      - path: /coffee
        backend:
          service:
            name: coffee-svc
            port:
              number: 80

오류

오류는 수신 리소스에 주석으로 추가됩니다. 오류 키는 ncp/error.loadbalancer이고 주의 키는 ncp/warning.loadbalancer입니다. 다음과 같은 오류 및 주의가 발생할 수 있습니다.

ncp/error.loadbalancer: DEFAULT_BACKEND_IN_USE
이 오류는 기본 백엔드가 있는 수신이 이미 있음을 나타냅니다. 이 경우 수신은 비활성 상태입니다. (1) 이 수신이 HTTP에 대한 것이고 기본 백엔드가 있는 HTTP에 대해 다른 수신이 존재하는 경우, (2) 이 수신이 HTTPS에 대한 것이고 기본 백엔드가 있는 HTTPS에 대해 다른 수신이 존재하는 경우, 또는 (3) 이 수신이 HTTP 및 HTTPS에 대한 것이고 기본 백엔드가 있는 HTTP 및 HTTPS에 대해 다른 수신이 존재하는 경우 이 오류가 발생합니다. 이 오류를 해결하려면 수신을 삭제한 후 올바른 규격을 사용하여 다시 생성하십시오.
ncp/warning.loadbalancer: SECRET_NOT_FOUND
이 오류는 수신 규격에 지정된 암호가 존재하지 않거나 ncp/jwt-alg 및 ncp/jwt-secret가 주석으로 처리되었지만 해당 암호를 수신과 동일한 네임스페이스에서 찾을 수 없음을 나타냅니다. 이 경우 수신은 부분적으로 활성 상태입니다. 이 오류를 해결하려면 누락된 암호를 생성하십시오. 참고로 주석에 주의가 있으면 해당 주의는 수신 리소스의 수명주기 동안 지워지지 않습니다.
ncp/warning.loadbalancer: INVALID_INGRESS
이 오류는 다음 조건 중 하나가 true임을 나타냅니다. 이 경우 수신은 비활성 상태입니다. 이 오류를 해결하려면 수신을 삭제한 후 올바른 규격을 사용하여 다시 생성하십시오.
- 수신 규칙이 동일한 Kubernetes 클러스터의 다른 수신 규칙과 충돌합니다. 동일한 일치 전략, 즉 동일한 ncp/use-regex 주석 값을 갖는 수신에 대해서만 충돌이 확인됩니다.
- kubernetes.io/ingress.allow-http 주석이 false로 설정되고 수신에 TLS 섹션이 포함되지 않습니다.
- ncp/http-redirect 주석이 true로 설정되고 수신에 TLS 섹션이 포함되지 않습니다.
- 수신 규칙에 host 및 path가 지정되어 있지 않습니다. 이러한 수신 규칙에 수신 기본 백엔드와 동일한 기능이 있습니다. 대신 수신 기본 백엔드를 사용합니다.
- 수신에 올바르게 처리할 수 없는 JWL 주석이 있습니다. 예:
  - ncp/jwt-alg 또는 ncp/jwt-secret가 누락되었습니다.
  - ncp/jwt-alg가 지원되지 않는 알고리즘으로 구성되어 있습니다.
  - ncp/jwt-alg 및 ncp/jwt-secret가 다른 HTTP 지원 주석과 SSL 통과를 사용하여 구성됩니다.