Edit

Reference: Self-hosted gateway container configuration settings

  • Article
  • 3 minutes to read

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

Important

This reference applies only to the self-hosted gateway v2.

Deployment

Name Description Required Default
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
config.service.auth Access token (authentication key) of the self-hosted gateway. Find this value in the Azure portal under Gateways > Deployment. Yes N/A
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
neighborhood.heartbeat.port UDP port used for instances of a self-hosted gateway deployment to send heartbeats to other instances. No 4291
policy.rate-limit.sync.port UDP port used for self-hosted gateway instances to synchronize rate limiting across multiple instances. No 4290

Metrics

Name Description Required Default
telemetry.metrics.local Enable local metrics collection through StatsD. Value is one of the following options: none, statsd. No none
telemetry.metrics.local.statsd.endpoint StatsD endpoint. Yes, if telemetry.metrics.local is set to statsd; otherwise no. N/A
telemetry.metrics.local.statsd.sampling StatsD metrics sampling rate. Value must be between 0 and 1, for example, 0.5. No N/A
telemetry.metrics.local.statsd.tag-format StatsD exporter tagging format. Value is one of the following options: ibrato, dogStatsD, influxDB. No N/A
telemetry.metrics.cloud Indication whether or not to enable emitting metrics to Azure Monitor. No true
observability.opentelemetry.enabled Indication whether or not to enable emitting metrics to an OpenTelemetry collector on Kubernetes. No false
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
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"

Logs

Name Description Required Default
telemetry.logs.std Enable logging to a standard stream. Value is one of the following options: none, text, json. No text
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
telemetry.logs.std.color Indication whether or not colored logs should be used in standard stream. No true
telemetry.logs.local Enable local logging. Value is one of the following options: none, auto, localsyslog, rfc5424, journal, json No auto
telemetry.logs.local.localsyslog.endpoint localsyslog endpoint. Yes if telemetry.logs.local is set to localsyslog; otherwise no. N/A
telemetry.logs.local.localsyslog.facility Specifies localsyslog facility code, for example, 7. No N/A
telemetry.logs.local.rfc5424.endpoint rfc5424 endpoint. Yes if telemetry.logs.local is set to rfc5424; otherwise no. N/A
telemetry.logs.local.rfc5424.facility Facility code per rfc5424, for example, 7 No N/A
telemetry.logs.local.journal.endpoint Journal endpoint. Yes if telemetry.logs.local is set to journal; otherwise no. N/A
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

Security

Name Description Required Default
certificates.local.ca.enabled Indication whether or not to 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
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 N/A
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 N/A

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.net"
        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.net' \
    --set gateway.auth.key='GatewayKey contosogw&xxxxxxxxxxxxxx...' \
    --set secret.createSecret=false \
    --set secret.existingSecretName=`mysecret` \
    azure-apim-gateway/azure-api-management-gateway

Next steps