기존 Application Gateway 배포를 사용하여 AGIC 설치

아티클
10/17/2024

AGIC(Application Gateway 수신 컨트롤러)는 AKS(Azure Kubernetes Service) 클러스터 내의 Pod입니다. AGIC는 Kubernetes 수신 리소스를 모니터링합니다. Kubernetes 클러스터의 상태에 따라 Azure 애플리케이션 게이트웨이 구성을 만들고 적용합니다.

팁

Kubernetes 수신 솔루션에 대한 컨테이너용 Application Gateway를 고려합니다. 자세한 내용은 빠른 시작: 컨테이너용 Application Gateway ALB 컨트롤러 배포를 참조 하세요.

필수 조건

이 문서에서는 다음 도구 및 인프라를 이미 설치했다고 가정합니다.

Azure CNI(Container Networking Interface)를 사용하는 AKS 클러스터입니다.
AKS 클러스터와 동일한 가상 네트워크에 있는 Application Gateway v2 .
AKS 클러스터에 대해 구성된 Microsoft Entra 워크로드 ID.
Azure Cloud Shell은 (Azure CLI) kubectl및 helm 설치되어 있는 az Azure 셸 환경입니다. 이러한 도구는 이 배포 구성을 지원하는 명령에 필요합니다.

Helm 리포지토리 추가

Helm은 Kubernetes 패키지 관리자입니다. 패키지를 설치 application-gateway-kubernetes-ingress 하는 데 사용합니다.

Cloud Shell을 사용하는 경우에는 Helm을 설치할 필요가 없습니다. Cloud Shell은 Helm 버전 3과 함께 제공됩니다. 다음 명령을 실행하여 KUbernetes RBAC(역할 기반 액세스 제어)로 사용하도록 설정된 AKS 클러스터에 대한 AGIC Helm 리포지토리를 추가합니다.

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

Application Gateway 배포 백업

AGIC를 설치하기 전에 Application Gateway 배포의 구성을 백업합니다.

Azure Portal에서 Application Gateway 배포로 이동합니다.
Automation 섹션에서 템플릿 내보내기를 선택한 다음 다운로드를 선택합니다.

다운로드한 .zip 파일에는 복원이 필요한 경우 Application Gateway를 복원하는 데 사용할 수 있는 JSON 템플릿, Bash 스크립트 및 PowerShell 스크립트가 포함되어 있습니다.

Resource Manager 인증에 대한 ID 설정

AGIC는 Kubernetes API 서버 및 Azure Resource Manager와 통신합니다. 이러한 API에 액세스하려면 ID가 필요합니다. Microsoft Entra 워크로드 ID 또는 서비스 주체를 사용할 수 있습니다.

Microsoft Entra 워크로드 ID 설치

Microsoft Entra 워크로드 ID 소프트웨어 워크로드에 할당하는 ID입니다. 이 ID를 사용하면 AKS Pod가 다른 Azure 리소스로 인증할 수 있습니다.

이 구성의 경우 AZURE Resource Manager에 HTTP 요청을 수행하려면 AGIC Pod에 대한 권한 부여가 필요합니다.

Azure CLI az 계정 집합 명령을 사용하여 특정 구독을 현재 활성 구독으로 설정합니다.
```
az account set --subscription "subscriptionID"
```
그런 다음, 관리 ID를 만들려면 az identity create 명령을 사용합니다. 노드 리소스 그룹에서 ID를 만들어야 합니다. 노드 리소스 그룹에는 기본적으로 이름이 할당됩니다(예: MC_myResourceGroup_myAKSCluster_eastus.).
```
az identity create --name "userAssignedIdentityName" --resource-group "resourceGroupName" --location "location" --subscription "subscriptionID"
```

역할 할당의 경우 다음 명령을 실행하여 새로 만든 ID의 principalId 값을 식별합니다.

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

Application Gateway 배포에 대한 ID 기여자 액세스 권한을 부여합니다. 다음과 같은 /subscriptions/A/resourceGroups/B/providers/Microsoft.Network/applicationGateways/CApplication Gateway 배포의 ID가 필요합니다.

먼저 다음 명령을 실행하여 구독의 Application Gateway ID 목록을 가져옵니다.

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

ID 기여자에 액세스 권한을 할당하려면 다음 명령을 실행합니다.

$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

ID 판독기에 Application Gateway 리소스 그룹에 대한 액세스 권한을 부여합니다. 리소스 그룹 ID는 다음과 같습니다 /subscriptions/A/resourceGroups/B. 를 실행 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

참고 항목

AGIC에서 사용하는 ID에 Application Gateway가 배포된 서브넷에 위임된 Microsoft.Network/virtualNetworks/서브넷/조인/작업 권한이 있는지 확인합니다. 이 권한이 있는 사용자 지정 역할을 정의하지 않은 경우 기본 제공 네트워크 기여자 역할을 사용할 수 있습니다.

서비스 주체 설정

Kubernetes 비밀을 사용하여 Azure Resource Manager에 AGIC 액세스를 제공할 수도 있습니다.

Active Directory 서비스 주체를 만들고 Base64로 인코딩합니다. JSON Blob을 Kubernetes에 저장하려면 Base64 인코딩이 필요합니다.
```
az ad sp create-for-rbac --role Contributor --sdk-auth | base64 -w0
```
Base64로 인코딩된 JSON Blob을 파일에 추가합니다 helm-config.yaml . 파일은 helm-config.yaml AGIC를 구성합니다.
```
armAuth:
    type: servicePrincipal
    secretJSON: <Base64-Encoded-Credentials>
```

AGIC 추가 기능 배포

수신 컨트롤러에 대한 배포 매니페스트 만들기

---
# 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

수신 컨트롤러 배포

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

Helm 차트로 수신 컨트롤러 설치

Cloud Shell를 사용하여 AGIC Helm 패키지를 설치합니다.

Helm 업데이트를 수행합니다.
```
helm repo update
```

다운로드 helm-config.yaml:

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

에 대한 값을 편집 helm-config.yaml 하고 입력합니다armAuth.appgw

참고 항목

<identity-client-id>는 이전 섹션에서 설정한 Microsoft Entra 워크로드 ID 값의 속성입니다. 다음 명령을 az identity show -g <resourcegroup> -n <identity-name>실행하여 이 정보를 검색할 수 있습니다. 이 명령에서 AKS 클러스터, <resourcegroup> Application Gateway 및 관리 ID와 관련된 인프라 리소스를 호스트하는 리소스 그룹입니다.

이전 단계의 구성을 사용하여 helm-config.yaml Helm 차트를 설치합니다.

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

또는 한 단계로 결합 helm-config.yaml 하고 Helm 명령을 사용할 수 있습니다.

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

새로 만든 Pod의 로그를 확인하여 제대로 시작되었는지 확인합니다.

Azure 애플리케이션 게이트웨이 배포를 사용하여 HTTP 또는 HTTPS를 통해 AKS 서비스를 인터넷에 노출하는 방법을 이해하려면 이 방법 가이드를 참조하세요.

공유 Application Gateway 배포 설정

기본적으로 AGIC는 연결된 Application Gateway 배포의 전체 소유권을 가정합니다. AGIC 버전 0.8.0 이상에서는 단일 Application Gateway 배포를 다른 Azure 구성 요소와 공유할 수 있습니다. 예를 들어 Azure 가상 머신 확장 집합 및 AKS 클러스터에서 호스트되는 앱에 대해 동일한 Application Gateway 배포를 사용할 수 있습니다.

예제 시나리오

다음 두 웹 사이트의 트래픽을 관리하는 가상의 Application Gateway 배포를 살펴보겠습니다.

dev.contoso.com: Application Gateway 및 AGIC를 사용하여 새 AKS 클러스터에서 호스트됩니다.
prod.contoso.com: 가상 머신 확장 집합에서 호스트됩니다.

기본 설정을 사용하면 AGIC에서 가리키는 Application Gateway 배포의 100% 소유권을 가정합니다. AGIC는 모든 App Gateway 구성을 덮어씁니다. Kubernetes 수신에서 정의하지 않고 Application Gateway에 대한 prod.contoso.com 수신기를 수동으로 만드는 경우 AGIC는 몇 초 내에 구성을 prod.contoso.com 삭제합니다.

AGIC를 설치하고 가상 머신 확장 집합을 사용하는 컴퓨터에서 서비스를 제공 prod.contoso.com 하려면 AGIC만 구성 dev.contoso.com 하도록 제한해야 합니다. 다음 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

앞의 명령은 개체를 AzureIngressProhibitedTarget 만듭니다. 이 개체를 사용하면 AGIC(버전 0.8.0 이상)에서 Application Gateway 구성이 있는지 인식할 수 prod.contoso.com있습니다. 또한 이 개체는 해당 호스트 이름과 관련된 구성을 변경하지 않도록 AGIC에 명시적으로 지시합니다.

새 AGIC 설치를 사용하여 공유 Application Gateway 배포 사용

AGIC(버전 0.8.0 이상)를 Application Gateway 구성의 하위 집합으로 제한하려면 helm-config.yaml 템플릿을 수정합니다. appgw: 섹션에서 키를 추가하고 다음으로 shared true설정합니다.

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

Helm 변경 내용을 적용합니다.

CRD가 AzureIngressProhibitedTarget 설치되어 있는지 확인합니다.

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

Helm을 업데이트합니다.

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

결과적으로 AKS 클러스터에는 prohibit-all-targets라는 AzureIngressProhibitedTarget의 새 인스턴스가 있습니다.

kubectl get AzureIngressProhibitedTargets prohibit-all-targets -o yaml

개체는 prohibit-all-targets AGIC가 호스트 및 경로에 대한 구성을 변경하는 것을 금지합니다. HELM은 appgw.shared=true AGIC를 배포하여 설치하지만 Application Gateway를 변경하지는 않습니다.

사용 권한 확장

Helm appgw.shared=true 및 기본값 prohibit-all-targets 은 AGIC가 구성을 적용하지 못하도록 차단하므로 AGIC 권한을 확대해야 합니다.

특정 설정을 포함하는 다음 코드 조각을 사용하여 명명 AzureIngressProhibitedTarget 된 새 YAML 파일을 만듭니다.

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

이제 사용자 지정 금지를 만들었으므로 너무 광범위한 기본 금지를 삭제할 수 있습니다.
```
kubectl delete AzureIngressProhibitedTarget prohibit-all-targets
```

기존 AGIC 설치에 공유 Application Gateway 배포 사용

이미 작동하는 AKS 클러스터 및 Application Gateway 배포가 있고 클러스터에서 AGIC를 구성한 것으로 가정합니다. 수신 prod.contoso.com 이 있고 클러스터에서 트래픽을 성공적으로 처리하고 있습니다.

기존 Application Gateway 배포에 추가 staging.contoso.com 하려고 하지만 가상 머신에서 호스트해야 합니다. 기존 Application Gateway 배포를 다시 사용하고 수신기 및 백 엔드 풀을 staging.contoso.com수동으로 구성합니다. 그러나 Azure Portal, Resource Manager API 또는 Terraform을 사용하여 Application Gateway 구성을 수동으로 조정하면 AGIC의 전체 소유권 가정과 충돌합니다. 변경 내용을 적용한 직후 AGIC는 변경 내용을 덮어쓰거나 삭제합니다.

AGIC가 구성의 하위 집합을 변경하는 것을 금지할 수 있습니다.

다음 코드 조각을 사용하여 명명된 AzureIngressProhibitedTarget 새 YAML 파일을 만듭니다.

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

새로 만든 개체를 확인합니다.

kubectl get AzureIngressProhibitedTargets

Azure Portal에서 Application Gateway 구성을 수정합니다. 예를 들어 수신기, 라우팅 규칙 및 백 엔드를 추가합니다. 만든 새 개체(manually-configured-staging-environment)는 AGIC가 관련된 Application Gateway 구성을 덮어쓰는 것을 금지합니다 staging.contoso.com.

컨테이너용 Application Gateway

다음을 통해 공유

기존 Application Gateway 배포를 사용하여 AGIC 설치

필수 조건

Helm 리포지토리 추가

Application Gateway 배포 백업

Resource Manager 인증에 대한 ID 설정

Microsoft Entra 워크로드 ID 설치

서비스 주체 설정

AGIC 추가 기능 배포

수신 컨트롤러에 대한 배포 매니페스트 만들기

수신 컨트롤러 배포

Helm 차트로 수신 컨트롤러 설치

공유 Application Gateway 배포 설정

예제 시나리오

새 AGIC 설치를 사용하여 공유 Application Gateway 배포 사용

사용 권한 확장

기존 AGIC 설치에 공유 Application Gateway 배포 사용

피드백

추가 리소스

다음을 통해 공유

기존 Application Gateway 배포를 사용하여 AGIC 설치

필수 조건

Helm 리포지토리 추가

Application Gateway 배포 백업

Resource Manager 인증에 대한 ID 설정

Microsoft Entra 워크로드 ID 설치

서비스 주체 설정

AGIC 추가 기능 배포

수신 컨트롤러에 대한 배포 매니페스트 만들기

수신 컨트롤러 배포

Helm 차트로 수신 컨트롤러 설치

공유 Application Gateway 배포 설정

예제 시나리오

새 AGIC 설치를 사용하여 공유 Application Gateway 배포 사용

사용 권한 확장

기존 AGIC 설치에 공유 Application Gateway 배포 사용

관련 콘텐츠

피드백

추가 리소스