Reference: Self-hosted gateway container configuration settings

Availability

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.

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

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

• Learn more about guidance for running the self-hosted gateway on Kubernetes in production

• Deploy self-hosted gateway to Docker

• Deploy self-hosted gateway to Kubernetes

• Enable Dapr support on self-hosted gateway