Instalar o AGIC usando uma implantação existente do Gateway de Aplicativo

Artigo
10/22/2024

O Controlador de Entrada do Gateway de Aplicativo (AGIC) é um pod no cluster do Serviço de Kubernetes do Azure (AKS). O AGIC monitora os recursos de entrada do Kubernetes. Ele cria e aplica uma configuração do Gateway de Aplicativo do Azure com base no status do cluster do Kubernetes.

Dica

Considere o Gateway de Aplicativos para Contêineres como a sua solução de entrada do Kubernetes. Para obter mais informações, confira Início rápido: implantar o Controlador ALB do Gateway de Aplicativos para Contêineres.

Pré-requisitos

Este artigo pressupõe que você já tenha instalado as seguintes ferramentas e infraestrutura:

Um cluster do AKS com a Interface de Rede de Contêiner do Azure (CNI).
Gateway de Aplicativo v2 na mesma rede virtual que o cluster do AKS.
ID de carga de trabalho do Microsoft Entra configurada para o cluster do AKS.
O Azure Cloud Shell como o ambiente do shell do Azure, que tem az (CLI do Azure), kubectl e helm instalados. Essas ferramentas são necessárias para comandos que dão suporte à configuração desta implantação.

Adicione o repositório do Helm

O Helm é um gerenciador de pacotes para Kubernetes. Use-o para instalar o pacote application-gateway-kubernetes-ingress.

Se você usar Cloud Shell, não precisará instalar o Helm. O Cloud Shell vem com o Helm versão 3. Execute os seguintes comandos para adicionar o repositório do Helm do AGIC para um cluster do AKS habilitado com o controle de acesso baseado em função (RBAC) do Kubernetes:

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

Fazer backup da implantação do Gateway de Aplicativo

Antes de instalar o AGIC, faça backup da configuração da implantação do Gateway de Aplicativo:

No portal do Azure, acesse a sua implantação do Gateway de Aplicativo.
Na seção Automação, selecione Exportar modelo e, em seguida, selecione Baixar.

O arquivo de .zip baixado contém modelos JSON, scripts Bash e scripts do PowerShell que você pode usar para restaurar o Gateway de Aplicativo, se uma restauração se tornar necessária.

Configurar uma identidade para autenticação do Resource Manager

O AGIC se comunica com o servidor de API do Kubernetes e o Azure Resource Manager. Ele exige uma identidade para acessar essas APIs. Você pode usar a ID de carga de trabalho do Microsoft Entra ou uma entidade de serviço.

Configurar a Carga de Trabalho do Microsoft Entra ID

A ID de carga de trabalho do Microsoft Entra é uma identidade que você atribui a uma carga de trabalho de software. Esta identidade permite que o pod do AKS se autentique com outros recursos do Azure.

Para esta configuração, você precisa de autorização para que o pod do AGIC faça solicitações HTTP ao Azure Resource Manager.

Use o comando az account set da CLI do Azure para definir uma assinatura específica para ser a assinatura ativa atual:
```
az account set --subscription "subscriptionID"
```
Em seguida, use o comando az identity create para criar uma identidade gerenciada. Você deve criar a identidade no grupo de recursos do nó. O grupo de recursos do nó recebe um nome por padrão, como MC_myResourceGroup_myAKSCluster_eastus.
```
az identity create --name "userAssignedIdentityName" --resource-group "resourceGroupName" --location "location" --subscription "subscriptionID"
```

Para a atribuição de função, execute o seguinte comando para identificar o valor principalId da identidade recém-criada:

$resourceGroup="resource-group-name"
$identityName="identity-name"
az identity list -g $resourceGroup --query "[?name == '$identityName'].principalId | [0]" -o tsv

Conceda ao Colaborador de identidade acesso à implantação do Gateway de Aplicativo. Você precisa da ID da implantação do Gateway de Aplicativo, que se parece com /subscriptions/A/resourceGroups/B/providers/Microsoft.Network/applicationGateways/C.

Primeiro, obtenha a lista de IDs do Gateway de Aplicativo na sua assinatura executando o seguinte comando:

az network application-gateway list --query '[].id'

Para atribuir o acesso de Colaborador de identidade, execute o seguinte comando:

$resourceGroup="resource-group-name"
$identityName="identity-Name"
# Get the Application Gateway ID
$AppGatewayID=$(az network application-gateway list --query '[].id' -o tsv)
$role="contributor"
# Get the principal ID for the user-assigned identity
$principalId=$(az identity list -g $resourceGroup --query "[?name == '$identityName'].principalId | [0]" -o tsv)
az role assignment create --assignee $principalId --role $role --scope $AppGatewayID

Conceda ao Leitor de identidade acesso ao grupo de recursos do Gateway de Aplicativo. A ID do grupo de recursos é semelhante a /subscriptions/A/resourceGroups/B. Você pode obter todos os grupos de recursos executando az group list --query '[].id'.

$resourceGroup="resource-group-name"
$identityName="identity-Name"
# Get the Application Gateway resource group
$AppGatewayResourceGroup=$(az network application-gateway list --query '[].resourceGroup' -o tsv)
# Get the Application Gateway resource group ID
$AppGatewayResourceGroupID=$(az group show --name $AppGatewayResourceGroup --query id -o tsv)
$role="Reader"
# Get the principal ID for the user-assigned identity
$principalId=$(az identity list -g $resourceGroup --query "[?name == '$identityName'].principalId | [0]" -o tsv)
# Assign the Reader role to the user-assigned identity at the resource group scope
az role assignment create --role $role --assignee $principalId  --scope $AppGatewayResourceGroupID

Observação

Verifique se a identidade que o AGIC usa tem a permissão Microsoft.Network/virtualNetworks/subnets/join/action delegada à sub-rede em que o Gateway de Aplicativo é implantado. Se você não definiu uma função personalizada que tenha essa permissão, poderá usar a função interna Colaborador de rede.

Configurar uma entidade de serviço

Também é possível fornecer ao AGIC acesso ao Azure Resource Manager usando um segredo do Kubernetes:

Crie uma entidade de serviço do Active Directory e codifique-a com Base64. A codificação Base64 é necessária para que o blob JSON seja salvo no Kubernetes.
```
az ad sp create-for-rbac --role Contributor --sdk-auth | base64 -w0
```
Adicione o blob JSON codificado em Base64 ao arquivo helm-config.yaml. O arquivo helm-config.yaml configura o AGIC.
```
armAuth:
    type: servicePrincipal
    secretJSON: <Base64-Encoded-Credentials>
```

Implantar o complemento do AGIC

Criar um manifesto de implantação para o controlador de entrada

---
# file: pet-supplies-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: pet-supplies-ingress
spec:
  ingressClassName: azure-application-gateway
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: store-front
            port:
              number: 80
      - path: /order-service
        pathType: Prefix
        backend:
          service:
            name: order-service
            port:
              number: 3000
      - path: /product-service
        pathType: Prefix
        backend:
          service:
            name: product-service
            port:
              number: 3002

Implantar o controlador de entrada

$namespace="namespace"
$file="pet-supplies-ingress.yaml"
kubectl apply -f $file -n $namespace

Instalar o controlador de entrada como um gráfico do Helm

Use o Cloud Shell para instalar o pacote AGIC Helm:

Execute uma atualização do Helm:
```
helm repo update
```

Baixe helm-config.yaml:

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

Ou copie o seguinte arquivo 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 must manage
#
appgw:
    subscriptionId: <subscriptionId>
    resourceGroup: <resourceGroupName>
    name: <applicationGatewayName>

    # Setting appgw.shared to "true" creates 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 must 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: Azure-AD-workload-identity
armAuth:
    type: workloadIdentity
    identityClientID:  <identityClientId>

## Alternatively you can use Service Principal credentials
# armAuth:
#    type: servicePrincipal
#    secretJSON: <<Generate this value with: "az ad sp create-for-rbac --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>

Edite helm-config.yaml e preencha os valores para appgw e armAuth.

Observação

<identity-client-id> é uma propriedade de valor da ID de carga de trabalho do Microsoft Entra que você configurou na seção anterior. Você pode recuperar essas informações executando o seguinte comando: az identity show -g <resourcegroup> -n <identity-name>. Nesse comando, <resourcegroup> é o grupo de recursos que hospeda os recursos de infraestrutura relacionados ao cluster do AKS, ao Gateway de Aplicativo e à identidade gerenciada.

Instale o gráfico do Helm com a configuração helm-config.yaml da etapa anterior:

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

Como alternativa, você pode combinar helm-config.yaml e o comando Helm em uma etapa:

helm install oci://mcr.microsoft.com/azure-application-gateway/charts/ingress-azure \
     --name agic-controller \
     --version 1.7.5 \
     --namespace default \
     --debug \
     --set appgw.name=applicationgatewayABCD \
     --set appgw.resourceGroup=your-resource-group \
     --set appgw.subscriptionId=subscription-uuid \
     --set appgw.shared=false \
     --set armAuth.type=servicePrincipal \
     --set armAuth.secretJSON=$(az ad sp create-for-rbac --role Contributor --sdk-auth | base64 -w0) \
     --set rbac.enabled=true \
     --set verbosityLevel=3 \
     --set kubernetes.watchNamespace=default \
     --set aksClusterConfiguration.apiServerAddress=aks-abcdefg.hcp.westus2.azmk8s.io

Confira o log do pod recém-criado para verificar se ele foi iniciado corretamente.

Para entender como você pode expor um serviço do AKS à Internet por HTTP ou HTTPS usando uma implantação do Gateway de Aplicativo do Azure, confira este guia de instruções.

Configurar uma implantação de Gateway de Aplicativo compartilhado

Por padrão, o AGIC assume a propriedade total da implantação do Gateway de Aplicativo à qual está vinculado. O AGIC versão 0.8.0 e posterior pode compartilhar uma única implantação do Gateway de Aplicativo com outros componentes do Azure. Por exemplo, você pode usar a mesma implantação do Gateway de Aplicativo para um aplicativo hospedado em um conjunto de dimensionamento de máquinas virtuais do Azure e em um cluster do AKS.

Cenário de exemplo

Vamos examinar uma implantação imaginária do Gateway de Aplicativo que gerencia o tráfego de dois sites:

dev.contoso.com: hospedado em um novo cluster do AKS usando o Gateway de Aplicativo e o AGIC.
prod.contoso.com: hospedado em um conjunto de dimensionamento de máquinas virtuais.

Com as configurações padrão, o AGIC assume 100% de propriedade da implantação do Gateway de Aplicativo para o qual ele é apontado. O AGIC substitui toda a configuração do Gateway de Aplicativo. Se você criar manualmente um ouvinte para prod.contoso.com no Gateway de Aplicativo sem defini-lo na entrada do Kubernetes, o AGIC excluirá a configuração prod.contoso.com em segundos.

Para instalar o AGIC e também servir prod.contoso.com das máquinas que usam o conjunto de dimensionamento de máquinas virtuais, você deve restringir o AGIC à configuração dev.contoso.com somente. Você facilita esta restrição instanciando a seguinte definição de recurso personalizado (CRD):

cat <<EOF | kubectl apply -f -
apiVersion: "appgw.ingress.k8s.io/v1"
kind: AzureIngressProhibitedTarget
metadata:
  name: prod-contoso-com
spec:
  hostname: prod.contoso.com
EOF

O comando anterior cria um objeto AzureIngressProhibitedTarget. Esse objeto torna o AGIC (versão 0.8.0 e posterior) ciente da existência da configuração do Gateway de Aplicativo para prod.contoso.com. Este objeto também instrui explicitamente o AGIC a evitar a alteração de quaisquer configurações relacionadas a esse nome de host.

Habilitar uma implantação de Gateway de Aplicativo compartilhado usando uma nova instalação do AGIC

Para limitar o AGIC (versão 0.8.0 e posterior) a um subconjunto da configuração do Gateway de Aplicativo, modifique o modelo helm-config.yaml. Na seção appgw:, adicione uma chave shared e defina-a como true:

appgw:
    subscriptionId: <subscriptionId>    # existing field
    resourceGroup: <resourceGroupName>  # existing field
    name: <applicationGatewayName>      # existing field
    shared: true                        # Add this field to enable shared Application Gateway

Aplicar as alterações do Helm:

Certifique-se de que o CRD AzureIngressProhibitedTarget esteja instalado:

kubectl apply -f https://raw.githubusercontent.com/Azure/application-gateway-kubernetes-ingress/7b55ad194e7582c47589eb9e78615042e00babf3/crds/AzureIngressProhibitedTarget-v1-CRD-v1.yaml

Atualizar Helm:

helm upgrade \
    --recreate-pods \
    -f helm-config.yaml \
    agic-controller
    oci://mcr.microsoft.com/azure-application-gateway/charts/ingress-azure

Como resultado, seu cluster do AKS terá uma nova instância do AzureIngressProhibitedTarget chamada prohibit-all-targets:

kubectl get AzureIngressProhibitedTargets prohibit-all-targets -o yaml

O objeto prohibit-all-targets proíbe o AGIC de alterar a configuração para qualquer host e caminho. O Helm instalado com appgw.shared=true implanta o AGIC, mas não faz nenhuma alteração no Gateway de Aplicativo.

Ampliar permissões

Como o Helm com appgw.shared=true e o padrão prohibit-all-targets impedem o AGIC de aplicar uma configuração, você deve ampliar as permissões do AGIC:

Crie um novo arquivo YAML denominado AzureIngressProhibitedTarget com o seguinte snippet que contém a sua configuração específica:

cat <<EOF | kubectl apply -f -
apiVersion: "appgw.ingress.k8s.io/v1"
kind: AzureIngressProhibitedTarget
metadata:
  name: your-custom-prohibitions
spec:
  hostname: your.own-hostname.com
EOF

Agora que você criou a sua própria proibição personalizada, você pode excluir a padrão, que é muito ampla:
```
kubectl delete AzureIngressProhibitedTarget prohibit-all-targets
```

Habilitar uma implantação do Gateway de Aplicativo compartilhado para uma instalação do AGIC existente

Suponha que você já tenha um cluster do AKS em funcionamento e uma implantação do Gateway de Aplicativo e tenha configurado o AGIC em seu cluster. Você tem uma entrada para prod.contoso.com e está atendendo com sucesso o tráfego do cluster.

Você deseja adicionar staging.contoso.com à implantação do Gateway de Aplicativo existente, mas precisa hospedá-la em uma máquina virtual. Você reutilizará a implantação existente do Gateway de Aplicativo e configurará manualmente um ouvinte e pools de back-end para staging.contoso.com. Mas ajustar manualmente a configuração do Gateway de Aplicativo (usando o portal do Azure, APIs do Resource Manager ou o Terraform) entraria em conflito com as suposições do AGIC de propriedade total. Pouco depois de você aplicar alterações, o AGIC as substitui ou exclui.

Você pode proibir o AGIC de fazer alterações em um subconjunto das configurações:

Crie um novo arquivo YAML denominado AzureIngressProhibitedTarget usando o seguinte snippet:

cat <<EOF | kubectl apply -f -
apiVersion: "appgw.ingress.k8s.io/v1"
kind: AzureIngressProhibitedTarget
metadata:
  name: manually-configured-staging-environment
spec:
  hostname: staging.contoso.com
EOF

Veja o objeto recém-criado:

kubectl get AzureIngressProhibitedTargets

Modifique a configuração do Gateway de Aplicativo no portal do Azure. Por exemplo, adicione ouvintes, regras de roteamento e back-ends. O novo objeto que você criou (manually-configured-staging-environment) proíbe o AGIC de substituir a configuração do Gateway de Aplicativo relacionada a staging.contoso.com.

Gateway de Aplicativos para Contêineres

Compartilhar via

Instalar o AGIC usando uma implantação existente do Gateway de Aplicativo

Pré-requisitos

Adicione o repositório do Helm

Fazer backup da implantação do Gateway de Aplicativo

Configurar uma identidade para autenticação do Resource Manager

Configurar a Carga de Trabalho do Microsoft Entra ID

Configurar uma entidade de serviço

Implantar o complemento do AGIC

Criar um manifesto de implantação para o controlador de entrada

Implantar o controlador de entrada

Instalar o controlador de entrada como um gráfico do Helm

Configurar uma implantação de Gateway de Aplicativo compartilhado

Cenário de exemplo

Habilitar uma implantação de Gateway de Aplicativo compartilhado usando uma nova instalação do AGIC

Ampliar permissões

Habilitar uma implantação do Gateway de Aplicativo compartilhado para uma instalação do AGIC existente

Comentários

Recursos adicionais

Compartilhar via

Instalar o AGIC usando uma implantação existente do Gateway de Aplicativo

Pré-requisitos

Adicione o repositório do Helm

Fazer backup da implantação do Gateway de Aplicativo

Configurar uma identidade para autenticação do Resource Manager

Configurar a Carga de Trabalho do Microsoft Entra ID

Configurar uma entidade de serviço

Implantar o complemento do AGIC

Criar um manifesto de implantação para o controlador de entrada

Implantar o controlador de entrada

Instalar o controlador de entrada como um gráfico do Helm

Configurar uma implantação de Gateway de Aplicativo compartilhado

Cenário de exemplo

Habilitar uma implantação de Gateway de Aplicativo compartilhado usando uma nova instalação do AGIC

Ampliar permissões

Habilitar uma implantação do Gateway de Aplicativo compartilhado para uma instalação do AGIC existente

Conteúdo relacionado

Comentários

Recursos adicionais