Reference: Self-hosted gateway container configuration settings

  • Article

Availability

Important

This feature is available in the Premium and Developer tiers of API Management.

This article provides a reference for required and optional settings that are used to configure the API Management self-hosted gateway container.

To learn more about our (Kubernetes) production guidance, we recommend reading this article.

Important

This reference applies only to the self-hosted gateway v2. Minimum versions for availability of settings are provided.

Configuration API integration

The Configuration API is used by the self-hosted gateway to connect to Azure API Management to get the latest configuration and send metrics, when enabled.

Here is an overview of all configuration options:

Name Description Required Default Availability
gateway.name ID of the self-hosted gateway resource. Yes, when using Microsoft Entra authentication N/A v2.3+
config.service.endpoint Configuration endpoint in Azure API Management for the self-hosted gateway. Find this value in the Azure portal under Gateways > Deployment. Yes N/A v2.0+
config.service.auth Defines how the self-hosted gateway should authenticate to the Configuration API. Currently gateway token and Microsoft Entra authentication are supported. Yes N/A v2.0+
config.service.auth.azureAd.tenantId ID of the Microsoft Entra tenant. Yes, when using Microsoft Entra authentication N/A v2.3+
config.service.auth.azureAd.clientId Client ID of the Microsoft Entra app to authenticate with (also known as application ID). Yes, when using Microsoft Entra authentication N/A v2.3+
config.service.auth.azureAd.clientSecret Secret of the Microsoft Entra app to authenticate with. Yes, when using Microsoft Entra authentication (unless certificate is specified) N/A v2.3+
config.service.auth.azureAd.certificatePath Path to certificate to authenticate with for the Microsoft Entra app. Yes, when using Microsoft Entra authentication (unless secret is specified) N/A v2.3+
config.service.endpoint.disableCertificateValidation Defines if the self-hosted gateway should validate the server-side certificate of the Configuration API. It is recommended to use certificate validation, only disable for testing purposes and with caution as it can introduce security risk. No false v2.0+

The self-hosted gateway provides support for a few authentication options to integrate with the Configuration API which can be defined by using config.service.auth.

This guidance helps you provide the required information to define how to authenticate:

  • For gateway token-based authentication, specify an access token (authentication key) of the self-hosted gateway in the Azure portal under Gateways > Deployment.
  • For Microsoft Entra ID-based authentication, specify azureAdApp and provide the additional config.service.auth.azureAd authentication settings.

Cross-instance discovery & synchronization

Name Description Required Default Availability
neighborhood.host DNS name used to resolve all instances of a self-hosted gateway deployment for cross-instance synchronization. In Kubernetes, it can be achieved by using a headless Service. No N/A v2.0+
neighborhood.heartbeat.port UDP port used for instances of a self-hosted gateway deployment to send heartbeats to other instances. No 4291 v2.0+
policy.rate-limit.sync.port UDP port used for self-hosted gateway instances to synchronize rate limiting across multiple instances. No 4290 v2.0+

HTTP

Name Description Required Default Availability
net.server.http.forwarded.proto.enabled Capability to honor X-Forwarded-Proto header to identify scheme to resolve called API route (http/https only). No false v2.5+

Kubernetes Integration

Kubernetes Ingress

Important

Support for Kubernetes Ingress is currently experimental and not covered through Azure Support. Learn more on GitHub.

Name Description Required Default Availability
k8s.ingress.enabled Enable Kubernetes Ingress integration. No false v1.2+
k8s.ingress.namespace Kubernetes namespace to watch Kubernetes Ingress resources in. No default v1.2+
k8s.ingress.dns.suffix DNS suffix to build DNS hostname for services to send requests to. No svc.cluster.local v2.4+
k8s.ingress.config.path Path to Kubernetes configuration (Kubeconfig). No N/A v2.4+

Metrics

Name Description Required Default Availability
telemetry.metrics.local Enable local metrics collection through StatsD. Value is one of the following options: none, statsd. No none v2.0+
telemetry.metrics.local.statsd.endpoint StatsD endpoint. Yes, if telemetry.metrics.local is set to statsd; otherwise no. N/A v2.0+
telemetry.metrics.local.statsd.sampling StatsD metrics sampling rate. Value must be between 0 and 1, for example, 0.5. No N/A v2.0+
telemetry.metrics.local.statsd.tag-format StatsD exporter tagging format. Value is one of the following options: ibrato, dogStatsD, influxDB. No N/A v2.0+
telemetry.metrics.cloud Indication whether or not to enable emitting metrics to Azure Monitor. No true v2.0+
observability.opentelemetry.enabled Indication whether or not to enable emitting metrics to an OpenTelemetry collector on Kubernetes. No false v2.0+
observability.opentelemetry.collector.uri URI of the OpenTelemetry collector to send metrics to. Yes, if observability.opentelemetry.enabled is set to true; otherwise no. N/A v2.0+
observability.opentelemetry.system-metrics.enabled Enable sending system metrics to the OpenTelemetry collector such as CPU, memory, garbage collection, etc. No false v2.3+
observability.opentelemetry.histogram.buckets Histogram buckets in which OpenTelemetry metrics should be reported. Format: "x,y,z,...". No "5,10,25,50,100,250,500,1000,2500,5000,10000" v2.0+

Logs

Name Description Required Default Availability
telemetry.logs.std Enable logging to a standard stream. Value is one of the following options: none, text, json. No text v2.0+
telemetry.logs.std.level Defines the log level of logs sent to standard stream. Value is one of the following options: all, debug, info, warn, error or fatal. No info v2.0+
telemetry.logs.std.color Indication whether or not colored logs should be used in standard stream. No true v2.0+
telemetry.logs.local Enable local logging. Value is one of the following options: none, auto, localsyslog, rfc5424, journal, json No auto v2.0+
telemetry.logs.local.localsyslog.endpoint localsyslog endpoint. Yes if telemetry.logs.local is set to localsyslog; otherwise no. See local syslog documentation for more details on configuration. N/A v2.0+
telemetry.logs.local.localsyslog.facility Specifies localsyslog facility code, for example, 7. No N/A v2.0+
telemetry.logs.local.rfc5424.endpoint rfc5424 endpoint. Yes if telemetry.logs.local is set to rfc5424; otherwise no. N/A v2.0+
telemetry.logs.local.rfc5424.facility Facility code per rfc5424, for example, 7 No N/A v2.0+
telemetry.logs.local.journal.endpoint Journal endpoint. Yes if telemetry.logs.local is set to journal; otherwise no. N/A v2.0+
telemetry.logs.local.json.endpoint UDP endpoint that accepts JSON data, specified as file path, IP:port, or hostname:port. Yes if telemetry.logs.local is set to json; otherwise no. 127.0.0.1:8888 v2.0+

Security

Certificates and Ciphers

Name Description Required Default Availability
certificates.local.ca.enabled Indication whether or not the self-hosted gateway should use local CA certificates that are mounted. It's required to run the self-hosted gateway as root or with user ID 1001. No false v2.0+
net.server.tls.ciphers.allowed-suites Comma-separated list of ciphers to use for TLS connection between API client and the self-hosted gateway. 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 Comma-separated list of ciphers to use for TLS connection between the self-hosted gateway and the backend. 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 Provides capability to turn certificate revocation list validation on/off No false v2.3.6+

TLS

Name Description Required Default Availability
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls13 Indication whether or not TLS 1.3 is allowed towards the backend. Similar to managing protocol ciphers in managed gateway. No true v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls12 Indication whether or not TLS 1.2 is allowed towards the backend. Similar to managing protocol ciphers in managed gateway. No true v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls11 Indication whether or not TLS 1.1 is allowed towards the backend. Similar to managing protocol ciphers in managed gateway. No false v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls10 Indication whether or not TLS 1.0 is allowed towards the backend. Similar to managing protocol ciphers in managed gateway. No false v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Ssl30 Indication whether or not SSL 3.0 is allowed towards the backend. Similar to managing protocol ciphers in managed gateway. No false v2.0+

Sovereign clouds

Here is an overview of settings that need to be configured to be able to work with sovereign clouds:

Name Azure operated by 21Vianet
config.service.auth.tokenAudience https://azure-api.cn/configuration
logs.applicationinsights.endpoint https://dc.applicationinsights.azure.cn/v2/track

How to configure settings

Kubernetes YAML file

When deploying the self-hosted gateway to Kubernetes using a YAML file, configure settings as name-value pairs in the data element of the gateway's ConfigMap. For example:

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

[...]

Helm chart

When using Helm to deploy the self-hosted gateway to Kubernetes, pass chart configuration settings as parameters to the helm install command. For example:

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

Next steps