적용 대상: 개발자 | 프리미엄
이 문서에서는 API Management 자체 호스팅 게이트웨이 컨테이너를 구성하는 데 사용되는 필수 및 선택적 설정에 대한 참조를 제공합니다.
자세한 내용은 본용 환경에서 Kubernetes에서 셀프 호스팅 게이트웨이를 실행하는 방법에 관한 지침을 참조하세요.
중요합니다
이 참조는 자체 호스팅 게이트웨이 v2에만 적용됩니다. 이 참고문헌은 각 설정을 지원하는 최소 버전을 명시합니다.
구성 API 통합
셀프 호스팅 게이트웨이는 Configuration API를 사용해 Azure API Management에 연결하고, 최신 구성을 받으며, 활성화 시 메트릭을 전송합니다.
다음 표는 구성 API 통합을 위한 구성 옵션을 설명합니다:
| 속성 | 설명 | 필수 항목 | 기본값 | 가용성 |
|---|---|---|---|---|
| gateway.name | 자체 호스팅 게이트웨이 리소스의 ID입니다. | 예, Microsoft Entra 인증을 사용하는 경우 | 해당 없음 | v2.3 이상 |
| config.service.endpoint | 자체 호스팅 게이트웨이에 대한 Azure API Management의 구성 엔드포인트입니다. Azure Portal의 게이트웨이>배포에서 이 값을 찾습니다. | 예 | 해당 없음 | v2.0 이상 |
| config.service.auth | 셀프 호스팅 게이트웨이가 구성 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정의합니다.
인증 방법을 정의하려면 다음 정보를 제공하세요:
- 게이트웨이 토큰 기반 인증의 경우 게이트웨이 배포에서 >
- Microsoft Entra ID 기반 인증의 경우 추가
azureAdApp인증 설정을 지정config.service.auth.azureAd하고 제공합니다.
크로스 인스턴스 발견 및 동기화
| 속성 | 설명 | 필수 항목 | 기본값 | 가용성 |
|---|---|---|---|---|
| neighborhood.host | 인스턴스 간 동기화를 위해 자체 호스팅 게이트웨이 배포의 모든 인스턴스를 확인하는 데 사용되는 DNS 이름입니다. Kubernetes에서는 인스턴스를 해결하기 위해 헤드리스 서비스를 사용하세요. | 아니요 | 해당 없음 | v2.0 이상 |
| neighborhood.heartbeat.port | 하트비트를 다른 인스턴스로 보내기 위해 자체 호스팅 게이트웨이 배포 인스턴스에 사용되는 UDP 포트입니다. | 아니요 | 4291 |
v2.0 이상 |
| policy.rate-limit.sync.port | 여러 인스턴스에서 속도 제한을 동기화하기 위해 자체 호스팅 게이트웨이 인스턴스에 사용되는 UDP 포트입니다. | 아니요 | 4290 |
v2.0 이상 |
HTTP(HTTP)
| 속성 | 설명 | 필수 항목 | 기본값 | 가용성 |
|---|---|---|---|---|
| net.server.http.forwarded.proto.enabled | 호출된 API 경로를 해석하는 방식을 식별하기 위해 헤더를 X-Forwarded-Proto 존중합니다(http/https만). |
아니요 | false |
v2.5 이상 |
Kubernetes 통합
Kubernetes Ingress (preview)
중요합니다
Kubernetes Ingress 지원은 실험 단계이며, Azure 지원은 이를 지원하지 않습니다. Kubernetes Ingress GitHub 저장소에서 더 알아보세요.
| 속성 | 설명 | 필수 항목 | 기본값 | 가용성 |
|---|---|---|---|---|
| k8s.ingress.enabled | Kubernetes 수신 통합을 사용하도록 설정합니다. | 아니요 | false |
v2.0 이상 |
| k8s.ingress.namespace | Kubernetes 수신 리소스를 감시할 Kubernetes 네임스페이스입니다. | 아니요 | default |
v2.0 이상 |
| 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 이상 |
| 텔레메트리.메트릭.로컬.statsd.샘플링 | StatsD 메트릭 샘플링 속도. 값은 0과 1 사이여야 합니다(예: 0.5). | 아니요 | 해당 없음 | v2.0 이상 |
| telemetry.metrics.local.statsd.태그-형식 | StatsD 내보내기 태그 지정 형식. 값은 librato, 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, warnerror.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 이상 |
| .endpoint telemetry.logs.local.json | 파일 경로, 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
관련 콘텐츠
- 운영 환경에서 Kubernetes에서 셀프 호스팅 게이트웨이를 실행하는 방법에 대해 더 알아보세요
- Docker에 자체 호스팅 게이트웨이 배포
- Kubernetes에 자체 호스팅 게이트웨이 배포
- Azure Arc 지원 Kubernetes 클러스터에 자체 호스팅 게이트웨이 배포
- 자체 호스팅 게이트웨이에서 Dapr 지원 사용
- Azure Arc 확장에 대한 구성 옵션에 대해 자세히 알아보기