Compartilhar via

Referência: definições de configuração de contêiner de gateway auto-hospedado

  • Artigo

APLICA-SE A: Desenvolvedor | Premium

Este artigo fornece uma referência para configurações obrigatórias e opcionais que são usadas para configurar o contêiner de gateway auto-hospedado do Gerenciamento de API.

Para saber mais sobre nossas diretrizes de produção (Kubernetes), recomendamos a leitura deste artigo.

Importante

Esta referência se aplica apenas ao gateway auto-hospedado v2. Versões mínimas para disponibilidade de configurações são fornecidas.

Integração da API de configuração

A API de Configuração é usada pelo gateway auto-hospedado para se conectar ao Gerenciamento de API do Azure para obter a configuração mais recente e enviar métricas, quando habilitada.

Aqui está uma visão geral de todas as opções de configuração:

Nome Descrição Obrigatório Padrão Disponibilidade
gateway.name ID do recurso de gateway auto-hospedado. Sim, ao usar a autenticação do Microsoft Entra N/D v2.3+
config.service.endpoint Ponto de extremidade de configuração no Gerenciamento de API do Azure para o gateway auto-hospedado. Encontre este valor no portal do Azure em Gateways>Implantação. Sim N/D v2.0+
config.service.auth Define como o gateway auto-hospedado deve ser autenticado na API de Configuração. Atualmente, há suporte para token de gateway e autenticação do Microsoft Entra. Sim N/D v2.0+
config.service.auth.azureAd.tenantId ID do locatário do Microsoft Entra. Sim, ao usar a autenticação do Microsoft Entra N/D v2.3+
config.service.auth.azureAd.clientId ID do cliente do aplicativo Microsoft Entra para autenticação (também conhecida como ID do aplicativo). Sim, ao usar a autenticação do Microsoft Entra N/D v2.3+
config.service.auth.azureAd.clientSecret Segredo do aplicativo Microsoft Entra com o qual autenticar. Sim, ao usar a autenticação do Microsoft Entra (a menos que o certificado seja especificado) N/D v2.3+
config.service.auth.azureAd.certificatePath Caminho para o certificado a ser autenticado para o aplicativo Microsoft Entra. Sim, ao usar a autenticação do Microsoft Entra (a menos que o segredo seja especificado) N/D v2.3+
config.service.auth.azureAd.authority URL de autoridade da ID do Microsoft Entra. Não https://login.microsoftonline.com v2.3+
config.service.auth.tokenAudience Público-alvo do token usado para autenticação do Microsoft Entra Não https://azure-api.net/configuration v2.3+
config.service.endpoint.disableCertificateValidation Define se o gateway auto-hospedado deve validar o certificado do lado do servidor da API de Configuração. É recomendável usar a validação de certificado; desabilite-a apenas para fins de teste e com cuidado, pois isso pode introduzir riscos de segurança. No false v2.0+
config.service.integration.timeout Define o tempo limite para interagir com a API de Configuração. Não 00:01:40 v2.3.5+

O gateway auto-hospedado oferece suporte para algumas opções de autenticação a serem integradas à API de Configuração que pode ser definida usando config.service.auth.

Essas diretrizes ajudam você a fornecer as informações necessárias para definir como autenticar:

  • Para autenticação baseada em token de gateway, especifique um token de acesso (chave de autenticação) do gateway auto-hospedado no portal do Azure emImplantação>Gateways.
  • Para autenticação baseada em ID do Microsoft Entra, especifique azureAdApp e forneça as configurações de autenticação adicionais config.service.auth.azureAd.

Descoberta e sincronização entre instâncias

Nome Descrição Obrigatório Padrão Disponibilidade
neighborhood.host Nome DNS usado para resolver todas as instâncias de uma implantação de gateway auto-hospedada para sincronização entre instâncias. No Kubernetes, pode ser obtido usando um Serviço sem periféricos. Não N/D v2.0+
neighborhood.heartbeat.port Porta UDP usada para instâncias de uma implantação de gateway auto-hospedada para enviar pulsações para outras instâncias. Não 4291 v2.0+
policy.rate-limit.sync.port Porta UDP usada para instâncias de gateway auto-hospedadas para sincronizar a limitação de taxa em várias instâncias. Não 4290 v2.0+

HTTP

Nome Descrição Obrigatório Padrão Disponibilidade
net.server.http.forwarded.proto.enabled Capacidade de honrar X-Forwarded-Proto o cabeçalho para identificar o esquema a ser resolvido pela rota de API chamada (somente http/https). Não false v2.5+

Integração com Kubernetes

Entrada do Kubernetes

Importante

O suporte para o Kubernetes Ingress é atualmente experimental e não é coberto pelo Suporte do Azure. Saiba mais em GitHub.

Nome Descrição Obrigatório Padrão Disponibilidade
k8s.ingress.enabled Habilite a integração do Kubernetes Ingress. Não false v1.2+
k8s.ingress.namespace Namespace do Kubernetes para observar os recursos de entrada do Kubernetes. Não default v1.2+
k8s.ingress.dns.sufix Sufixo DNS para criar o nome de host DNS para os serviços para os quais enviar solicitações. Não svc.cluster.local v2.4+
k8s.ingress.config.path Caminho para a configuração do Kubernetes (Kubeconfig). Não N/D v2.4+

Métrica

Nome Descrição Obrigatório Padrão Disponibilidade
telemetry.metrics.local Habilite a coleta de métricas locais por meio do StatsD. O valor é uma das seguintes opções: none, statsd. No none v2.0+
telemetry.metrics.local.statsd.endpoint Ponto de extremidade StatsD. Sim, se telemetry.metrics.local estiver definido como statsd; caso contrário, não. N/D v2.0+
telemetry.metrics.local.statsd.sampling Taxa de amostragem de métricas do StatsD. O valor deve estar entre 0 e 1, por exemplo, 0,5. Não N/D v2.0+
telemetry.metrics.local.statsd.tag-format Formato de marcaçãode exportador do StatsD. O valor é uma das seguintes opções: ibrato, dogStatsD, influxDB. Não N/D v2.0+
telemetry.metrics.cloud Indica se você deve ou não habilitar a emissão de métricas para o Azure Monitor. No true v2.0+
observability.opentelemetry.enabled Indicação se deve ou não habilitar a emissão de métricas para um coletor OpenTelemetry no Kubernetes. No false v2.0+
observability.opentelemetry.collector.uri URI do coletor OpenTelemetry para enviar métricas. Sim, se observability.opentelemetry.enabled estiver definido como true; caso contrário, não. N/D v2.0+
observability.opentelemetry.system-metrics.enabled Habilite o envio de métricas do sistema para o coletor OpenTelemetry, como CPU, memória, coleta de lixo etc. Não false v2.3+
observability.opentelemetry.histogram.buckets Buckets de histograma nos quais as métricas do OpenTelemetry devem ser relatadas. Formato: "x,y,z,...". No "5,10,25,50,100,250,500,1000,2500,5000,10000" v2.0+

Logs

Nome Descrição Obrigatório Padrão Disponibilidade
telemetry.logs.std Habilite o registro em log em um fluxo padrão. O valor é uma das seguintes opções: none, text, json. Não text v2.0+
telemetry.logs.std.level Define o nível dos logs enviados ao fluxo padrão. O valor é uma das seguintes opções: all, debug, info, warn, error ou fatal. Não info v2.0+
telemetry.logs.std.color Indica se logs coloridos devem ou não ser usados no fluxo padrão. No true v2.0+
telemetry.logs.local Habilite o registro em log local. O valor é uma das seguintes opções: none, auto, localsyslog, rfc5424, journal, json No auto v2.0+
telemetry.logs.local.localsyslog.endpoint ponto de extremidade localsyslog. Sim, se telemetry.logs.local estiver definido como localsyslog; caso contrário, não. Consulte a documentação do syslog local para obter mais detalhes sobre a configuração. N/D v2.0+
telemetry.logs.local.localsyslog.facility Especifica o código do recurso, localsyslog, por exemplo,7. Não N/D v2.0+
telemetry.logs.local.rfc5424.endpoint ponto de extremidade rfc5424. Sim, se telemetry.logs.local estiver definido como rfc5424; caso contrário, não. N/D v2.0+
telemetry.logs.local.rfc5424.facility Código de instalação por rfc5424, por exemplo, 7 Não N/D v2.0+
telemetry.logs.local.journal.endpoint Ponto de extremidade do diário. Sim, se telemetry.logs.local estiver definido como journal; caso contrário, não. N/D v2.0+
telemetry.logs.local.json.endpoint Ponto de extremidade UDP que aceita dados JSON, especificados como caminho do arquivo, IP:porta ou nome do host:porta. Sim, se telemetry.logs.local estiver definido como json; caso contrário, não. 127.0.0.1:8888 v2.0+

Segurança

Certificados e cifras

Nome Descrição Obrigatório Padrão Disponibilidade
certificates.local.ca.enabled Indicação se o gateway auto-hospedado deve ou não usar certificados de CA locais que estão montados. É necessário executar o gateway auto-hospedado como root ou com o ID de usuário 1001. No false v2.0+
net.server.tls.ciphers.allowed-suites Lista de cifras separadas por vírgulas a serem usadas para conexão TLS entre o cliente de API e o gateway auto-hospedado. Não 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 Lista de cifras separadas por vírgulas a serem usadas para conexão TLS entre o gateway auto-hospedado e o back-end. Não 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 Fornece capacidade para ativar/desativar a validação da lista de revogação de certificado Não false v2.3.6+

TLS

Nome Descrição Obrigatório Padrão Disponibilidade
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls13 Indicação se o TLS 1.3 é permitido ou não para o back-end. Semelhante ao gerenciamento de cifras de protocolo no gateway gerenciado. Não true v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls12 Indicação se o TLS 1.2 é permitido ou não para o back-end. Semelhante ao gerenciamento de cifras de protocolo no gateway gerenciado. Não true v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls11 Indicação se o TLS 1.1 é permitido ou não para o back-end. Semelhante ao gerenciamento de cifras de protocolo no gateway gerenciado. Não false v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls10 Indicação se o TLS 1.0 é permitido ou não para o back-end. Semelhante ao gerenciamento de cifras de protocolo no gateway gerenciado. Não false v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Ssl30 Indicação se o SSL 3.0 é permitido ou não para o back-end. Semelhante ao gerenciamento de cifras de protocolo no gateway gerenciado. Não false v2.0+

Nuvens soberanas

Aqui está uma visão geral das configurações que precisam ser definidas para poder trabalhar com nuvens soberanas:

Nome Setor Público Azure China Governo dos EUA
config.service.auth.tokenAudience https://azure-api.net/configuration (Padrão) https://azure-api.cn/configuration https://azure-api.us/configuration
logs.applicationinsights.endpoint https://dc.services.visualstudio.com/v2/track (Padrão) https://dc.applicationinsights.azure.cn/v2/track https://dc.applicationinsights.us/v2/track

Como definir as configurações

Arquivo YAML do Kubernetes

Ao implantar o gateway auto-hospedado no Kubernetes usando um arquivo YAML, defina as configurações como pares nome-valor no elemento data do ConfigMap do gateway. Por exemplo:

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"

[...]

Gráfico Helm

Ao usar o Helm para implantar o gateway auto-hospedado no Kubernetes, passe as configurações do gráfico como parâmetros para o comando helm install. Por exemplo:

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

Próximas etapas