다음을 통해 공유

참조: 자체 호스팅 게이트웨이 컨테이너 구성 설정

  • 아티클

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

이 문서에서는 API Management 자체 호스팅 게이트웨이 컨테이너를 구성하는 데 사용되는 필수 및 선택적 설정에 대한 참조를 제공합니다.

(Kubernetes) 프로덕션 지침에 대해 자세히 알아보려면 이 문서를 참조하는 것이 좋습니다.

Important

이 참조는 자체 호스팅 게이트웨이 v2에만 적용됩니다. 설정의 가용성에 대한 최소 버전이 제공됩니다.

구성 API 통합

구성 API는 사용하도록 설정된 경우 자체 호스팅 게이트웨이에서 Azure API Management에 연결하여 최신 구성을 가져오고 메트릭을 보내는 데 사용됩니다.

다음은 모든 구성 옵션에 대한 개요입니다.

속성 설명 필수 항목 기본값 가용성
gateway.name 자체 호스팅 게이트웨이 리소스의 ID입니다. 예, Microsoft Entra 인증을 사용하는 경우 해당 없음 v2.3 이상
config.service.endpoint 자체 호스팅 게이트웨이에 대한 Azure API Management의 구성 엔드포인트입니다. Azure Portal의 게이트웨이>배포에서 이 값을 찾습니다. 예 해당 없음 v2.0 이상
config.service.auth 자체 호스팅 게이트웨이가 Configuration API에 인증하는 방법을 정의합니다. 현재 게이트웨이 토큰 및 Microsoft Entra 인증이 지원됩니다. 예 해당 없음 v2.0 이상
config.service.auth.azureAd.tenantId Microsoft Entra 테넌트 ID입니다. 예, Microsoft Entra 인증을 사용하는 경우 해당 없음 v2.3 이상
config.service.auth.azureAd.clientId 인증할 Microsoft Entra 앱의 클라이언트 ID(애플리케이션 ID라고도 함). 예, Microsoft Entra 인증을 사용하는 경우 해당 없음 v2.3 이상
config.service.auth.azureAd.clientSecret 인증할 Microsoft Entra 앱의 비밀입니다. 예, Microsoft Entra 인증을 사용하는 경우(인증서가 지정되지 않은 경우) 해당 없음 v2.3 이상
config.service.auth.azureAd.certificatePath Microsoft Entra 앱에 대해 인증할 인증서의 경로입니다. 예, Microsoft Entra 인증을 사용하는 경우(비밀이 지정되지 않은 경우) 해당 없음 v2.3 이상
config.service.auth.azureAd.authority Microsoft Entra ID의 기관 URL입니다. 아니요 https://login.microsoftonline.com v2.3 이상
config.service.auth.tokenAudience Microsoft Entra 인증에 사용되는 토큰 대상 그룹 아니요 https://azure-api.net/configuration v2.3 이상
config.service.endpoint.disableCertificateValidation 자체 호스팅 게이트웨이가 구성 API의 서버 쪽 인증서의 유효성을 검사해야 하는지를 정의합니다. 인증서 유효성 검사를 사용하는 것이 좋습니다. 테스트 목적으로만 사용하지 않도록 설정하고 보안 위험을 초래할 수 있으므로 주의해야 합니다. 아니요 false v2.0 이상
config.service.integration.timeout 구성 API와 상호 작용하기 위한 시간 제한을 정의합니다. 아니요 00:01:40 v2.3.5 이상

자체 호스팅 게이트웨이는 구성 API와 통합하기 위한 몇 가지 인증 옵션을 지원하며, 이 옵션은 사용하여 config.service.auth정의할 수 있습니다.

이 지침은 인증 방법을 정의하는 데 필요한 정보를 제공하는 데 도움이 됩니다.

  • 게이트웨이 토큰 기반 인증의 경우 게이트웨이 배포에서 Azure Portal에서 자체 호스팅 게이트웨이의 액세스 토큰(인증 키)을 지정합니다>.
  • Microsoft Entra ID 기반 인증의 경우 추가 config.service.auth.azureAd 인증 설정을 지정 azureAdApp 하고 제공합니다.

인스턴스 간 검색 및 동기화

속성 설명 필수 항목 기본값 가용성
neighborhood.host 인스턴스 간 동기화를 위해 자체 호스팅 게이트웨이 배포의 모든 인스턴스를 확인하는 데 사용되는 DNS 이름입니다. Kubernetes에서는 헤드리스 서비스를 사용하여 달성할 수 있습니다. 아니요 해당 없음 v2.0 이상
neighborhood.heartbeat.port 하트비트를 다른 인스턴스로 보내기 위해 자체 호스팅 게이트웨이 배포 인스턴스에 사용되는 UDP 포트입니다. 아니요 4291 v2.0 이상
policy.rate-limit.sync.port 여러 인스턴스에서 속도 제한을 동기화하기 위해 자체 호스팅 게이트웨이 인스턴스에 사용되는 UDP 포트입니다. 아니요 4290 v2.0 이상

HTTP

속성 설명 필수 항목 기본값 가용성
net.server.http.forwarded.proto.enabled 호출된 API 경로(http/https에만 해당)를 확인하는 체계를 식별하기 위해 헤더를 적용 X-Forwarded-Proto 하는 기능입니다. 아니요 false v2.5 이상

Kubernetes 통합

Kubernetes 수신

Important

Kubernetes 수신에 대한 지원은 현재 실험적이며 Azure 지원을 통해 다루지 않습니다. GitHub에 대해 자세히 알아보세요.

속성 설명 필수 항목 기본값 가용성
k8s.ingress.enabled Kubernetes 수신 통합을 사용하도록 설정합니다. 아니요 false v1.2 이상
k8s.ingress.namespace Kubernetes 수신 리소스를 감시할 Kubernetes 네임스페이스입니다. 아니요 default v1.2 이상
k8s.ingress.dns.suffix 요청을 보낼 서비스에 대한 DNS 호스트 이름을 빌드하는 DNS 접미사입니다. 아니요 svc.cluster.local v2.4 이상
k8s.ingress.config.path Kubernetes 구성 경로(Kubeconfig). 아니요 해당 없음 v2.4 이상

메트릭

이름 설명 필수 항목 기본값 가용성
telemetry.metrics.local StatsD를 통해 로컬 메트릭 수집을 사용하도록 설정합니다. 값은 none, statsd 옵션 중 하나입니다. 아니요 none v2.0 이상
telemetry.metrics.local.statsd.endpoint StatsD 엔드포인트. telemetry.metrics.local이 statsd로 설정된 경우 예, 그렇지 않으면 아니요입니다. 해당 없음 v2.0 이상
telemetry.metrics.local.statsd.sampling StatsD 메트릭 샘플링 속도. 값은 0과 1 사이여야 합니다(예: 0.5). 아니요 해당 없음 v2.0 이상
telemetry.metrics.local.statsd.tag-format StatsD 내보내기 태그 지정 형식. 값은 ibrato, dogStatsD, influxDB 옵션 중 하나입니다. 아니요 해당 없음 v2.0 이상
telemetry.metrics.cloud Azure Monitor로 메트릭을 내보내도록 사용 설정 여부를 나타냅니다. 아니요 true v2.0 이상
observability.opentelemetry.enabled Kubernetes에서 OpenTelemetry 수집기로 메트릭 내보내기를 사용할지 여부를 나타냅니다. 아니요 false v2.0 이상
observability.opentelemetry.collector.uri 메트릭을 보낼 OpenTelemetry 수집기의 URI입니다. observability.opentelemetry.enabled이 true로 설정된 경우 예, 그렇지 않으면 아니요입니다. 해당 없음 v2.0 이상
observability.opentelemetry.system-metrics.enabled CPU, 메모리, 가비지 수집 등과 같은 OpenTelemetry 수집기로 시스템 메트릭 전송을 사용하도록 설정합니다. 아니요 false v2.3 이상
observability.opentelemetry.histogram.buckets OpenTelemetry 메트릭을 보고해야 하는 히스토그램 버킷입니다. 형식: "x,y,z,..." 아니요 "5,10,25,50,100,250,500,1000,2500,5000,10000" v2.0 이상

로그

속성 설명 필수 항목 기본값 가용성
telemetry.logs.std 표준 스트림에 로깅을 사용하도록 설정합니다. 값은 none, text, json 옵션 중 하나입니다. 아니요 text v2.0 이상
telemetry.logs.std.level 표준 스트림으로 전송되는 로그의 로그 수준을 정의합니다. 값은 all, debug, info, warn, error 또는 fatal 옵션 중 하나입니다. 아니요 info v2.0 이상
telemetry.logs.std.color 표준 스트림에서 색이 지정된 로그를 사용해야 하는지 여부를 나타냅니다. 아니요 true v2.0 이상
telemetry.logs.local 로컬 로깅을 사용하도록 설정합니다. 값은 none, auto, localsyslog, rfc5424, journal, json 옵션 중 하나입니다. 아니요 auto v2.0 이상
telemetry.logs.local.localsyslog.endpoint localsyslog 엔드포인트. telemetry.logs.local이 localsyslog로 설정된 경우 예, 그렇지 않으면 아니요입니다. 구성에 대한 자세한 내용은 로컬 syslog 설명서를 참조하세요. 해당 없음 v2.0 이상
telemetry.logs.local.localsyslog.facility localsyslog 기능 코드를 지정합니다(예: 7). 아니요 해당 없음 v2.0 이상
telemetry.logs.local.rfc5424.endpoint rfc5424 엔드포인트. telemetry.logs.local이 rfc5424로 설정된 경우 예, 그렇지 않으면 아니요입니다. 해당 없음 v2.0 이상
telemetry.logs.local.rfc5424.facility rfc5424당 시설 코드(예: 7) 아니요 해당 없음 v2.0 이상
telemetry.logs.local.journal.endpoint 저널 엔드포인트. telemetry.logs.local이 journal로 설정된 경우 예, 그렇지 않으면 아니요입니다. 해당 없음 v2.0 이상
telemetry.logs.local.json.endpoint 파일 경로, IP:포트 또는 호스트 이름:포트와 같은 JSON 데이터를 허용하는 UDP 엔드포인트. telemetry.logs.local이 json로 설정된 경우 예, 그렇지 않으면 아니요입니다. 127.0.0.1:8888 v2.0 이상

보안

인증서 및 암호화

속성 설명 필수 항목 기본값 가용성
certificates.local.ca.enabled 자체 호스팅 게이트웨이가 탑재된 로컬 CA 인증서를 사용해야 하는지 여부를 나타냅니다. 자체 호스팅 게이트웨이를 루트 또는 사용자 ID 1001로 실행해야 합니다. 아니요 false v2.0 이상
net.server.tls.ciphers.allowed-suites API 클라이언트와 자체 호스팅 게이트웨이 간의 TLS 연결에 사용할 쉼표로 구분된 암호 목록입니다. 아니요 TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_DHE_RSA_WITH_AES_256_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA v2.0 이상
net.client.tls.ciphers.allowed-suites 자체 호스팅 게이트웨이와 백 엔드 간의 TLS 연결에 사용할 쉼표로 구분된 암호화 목록입니다. 아니요 TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_DHE_RSA_WITH_AES_256_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA v2.0 이상
security.certificate-revocation.validation.enabled 인증서 해지 목록 유효성 검사를 설정/해제하는 기능을 제공합니다. 아니요 false v2.3.6 이상

TLS

속성 설명 필수 항목 기본값 가용성
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls13 TLS 1.3이 백 엔드에 허용되는지 여부를 나타냅니다. 관리되는 게이트웨이에서 프로토콜 암호화를 관리하는 것과 유사합니다. 아니요 true v2.0 이상
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls12 TLS 1.2가 백 엔드에 허용되는지 여부를 나타냅니다. 관리되는 게이트웨이에서 프로토콜 암호화를 관리하는 것과 유사합니다. 아니요 true v2.0 이상
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls11 TLS 1.1이 백 엔드에 허용되는지 여부를 나타냅니다. 관리되는 게이트웨이에서 프로토콜 암호화를 관리하는 것과 유사합니다. 아니요 false v2.0 이상
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls10 TLS 1.0이 백 엔드에 허용되는지 여부를 나타냅니다. 관리되는 게이트웨이에서 프로토콜 암호화를 관리하는 것과 유사합니다. 아니요 false v2.0 이상
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Ssl30 백 엔드에 대해 SSL 3.0이 허용되는지 여부를 나타냅니다. 관리되는 게이트웨이에서 프로토콜 암호화를 관리하는 것과 유사합니다. 아니요 false v2.0 이상

소버린 클라우드

소버린 클라우드를 사용할 수 있도록 구성해야 하는 설정의 개요는 다음과 같습니다.

속성 공공 사업 Azure 중국 미국 정부
config.service.auth.tokenAudience https://azure-api.net/configuration(기본값) https://azure-api.cn/configuration https://azure-api.us/configuration
logs.applicationinsights.endpoint https://dc.services.visualstudio.com/v2/track(기본값) https://dc.applicationinsights.azure.cn/v2/track https://dc.applicationinsights.us/v2/track

설정을 구성하는 방법

Kubernetes YAML 파일

YAML 파일을 사용하여 자체 호스팅 게이트웨이를 Kubernetes에 배포할 때 게이트웨이 ConfigMap의 data 요소에서 이름-값 쌍으로 설정을 구성합니다. 예시:

apiVersion: v1
    kind: ConfigMap
    metadata:
        name: contoso-gateway-environment
    data:
        config.service.endpoint: "contoso.configuration.azure-api.net"
        telemetry.logs.std: "text"
        telemetry.logs.local.localsyslog.endpoint: "/dev/log"
        telemetry.logs.local.localsyslog.facility: "7"

[...]

Helm 차트

Helm을 사용하여 자체 호스팅 게이트웨이를 Kubernetes에 배포하는 경우 차트 구성 설정을 helm install 명령에 매개변수로 전달합니다. 예시:

helm install azure-api-management-gateway \
    --set gateway.configuration.uri='contoso.configuration.azure-api.net' \
    --set gateway.auth.key='GatewayKey contosogw&xxxxxxxxxxxxxx...' \
    --set secret.createSecret=false \
    --set secret.existingSecretName=`mysecret` \
    azure-apim-gateway/azure-api-management-gateway

다음 단계