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가 재시작될 때마다 보고됩니다.

목차

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는 두 개의 Kubernetes Secrets로 저장됩니다: NGINX Plus 컨테이너 이미지 다운로드용과 NGINX Plus 실행용.

Note:

시스템과 데이터의 보안을 위해 JSON Wev Tokens (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

Kubernetes의 docker-registry 타입의 secret을 JWT의 내용을 username으로, none을 password로 사용하여 생성합니다. 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 토큰 파일이 아니라, 토큰의 내용이 들어가야 한다는 것을 명심하세요. JWT의 내용을 복사할 때, 공백과 같은 추가 문자가 들어가지 않도록 주의하세요. 토큰이 무효가 되어 레지스트리 인증 중 401 에러가 발생할 수 있습니다.

NGINX Gateway Fabric 설치 시 Secret의 이름을 설정합니다:

  • Helm

Secret 이름을 serviceAccount.imagePullSecret 혹은 serviceAccount.imagePullSecrets helm 값으로 지정합니다.

  • Manifests

nginx-gateway ServiceAccount의 imagePullSecrets 필드를 Secret 이름으로 지정합니다.

1-3. NGINX Plus Secret

JWT를 license.jwt 이름으로 변경합니다. Kubernetes Secret을 JWT 파일을 통해 생성합니다.

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

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

JWT 파일의 업데이트가 필요할 경우, kubectl edit 명령어를 사용하여 license.jwt 필드를 수정하여 변경 사항을 반영하세요.

기본 이름인 nplus-license가 아닌 다른 이름을 사용할 경우, 해당 Secret의 이름을 NGINX Gateway Fabric 설치 시 설정합니다:

  • Helm

Secret 이름을 nginx.usage.secretName helm 값으로 지정합니다

  • Manifests

nginx-gateway 컨테이너의 --usage-report-secret 명령줄 플래그에 Secret 이름을 지정합니다.

Secret을 nginx 컨테이너에 마운트하기 위해 적절한 볼륨 마운트를 정의해야 합니다. 구성하지 않았다면, 다음 볼륨을 Deployment에 추가합니다.

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

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

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

기본 라이선싱 엔드포인트로 보고하는 경우, 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 값에 엔드포인트를 지정합니다.

  • Manifests

nginx-gateway 컨테이너의 --usage-report-secret 명령줄 플래그에 Secret 이름을 지정합니다. 추가로 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 값에 CA Secret을 지정합니다. nginx.usage.clientSSLSecretName helm 값에 클라이언트 Secret 이름을 지정합니다.

  • Manifests

nginx-gateway 컨테이너의 --usage-report-ca-secret 명령줄 플래그에 CA Secret 이름을 지정합니다. nginx-gateway 컨테이너의 --usage-report-client-ssl-secret 명령줄 플래그에 클라이언트 Secret 이름을 지정합니다.

Secret을 nginx 컨테이너에 마운트하기 위해 적절한 볼륨 마운트를 정의해야 합니다. 다음 볼륨을 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;

Secret들과 설정 옵션 구성이 완료되면, NGINX Gateway Fabric 설치를 진행하셔도 좋습니다.

2. 사용 보고 구성을 위한 설치 플래그

NGINX Gateway Fabric 설치 중 다음 플래그를 사용하여 요구사항에 맞는 사용 보고를 구성할 수 있습니다.

Helm을 사용할 경우 nginx.usage 값은 필수적으로 설정되어야 합니다.

  • secretName은 생성한 JWT Secret의 이름으로 설정해야 합니다. 기본적으로 해당 필드는 nplus-license로 설정되어 있습니다. 이 필드는 필수입니다.
  • endpoint는 원격 측정 데이터를 전송할 엔드포인트입니다. 이 옵션은 선택 사항이며, 기본값은 product.connect.nginx.com입니다.
  • resolver는 NGINX Plus 사용 리포트 엔드포인트 질의에 사용하는 네임서버입니다. 이 옵션은 선택 사항이며, 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)와 동일한 네임스페이스에 존재해야 합니다.

Manifests를 사용할 경우 다음 명령줄 옵션을 nginx-gateway 컨테이너에 필요에 따라 구성되어야 합니다.

  • --usage-report-secret는 생성한 JWT Secet의 이름으로 설정해야 합니다. NGINX Gateway Fabric control plane이 실행되는 네임스페이스(기본: nginx-gateway)와 동일한 네임스페이스에 존재해야 합니다. 이 필드의 기본값은 nplus-license입니다. 설치를 위해 이 시크릿의 볼륨 마운트가 필요합니다.
  • --usage-report-endpoint는 원격 측정 데이터를 전송할 엔드포인트입니다. 이 옵션은 선택 사항이며, 기본값은 product.connect.nginx.com입니다. 지정된 경우 추가 설정이 필요합니다.
  • --usage-report-resolver는 NGINX Plus 사용 리포트 엔드포인트 질의에 사용하는 네임서버입니다. 이 옵션은 선택 사항이며, 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 인스턴스의 UUID(범용 고유 식별자)
  • 트래픽 데이터:
    • 클라이언트로부터 수신/전송한 바이트: 클라이언트와 NGINX Plus 사이의 HTTP, stream 트래픽 크기
    • 업스트림으로부터 수신/전송한 바이트: NGINX Plus와 업스트림 서버 사이의 HTTP, stream 트래픽 크기
    • 클라이언트 연결: 승인된 클라이언트의 연결 수(HTTP, stream 트래픽)
    • 처리된 요청: 처리된 HTTP 요청의 총수
  • NGINX 업타임: 업타임 중 reload 및 worker 연결 횟수
  • 사용 보고 타임스탬프: 각 사용 보고의 시작 시각과 끝난 시간
  • Kubernetes 노드 세부 정보: Kubernetes 노드들의 정보
보고된 데이터의 보안 및 개인정보 보호

NGINX Plus, 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.5.1

성공적으로 이미지를 pull 했다면 필요에 따라 tag를 지정하고, 다른 컨테이너 레지스트리로 push 합니다.

5. 기타 설치 옵션

NGINX Gateway Fabric 의 NGINX Plus 이미지를 얻는 대안이 있습니다:

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

* indicates required