Condividi tramite

Riferimento: Impostazioni di configurazione del contenitore del gateway self-hosted

  • Articolo

SI APPLICA A: Sviluppatore | Premium

Questo articolo fornisce informazioni di riferimento per le impostazioni obbligatorie e facoltative usate per configurare il contenitore del gateway self-hosted Gestione API.

Per altre informazioni sulle linee guida per la produzione (Kubernetes), è consigliabile leggere questo articolo.

Importante

Questo riferimento si applica solo al gateway self-hosted v2. Vengono fornite versioni minime per la disponibilità delle impostazioni.

Integrazione dell'API di configurazione

L'API di configurazione viene usata dal gateway self-hosted per connettersi ad Azure Gestione API per ottenere la configurazione più recente e inviare le metriche, se abilitata.

Ecco una panoramica di tutte le opzioni di configurazione:

Nome Descrizione Richiesto Valore predefinito Disponibilità
gateway.name ID della risorsa gateway self-hosted. Sì, quando si usa l'autenticazione Microsoft Entra N/D v2.3+
config.service.endpoint Endpoint di configurazione in Azure Gestione API per il gateway self-hosted. Trovare questo valore nella portale di Azure in Distribuzione gateway>. Sì N/D v2.0+
config.service.auth Definisce il modo in cui il gateway self-hosted deve eseguire l'autenticazione all'API di configurazione. Attualmente sono supportati il token del gateway e l'autenticazione di Microsoft Entra. Sì N/D v2.0+
config.service.auth.azureAd.tenantId ID del tenant di Microsoft Entra. Sì, quando si usa l'autenticazione Microsoft Entra N/D v2.3+
config.service.auth.azureAd.clientId ID client dell'app Microsoft Entra per l'autenticazione con (noto anche come ID applicazione). Sì, quando si usa l'autenticazione Microsoft Entra N/D v2.3+
config.service.auth.azureAd.clientSecret Segreto dell'app Microsoft Entra con cui eseguire l'autenticazione. Sì, quando si usa l'autenticazione Microsoft Entra (a meno che non sia specificato il certificato) N/D v2.3+
config.service.auth.azureAd.certificatePath Percorso del certificato con cui eseguire l'autenticazione per l'app Microsoft Entra. Sì, quando si usa l'autenticazione Microsoft Entra (a meno che non venga specificato il segreto) N/D v2.3+
config.service.auth.azureAd.authority URL autorità di Microsoft Entra ID. No https://login.microsoftonline.com v2.3+
config.service.auth.tokenAudience Destinatari del token usato per l'autenticazione di Microsoft Entra No https://azure-api.net/configuration v2.3+
config.service.endpoint.disableCertificateValidation Definisce se il gateway self-hosted deve convalidare il certificato lato server dell'API di configurazione. È consigliabile usare la convalida dei certificati, disabilitare solo a scopo di test e con cautela perché può introdurre rischi per la sicurezza. No false v2.0+
config.service.integration.timeout Definisce il timeout per interagire con l'API di configurazione. No 00:01:40 v2.3.5+

Il gateway self-hosted offre supporto per alcune opzioni di autenticazione da integrare con l'API di configurazione che può essere definita tramite config.service.auth.

Queste indicazioni consentono di fornire le informazioni necessarie per definire come eseguire l'autenticazione:

  • Per l'autenticazione basata su token del gateway, specificare un token di accesso (chiave di autenticazione) del gateway self-hosted nella portale di Azure in Distribuzione gateway>.
  • Per l'autenticazione basata su ID Di Microsoft Entra specificare e specificare azureAdApp le impostazioni di autenticazione aggiuntive config.service.auth.azureAd .

Individuazione e sincronizzazione tra istanze

Nome Descrizione Richiesto Valore predefinito Disponibilità
neighborhood.host Nome DNS usato per risolvere tutte le istanze di una distribuzione del gateway self-hosted per la sincronizzazione tra istanze. In Kubernetes può essere ottenuto usando un servizio headless. No N/D v2.0+
neighborhood.heartbeat.port Porta UDP usata per le istanze di una distribuzione di gateway self-hosted per inviare heartbeat ad altre istanze. No 4291 v2.0+
policy.rate-limit.sync.port Porta UDP usata per le istanze del gateway self-hosted per sincronizzare la limitazione della frequenza tra più istanze. No 4290 v2.0+

HTTP

Nome Descrizione Richiesto Valore predefinito Disponibilità
net.server.http.forwarded.proto.enabled Capacità di rispettare X-Forwarded-Proto l'intestazione per identificare lo schema da risolvere denominato route API (solo http/https). No false v2.5+

Integrazione di Kubernetes

Ingresso di Kubernetes

Importante

Il supporto per l'ingresso di Kubernetes è attualmente sperimentale e non è coperto dal supporto tecnico di Azure. Altre informazioni su GitHub.

Nome Descrizione Richiesto Valore predefinito Disponibilità
k8s.ingress.enabled Abilitare l'integrazione in ingresso di Kubernetes. No false v1.2+
k8s.ingress.namespace Spazio dei nomi Kubernetes per controllare le risorse in ingresso di Kubernetes. No default v1.2+
k8s.ingress.dns.suffix Suffisso DNS per compilare il nome host DNS per i servizi a cui inviare richieste. No svc.cluster.local v2.4+
k8s.ingress.config.path Percorso della configurazione di Kubernetes (Kubeconfig). No N/D v2.4+

Metriche

Nome Descrizione Richiesto Valore predefinito Disponibilità
telemetry.metrics.local Abilitare la raccolta delle metriche locali tramite StatsD. Il valore è una delle opzioni seguenti: none, statsd. No none v2.0+
telemetry.metrics.local.statsd.endpoint Endpoint StatsD. Sì, se telemetry.metrics.local è impostato su statsd; in caso contrario, no. N/D v2.0+
telemetry.metrics.local.statsd.sampling Frequenza di campionamento delle metriche StatsD. Il valore deve essere compreso tra 0 e 1, ad esempio 0,5. No N/D v2.0+
telemetry.metrics.local.statsd.tag-format L'utilità di esportazione StatsD formato di assegnazione di tag. Value è una delle opzioni seguenti: ibrato, dogStatsD, influxDB. No N/D v2.0+
telemetry.metrics.cloud Indica se abilitare o meno la creazione di metriche in Monitoraggio di Azure. No true v2.0+
observability.opentelemetry.enabled Indica se abilitare o meno la creazione di metriche a un agente di raccolta OpenTelemetry in Kubernetes. No false v2.0+
observability.opentelemetry.collector.uri URI dell'agente di raccolta OpenTelemetry a cui inviare le metriche. Sì, se observability.opentelemetry.enabled è impostato su true; in caso contrario, no. N/D v2.0+
observability.opentelemetry.system-metrics.enabled Abilitare l'invio delle metriche di sistema all'agente di raccolta OpenTelemetry, ad esempio CPU, memoria, Garbage Collection e così via. No false v2.3+
observability.opentelemetry.histogram.buckets Bucket istogrammi in cui devono essere segnalate le metriche OpenTelemetry. Formato: "x,y,z,...". No "5,10,25,50,100,250,500,1000,2500,5000,10000" v2.0+

Registri

Nome Descrizione Richiesto Valore predefinito Disponibilità
telemetry.logs.std Abilitare la registrazione in un flusso standard. Value è una delle opzioni seguenti: none, text, json. No text v2.0+
telemetry.logs.std.level Definisce il livello di log dei log inviati al flusso standard. Value è una delle opzioni seguenti: all, debug, info, warnerror o fatal. No info v2.0+
telemetry.logs.std.color Indica se i log colorati devono essere usati nel flusso standard. No true v2.0+
telemetry.logs.local Abilitare la registrazione locale. Value è una delle opzioni seguenti: none, auto, localsyslog, rfc5424, journaljson No auto v2.0+
telemetry.logs.local.localsyslog.endpoint endpoint localsyslog. Sì se telemetry.logs.local è impostato su localsyslog; in caso contrario, no. Per altre informazioni sulla configurazione, vedere la documentazione di syslog locale. N/D v2.0+
telemetry.logs.local.localsyslog.facility Specifica il codice della struttura localsyslog, 7ad esempio . No N/D v2.0+
telemetry.logs.local.rfc5424.endpoint rfc5424 endpoint. Sì se telemetry.logs.local è impostato su rfc5424; in caso contrario, no. N/D v2.0+
telemetry.logs.local.rfc5424.facility Codice della struttura per rfc5424, ad esempio 7 No N/D v2.0+
telemetry.logs.local.journal.endpoint Endpoint journal. Sì se telemetry.logs.local è impostato su journal; in caso contrario, no. N/D v2.0+
telemetry.logs.local.json.endpoint Endpoint UDP che accetta dati JSON, specificati come percorso file, IP:port o hostname:port. Sì se telemetry.logs.local è impostato su json; in caso contrario, no. 127.0.0.1:8888 v2.0+

Sicurezza

Certificati e crittografie

Nome Descrizione Richiesto Valore predefinito Disponibilità
certificates.local.ca.enabled Indica se il gateway self-hosted deve usare certificati CA locali montati. È necessario eseguire il gateway self-hosted come radice o con ID utente 1001. No false v2.0+
net.server.tls.ciphers.allowed-suites Elenco delimitato da virgole di crittografie da usare per la connessione TLS tra il client API e il gateway self-hosted. No 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 Elenco delimitato da virgole di crittografie da usare per la connessione TLS tra il gateway self-hosted e il back-end. No 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 Offre la possibilità di attivare/disattivare la convalida dell'elenco di revoche di certificati No false v2.3.6+

TLS

Nome Descrizione Richiesto Valore predefinito Disponibilità
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls13 Indica se TLS 1.3 è consentito o meno verso il back-end. Analogamente alla gestione delle crittografie dei protocolli nel gateway gestito. No true v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls12 Indica se TLS 1.2 è consentito verso il back-end. Analogamente alla gestione delle crittografie dei protocolli nel gateway gestito. No true v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls11 Indica se TLS 1.1 è consentito verso il back-end. Analogamente alla gestione delle crittografie dei protocolli nel gateway gestito. No false v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls10 Indica se TLS 1.0 è consentito o meno verso il back-end. Analogamente alla gestione delle crittografie dei protocolli nel gateway gestito. No false v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Ssl30 Indica se SSL 3.0 è consentito verso il back-end. Analogamente alla gestione delle crittografie dei protocolli nel gateway gestito. No false v2.0+

Cloud sovrani

Ecco una panoramica delle impostazioni che devono essere configurate per poter usare i cloud sovrani:

Nome Pubblico Azure Cina US Government
config.service.auth.tokenAudience https://azure-api.net/configuration (impostazione predefinita) https://azure-api.cn/configuration https://azure-api.us/configuration
logs.applicationinsights.endpoint https://dc.services.visualstudio.com/v2/track (impostazione predefinita) https://dc.applicationinsights.azure.cn/v2/track https://dc.applicationinsights.us/v2/track

Come configurare le impostazioni

File YAML di Kubernetes

Quando si distribuisce il gateway self-hosted in Kubernetes usando un file YAML, configurare le impostazioni come coppie nome-valore nell'elemento data dell'oggetto ConfigMap del gateway. Ad esempio:

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"

[...]

Grafico Helm

Quando si usa Helm per distribuire il gateway self-hosted in Kubernetes, passare le impostazioni di configurazione del grafico come parametri al helm install comando. Ad esempio:

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

Passaggi successivi