How to Install an Application Gateway Ingress Controller (AGIC) Using a New Application Gateway
The instructions below assume Application Gateway Ingress Controller (AGIC) will be installed in an environment with no preexisting components.
Required Command Line Tools
Please ensure the following command-line tools are installed:
az
- Azure CLI: installation instructionskubectl
- Kubernetes command-line tool: installation instructionshelm
- Kubernetes package manager: installation instructionsjq
- command-line JSON processor: installation instructions
Create an Identity
Follow the steps below to create a Microsoft Entra service principal object. Record the appId
, password
, and objectId
values - these values are used in the following steps.
Create AD service principal (Read more about 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)
The
appId
andpassword
values from the JSON output will be used in the following stepsUse the
appId
from the previous command's output to get theid
of the new service principal:objectId=$(az ad sp show --id $appId --query "id" -o tsv)
The output of this command is
objectId
, which will be used in the Azure Resource Manager template belowCreate the parameter file that is used in the Azure Resource Manager template deployment later.
cat <<EOF > parameters.json { "aksServicePrincipalAppId": { "value": "$appId" }, "aksServicePrincipalClientSecret": { "value": "$password" }, "aksServicePrincipalObjectId": { "value": "$objectId" }, "aksEnableRBAC": { "value": false } } EOF
To deploy an Kubernetes RBAC enabled cluster, set the
aksEnableRBAC
field totrue
Deploy Components
This step adds the following components to your subscription:
- Azure Kubernetes Service
- Application Gateway v2
- Virtual Network with two subnets
- Public IP Address
- Managed Identity, which will be used by Microsoft Entra Pod Identity
Download the Azure Resource Manager template and modify the template as needed.
wget https://raw.githubusercontent.com/Azure/application-gateway-kubernetes-ingress/master/deploy/azuredeploy.json -O template.json
Deploy the Azure Resource Manager template using the Azure CLI. The deployment might take up to 5 minutes.
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
Once the deployment finished, download the deployment output into a file named
deployment-outputs.json
.az deployment group show -g $resourceGroupName -n $deploymentName --query "properties.outputs" -o json > deployment-outputs.json
Set up Application Gateway Ingress Controller
With the instructions in the previous section, we created and configured a new AKS cluster and an Application Gateway. We're now ready to deploy a sample app and an ingress controller to our new Kubernetes infrastructure.
Set up Kubernetes Credentials
For the following steps, we need setup kubectl command,
which we use to connect to our new Kubernetes cluster. We'll use az
CLI to obtain credentials for Kubernetes.
Get credentials for your newly deployed AKS (read more):
# use the deployment-outputs.json 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
Install Microsoft Entra Pod Identity
Microsoft Entra Pod Identity provides token-based access to Azure Resource Manager (ARM).
Microsoft Entra Pod Identity will add the following components to your Kubernetes cluster:
- Kubernetes CRDs:
AzureIdentity
,AzureAssignedIdentity
,AzureIdentityBinding
- Managed Identity Controller (MIC) component
- Node Managed Identity (NMI) component
To install Microsoft Entra Pod Identity to your cluster:
Kubernetes RBAC enabled AKS cluster
kubectl create -f https://raw.githubusercontent.com/Azure/aad-pod-identity/master/deploy/infra/deployment-rbac.yaml
Kubernetes RBAC disabled AKS cluster
kubectl create -f https://raw.githubusercontent.com/Azure/aad-pod-identity/master/deploy/infra/deployment.yaml
Install Helm
Helm is a package manager for Kubernetes. We use it to install the application-gateway-kubernetes-ingress
package.
Install Helm and run the following:
Kubernetes RBAC enabled AKS cluster
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 disabled AKS cluster
helm init
Install Ingress Controller Helm Chart
Use the
deployment-outputs.json
file created above and create the following variables.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)
Download helm-config.yaml, which will configure AGIC:
wget https://raw.githubusercontent.com/Azure/application-gateway-kubernetes-ingress/master/docs/examples/sample-helm-config.yaml -O helm-config.yaml
Or copy the YAML file below:
# 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 acessible 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>
Edit the newly downloaded helm-config.yaml and fill out the sections
appgw
andarmAuth
.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
Note
For deploying to Sovereign Clouds, the
appgw.environment
configuration parameter must be added and set to the appropriate value as documented below.Values:
verbosityLevel
: Sets the verbosity level of the AGIC logging infrastructure. See Logging Levels for possible values.appgw.environment
: Sets cloud environment. Possible values:AZURECHINACLOUD
,AZUREGERMANCLOUD
,AZUREPUBLICCLOUD
appgw.subscriptionId
: The Azure Subscription ID in which Application Gateway resides. Example:a123b234-a3b4-557d-b2df-a0bc12de1234
appgw.resourceGroup
: Name of the Azure Resource Group in which Application Gateway was created. Example:app-gw-resource-group
appgw.name
: Name of the Application Gateway. Example:applicationgatewayd0f0
appgw.shared
: This boolean flag should be defaulted tofalse
. Set totrue
should you need a Shared Application Gateway.kubernetes.watchNamespace
: Specify the namespace that AGIC should watch. The namespace value can be a single string value, or a comma-separated list of namespaces.armAuth.type
: could beaadPodIdentity
orservicePrincipal
armAuth.identityResourceID
: Resource ID of the Azure Managed IdentityarmAuth.identityClientID
: The Client ID of the Identity. More information about identityClientID is provided below.armAuth.secretJSON
: Only needed when Service Principal Secret type is chosen (whenarmAuth.type
has been set toservicePrincipal
)
Note
The
identityResourceID
andidentityClientID
are values that were created during the Deploy Components steps, and could be obtained again using the following command:az identity show -g <resource-group> -n <identity-name>
<resource-group>
in the command above is the resource group of your Application Gateway.<identity-name>
is the name of the created identity. All identities for a given subscription can be listed using:az identity list
Install the Application Gateway ingress controller package:
helm install agic-controller oci://mcr.microsoft.com/azure-application-gateway/charts/ingress-azure --version 1.7.5 -f helm-config.yaml
Install a Sample App
Now that we have Application Gateway, AKS, and AGIC installed we can install a sample app:
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
Alternatively you can:
Download the YAML file above:
curl https://raw.githubusercontent.com/Azure/application-gateway-kubernetes-ingress/master/docs/examples/aspnetapp.yaml -o aspnetapp.yaml
Apply the YAML file:
kubectl apply -f aspnetapp.yaml
Other Examples
This how-to guide contains more examples on how to expose an AKS service via HTTP or HTTPS, to the Internet with Application Gateway.