参考：自承载网关容器配置设置

  • 项目

本文提供了用于配置 API 管理自承载网关容器的必需设置和可选设置的参考。

若要详细了解我们的 (Kubernetes) 生产指南，建议阅读此文章。

重要

此参考仅适用于自托管网关 v2。 我们提供了支持进行设置的最低版本。

配置 API 集成

配置 API 可供自承载网关用于连接到 Azure API 管理，以获取最新配置并发送指标（如果已启用）。

下面是所有配置选项的概述：

名称 说明 需要 默认 可用性
gateway.name 自承载网关资源的 ID。 是，在使用 Microsoft Entra 身份验证时 不可用 v2.3+
config.service.endpoint Azure API 管理中用于自托管网关的配置终结点。 在 Azure 门户中的“网关”>“部署”下找到此值。 是 空值 v2.0+
config.service.auth 定义自承载网关应如何向配置 API 进行身份验证。 目前支持网关令牌和 Microsoft Entra 身份验证。 是 空值 v2.0+
config.service.auth.azureAd.tenantId Microsoft Entra 租户的 ID。 是，在使用 Microsoft Entra 身份验证时 不可用 v2.3+
config.service.auth.azureAd.clientId 要用于进行身份验证的 Microsoft Entra 应用的客户端 ID（也称为应用程序 ID）。 是，在使用 Microsoft Entra 身份验证时 不可用 v2.3+
config.service.auth.azureAd.clientSecret 要用于进行身份验证的 Microsoft Entra 应用的机密。 是，在使用 Microsoft Entra 身份验证时（除非指定了证书） 不可用 v2.3+
config.service.auth.azureAd.certificatePath 用于对 Microsoft Entra 应用进行身份验证的证书的路径。 是，在使用 Microsoft Entra 身份验证时（除非指定了机密） 不可用 v2.3+
config.service.endpoint.disableCertificateValidation 定义自承载网关是否应验证配置 API 的服务器端证书。 建议使用证书验证，仅出于测试目的禁用，并谨慎使用，因为它可能会带来安全风险。 否 false v2.0+

自承载网关可为一些身份验证选项提供支持，以与可以使用 config.service.auth 定义的配置 API 集成。

本指南可帮助你提供定义如何进行身份验证所需的信息：

  • 对于基于网关令牌的身份验证，请在 Azure 门户的“网关”>“部署”下指定自承载网关的访问令牌（身份验证密钥）。
  • 对于基于 Microsoft Entra ID 的身份验证，请指定 azureAdApp 并提供其他 config.service.auth.azureAd 身份验证设置。

跨实例发现和同步

名称 说明 需要 默认 可用性
neighborhood.host 用于解析自承载网关部署的所有实例以实现跨实例同步的 DNS 名称。 在 Kubernetes 中，可以通过使用无头服务来实现。 否 空值 v2.0+
neighborhood.heartbeat.port 用于自承载网关部署实例的 UDP 端口，用于向其他实例发送检测信号。 否 4291 v2.0+
policy.rate-limit.sync.port 用于自承载网关实例的 UDP 端口，用于跨多个实例同步速率限制。 否 4290 v2.0+

HTTP

名称 说明 需要 默认 可用性
net.server.http.forwarded.proto.enabled 能够遵循 X-Forwarded-Proto 标头以识别用于解析调用的 API 路由的方案（仅限 http/https）。 否 false v2.5+

Kubernetes 集成

Kubernetes 入口

重要

对 Kubernetes 入口的支持目前是试验性的，不包含在 Azure 支持中。 在 GitHub 上了解详细信息。

名称 说明 需要 默认 可用性
k8s.ingress.enabled 启用 Kubernetes 入口集成。 否 false v1.2+
k8s.ingress.namespace 要在其中监视 Kubernetes 入口资源的 Kubernetes 命名空间。 否 default v1.2+
k8s.ingress.dns.suffix 用于生成 DNS 主机名的 DNS 后缀，以便服务向其发送请求。 否 svc.cluster.local v2.4+
k8s.ingress.config.path Kubernetes 配置的路径 (Kubeconfig)。 否 空值 v2.4+

指标

名称 说明 需要 默认 可用性
telemetry.metrics.local 通过 StatsD 启用本地指标收集。 值是以下选项之一：none、statsd。 否 none v2.0+
telemetry.metrics.local.statsd.endpoint StatsD 终结点。 如果 telemetry.metrics.local 设置为 statsd，则为“是”；否则为“否”。 空值 v2.0+
telemetry.metrics.local.statsd.sampling StatsD 指标采样率。 值必须介于 0 和 1 之间，例如 0.5。 否 空值 v2.0+
telemetry.metrics.local.statsd.tag-format StatsD 导出程序标记格式。 值是以下选项之一：ibrato、dogStatsD、influxDB。 否 空值 v2.0+
telemetry.metrics.cloud 指示是否启用向 Azure Monitor 发送指标。 否 true v2.0+
observability.opentelemetry.enabled 指示是否在 Kubernetes 上启用向 OpenTelemetry 收集器发送指标。 否 false v2.0+
observability.opentelemetry.collector.uri 要将指标发送到的 OpenTelemetry 收集器的 URI。 如果 observability.opentelemetry.enabled 设置为 true，则为“是”；否则为“否”。 空值 v2.0+
observability.opentelemetry.system-metrics.enabled 支持将系统指标发送到 OpenTelemetry 收集器，例如 CPU、内存、垃圾回收等。 否 false v2.3+
observability.opentelemetry.histogram.buckets 应该在其中报告 OpenTelemetry 指标的直方图 Bucket。 格式：“x,y,z,...”。 否 "5,10,25,50,100,250,500,1000,2500,5000,10000" v2.0+

日志

名称 说明 需要 默认 可用性
telemetry.logs.std 启用记录到标准流。 值是以下选项之一：none、text、json。 否 text v2.0+
telemetry.logs.std.level 定义发送到标准流的日志的日志级别。 值是以下选项之一：all、debug、info、warn、error 或 fatal。 否 info v2.0+
telemetry.logs.std.color 指示是否应在标准流中使用彩色日志。 否 true v2.0+
telemetry.logs.local 启用本地日志记录。 值是以下选项之一：none、auto、localsyslog、rfc5424、journal、json 否 auto v2.0+
telemetry.logs.local.localsyslog.endpoint localsyslog 终结点。 如果 telemetry.logs.local 设置为 localsyslog，则为“是”；否则为“否”。 空值 v2.0+
telemetry.logs.local.localsyslog.facility 指定 localsyslog 设备代码（例如 7）。 否 空值 v2.0+
telemetry.logs.local.rfc5424.endpoint rfc5424 终结点。 如果 telemetry.logs.local 设置为 rfc5424，则为“是”；否则为“否”。 空值 v2.0+
telemetry.logs.local.rfc5424.facility 每个 rfc5424 的设备代码（例如 7） 否 空值 v2.0+
telemetry.logs.local.journal.endpoint 日志终结点。 如果 telemetry.logs.local 设置为 journal，则为“是”；否则为“否”。 空值 v2.0+
telemetry.logs.local.json.endpoint 接受 JSON 数据的 UDP 终结点，指定为文件路径、IP:端口或主机名:端口。 如果 telemetry.logs.local 设置为 json，则为“是”；否则为“否”。 127.0.0.1:8888 v2.0+

安全性

名称 说明 需要 默认 可用性
certificates.local.ca.enabled 指示自托管网关是否应使用装载的本地 CA 证书。 需要以 root 身份或用户 ID 1001 运行自承载网关。 否 false v2.0+
net.server.tls.ciphers.allowed-suites 以逗号分隔的密码列表，用于在 API 客户端和自托管网关之间建立 TLS 连接。 否 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 以逗号分隔的密码列表，用于在自托管网关和后端之间建立 TLS 连接。 否 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 提供打开/关闭证书吊销列表验证的功能 否 false v2.3.6+

主权云

下面是需要配置为能够适配主权云的设置的概述：

名称 由世纪互联运营的 Azure
config.service.auth.tokenAudience https://azure-api.cn/configuration
logs.applicationinsights.endpoint https://dc.applicationinsights.azure.cn/v2/track

如何配置设置

Kubernetes YAML 文件

使用 YAML 文件将自托管网关部署到 Kubernetes 时，将设置配置为网关 ConfigMap 的 data 元素中的名称-值对。 例如：

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 图表

使用 Helm 将自托管网关部署到 Kubernetes 时，将图表配置设置作为参数传递给 helm install 命令。 例如：

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

后续步骤