Referenz: Konfigurationseinstellungen für selbstgehostete Gatewaycontainer

  • Artikel

GILT FÜR: Developer | Premium

Dieser Artikel enthält eine Referenz für erforderliche und optionale Einstellungen, die zum Konfigurieren des selbstgehosteten Gatewaycontainers von API Management verwendet werden.

Weitere Informationen zu unseren (Kubernetes)-Produktionsanleitungen finden Sie in diesem Artikel.

Wichtig

Diese Referenz gilt nur für das selbstgehostete Gateway v2. Es werden Mindestversionen für die Verfügbarkeit von Einstellungen bereitgestellt.

Integration der Konfigurations-API

Die Konfigurations-API wird vom selbstgehosteten Gateway verwendet, um eine Verbindung mit Azure API Management herzustellen, um die neueste Konfiguration abzurufen und Metriken zu senden, falls aktiviert.

Hier finden Sie eine Übersicht aller Konfigurationsoptionen:

Name BESCHREIBUNG Erforderlich Standard Verfügbarkeit
gateway.name ID der selbst gehosteten Gatewayressource. Ja, bei Verwendung der Microsoft Entra-Authentifizierung Nicht zutreffend v2.3+
config.service.endpoint Konfigurationsendpunkt in Azure API Management für das selbstgehostete Gateway. Suchen Sie diesen Wert im Azure-Portal unter Gateways>Deployment. Ja – v2.0+
config.service.auth Definiert, wie sich das selbstgehostete Gateway bei der Konfigurations-API authentifizieren soll. Derzeit werden Gatewaytoken und Microsoft Entra-Authentifizierung unterstützt. Ja – v2.0+
config.service.auth.azureAd.tenantId ID des Microsoft Entra-Mandanten. Ja, bei Verwendung der Microsoft Entra-Authentifizierung Nicht zutreffend v2.3+
config.service.auth.azureAd.clientId Client-ID der Microsoft Entra-App für die Authentifizierung (auch als Anwendungs-ID bezeichnet). Ja, bei Verwendung der Microsoft Entra-Authentifizierung Nicht zutreffend v2.3+
config.service.auth.azureAd.clientSecret Geheimnis der Microsoft Entra-App für die Authentifizierung. Ja, wenn Microsoft Entra-Authentifizierung verwendet wird (sofern kein Zertifikat angegeben ist) Nicht zutreffend v2.3+
config.service.auth.azureAd.certificatePath Pfad zum Zertifikat, mit dem sich die Microsoft Entra-App authentifizieren soll. Ja, wenn Microsoft Entra-Authentifizierung verwendet wird (sofern kein Geheimnis angegeben ist) Nicht zutreffend v2.3+
config.service.auth.azureAd.authority Autoritäts-URL der Microsoft Entra ID. Nein https://login.microsoftonline.com v2.3+
config.service.auth.tokenAudience Zielgruppe des für die Microsoft Entra-Authentifizierung verwendeten Tokens Nein https://azure-api.net/configuration v2.3+
config.service.endpoint.disableCertificateValidation Definiert, ob das selbstgehostete Gateway das serverseitige Zertifikat der Konfigurations-API überprüfen soll. Es wird empfohlen, die Zertifikatüberprüfung zu verwenden und diese nur zu Testzwecken und mit größter Vorsicht zu deaktivieren, da dies ein Sicherheitsrisiko mit sich bringen kann. Nein false v2.0+
config.service.integration.timeout Definiert das Timeout für die Interaktion mit der Konfigurations-API. Nein 00:01:40 v2.3.5+

Das selbstgehostete Gateway bietet Unterstützung für ein paar Authentifizierungsoptionen zur Integration in die Konfigurations-API, die mithilfe von config.service.auth definiert werden können.

Dieser Leitfaden hilft Ihnen dabei, die erforderlichen Informationen bereitzustellen, um zu definieren, wie die Authentifizierung erfolgen soll:

  • Geben Sie für die auf Gatewaytoken basierende Authentifizierung ein Zugriffstoken (Authentifizierungsschlüssel) des selbstgehosteten Gateways im Azure-Portal unter Gateways>Bereitstellung an.
  • Geben Sie für die Microsoft Entra ID-basierte Authentifizierung azureAdApp an, und stellen Sie die zusätzlichen config.service.auth.azureAd-Authentifizierungseinstellungen bereit.

Instanzübergreifende Erkennung und Synchronisierung

Name BESCHREIBUNG Erforderlich Standard Verfügbarkeit
neighborhood.host DNS-Name, der verwendet wird, um alle Instanzen einer selbstgehosteten Gatewaybereitstellung für die instanzenübergreifende Synchronisierung aufzulösen. In Kubernetes kann dies mithilfe eines Headless-Diensts erreicht werden. Nein – v2.0+
neighborhood.heartbeat.port UDP-Port, der für Instanzen einer selbstgehosteten Gatewaybereitstellung verwendet wird, um Heartbeats an andere Instanzen zu senden. Nein 4.291 v2.0+
policy.rate-limit.sync.port UDP-Port, der für selbstgehostete Gatewayinstanzen verwendet wird, um die Ratenbegrenzung über mehrere Instanzen hinweg zu synchronisieren. Nein 4290 v2.0+

HTTP

Name BESCHREIBUNG Erforderlich Standard Verfügbarkeit
net.server.http.forwarded.proto.enabled Funktion zum Berücksichtigen X-Forwarded-Proto des Headers zum Identifizieren des Schemas zum Auflösen der aufgerufenen API-Route (nur http/https). No false v2.5+

Kubernetes-Integration

Ingress von Kubernetes

Wichtig

Die Unterstützung für Kubernetes Ingress ist derzeit experimentell und wird nicht über den Azure-Support abgedeckt. Erfahren Sie mehr über GitHub.

Name BESCHREIBUNG Erforderlich Standard Verfügbarkeit
k8s.ingress.enabled Aktivieren Sie die Kubernetes Ingress-Integration. Nein false v1.2+
k8s.ingress.namespace Kubernetes-Namespace zum Überwachen von Kubernetes Ingress-Ressourcen. Nein default v1.2+
k8s.ingress.dns.suffix DNS-Suffix zum Erstellen des DNS-Hostnamens für Dienste zum Senden von Anforderungen an. Nein svc.cluster.local v2.4+
k8s.ingress.config.path Pfad zur Kubernetes-Konfiguration (Kubeconfig). Nein – v2.4+

metrics

Name BESCHREIBUNG Erforderlich Standard Verfügbarkeit
telemetry.metrics.local Aktivieren Sie die Erfassung lokaler Metriken über StatsD. Der Wert ist eine der folgenden Optionen: none, statsd. Nein none v2.0+
telemetry.metrics.local.statsd.endpoint StatsD-Endpunkt. Ja, wenn telemetry.metrics.local auf statsd festgelegt ist; andernfalls nein. – v2.0+
telemetry.metrics.local.statsd.sampling Abtastrate der StatsD-Metriken. Der Wert muss zwischen 0 und 1 liegen, z. B. 0,5. Nein – v2.0+
telemetry.metrics.local.statsd.tag-format Taggingformat der Exportfunktion von StatsD. Der Wert ist eine der folgenden Optionen: ibrato, dogStatsD, influxDB. Nein – v2.0+
telemetry.metrics.cloud Angabe, ob die Ausgabe von Metriken an Azure Monitor aktiviert werden soll oder nicht. No true v2.0+
observability.opentelemetry.enabled Geben Sie an, ob Metriken an einen OpenTelemetrie-Sammler auf Kubernetes übergeben werden sollen. Nein false v2.0+
observability.opentelemetry.collector.uri URI des OpenTelemetry-Collectors, an den Metriken gesendet werden sollen. Ja, wenn observability.opentelemetry.enabled auf true festgelegt ist; andernfalls nein. – v2.0+
observability.opentelemetry.system-metrics.enabled Aktivieren des Sendens von Systemmetriken an den OpenTelemetry-Collector, z. B. CPU, Arbeitsspeicher, automatische Speicherbereinigung usw. Nein false v2.3+
observability.opentelemetry.histogram.buckets Histogramm-Buckets, in denen OpenTelemetry-Metriken gemeldet werden sollen. Format: "x,y,z,...". Nein "5,10,25,50,100,250,500,1000,2500,5000,10000" v2.0+

Protokolle

Name BESCHREIBUNG Erforderlich Standard Verfügbarkeit
telemetry.logs.std Aktivieren Sie die Protokollierung in einem Standardstream. Der Wert ist eine der folgenden Optionen: none, text, json. Nein text v2.0+
telemetry.logs.std.level Definiert den Protokolliergrad von Protokollen, die an Standardstream gesendet werden. Der Wert ist eine der folgenden Optionen: all, debug, info, warn, error oder fatal. Nein info v2.0+
telemetry.logs.std.color Gibt an, ob im Standardstream farbige Protokolle verwendet werden sollen. No true v2.0+
telemetry.logs.local Aktivieren Sie die lokale Protokollierung. Der Wert ist eine der folgenden Optionen: none, auto, localsyslog, rfc5424, journal, json. Nein auto v2.0+
telemetry.logs.local.localsyslog.endpoint localsyslog Endpunkt. Ja, wenn telemetry.logs.local auf localsyslog festgelegt ist; andernfalls nein. Weitere Informationen zur Konfiguration finden Sie in der lokalen Syslog-Dokumentation . N/V v2.0+
telemetry.logs.local.localsyslog.facility Gibt den Facilitycode für localsyslog an, zum Beispiel 7. Nein – v2.0+
telemetry.logs.local.rfc5424.endpoint rfc5424-Endpunkt. Ja, wenn telemetry.logs.local auf rfc5424 festgelegt ist; andernfalls nein. – v2.0+
telemetry.logs.local.rfc5424.facility Einrichtungscode pro rfc5424, z.B. 7 Nein – v2.0+
telemetry.logs.local.journal.endpoint Journalendpunkt. Ja, wenn telemetry.logs.local auf journal festgelegt ist; andernfalls nein. – v2.0+
telemetry.logs.local.json.endpoint UDP-Endpunkt, der JSON-Daten akzeptiert, angegeben als Dateipfad, IP:Port oder Hostname:Port. Ja, wenn telemetry.logs.local auf json festgelegt ist; andernfalls nein. 127.0.0.1:8888 v2.0+

Sicherheit

Zertifikate und Chiffre

Name BESCHREIBUNG Erforderlich Standard Verfügbarkeit
certificates.local.ca.enabled Gibt an, ob das selbstgehostete Gateway lokale CA-Zertifikate verwenden soll, die eingebunden sind, oder nicht. Es ist erforderlich, das selbstgehostete Gateway als „root“ oder mit der Benutzer-ID 1001 auszuführen. No false v2.0+
net.server.tls.ciphers.allowed-suites Durch Kommas getrennte Liste von Chiffren, die für die TLS-Verbindung zwischen dem API-Client und dem selbstgehosteten Gateway verwendet werden sollen. Nein 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 Durch Kommas getrennte Liste von Chiffren, die für die TLS-Verbindung zwischen dem selbstgehosteten Gateway und dem Back-End verwendet werden sollen. Nein 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 Bietet Funktionen zum Aktivieren/Deaktivieren der Überprüfung der Zertifikatsperrliste Nein false v2.3.6+

TLS

Name BESCHREIBUNG Erforderlich Standard Verfügbarkeit
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Back.Protocols.Tls13 Gibt an, ob TLS 1.3 für das Back-End zulässig ist. Ähnlich wie beim Verwalten von Protokollchiffre in verwaltetem Gateway. No true v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Back.Protocols.Tls12 Gibt an, ob TLS 1.2 für das Back-End zulässig ist. Ähnlich wie beim Verwalten von Protokollchiffre in verwaltetem Gateway. No true v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Back.Protocols.Tls11 Gibt an, ob TLS 1.1 für das Back-End zulässig ist. Ähnlich wie beim Verwalten von Protokollchiffre in verwaltetem Gateway. No false v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Back.Protocols.Tls10 Gibt an, ob TLS 1.0 für das Back-End zulässig ist. Ähnlich wie beim Verwalten von Protokollchiffre in verwaltetem Gateway. No false v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Back.Protocols.Ssl30 Gibt an, ob SSL 3.0 für das Back-End zulässig ist. Ähnlich wie beim Verwalten von Protokollchiffre in verwaltetem Gateway. No false v2.0+

Sovereign Clouds

Hier ist eine Übersicht über Einstellungen, die so konfiguriert werden müssen, dass sie mit souveränen Clouds arbeiten können:

Name Öffentlich Azure China US Government
config.service.auth.tokenAudience https://azure-api.net/configuration (Standard) https://azure-api.cn/configuration https://azure-api.us/configuration
logs.applicationinsights.endpoint https://dc.services.visualstudio.com/v2/track (Standard) https://dc.applicationinsights.azure.cn/v2/track https://dc.applicationinsights.us/v2/track

So konfigurieren Sie Einstellungen

Kubernetes-YAML-Datei

Konfigurieren Sie beim Bereitstellen des selbstgehosteten Gateways in Kubernetes mithilfe einer YAML-Datei Einstellungen als Name/Wert-Paare im dataElement der ConfigMap des Gateways. Beispiel:

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-Chart

Wenn Sie Helm verwenden, um das selbst gehostete Gateway für Kubernetes bereitzustellen, übergeben Sie Diagrammkonfigurationseinstellungen als Parameter an den helm install Befehl. Beispiel:

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

Nächste Schritte