NGINX Gateway Fabric 설치
이 문서는 Kubernetes manifests를 활용하여 NGINX Gateway Fabric 을 설치, 업그레이드, 삭제하는 방법에 관해서 설명합니다.
중요:
버전 1.4.0에서 1.5.x로 업그레이드하는 NGINX Plus 사용자는 NGINX Plus JWT Secret을 업그레이드 전에 생성해야 합니다. 사전 구성 섹션의 과정을 따라 최신 버전의 deployment manifest가 참조하는 Secret을 생성하세요.
목차
1. NGINX Gateway Fabric 설치 사전 구성
1-1. NGINX Plus JWT 설정
2. NGINX Gateway Fabric 설치
3. NGINX Gateway Fabric 업그레이드
4. 무중단 업그레이드를 위한 Pod 종료 지연
5. NGINX Gateway Fabric 삭제
1. NGINX Gateway Fabric 설치 사전 구성
이 가이드를 진행하기 위해, kubectl 설치가 필요합니다.
중요:
NGINX Plus를 사용하려면 추가적인 설정이 필요합니다.
1-1. NGINX Plus JWT 설정
Note:
시스템과 데이터의 보안을 위해 JSON Wev Tokens (JWTs), 비밀번호, 셸 히스토리에 대한 다음 과정을 따르세요.
1. JWTs: JWTs는 민감한 정보입니다. 안전하게 보관하세요. 인증되지 않은 접근을 방지하기 위해 사용 후 삭제하세요.
2. 셸 히스토리: JWTs 혹은 비밀번호가 포함된 명령어는 셸 히스토리에 평문으로 기록됩니다. 해당 명령어를 사용한 후 셀 히스토리를 정리하세요. 예를 들어, bash를 사용하는 경우,~/.bash_history파일의 명령어들을 삭제할 수 있습니다. 아니면history -c명령어를 사용해 셀 히스토리의 명령어들을 삭제할 수 있습니다.
1. MyF5에서 JWT 다운로드
- MyF5에 로그인합니다.
- My Products & Plans > Subscriptions로 이동해 활성화된 구독을 확인합니다.
- NGINX 제품 혹은 서비스 구독의 Subscription ID를 선택하여 세부 사항을 확인합니다.
- 구독 페이지에서 JSON Web Token (JWT) 파일을 다운로드합니다.
Note:
Connectivity Stack for Kubernetes JWT는 NGINX Plus 리포트에 사용할 수 없습니다. 일반 NGINX Plus 인스턴스 JWT를 사용해야 합니다.
2. Docker 레지스트리 Secret 생성
Note:
NGINX Plus 이미지를 pull하고 개인 레지스트리에 push하려면, 이 과정을 건너뛰고 링크의 과정을 따르세요.
nginx-gateway 네임스페이스가 존재하지 않는다면, 생성합니다.
$ kubectl create namespace nginx-gatewayKubernetes의 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 에러가 발생할 수 있습니다.
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 필드를 수정하여 변경 사항을 반영하세요.
Note:
이 과정이 필요한 이유, NGINX Instance Manager로 리포트 대신 전송 방법과 같은 추가적인 설정 옵션 등의 더 많은 정보는 NGINX Plus Image and JWT Requirement 문서를 참고하세요.
2. NGINX Gateway Fabric 설치
Kubernetes manifests를 활용하여 NGINX Gateway Fabric을 배포하는 것은 몇 단계만 거치면 됩니다. Manifests를 활용하면 deployment를 정확히 원하는 대로 설정할 수 있습니다. Manifests는 다양한 환경/클러스터에 deployment를 손쉽게 복제하여 일관성을 유지할 수 있습니다.
1. Gateway API 리소스 설치
Note:
NGINX Gateway Fabric를 설치 하기 전에 표준 채널에서 제공되는 Gateway API 리소스를 설치해야 합니다. 이미 클러스터에 설치된 경우, NGINX Gateway Fabric이 지원하는 올바른 버전인지 확인하세요. – 기술 사양을 확인하세요.
Gateway API 리소스 설치를 위해 다음 명령어를 사용합니다.
$ kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.5.1" | kubectl apply -f -Note:
edge버전의 NGINX Gateway Fabric을 사용하려면,ref의 버전을main으로 수정하세요. 예시:ref=main
실험 채널에서 Gateway API 리소스를 설치할 수도 있습니다. 실험 채널에서 Gateway API를 설치하면 표준 채널의 모든 내용과 실험적인 리소스와 필드가 포함됩니다. NGINX Gateway Fabric은 현재 실험 채널에서 제공하는 추가 기능의 일부만 지원합니다.
실험 채널에서 설치하려면 다음 명령어를 사용합니다.
$ kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.5.1" | kubectl apply -f -Note:
현재 NGINX Gateway Fabric이 지원하는 Gateway API 리소스에 대해 더 알아보시려면, Gateway API 호환성 문서를 참고하세요.
2. NGINX Gateway Fabric CRDs 배포
Stable 릴리즈
$ kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.5.1/deploy/crds.yamlEdge 버전
$ kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/main/deploy/crds.yaml3. NGINX Gateway Fabric 배포
Note:
기본적으로 NGINX Gateway Fabric은 nginx-gateway 네임스페이스에 설치됩니다. Manifest 파일을 수정하여 다른 네임스페이스에 배포할 수 있습니다.
NGINX OSS를 사용하여 NGINX Gateway Fabric을 배포합니다.
$ kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.5.1/deploy/default/deploy.yaml4. 배포 확인
NGINX Gateway가 실행 중임을 확인하려면, nginx-gateway 네임스페이스의 Pod를 확인하세요.
$ kubectl get pods -n nginx-gateway출력은 다음과 같은 형식으로 나타납니다. Pod의 이름에는 고유한 문자열이 포함됩니다.
NAME READY STATUS RESTARTS AGE
nginx-gateway-5d4f4c7db7-xk2kq 2/2 Running 0 112s5. NGINX Gateway Fabric에 접근
설치에 사용한 로드 밸런서 서비스에 따라 NGINX Gateway Fabric에 접근하는 두 가지 옵션이 있습니다.
1. 로드 밸런서 타입이 NodePort인 경우
- Kubernetes는 클러스터의 모든 노드에 2개의 포트를 무작위로 할당합니다. NGINX Gateway Fabric에 접근하기 위해 클러스터의 아무 노드의 IP와 할당된 2개의 포트를 사용하세요.
팁:
NodePort에 대한 더 많은 정보는 Kubernetes 문서를 읽어보세요.
2. 로드 밸런서 타입이 LoadBalancer인 경우
- GCP 혹은 Azure의 경우 Kubernetes는 클라우드 로드 밸런서를 NGINX Gateway Fabric Pod에 할당합니다. NGINX Gateway Fabric에 접근하기 위해 로드 밸런서의 공인 IP를 사용하세요.
- AWS의 경우, Kubernetes는 클라이언트의 정보(IP 주소와 포트)를 전달하기 위해 네트워크 로드 밸런서(NLB)를 PROXY 프로토콜을 활성화한 TCP 모드로 할당합니다.
NGINX Gateway Fabric에 접근하기 위해 로드 밸런서의 공인 IP를 사용하세요. EXTERNAL-IP 열에 나타나는 공인 IP를 확인하려면 다음 명령어를 사용하세요:
- GCP, Azure
$ kubectl get svc nginx-gateway -n nginx-gateway- AWS의 경우, 공인 IP 대신 Kubernetes가 NLB (Network Load Balancer)의 DNS (directory name system) 이름을 반환합니다. DNS 이름을 확인하려면 다음 명령어를 사용합니다.
$ kubectl get svc nginx-gateway -n nginx-gatewayNote:
가능하면 NLB DNS를 사용하는 것을 권장하지만, 테스트 목적일 경우 DNS 이름을 확인하여 로드 밸런서의 IP 주소를 얻을 수 있습니다.
$ nslookup <dns-name>팁:
Kubernetes 문서에서 로드 밸런서 타입에 대해 더 많은 정보를 확인하세요.
AWS의 경우 할당된 로드 밸런서에 대해 타입, SSL termination과 같은 추가 옵션을 사용할 수 있습니다. Kubernetes 문서를 참고하여 더 많은 정보를 확인하세요.
중요:
기본적으로 Helm과 manifests는 NGINX Gateway Fabric을 80, 443 포트로 설정하여 해당 포트의 모든 gateway listeners에 영향을 끼칩니다. 다른 포트를 사용하려면 설정을 업데이트하세요. NGINX Gateway Fabric은 포트에서 수신하기 위해 유효한 리스너가 구성된 gateway 리소스를 필요로 합니다.
NGINX Gateway Fabric은 생성된 Service를 사용하여 Gateway Status 리소스의 Addresses 필드를 업데이트합니다. LoadBalancer Service를 사용하면 이 필드를 해당 Service의 IP 주소 그리고/혹은 hostname으로 설정합니다. Service가 없는 경우 Pod IP 주소가 사용됩니다.
게이트웨이는 gatewayClassName 필드를 통해 NGINX Gateway Fabric과 연결됩니다. NGINX Gateway Fabric의 기본 설치는 nginx 이름으로 GatewayClass를 생성합니다. NGINX Gateway Fabric은 --gatewayclass command-line flag를 변경하지 않는 이상 nginx 이름으로 gatewayClassName을 생성합니다.
3. NGINX Gateway Fabric 업그레이드
중요:
버전 1.4.0에서 1.5.x로 업그레이드하는 NGINX Plus 사용자는 NGINX Plus JWT Secret을 업그레이드 전에 생성해야 합니다. 사전 구성 섹션의 과정을 따라 최신 버전의 deployment manifest가 참조하는 Secret을 생성하세요.
팁:
무중단 업그레이드에 대한 안내는 하단의 Pod 종료 지연 섹션을 참고하세요.
다음 단계를 따라 NGINX Gateway Fabric을 업그레이드하여 최신 기능과 개선 사항을 활용하세요.
1. Gateway API 리소스 업그레이드:
- NGINX Gateway Fabric 버전이 Gateway API 리소스와 호환되는지 확인합니다. 자세한 내용은 기술 사양을 참고하세요.
- Gateway API 리소스를 업그레이드하기 위해 다음 명령어를 사용합니다.
$ kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.5.1" | kubectl apply -f -실험 채널을 통해 설치한 경우 다음 명령어를 사용합니다.
$ kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.5.1" | kubectl apply -f -2. NGINX Gateway Fabric CRDs 업그레이드:
Custom Resource Definitions (CRDs)을 업그레이드하기 위해 다음 명령어를 사용합니다.
$ kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.5.1/deploy/crds.yaml3. NGINX Gateway Fabric deployment 업그레이드:
NGINX Gateway Fabric 배포 섹션을 참고하여 현재 배포 방식에 맞는 방식의 deployment manifest를 선택하여 적용합니다.
4. 무중단 업그레이드를 위한 Pod 종료 지연
NGINX Gateway Fabric을 업그레이드할 때 클라이언트 서비스 중단을 피하기 위해 NGINX Gateway Fabric Pod 종료를 지연하도록 PreStop hooks를 구성하여, Pod가 종료되기 전에 특정 작업을 완료하도록 할 수 있습니다. 이렇게 하면 다운타임 없이 원활하게 업그레이드할 수 있으며, 이를 무중단 업그레이드라고도 합니다.
Kubernetes가 Pod의 종료를 다루는 방식에 대한 상세한 설명은 공식 사이트의 Termination of Pods를 참고하세요.
Note:
NGINX는 웹 소켓 혹은 다른 장기적인 연결이 열려있는 동안에는 종료되지 않는다는 것을 명심하세요. NGINX는 이러한 연결들이 클라이언트 혹은 백엔드에 의해 종료된 경우에만 종료됩니다. 만약 이런 연결들이 업그레이드 동안 열려있다면, kubernetes는 NGINX를 강제로 종료해야 할 수도 있습니다. 이런 갑작스러운 종료는 클라이언트의 서비스를 중단할 수 있습니다.
다음 단계를 따라 Pod 종료 지연을 설정합니다.
1. deploy.yaml을 열어 수정합니다.
2. delayed shutdown hooks를 추가합니다:
deploy.yaml 파일에서 lifecycle: preStop hooks를 nginx와 nginx-gateway 컨테이너에 모두 추가합니다. 이 hooks는 컨테이너의 종료 프로세스를 지연하도록 지시하여 연결이 우아하게 종료되도록 합니다. sleep 값을 사용하는 환경에 맞게 변경하세요.
<...>
name: nginx-gateway
<...>
lifecycle:
preStop:
exec:
command:
- /usr/bin/gateway
- sleep
- --duration=40s # This flag is optional, the default is 30s
<...>
name: nginx
<...>
lifecycle:
preStop:
exec:
command:
- /bin/sleep
- "40"
<...>3. termination grace period를 설정합니다:
terminationGracePeriodSeconds 값을 preStop hook에 정의된 sleep 값(기본값: 30) 이상으로 설정합니다. 이 설정은 Kubernetes가 preStop hook의 실행이 끝나기 전에 Pod를 종료하는 것을 방지합니다.
terminationGracePeriodSeconds: 504. 변경 사항을 저장합니다.
추가 참조:
컨테이너와 Pod의 수명 주기 동안의 동작을 구성하고 이해하는 방법에 대한 추가 정보를 확인하려면 다음 Kubernetes 문서를 참고하세요.
– Container Lifecycle Hooks
– Pod Lifecycle
5. NGINX Gateway Fabric 삭제
다음 단계를 따라 Kubernetes 클러스터에서 NGINX Gateway Fabric과 Gateway API를 삭제하세요.
1. NGINX Gateway Fabric 삭제:
NGINX Gateway Fabric과 custom resource definitions (CRDs) 삭제를 위해 다음 명령어를 사용합니다.
kubectl delete namespace nginx-gateway
kubectl delete cluterrole nginx-gateway
kubectl delete clusterrolebinding nginx-gateway$ kubectl delete -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.5.1/deploy/crds.yaml2. Gateway API 리소스 삭제:
주의:
이 작업은 클러스터 전체의 모든 네임스페이스에서 관련된 모든 custom resouces를 제거합니다.
유지해야 할 custom resouces가 없는지 다시 한 번 확인하고, 클러스터에 활성화된 다른 Gateway API 구현체가 없는지 확인하세요.
Gateway API 리소스 삭제를 위해 다음 명령어를 사용합니다.
$ kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.5.1" | kubectl delete -f -Gateway API를 실험 채널에서 설치한 경우 다음 명령어를 사용합니다.
$ kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.5.1" | kubectl delete -f -
