使用新的应用程序网关部署安装 AGIC

2025-09-29

本文中的说明假定你要在没有预先存在的组件的环境中安装应用程序网关入口控制器 (AGIC)。

安装所需的命令行工具

请确保已安装以下命令行工具：

az：Azure CLI（安装说明）
kubectl：Kubernetes 命令行工具（安装说明）
helm：Kubernetes 包管理器（安装说明）
jq：命令行 JSON 处理器（安装说明）

创建标识

使用以下步骤创建 Microsoft Entra 服务主体对象。

创建 Active Directory 服务主体，其中包括 Azure 基于角色的访问控制 (RBAC) 角色：
```
az ad sp create-for-rbac --role Contributor --scopes /subscriptions/mySubscriptionID -o json > auth.json
appId=$(jq -r ".appId" auth.json)
password=$(jq -r ".password" auth.json)
```
记录 JSON 输出中的 appId 和 password 值。您将在接下来的步骤中用到它们。
使用上一命令的输出中的 appId 值获取新服务主体的 id：
```
objectId=$(az ad sp show --id $appId --query "id" -o tsv)
```
此命令的输出为 objectId。记录此值，因为下一步中将用到它。

创建你将在 Azure 资源管理器模板（ARM 模板）部署中使用的参数文件：

cat <<EOF > parameters.json
{
  "aksServicePrincipalAppId": { "value": "$appId" },
  "aksServicePrincipalClientSecret": { "value": "$password" },
  "aksServicePrincipalObjectId": { "value": "$objectId" },
  "aksEnableRBAC": { "value": false }
}
EOF

若要部署已启用 Kubernetes RBAC 的群集，请将 aksEnableRBAC 设置为 true。

部署组件

以下过程会将这些组件添加到你的订阅：

部署组件：

下载 ARM 模板：

wget https://raw.githubusercontent.com/Azure/application-gateway-kubernetes-ingress/master/deploy/azuredeploy.json -O template.json

使用 Azure CLI 部署 ARM 模板，并根据需要对其进行修改。部署最多可能需要 5 分钟。

resourceGroupName="MyResourceGroup"
location="chinanorth2"
deploymentName="ingress-appgw"

# create a resource group
az group create -n $resourceGroupName -l $location

# modify the template as needed
az deployment group create \
        -g $resourceGroupName \
        -n $deploymentName \
        --template-file template.json \
        --parameters parameters.json

部署完成后，将部署输出下载到名为 deployment-outputs.json 的文件中：

az deployment group show -g $resourceGroupName -n $deploymentName --query "properties.outputs" -o json > deployment-outputs.json

设置 AGIC

根据上一部分中的说明，你创建并配置了新的 AKS 群集和应用程序网关部署。现在，你已准备好将一个示例应用和入口控制器部署到新的 Kubernetes 基础结构。

设置 Kubernetes 凭据

对于以下步骤，你需要设置 kubectl 命令，用于连接到新的 Kubernetes 群集。你将使用 az (Azure CLI) 获取 Kubernetes 的凭据。

获取新部署的 AKS 实例的凭据。有关以下命令的详细信息，请参阅通过 kubectl 将 Azure RBAC 用于 Kubernetes 授权。

# use the deployment-outputs.json file created after deployment to get the cluster name and resource group name
aksClusterName=$(jq -r ".aksClusterName.value" deployment-outputs.json)
resourceGroupName=$(jq -r ".resourceGroupName.value" deployment-outputs.json)

az aks get-credentials --resource-group $resourceGroupName --name $aksClusterName

安装 Microsoft Entra 工作负荷 ID

Microsoft Entra 工作负荷 ID 提供对 Azure 资源管理器的基于令牌的访问。

Microsoft Entra 工作负荷 ID 将以下组件添加到 Kubernetes 集群：

Kubernetes 自定义资源定义 (CRD)：AzureIdentity、AzureAssignedIdentity、AzureIdentityBinding
托管标识控制器 (MIC) 组件
节点托管标识 (NMI) 组件

若要将 Microsoft Entra 工作负荷 ID 安装到群集，请使用以下命令之一：

已启用 Kubernetes RBAC 的 AKS 群集：

kubectl create -f https://raw.githubusercontent.com/Azure/aad-pod-identity/master/deploy/infra/deployment-rbac.yaml

已禁用 Kubernetes RBAC 的 AKS 群集：

kubectl create -f https://raw.githubusercontent.com/Azure/aad-pod-identity/master/deploy/infra/deployment.yaml

添加 Helm 存储库

Helm 是 Kubernetes 的包管理器。你使用它来安装 application-gateway-kubernetes-ingress 包。

安装 Helm。运行以下命令之一添加 AGIC Helm 存储库：

已启用 Kubernetes RBAC 的 AKS 群集：

kubectl create serviceaccount --namespace kube-system tiller-sa
kubectl create clusterrolebinding tiller-cluster-rule --clusterrole=cluster-admin --serviceaccount=kube-system:tiller-sa
helm init --tiller-namespace kube-system --service-account tiller-sa

已禁用 Kubernetes RBAC 的 AKS 群集：
```
helm init
```

安装入口控制器的 Helm 图表

使用你之前创建的 deployment-outputs.json 文件创建以下变量：

applicationGatewayName=$(jq -r ".applicationGatewayName.value" deployment-outputs.json)
resourceGroupName=$(jq -r ".resourceGroupName.value" deployment-outputs.json)
subscriptionId=$(jq -r ".subscriptionId.value" deployment-outputs.json)
identityClientId=$(jq -r ".identityClientId.value" deployment-outputs.json)
identityResourceId=$(jq -r ".identityResourceId.value" deployment-outputs.json)

下载 helm-config.yaml，用于配置 AGIC：

wget https://raw.githubusercontent.com/Azure/application-gateway-kubernetes-ingress/master/docs/examples/sample-helm-config.yaml -O helm-config.yaml

或者复制以下 YAML 文件：

# This file contains the essential configs for the ingress controller helm chart

# Verbosity level of the App Gateway Ingress Controller
verbosityLevel: 3

################################################################################
# Specify which application gateway the ingress controller will manage
#
appgw:
    subscriptionId: <subscriptionId>
    resourceGroup: <resourceGroupName>
    name: <applicationGatewayName>
    environment: AzureChinaCloud

    # Setting appgw.shared to "true" will create an AzureIngressProhibitedTarget CRD.
    # This prohibits AGIC from applying config for any host/path.
    # Use "kubectl get AzureIngressProhibitedTargets" to view and change this.
    shared: false

################################################################################
# Specify which kubernetes namespace the ingress controller will watch
# Default value is "default"
# Leaving this variable out or setting it to blank or empty string would
# result in Ingress Controller observing all accessible namespaces.
#
# kubernetes:
#   watchNamespace: <namespace>

################################################################################
# Specify the authentication with Azure Resource Manager
#
# Two authentication methods are available:
# - Option 1: AAD-Pod-Identity (https://github.com/Azure/aad-pod-identity)
armAuth:
    type: aadPodIdentity
    identityResourceID: <identityResourceId>
    identityClientID:  <identityClientId>

## Alternatively you can use Service Principal credentials
# armAuth:
#    type: servicePrincipal
#    secretJSON: <<Generate this value with: "az ad sp create-for-rbac --subscription <subscription-uuid> --role Contributor --sdk-auth | base64 -w0" >>

################################################################################
# Specify if the cluster is Kubernetes RBAC enabled or not
rbac:
    enabled: false # true/false

# Specify aks cluster related information. THIS IS BEING DEPRECATED.
aksClusterConfiguration:
    apiServerAddress: <aks-api-server-address>

编辑新下载的 helm-config.yaml 文件，并填写 appgw 和 armAuth 的部分：
```
sed -i "s|<subscriptionId>|${subscriptionId}|g" helm-config.yaml
sed -i "s|<resourceGroupName>|${resourceGroupName}|g" helm-config.yaml
sed -i "s|<applicationGatewayName>|${applicationGatewayName}|g" helm-config.yaml
sed -i "s|<identityResourceId>|${identityResourceId}|g" helm-config.yaml
sed -i "s|<identityClientId>|${identityClientId}|g" helm-config.yaml
```
注意

如果要部署到主权云，则必须添加 appgw.environment 配置参数并将其设置为适当的值。

下面是值：
- verbosityLevel：设置 AGIC 日志记录基础结构的详细级别。有关可能的值，请参阅日志记录级别。
- appgw.environment：设置云环境。可能的值：AZURECHINACLOUD、AZUREGERMANCLOUD、AZUREPUBLICCLOUD。
- appgw.subscriptionId：应用程序网关所在的 Azure 订阅 ID。示例：aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e。
- appgw.resourceGroup：你在其中创建了应用程序网关部署的 Azure 资源组的名称。示例：app-gw-resource-group。
- appgw.name：应用程序网关部署的名称。示例：applicationgatewayd0f0。
- appgw.shared：布尔标志，默认为 false。如果需要true，请将其设置为。
- kubernetes.watchNamespace：指定 AGIC 应监视的命名空间。命名空间值可以是单字符串值，也可以是逗号分隔的命名空间列表。
- armAuth.type：可以是 aadPodIdentity 或 servicePrincipal。
- armAuth.identityResourceID：Azure 托管标识的资源 ID。
- armAuth.identityClientID：标识的客户端 ID。
- armAuth.secretJSON：仅在选择服务主体作为机密类型（即将 armAuth.type 设置为 servicePrincipal）时才需要。
注意

你在前面的步骤中为identityResourceID创建了 identityClientID 和值。可以使用以下命令再次获取它们：
```
az identity show -g <resource-group> -n <identity-name>
```
在该命令中，<resource-group> 是你的应用程序网关部署的资源组。 <identity-name> 占位符是创建的标识的名称。可以使用 az identity list 列出特定订阅的所有标识。

安装 AGIC 包：

helm install agic-controller oci://mcr.microsoft.com/azure-application-gateway/charts/ingress-azure --version 1.8.1 -f helm-config.yaml

安装示例应用

现在你已经安装了应用程序网关、AKS 和 AGIC，接下来可以安装示例应用：

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: aspnetapp
  labels:
    app: aspnetapp
spec:
  containers:
  - image: "mcr.microsoft.com/dotnet/samples:aspnetapp"
    name: aspnetapp-image
    ports:
    - containerPort: 8080
      protocol: TCP

---

apiVersion: v1
kind: Service
metadata:
  name: aspnetapp
spec:
  selector:
    app: aspnetapp
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080

---

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aspnetapp
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Exact
        backend:
          service:
            name: aspnetapp
            port:
              number: 80
        pathType: Exact
EOF

此外，也可以：

下载前面的 YAML 文件：

curl https://raw.githubusercontent.com/Azure/application-gateway-kubernetes-ingress/master/docs/examples/aspnetapp.yaml -o aspnetapp.yaml

应用 YAML 文件：
```
kubectl apply -f aspnetapp.yaml
```

有关如何使用应用程序网关通过 HTTP 或 HTTPS 向 Internet 公开 AKS 服务的更多示例，请参阅此操作指南。

通过