NGINX Gateway Fabric NGINX Plus JWT 구성 가이드

NGINX Plus 로 구성된 NGINX Gateway Fabric 은 F5 레지스트리에서 컨테이너 이미지를 다운받기 위해 유효한 JSON Web Token (JWT)가 필요합니다. 1.5.0 버전부터 이 JWT 토큰은 NGINX Plus 실행에도 필요합니다.

이 요구 사항은 F5의 라이선스 프로그램 중 일부이며 업계 모범 사례와 일치합니다. JWT는 구독 갱신 및 사용량 보고를 간소화하여 NGINX Plus 구독 관리를 더욱 효율적으로 할 수 있도록 도와줍니다. 수집한 원격 측정 데이터는 사용자의 요구를 충족하기 위한 제품 및 서비스 개선에 도움이 됩니다.

JWT는 구독과 보고되는 원격 측정 데이터 검증에 필요합니다.인터넷에 연결된 환경의 경우, 원격 측정 데이터는 자동으로 F5의 라이선싱 엔드포인트로 전송됩니다. 오프라인 환경에서는 원격 측정 데이터가 NGINX Instance Manager를 통해 라우팅 됩니다. 사용량은 매 시간마다, 혹은 NGINX가 reload 될 때마다 보고됩니다.

목차

1. JWT 설정
 1-1. MyF5에서 JWT 다운로드
 1-2. Docker 레지스트리 Secret
 1-3. NGINX Plus Secret
 1-4. NGINX Instance Manager로 리포팅
2. 사용량 보고 설정을 위한 설치 플래그
3. 리포팅되는 내용과 보호되는 방법
4. 로컬 사용을 위한 이미지 pull
5. 다른 설치 옵션

1. JWT 설정

JWT는 NGINX Gateway Fabric이 배포되기 전에 설정되어야 합니다. JWT는 2개의 Kubernetes secrets에 저장됩니다: 하나는 NGINX Plus 컨테이너 이미지를 다운로드 하기 위해, 나머지 하나는 NGINX Plus 실행을 위해.

Note:

보안을 위해, JSON Web Token(JWTS), 비밀번호, 쉘 히스토리를 사용할 때 다음 지침을 따르세요.

1. JWTs: JWTs는 민감한 정보입니다. 안전하게 보관하세요. 무단 사용을 방지하기 위해 사용한 후 삭제하세요.
2. 쉘 히스토리: JWTs 혹은 비밀번호를 포함하는 명령어는 당신의 쉘 히스토리에 평문으로 기록됩니다. 해당 명령어들을 사용한 후 쉘 히스토리를 지우세요. 예를 들어, bash를 사용한다면, ~/.bash_history 파일의 명령어를 삭제합니다. 또는 history -c 명령어를 사용하여 쉘 히스토리를 지울 수 있습니다.

이러한 지침을 따라 시스템과 데이터의 보안을 보장하세요.
1-1. MyF5에서 JWT 다운로드
  1. MyF5에 로그인합니다.
  2. My Products & Plans > Subscriptions 으로 이동해 활성화된 구독을 확인합니다.
  3. NGINX 제품 혹은 서비스 구독을 찾아 Subscription ID를 선택해 자세한 내용을 확인합니다.
  4. 구독 페이지에서 JSON Web Token (JWT)를 다운로드합니다.

Note:

Connectivity Stack for Kubernetes JWT는 NGINX Plus 리포팅에 사용되지 않습니다. 일반 NGINX Plus 인스턴스 JWT를 사용해야 합니다.
1-2. Docker 레지스트리 Secret

Note:

NGINX Plus 이미지를 pull하고 프라이빗 레지스트리에 push하는 대신, 이 과정을 생략하고 다음 과정을 따를 수 있습니다.

nginx-gateway 네임스페이스가 아직 존재하지 않는다면 생성합니다.

$ kubectl create namespace nginx-gateway

username 값은 JWT의 내용, password는 none으로 설정하여 Kubernetes의 docker-registry 타입의 secret을 생성합니다. Docker 서버의 이름은 private-registry.nginx.com 입니다.

$ kubectl create secret docker-registry nginx-plus-registry-secret --docker-server=private-registry.nginx.com --docker-username=<JWT Token> --docker-password=none -n nginx-gateway

--docker-username=<JWT Token>에는 토큰 자체를 명시하는게 아닌, 토큰의 값(내용)을 명시하는것이 중요합니다. JWT의 내용을 복사할 때 공백과 같은 추가 문자가 없는지 확인하세요. 추가 문자가 포함되면 토큰이 무효화되어 레지스트리에 인증할 때 401 에러가 발생할 수 있습니다.

NGINX Gateway Fabric을 설치할 때 secret의 이름을 제공하세요.

  • Helm: serviceAccount.imagePullSecret 혹은 serviceAccount.imagePullSecrets helm value에 secret 이름을 명시합니다.
  • Manifests: nginx-gateway ServiceAccount의 imagePullSecrets 필드에 secret 이름을 명시합니다.
1-3. NGINX Plus Secret

license.jwt 파일에 JWT를 넣습니다. JWT 파일의 내용으로 Kubernetes secret을 생성합니다.

$ kubectl create secret generic nplus-license --from-file license.jwt -n nginx-gateway

이제 license.jwt 파일을 삭제해도 됩니다.

JWT를 업데이트 해야 할 경우 kubectl edit 명령어를 사용해 secret의 license.jwt 필드를 업데이트하여 변경 사항을 반영합니다.

기본 이름인 nplus-license가 아닌 다른 이름을 사용할 경우, NGINX Gateway Fabric을 설치할 때 해당 secret의 이름을 제공하세요.

  • Helm

nginx.usage.secretName helm value에 secret 이름을 명시합니다.

  • Manifests

 nginx-gateway 컨테이너의 --usage-report-secret 커맨드라인 플래그에 secret 이름을 명시합니다.

nginx 컨테이너에 secret을 마운트하기 위해 볼륨 마운트를 정의해야 합니다. 아직 정의하지 않았다면 Deployment에 다음 볼륨을 추가합니다.

- name: nginx-plus-license
  secret:
    secretName: nplus-license

 nginx 컨테이너에 다음 볼륨 마운트를 추가합니다.

- mountPath: /etc/nginx/license.jwt
  name: nginx-plus-license
  subPath: license.jwt

Note:

기본 라이선싱 엔드포인트로 리포팅을 할 경우, 이제 NGINX Gateway Fabric을 설치해도 됩니다. 그렇지 않으면 아래 단계를 따라 NGINX Instance Manager로 리포팅을 하도록 설정합니다.
1-4. NGINX Instance Manager로 리포팅

NGINX Gateway Fabric을 기본 라이선싱 엔드포인트가 아닌 NGINX Instance Manager로 리포팅을 해야하는 환경에 배포하는 경우, 다음 추가 단계가 필요합니다.

먼저, NGINX Instance Manager의 엔드포인트를 명시해야 합니다.

  • Helm: nginx.usage.endpoint helm value에 엔드포인트를 명시합니다.
  • Manifests: nginx-gateway 컨테이너의 --usage-report-endpoint 커맨드라인 플래그에 엔드포인트를 명시합니다. 추가로 nginx-includes-bootstrap ConfigMap의 mgmt 블록에 다음 내용을 추가해야 합니다.
usage_report endpoint=<your-endpoint>;
CA와 클라이언트 인증서/키

CA인증서 및/또는 클라이언트 인증서와 키를 구성하기 위해 몇 가지 추가 단계가 필요합니다.

먼저 nginx-gateway 네임스페이스에 2개의 secret을 생성해야 합니다. CA는 ca.crt 키에 구성되어야 합니다.

$ kubectl -n nginx-gateway create secret generic nim-ca --from-file ca.crt

클라이언트 인증서와 키는 TLS secret에 추가되어야 합니다.

$ kubectl -n nginx-gateway create secret tls nim-client --cert /path/to/cert --key /path/to/key
  • Helm

nginx.usage.caSecretName helm value에 CA secret 이름을 명시합니다. nginx.usage.clientSSLSecretName helm value에 클라이언트 secret 이름을 명시합니다.

  • Manifests

nginx-gateway 컨테이너의 --usage-report-ca-secret 커맨드라인 플래그에 CA secret 이름을 명시합니다. nginx-gateway 컨테이너의 --usage-report-client-ssl-secret 커맨드라인 플래그에 클라이언트 secret 이름을 명시합니다.

nginx 컨테이너에 secret을 마운트하기 위해 볼륨 마운트를 정의해야 합니다. Deployment에 다음 볼륨을 추가합니다.

- name: nginx-plus-usage-certs
  projected:
    sources:
      - secret:
          name: nim-ca
      - secret:
          name: nim-client

 nginx 컨테이너에 다음 볼륨 마운트를 추가합니다.

- mountPath: /etc/nginx/certs-bootstrap/
  name: nginx-plus-usage-certs

마지막으로, nginx-includes-bootstrap ConfigMap의 mgmt 블록에 다음 내용을 추가합니다.

ssl_trusted_certificate /etc/nginx/certs-bootstrap/ca.crt;
ssl_certificate        /etc/nginx/certs-bootstrap/tls.crt;
ssl_certificate_key    /etc/nginx/certs-bootstrap/tls.key;

Note:

Secrets가 생성되고 설정 옵션이 구성되면, 이제 NGINX Gateway Fabric을 설치해도 좋습니다.

2. 사용량 보고 설정을 위한 설치 플래그

NGINX Gateway Fabric을 설치할 때 다음 플래그를 사용하여 필요에 맞게 사용량 보고를 설정할 수 있습니다.

Helm을 사용할 경우, nginx.usage 값을 필요에 따라 설정합니다:

  • secretName은 생성한 JWT secret의 이름으로 지정되어야 합니다. 기본적으로 이 필드는 nplus-license로 설정되어 있습니다. 이 필드는 필수입니다.
  • endpoint는 원격 측정 데이터를 전송할 엔드포인트입니다. 기본적으로 이 필드는 product.connect.nginx.com로 설정되어 있습니다. 이 필드는 선택 필드입니다.
  • resolver는 NGINX Plus 사용량 리포팅 엔드포인트를 resolve 하는 데 사용하는 네임 서버입니다. 이 필드는 선택 필드이며 NGINX Instance Manager와 함께 사용됩니다.
  • skipVerify는 NGINX Plus 사용량 리포팅 서버 인증서의 클라이언트 검증을 비활성화 합니다.
  • caSecretName는 NGINX Instance Manager CA 인증서를 포함하는 secret의 이름입니다. NGINX Gateway Fabric control plane이 실행중인 네임스페이스(기본: nginx-gateway)와 동일한 네임스페이스에 존재해야 합니다.
  • clientSSLSecretName는 NGINX Instance Manager와의 인증을 위한 클라이언트 인증서와 키가 포함된 secret의 이름입니다. NGINX Gateway Fabric control plane이 실행중인 네임스페이스(기본: nginx-gateway)와 동일한 네임스페이스에 존재해야 합니다.

Manifest를 사용할 경우, nginx-gateway 컨테이너의 다음 커맨드라인 옵션을 필요에 따라 설정합니다:

  • --usage-report-secret은 생성한 JWT secret의 이름으로 지정되어야 합니다. NGINX Gateway Fabric control plane이 실행중인 네임스페이스(기본: nginx-gateway)와 동일한 네임스페이스에 존재해야 합니다. 기본적으로 이 필드는 nplus-license로 설정되어 있습니다. 설치를 위해 이 secret의 볼륨 마운트가 필요합니다.
  • --usage-report-endpoint는 원격 측정 데이터를 전송할 엔드포인트입니다. 이 옵션은 선택 옵션이며 기본값은 product.connect.nginx.com 입니다. 구성된 경우 추가 설정이 필요합니다.
  • --usage-report-resolver는 NGINX Plus 사용량 리포팅 엔드포인트를 resolve 하는 데 사용하는 네임 서버입니다. 이 옵션은 선택 옵션이며 NGINX Instance Manager와 함께 사용됩니다.
  • --usage-report-skip-verify는 NGINX Plus 사용량 리포팅 서버 인증서의 클라이언트 검증을 비활성화 합니다.
  • --usage-report-ca-secret은 NGINX Instance Manager CA 인증서를 포함하는 secret의 이름입니다. NGINX Gateway Fabric control plane이 실행중인 네임스페이스(기본: nginx-gateway)와 동일한 네임스페이스에 존재해야 합니다. 구성된 경우 추가 설정이 필요합니다.
  • --usage-report-client-ssl-secret은 NGINX Instance Manager와의 인증을 위한 클라이언트 인증서와 키가 포함된 secret의 이름입니다. NGINX Gateway Fabric control plane이 실행중인 네임스페이스(기본: nginx-gateway)와 동일한 네임스페이스에 존재해야 합니다. 구성된 경우 추가 설정이 필요합니다.

3. 리포팅되는 내용과 보호되는 방법

NGINX Plus는 기본적으로 매 시간마다 다음 데이터를 리포트합니다:

  • NGINX 버전과 상태: 인스턴스에서 실행중인 NGINX Plus 버전.
  • 인스턴스 UUID: 각 NGINX Plus 인스턴스의 고유 식별자.
  • 트래픽 데이터:
    • 클라이언트로부터 수신/송신한 Byte: 클라이언트와 NGINX Plus 사이의 HTTP/stream 트래픽량.
    • 업스트림으로부터 수신/송신한 Byte: NGINX Plus와 업스트림 사이의 HTTP/stream 트래픽량.
    • 클라이언트 연결: 수락된 클라이언트의 연결 수(HTTP/stream 트래픽).
    • 처리된 요청: 처리한 HTTP 요청의 총 량.
  • NGINX 가동 시간: 가동 시간 동안의 리로드 횟수와 워커 연결 수.
  • 사용량 리포트 타임스탬프: 각 사용량 리포트의 시작 및 종료 시간.
  • Kubernetes 노드 정보: Kubernetes 노드와 관련된 정보.
보고되는 데이터의 보안 및 개인 정보

NGINX Plus instances, NGINX Instance Manager, 그리고 F5의 라이선싱 엔드포인트(product.connect.nginx.com) 사이의 모든 통신은 SSL/TLS 암호화로 보호됩니다.

개인 식별 정보(PII)혹은 민감한 고객 정보는 전송되지 않고, 운영 지표만이 보고됩니다.

4. 로컬 사용을 위한 이미지 pull

로컬 사용을 위한 이미지를 pull 하기 위해 다음 명령어를 사용합니다.

$ docker login private-registry.nginx.com --username=<JWT Token> --password=none

<JWT Token>은 JWT 토큰의 내용물로 변경합니다.

그리고 이미지를 pull 할 수 있습니다.

$ docker pull private-registry.nginx.com/nginx-gateway-fabric/nginx-plus:1.6.2

성공적으로 이미지를 pull 했다면 필요에 따라 태그를 적용하고, 다른 컨테이너 레지스트리로 push 할 수 있습니다.

5. 다른 설치 옵션

NGINX Gateway Fabric을 위한 NGINX Plus 이미지를 얻는 다른 방법이 있습니다.

NGINX STORE를 통한 솔루션 도입 및 기술지원 무료 상담 신청

* indicates required