使用应用程序路由加载项为 Azure Kubernetes 服务 (AKS) 设置自定义域名和 SSL 证书

注意

Kubernetes SIG Network和安全响应委员会宣布即将停用 Ingress NGINX项目，维护将于2026年3月结束。目前，使用 NGINX 的应用程序路由加载项的 AKS 群集无需立即执行任何操作。 Microsoft将为应用程序路由加载项的NGINX Ingress资源的重要安全补丁提供正式支持，支持截止至2026年11月。

AKS 正在迁移到网关 API，这将作为入口和 L7 流量管理的长期标准，以便与上游 Kubernetes 社区保持一致。建议根据当前设置开始规划迁移路径：

应用程序路由扩展用户：生产工作负荷在 2026 年 11 月之前仍受全面支持。迁移到应用程序路由网关 API 实现，以获得基于网关 API 的入口流量管理体验。
OSS NGINX 用户 有多个选项：
- 迁移到使用 NGINX 的应用程序路由加载项，在规划长期网关 API 迁移的同时，从官方支持（截至2026年11月）中受益。
- 迁移到应用程序路由网关 API 实现，以获得基于网关 API 的入口流量管理体验。
服务网格用户：如果计划采用服务网格，请考虑基于 Istio 的服务网格加载项。今天使用 Istio 入口，计划在正式发布为 GA 时迁移到 Istio 网关 API 支持。

本文介绍如何使用 Azure 密钥保管库、Azure DNS，以及 AKS 应用程序路由附加组件为 AKS 入口配置自定义域名和 SSL/TLS 证书。

先决条件

具有应用程序路由附加产品的 AKS 群集。
如果您希望配置 SSL 终止并将证书存储在托管于 Azure 的保管库中，请使用 Azure 密钥保管库（Azure 密钥保管库）。如果没有密钥保管库，请参阅使用 Azure CLI。
若要启用对 HTTPS 流量的支持，需要 SSL 证书。如果没有证书，请参阅创建证书。
Azure DNS 用于配置全局区域和专用区域管理，并在 Azure 中托管它们。如果没有Azure DNS区域，可以创建一个。若要启用对 DNS 区域的支持，请执行：
- 所有全局Azure DNS区域都需要位于同一资源组中，该资源组可能不同于群集资源组。
- 所有专用Azure DNS区域都需要位于同一资源组中，该资源组可能不同于群集资源组。
- 资源组不需要与群集位于同一订阅中。

所需的 Azure 权限

您的用户帐户需要：在您的Azure订阅中担任所有者、Azure帐户管理员或Azure共同管理员角色。

命令的作用：当您运行 az aks approuting update --attach-kv 或 az aks approuting zone add --attach-zones 时，这些命令会使用您的角色分配权限，自动为应用程序路由加载项的托管标识授予以下角色：

在您的 Azure 密钥保管库上具备 密钥保管库证书用户 角色（用于证书访问）。
DNS 区域参与者 角色在您的 Azure DNS 区域（用于 DNS 记录管理）。

有关 AKS 托管标识的详细信息，请参阅托管标识摘要。

连接到 AKS 群集

若要从本地计算机连接到 Kubernetes 群集，请使用 Kubernetes 命令行客户端 kubectl。可以使用 az aks install-cli 命令在本地安装它。

使用 az aks get-credentials 命令配置 kubectl 以连接到 Kubernetes 群集。

# Set environment variables for your resource group and cluster name
export RESOURCE_GROUP=<resource-group-name>
export CLUSTER_NAME=<cluster-name>

# Get the AKS cluster credentials
az aks get-credentials --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME

创建并导出自签名 SSL 证书

对于测试，你可以使用自签名公用证书，而不是使用证书颁发机构 (CA) 签名证书。如果已有证书，则可跳过此步骤。

注意

自签名证书是未由受信任的第三方 CA 签名的数字证书。负责网站或软件的公司或开发人员创建、颁发和签名这些证书。这就是为什么对于面向公众的网站和应用程序，自签名证书被视为不安全的原因。 Azure 密钥保管库与某些证书颁发机构建立了受信任的合作关系。

使用 openssl req 命令创建自签名 SSL 证书，以供入口控制使用。请确保将 <host-name> 替换为正在使用的 DNS 名称。

openssl req -new -x509 -nodes -out aks-ingress-tls.crt -keyout aks-ingress-tls.key -subj "/CN=<host-name>" -addext "subjectAltName=DNS:<host-name>"

使用 openssl pkcs12 -export 命令导出 SSL 证书并跳过密码提示。

openssl pkcs12 -export -in aks-ingress-tls.crt -inkey aks-ingress-tls.key -out aks-ingress-tls.pfx

将自签名 SSL 证书导入Azure 密钥保管库

使用 az keyvault certificate import 命令将 SSL 证书导入Azure 密钥保管库。如果证书受密码保护，则可以通过 --password 标志传递密码。

# Set environment variables for your key vault name and certificate name
export KEY_VAULT_NAME=<key-vault-name>
export KEY_VAULT_CERT_NAME=<key-vault-certificate-name>

# Import the SSL certificate into Azure Key Vault
az keyvault certificate import --vault-name $KEY_VAULT_NAME --name $KEY_VAULT_CERT_NAME --file aks-ingress-tls.pfx [--password <certificate password if specified>]

注意事项

若要启用应用程序路由加载项以在更改证书时从 Azure 密钥保管库重新加载证书，应启用密钥存储 CSI 驱动程序的密钥自动轮换功能。启用自动轮换后，驱动程序会根据您预设的轮换轮询间隔定期轮询变更，以更新 pod 挂载和 Kubernetes Secret。默认的轮换轮询间隔为两分钟。

启用Azure 密钥保管库集成

Azure 密钥保管库提供两个授权系统：Azure基于角色的访问控制（Azure RBAC），该模型在管理平面上运行，access 策略模型在管理平面和数据平面上运行。 --attach-kv操作选择适当的访问模型来使用。

使用 az keyvault show 命令获取key vault的资源 ID，并将输出设置为环境变量。
```
KEY_VAULT_ID=$(az keyvault show --name <KeyVaultName> --query "id" --output tsv)
```
更新应用程序路由加载项以启用机密存储 CSI 驱动程序的 Azure 密钥保管库提供程序，并使用带有 az aks approuting update 和 --enable-kv 参数的 --attach-kv 命令应用所需的角色分配。
```
az aks approuting update --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --enable-kv --attach-kv ${KEY_VAULT_ID}
```

创建全局Azure DNS区域

如果已有Azure DNS区域，则可以跳过此步骤。

使用 az network dns zone create 命令创建Azure DNS区域。

# Set environment variables for your resource group and DNS zone name
export RESOURCE_GROUP=<resource-group-name>
export ZONE_NAME=<zone-name>

# Create the Azure DNS zone
az network dns zone create --resource-group $RESOURCE_GROUP --name $ZONE_NAME

启用Azure DNS集成

使用 az network dns zone show 命令获取 DNS 区域的资源 ID，并将输出设置为环境变量。

ZONE_ID=$(az network dns zone show --resource-group $RESOURCE_GROUP --name $ZONE_NAME --query "id" --output tsv)

更新应用程序路由加载项，以使用 az aks approuting zone 命令启用Azure DNS集成。可以传递以逗号分隔的 DNS 区域资源 ID 列表。
```
az aks approuting zone add --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --ids=${ZONE_ID} --attach-zones
```

创建一个使用主机名和来自 Azure 密钥保管库的证书的 Ingress 类

应用程序路由加载项在群集上创建一个名为 webapprouting.kubernetes.azure.com 的 Ingress 类。使用此类创建 Ingress 对象时，会激活插件。

使用 az keyvault certificate show 命令从Azure 密钥保管库获取要用于入口的证书 URI。

az keyvault certificate show --vault-name $KEY_VAULT_NAME --name $KEY_VAULT_CERT_NAME --query "id" --output tsv

以下示例输出显示了从命令返回的证书 URI：

https://KeyVaultName.vault.azure.cn/certificates/KeyVaultCertificateName/ab12c34567d89e01f2345g6h78ijkl90

将以下 YAML 清单复制到名为 ingress.yaml 的新文件中，并将该文件保存到本地计算机。

将<host-name>替换为您的 DNS 主机名称，将<key-vault-certificate-uri>替换为上一命令返回的 URI。 <key-vault-certificate-uri>的字符串值应仅包含 https://yourkeyvault.vault.azure.cn/certificates/certname。删除 URI 字符串末尾的 证书版本 以获取当前版本。

secretName 部分中的 tls 密钥用于定义包含此 Ingress 资源证书的机密名称。当客户端浏览到 <host-name> 密钥中指定的 URL 时，将在浏览器中显示此证书。确保 secretName 的值等于 keyvault-，其后是入口资源名称的值（来自 metadata.name）。在示例 YAML 中，secretName 需要等于 keyvault-<your-ingress-name>。
```
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.azure.com/tls-cert-keyvault-uri: <key-vault-certificate-uri>
  name: aks-helloworld
  namespace: hello-web-app-routing
spec:
  ingressClassName: webapprouting.kubernetes.azure.com
  rules:
  - host: <host-name>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - <host-name>
    secretName: keyvault-<your-ingress-name>
```

使用 kubectl apply 命令创建群集资源。

kubectl apply -f ingress.yaml -n hello-web-app-routing

以下示例输出显示了已创建的资源：

Ingress.networking.k8s.io/aks-helloworld created

验证是否已创建托管入口

使用 kubectl get ingress 命令验证是否已创建托管入口。

kubectl get ingress -n hello-web-app-routing

以下示例输出显示了创建的托管入口：

NAME             CLASS                                HOSTS               ADDRESS       PORTS     AGE
aks-helloworld   webapprouting.kubernetes.azure.com   myapp.contoso.com   20.51.92.19   80, 443   4m

Last updated on 2026-04-10

Compartilhar via