프로덕션 환경의 Kubernetes에서 자체 호스팅 게이트웨이를 실행하기 위한 지침

  • 아티클

적용 대상: 개발자 | 프리미엄

프로덕션 환경에서 자체 호스팅 게이트웨이를 실행하려면 다양한 측면을 염두에 두어야 합니다. 예를 들어, 고가용성 방식으로 배포해야 하며 구성 백업을 사용하여 임시 연결 끊기 등을 처리해야 합니다.

이 문서에서는 원활하고 안정적으로 실행되도록 프로덕션 워크로드용 Kubernetes에서 자체 호스팅 게이트웨이를 실행하는 방법에 대한 지침을 제공합니다.

Important

Azure API Management 자체 호스팅 게이트웨이 버전 0 및 버전 1 컨테이너 이미지에 대한 지원은 해당 구성 API v1과 함께 2023년 10월 1일에 종료됩니다. 구성 API v2와 함께 자체 호스팅 게이트웨이 v2.0.0 이상을 사용하려면 마이그레이션 가이드를 사용합니다. 사용 중단 설명서에서 자세히 알아보기

액세스 토큰

유효한 액세스 토큰이 없으면 자체 호스팅 게이트웨이가 연결된 API Management 서비스의 엔드포인트에 액세스하여 구성 데이터를 다운로드할 수 없습니다. 액세스 토큰은 최대 30일 동안 유효합니다. 만료되기 전에 수동으로 또는 자동화를 통해 액세스 토큰을 다시 생성하고 클러스터를 새 토큰으로 구성해야 합니다.

토큰 새로 고침을 자동화하는 경우 이 관리 API 작업을 사용하여 새 토큰을 생성합니다. Kubernetes 비밀 관리에 대한 자세한 내용은 Kubernetes 웹 사이트를 참조하세요.

팁

또한 Kubernetes에 자체 호스팅 게이트웨이를 배포하고 Microsoft Entra ID를 사용하여 API Management 인스턴스에 인증을 사용하도록 설정할 수 있습니다.

자동 확장

자체 호스팅 게이트웨이에 대한 최소 복제본 수에 대한 지침을 제공하지만 트래픽 수요를 보다 적극적으로 충족하려면 자체 호스팅 게이트웨이에 대한 자동 크기 조정을 사용하는 것이 좋습니다.

자체 호스팅 게이트웨이를 수평으로 자동 크기 조정하는 두 가지 방법이 있습니다.

  • 리소스 사용량(CPU 및 메모리)에 따라 자동 크기 조정
  • 초당 요청 수에 따라 자동 크기 조정

이는 네이티브 Kubernetes 기능을 통해 또는 KEDA(Kubernetes 이벤트 기반 자동 크기 조정)를 사용하여 가능합니다. KEDA는 애플리케이션 자동 크기 조정을 간단하게 만들기 위해 노력하는 CNCF 인큐베이션 프로젝트입니다.

참고 항목

KEDA는 Azure 지원에서 지원하지 않으며 고객이 운영해야 하는 오픈 소스 기술입니다.

리소스 기반 자동 크기 조정

Kubernetes를 사용하면 Horizontal Pod Autoscaler를 사용하여 리소스 사용량에 따라 자체 호스팅 게이트웨이를 자동 크기 조정할 수 있습니다. 이를 통해 CPU 및 메모리 임계값을 정의하고 스케일 아웃 또는 인할 복제본 수를 정의할 수 있습니다.

대안은 KEDA(Kubernetes 이벤트 기반 자동 크기 조정)를 사용하여 CPU 및 메모리를 포함한 다양한 배율 조정기를 기반으로 워크로드를 크기 조정하는 것입니다.

팁

이미 KEDA를 사용하여 다른 워크로드를 확장하고 있다면 KEDA를 통합 앱 자동 스케일러로 사용하는 것이 좋습니다. 그렇지 않은 경우 Horizontal Pod Autoscaler를 통해 네이티브 Kubernetes 기능에 의존하는 것이 좋습니다.

트래픽 기반 자동 크기 조정

Kubernetes는 트래픽 기반 자동 확장을 위한 기본 메커니즘을 제공하지 않습니다.

KEDA(Kubernetes 이벤트 기반 자동 크기 조정)는 트래픽 기반 자동 크기 조정에 도움이 되는 몇 가지 방법을 제공합니다.

  • 즉시 사용 가능한 배율 조정기를 사용하여 Prometheus 또는 Azure Monitor에서 사용할 수 있는 경우 Kubernetes 수신의 메트릭을 기반으로 확장할 수 있습니다.
  • 베타 버전으로 제공되며 초당 요청 수에 따라 확장되는 HTTP 추가 기능을 설치할 수 있습니다.

구성 백업

자체 호스팅 게이트웨이 컨테이너에 대한 로컬 스토리지 볼륨을 구성합니다. 그러면 다운로드한 최신 구성의 백업 복사본을 유지할 수 있습니다. 연결이 중단되면 스토리지 볼륨은 다시 시작할 때 백업 복사본을 사용할 수 있습니다. 볼륨 탑재 경로는 /apim/config여야 하며 그룹 ID 1001이 소유해야 합니다. GitHub의 예제를 참조하세요. Kubernetes의 스토리지에 대한 자세한 내용은 Kubernetes 웹 사이트를 참조하세요. 탑재된 경로에 대한 소유권을 변경하려면 Kubernetes 웹 사이트의 securityContext.fsGroup 설정을 참조하세요.

참고 항목

일시적으로 Azure 연결이 중단되었을 때 자체 호스팅 게이트웨이가 어떻게 동작하는지 알아보려면 자체 호스팅 게이트웨이 개요를 참조하세요.

컨테이너 이미지 태그

Azure Portal에서 제공하는 YAML 파일은 최신 태그를 사용합니다. 이 태그는 항상 자체 호스팅 게이트웨이 컨테이너 이미지의 최신 버전을 참조합니다.

의도치 않게 최신 버전으로 업그레이드되는 일이 없도록 프로덕션에서 특정 버전 태그를 사용하는 것이 좋습니다.

사용 가능한 태그의 전체 목록을 다운로드할 수 있습니다.

팁

Helm과 함께 설치하면 이미지 태그 지정이 최적화됩니다. Helm 차트의 애플리케이션 버전은 게이트웨이를 지정된 버전에 고정하며 latest에 의존하지 않습니다.

Helm을 사용하여 Kubernetes에 API Management 자체 호스팅 게이트웨이를 설치하는 방법에 대해 자세히 알아봅니다.

컨테이너 리소스

기본적으로 Azure Portal에서 제공하는 YAML 파일은 컨테이너 리소스 요청을 지정하지 않습니다.

컨테이너당 CPU 및 메모리 리소스의 양과 특정 워크로드를 지원하는 데 필요한 복제본 수를 안정적으로 예측하고 권장하는 것이 불가능합니다. 다음과 같은 많은 요소가 있습니다.

  • 클러스터가 실행 중인 특정 하드웨어
  • 가상화의 현재 상태 및 유형
  • 동시 클라이언트 연결 수 및 속도
  • 요청 속도.
  • 구성된 정책의 종류 및 수
  • 페이로드 크기 및 페이로드가 버퍼링되는지 아니면 스트리밍되는지 여부
  • 백 엔드 서비스 대기 시간

처음에는 리소스 요청을 2개 코어와 2GiB로 설정하는 것이 좋습니다. 부하 테스트를 수행하고 그 결과에 따라 스케일 업/아웃하거나 스케일 다운하면 됩니다.

사용자 지정 도메인 이름 및 SSL 인증서

API Management 엔드포인트에 사용자 지정 도메인 이름을 사용하는 경우, 특히 Management 엔드포인트에 사용자 지정 도메인 이름을 사용하는 경우 <gateway-name>.yaml 파일의 config.service.endpoint 값을 업데이트하여 기본 도메인 이름을 사용자 지정 도메인 이름으로 바꿔야 할 수 있습니다. Kubernetes 클러스터에 있는 자체 호스팅 게이트웨이의 Pod에서 Management 엔드포인트에 액세스할 수 있어야 합니다.

이 시나리오에서 Management 엔드포인트에서 사용하는 SSL 인증서가 잘 알려진 CA 인증서로 서명되지 않은 경우 자체 호스팅 게이트웨이의 Pod에서 CA 인증서를 신뢰하는지 확인해야 합니다.

참고 항목

자체 호스팅 게이트웨이 v2를 사용하여 API Management는 새로운 구성 엔드포인트 <apim-service-name>.configuration.azure-api.net을 제공합니다. 사용자 지정 호스트 이름은 이 엔드포인트에 대해 지원되며 기본 호스트 이름 대신 사용할 수 있습니다.

DNS 정책

DNS 이름 확인은 Azure의 종속성에 연결하고 API의 백엔드 서비스 호출을 디스패치하는 자체 호스팅 게이트웨이의 기능에 있어서 매우 중요한 역할을 합니다.

Azure Portal에 제공되는 YAML 파일은 기본 ClusterFirst 정책을 적용합니다. 이 정책은 클러스터 DNS에서 확인하지 못한 이름 확인 요청을 노드에서 상속된 업스트림 DNS 서버로 전달하게 합니다.

Kubernetes의 이름 확인에 대한 자세한 내용은 Kubernetes 웹 사이트를 참조하세요. 설치에 적합하도록 DNS 정책 또는 DNS 구성을 사용자 지정하는 방안을 고려해 보세요.

외부 트래픽 정책

Azure Portal에서 제공하는 YAML 파일은 Service 개체의 externalTrafficPolicy 필드를 Local로 설정합니다. 따라서 호출자 IP 주소(요청 컨텍스트에서 액세스 가능)가 유지되고 노드 간 부하 분산이 사용되지 않으므로 네트워크 홉이 발생하지 않습니다. 이 설정을 사용하면 노드당 게이트웨이 Pod 수가 균등하지 않은 배포에서 트래픽이 비대칭적으로 배포될 수 있습니다.

고가용성

자체 호스팅 게이트웨이는 인프라의 중요한 구성 요소이며 가용성이 높아야 합니다. 그러나 실패할 수 있습니다.

자체 호스팅 게이트웨이를 중단으로부터 보호하는 것이 좋습니다.

팁

Helm과 함께 설치할 때 highAvailability.enabled 구성 옵션을 사용하도록 설정하여 고가용성 일정을 쉽게 사용하도록 설정합니다.

Helm을 사용하여 Kubernetes에 API Management 자체 호스팅 게이트웨이를 설치하는 방법에 대해 자세히 알아봅니다.

노드 오류로부터 보호

데이터 센터 또는 노드 오류로 인한 영향을 방지하려면 가용성 영역을 사용하여 노드 수준에서 고가용성을 달성하는 Kubernetes 클러스터를 사용하는 것이 좋습니다.

가용성 영역을 사용하면 다음을 사용하여 영역에 분산된 노드에서 자체 호스팅 게이트웨이의 Pod를 예약할 수 있습니다.

참고 항목

Azure Kubernetes Service를 사용하는 경우 이 문서에서 가용성 영역을 사용하는 방법을 알아봅니다.

Pod 중단으로부터 보호

수동 Pod 삭제, 노드 유지 관리 등과 같은 다양한 이유로 Pod가 중단될 수 있습니다.

Pod 중단 예산을 사용하여 지정된 시간에 사용할 수 있는 최소 Pod 수를 적용하는 것이 좋습니다.

HTTP(S) 프록시

자체 호스팅 게이트웨이는 기존 HTTP_PROXY, HTTPS_PROXY 및 NO_PROXY 환경 변수를 사용하여 HTTP(S) 프록시를 지원합니다.

자체 호스팅 게이트웨이가 구성되면 백 엔드 서비스에 대한 모든 아웃바운드 HTTP(S) 요청에 자동으로 프록시를 사용합니다.

버전 2.1.5 이상부터 자체 호스팅 게이트웨이는 요청 프록시와 관련된 관찰 기능을 제공합니다.

  • API Inspector는 HTTP(S) 프록시가 사용될 때 추가 단계 및 관련된 상호 작용을 보여 줍니다.
  • 요청 프록시 동작을 표시하기 위해 상세 로그가 제공됩니다.

참고 항목

기본 인증을 사용하는 HTTP 프록시의 알려진 문제로 인해 CRL(인증서 해지 목록) 유효성 검사 사용은 지원되지 않습니다. 자체 호스트된 게이트웨이 설정 참조에서 적절하게 구성하는 방법에 대해 자세히 알아봅니다.

Warning

인프라 요구 사항이 충족되었는지, 자체 호스팅 게이트웨이가 여전히 인프라에 연결할 수 있는지 또는 특정 기능이 제대로 작동하지 않는지 확인합니다.

로컬 로그 및 메트릭

자체 호스팅 게이트웨이는 연결된 API Management 서비스의 구성 설정에 따라 Azure Monitor 및 Azure Application Insights에 원격 분석 데이터를 보냅니다. Azure에 대한 연결이 일시적으로 끊어지면 Azure로 전달되는 원격 분석 흐름이 중단되고 가동 중단 기간 동안 데이터가 손실됩니다.

Azure 연결 중단 시 API 트래픽을 관찰하고 원격 분석 데이터 손실을 방지할 수 있도록 Azure Monitor 컨테이너 인사이트를 사용하여 컨테이너를 모니터링하거나 로컬 모니터링을 설정하는 것이 좋습니다.

네임스페이스

Kubernetes 네임스페이스는 단일 클러스터를 여러 팀, 프로젝트 또는 애플리케이션 간에 분할하는 데 도움이 됩니다. 네임스페이스는 리소스 및 이름의 범위를 제공합니다. 리소스 할당량 및 액세스 제어 정책과 연결될 수 있습니다.

Azure Portal은 기본 네임스페이스에 자체 호스팅 게이트웨이 리소스를 만드는 명령을 제공합니다. 이 네임스페이스는 자동으로 만들어지고, 모든 클러스터에 있으며, 삭제할 수 없습니다. 프로덕션에서 자체 호스팅 게이트웨이를 만들고 별도의 네임스페이스에 배포하는 것이 좋습니다.

복제본 수

프로덕션에 적합한 최소 복제본 수는 3개이며 가급적이면 인스턴스의 고가용성 예약과 결합하는 것이 좋습니다.

기본적으로 자체 호스팅 게이트웨이는 RollingUpdate 배포 전략을 사용하여 배포됩니다. 기본값을 검토하고, 특히 복제본 수가 많은 경우 maxUnavailable 및 maxSurge 필드를 명시적으로 설정하는 것이 좋습니다.

성능

성능 개선을 위해 컨테이너 로그를 경고(warn)로 줄이는 것이 좋습니다. 자체 호스팅 게이트웨이 구성 참조에서 자세히 알아봅니다.

요청 제한

자체 호스팅 게이트웨이의 요청 제한은 API Management rate-limit 또는 rate-limit-by-key 정책을 사용하여 사용하도록 설정할 수 있습니다. 인스턴스 검색을 위해 Kubernetes 배포에서 다음 포트를 노출하여 클러스터 노드 전체의 게이트웨이 인스턴스 간에 동기화하도록 속도 제한 수를 구성합니다.

  • 속도 제한 동기화용 포트 4290(UDP)
  • 포트 4291(UDP), 하트비트를 다른 인스턴스로 전송

참고 항목

자체 호스팅 게이트웨이의 속도 제한 수는 예를 들어, Kubernetes용 Helm 차트 배포 또는 Azure Portal 배포 템플릿 사용을 통해 클러스터 노드 전체의 게이트웨이 인스턴스 간에 로컬로 동기화하도록 구성할 수 있습니다. 그러나 속도 제한 수는 클라우드의 관리 게이트웨이를 포함하여 API Management 인스턴스에 구성된 다른 게이트웨이 리소스와 동기화되지 않습니다.

보안

자체 호스팅 게이트웨이는 Kubernetes에서 루트가 아닌 게이트웨이로 실행하여 고객이 게이트웨이를 안전하게 실행할 수 있도록 합니다.

다음은 자체 호스팅 게이트웨이 컨테이너에 대한 보안 컨텍스트의 예입니다.

securityContext:
  allowPrivilegeEscalation: false
  runAsNonRoot: true
  runAsUser: 1001       # This is a built-in user, but you can use any user ie 1000 as well
  runAsGroup: 2000      # This is just an example
  privileged: false
  capabilities:
    drop:
    - all

Warning

읽기 전용 파일 시스템(readOnlyRootFilesystem: true)을 사용하여 자체 호스팅 게이트웨이를 실행하는 것은 지원되지 않습니다.

Warning

로컬 CA 인증서를 사용하는 경우 CA 인증서를 관리하도록 자체 호스팅 게이트웨이를 UID(사용자 ID) 1001로 실행해야 합니다. 그렇지 않으면 게이트웨이가 시작되지 않습니다.

다음 단계