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

项目
08/14/2024

可用性

重要

此功能在 API 管理的“高级”和“开发人员”层中可用。

本文提供了用于配置 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`，则为“是”；否则为“否”。有关配置的更多详细信息，请参阅本地 syslog 文档。	空值	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+

TLS

名称	说明	需要	默认	可用性
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls13	指示是否允许对后端使用 TLS 1.3。类似于管理托管网关中的协议密码。	否	`true`	v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls12	指示是否允许对后端使用 TLS 1.2。类似于管理托管网关中的协议密码。	否	`true`	v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls11	指示是否允许对后端使用 TLS 1.1。类似于管理托管网关中的协议密码。	否	`false`	v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls10	指示是否允许对后端使用 TLS 1.0。类似于管理托管网关中的协议密码。	否	`false`	v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Ssl30	指示是否允许对后端使用 SSL 3.0。类似于管理托管网关中的协议密码。	否	`false`	v2.0+

主权云

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

名称	由世纪互联运营的 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

通过