NGINX Gateway Fabric, Helm을 통해 설치
Helm을 사용하여 Kubernetes 클러스터에서 NGINX Gateway Fabric 을 설치, 업그레이드 및 제거하는 방법을 알아봅니다.
목차
1. 전제조건
2. NGINX Gateway Fabric 배포
2-1. Gateway API 리소스 설치
2-2. OCI Registry에서 설치
2-3. Source를 통해 설치
3. NGINX Gateway Fabric 업그레이드
3-1. NGINX Gateway Fabric API 리소스 업그레이드
3-2. CRD 업그레이드
3-3. Release 업그레이드
3-3-1. OCI Registry에서 업그레이드
3-3-2. Source를 통해 업그레이드
4. 무중단 업그레이드를 위한 Pod Termination 지원
5. NGINX Gateway Fabric 제거
1. 전제조건
이 가이드를 완료하려면 다음을 설치해야 합니다.
- Kubernetes 클러스터를 관리하기 위한 명령줄 도구인 kubectl
- Kubernetes에서 애플리케이션을 배포하고 관리하기 위한 Helm 3.0 이상
2. NGINX Gateway Fabric 배포
2-1. Gateway API 리소스 설치
참고:
NGINX Gateway Fabric 를 배포하기 전에 표준 채널의 Gateway API 리소스를 설치해야 합니다. 이미 클러스터에 설치되어 있는 경우 NGINX Gateway Fabric에서 지원하는 올바른 버전인지 확인하세요. 기술 사양을 참조하세요.
Stable release
NGINX Gateway Fabric의 최신 안정 버전을 설치하는 경우, 해당 버전의 Gateway API 리소스를 배포하는지 확인하세요.
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.8.1/standard-install.yamlEdge version
NGINX Gateway Fabric의 최신 edge 버전을 main 브랜치에서 설치하는 경우
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yamlKubernetes 1.23 또는 1.24에서 실행 중인 경우, validatingwebhook도 설치해야 합니다. 이를 위해 다음 명령을 실행하세요.
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml주의:
Kubernetes 1.25 이상을 실행 중인 경우, validatingwebhook은 필요하지 않습니다. 검증은 CRD에서 CEL을 사용하여 수행됩니다. 자세한 정보는 리소스 유효성 검사 문서를 참조하세요.
2-2. OCI Registry에서 설치
NGINX Gateway Fabric의 최신 안정 버전을 nginx-gateway 네임스페이스에 설치하려면 다음 명령을 실행하세요.
helm install <my-release> oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace --wait -n nginx-gateway을 원하는 릴리스 이름으로 변경하세요. 네임스페이스가 이미 존재하는 경우 선택적인 –create-namespace 플래그를 생략할 수 있습니다. main 브랜치에서 최신 버전을 원하는 경우 설치 명령에 –version 0.0.0-edge를 추가하세요.
2-3. Source를 통해 설치
1. NGINX Gateway Fabric 차트의 최신 안정 버전을 가져옵니다.
helm pull oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --untar
cd nginx-gateway-fabricmain 브랜치에서 최신 버전을 원하는 경우, pull 명령에 –version 0.0.0-edge를 추가하세요.
2. 차트를 nginx-gateway 네임스페이스에 설치하려면 다음 명령을 실행하세요.
helm install <my-release> . --create-namespace --wait -n nginx-gateway<my-release>를 원하는 릴리스 이름으로 변경하세요. 네임스페이스가 이미 존재하는 경우 선택적인 –create-namespace 플래그를 생략할 수 있습니다.
3. NGINX Gateway Fabric 업그레이드
참고:
무중단 업그레이드에 대한 지침은 아래의 “무중단 업그레이드를 위한 Pod Termination 지원” 목차를 참조하세요.
NGINX Gateway Fabric를 업그레이드하여 최신 기능과 개선 사항을 사용하려면 다음 단계를 수행하세요.
3-1. NGINX Gateway Fabric API 리소스 업그레이드
Gateway API 리소스를 업그레이드하려면 다음 단계를 수행하세요.
- NGINX Gateway Fabric 버전과 호환되는 Gateway API 리소스인지 확인하세요. 자세한 내용은 기술 사양을 참조하세요.
- 중요한 업그레이드 관련 정보를 확인하기 위해 릴리스 노트를 검토하세요.
- Gateway API 리소스를 업그레이드하려면 다음 명령을 실행하세요.
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml3-2. CRD 업그레이드
Helm의 업그레이드 프로세스는 CRD(Custom Resource Definition)를 자동으로 업그레이드하지 않습니다.
CRD(Custom Resource Definition)를 업그레이드하려면 다음 단계를 수행하세요.
1. NGINX Gateway Fabric 차트의 최신 안정 버전을 가져옵니다.
helm pull oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --untar
cd nginx-gateway-fabricmain 브랜치에서 최신 버전을 원하는 경우, pull 명령에 –version 0.0.0-edge를 추가하세요.
2. CRD를 업그레이드합니다.
kubectl apply -f crds/참고:
다음 경고는 예상되는 것이므로 무시하세요.
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply.3-3. Release 업그레이드
3-3-1. OCI Registry에서 업그레이드
NGINX Gateway Fabric의 최신 안정 버전으로 업그레이드하려면 다음 명령을 실행하세요.
helm upgrade oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric -n nginx-gateway<my-release>를 선택한 릴리스 이름으로 대체하세요.
3-3-2. Source를 통해 업그레이드
1. NGINX Gateway Fabric 차트의 최신 안정 버전을 가져옵니다.
helm pull oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --untar cd nginx-gateway-fabricmain branch에서 최신 버전을 원하는 경우, pull 명령에 –version 0.0.0-edge를 추가하세요.
2. 업그레이드하려면 다음 명령을 실행하세요.
helm upgrade . -n nginx-gateway<my-release>를 선택한 릴리스 이름으로 대체하세요.
4. 무중단 업그레이드를 위한 Pod Termination 지원
NGINX Gateway Fabric를 업그레이드할 때 클라이언트 서비스 중단을 피하려면 PreStop hook을 구성하여 Pod를 종료하기 전에 Pod가 특정 작업을 완료할 수 있도록 지연시킬 수 있습니다. 이를 통해 중단 없이 원활한 업그레이드가 가능합니다. 이를 무중단 업그레이드라고도 합니다.
Pod Termination을 처리하는 방법에 대한 자세한 설명은 Kubernetes 공식 웹사이트의 “Termination of Pods” 주제를 참조하세요.
참고:
WebSocket 또는 기타 장기간 유지되는 연결이 열려 있는 경우 NGINX는 종료되지 않습니다. 이러한 연결은 클라이언트나 Backend에서 닫힐 때까지 NGINX가 계속 실행됩니다. 이러한 연결이 업그레이드 중에 계속 유지되는 경우 Kubernetes는 NGINX를 강제로 종료해야 할 수 있습니다. 이러한 갑작스러운 종료로 인해 클라이언트의 서비스가 중단될 수 있습니다.
다음 단계를 따라 지연된 Pod Termination을 구성하세요.
1. 편집을 위해 values.yaml 파일을 엽니다.
2. 지연된 shutdown hook을 추가하세요.
- values.yaml 파일에서 nginx 및 nginx-gateway 컨테이너 정의에 lifecycle:
preStophook을 추가하세요. 이 hook은 컨테이너가 종료 프로세스를 지연시키도록 지시하며, 연결이 원활하게 닫힐 시간을 확보합니다. sleep 값을 환경에 맞게 업데이트하세요.
nginxGateway:
<...>
lifecycle:
preStop:
exec:
command:
- /usr/bin/gateway
- sleep
- --duration=40s # This flag is optional, the default is 30s
nginx:
<...>
lifecycle:
preStop:
exec:
command:
- /bin/sleep
- "40"3. Termination 유예 기간을 설정하세요.
terminationGracePeriodSeconds를preStophook에서 지정한sleep기간과 동일하거나 그보다 큰 값으로 설정하세요 (기본값은30입니다). 이 설정은preStophook이 실행을 완료하기 전에 Kubernetes가 pod를 종료하지 않도록 합니다.
terminationGracePeriodSeconds: 504. 변경 사항을 저장하세요.
5. NGINX Gateway Fabric 제거
Kubernetes 클러스터에서 Gateway API를 제거하려면 다음 단계를 따르세요.
1. NGINX Gateway Fabric을 제거:
- NGINX Gateway Fabric를 제거하려면 다음 명령을 실행하세요.
helm uninstall -n nginx-gateway<my-release>를 선택한 릴리스 이름으로 대체하세요.
2. 네임스페이스 및 CRD(Custom Resource Definition) 제거:
- nginx-gateway 네임스페이스와 해당 CRD를 제거하려면 다음 명령을 실행하세요.
kubectl delete ns nginx-gateway kubectl delete crd nginxgateways.gateway.nginx.org3. Gateway API 리소스 제거:
경고
이 명령은 클러스터 전체의 모든 네임스페이스에서 해당하는 모든 사용자 정의 리소스를 제거합니다. 보존해야 할 사용자 정의 리소스가 있는지 확인하고, 클러스터에 다른 Gateway API 구현이 활성화되어 있는지 확인하세요.
- CRD 및 validatingwebhook을 포함한 Gateway API 리소스를 제거하려면 다음 명령을 실행하세요.
Stable release
kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.8.1/standard-install.yamlEdge version
kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yamlKubernetes 1.23 또는 1.24에서 실행 중인 경우 validatingwebhook도 삭제해야 합니다. 이를 위해 다음 명령을 실행하세요.
kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml아래 뉴스레터를 구독하고 NGINX와 NGINX STORE의 최신 정보들을 빠르게 전달 받아보세요.
