diff --git a/docs/networking/agc-lab.md b/docs/networking/agc-lab.md new file mode 100644 index 00000000..e0bcc945 --- /dev/null +++ b/docs/networking/agc-lab.md @@ -0,0 +1,726 @@ +--- +title: Application Gateway for Containers +sidebar_label: Application Gateway for Containers +sidebar_position: 3 +--- +import Prerequisites from "../../src/components/SharedMarkdown/_prerequisites.mdx"; +import ProvisionResourceGroup from "../../src/components/SharedMarkdown/_provision_resource_group.mdx"; +import ProvisionAKSCluster from "../../src/components/SharedMarkdown/_provision_aks_cluster.mdx"; +import Cleanup from "../../src/components/SharedMarkdown/_cleanup.mdx"; + +Application Gateway for Containers is an application layer (layer 7) load balancing and dynamic traffic management product for workloads running in a Kubernetes cluster. It extends Azure's Application Load Balancing portfolio and is a new offering under the Application Gateway product family. It enables multiple Layer 7 features: + +- Traffic splitting / Weighted round robin + +- Mutual authentication to the backend target + +- Kubernetes support for Ingress and Gateway API + +- Flexible deployment strategies + +- Increased performance, offering near real-time updates to add or remove pods, routes, and probes + +--- + +## Objectives + +In this workshop, you will learn how to use Application Gateway for Containers with Azure Kubernetes Service (AKS). + +* Deploy and configure an ALB controller. + +* Create an Application Gateway for Containers resource via CRDs (managed by the ALB Controller). + +* Install and configure cert-manager to manage and assign certificates to your workloads exposed via Application Gateway for Containers. + +* Expose an application to the Internet over HTTPS. + +* Create a canary deployment by leveraging traffic splitting. + +* Apply Web Application Firewall Policies to your HTTPRoutes. + + +--- + + + +Before starting with the deployment and configuration of the Application Gateway for Containers, you will need to register a few providers in the subscription which will contain the resources. You must also enable the extension "Application Gateway for Containers ALB Controller" + +```bash +# Register required resource providers on Azure. +az provider register --namespace Microsoft.ContainerService +az provider register --namespace Microsoft.Network +az provider register --namespace Microsoft.NetworkFunction +az provider register --namespace Microsoft.ServiceNetworking + +# Register preview features required for the ALB Controller AKS add-on. +az feature register --namespace Microsoft.ContainerService --name ApplicationLoadBalancerPreview +az feature register --namespace Microsoft.ContainerService --name ManagedGatewayAPIPreview +az provider register --namespace Microsoft.ContainerService + +# Install Azure CLI extensions. +az extension add --name alb +az extension add --name aks-preview +``` + +## Expose an application over HTTP + +### Install and configure the ALB Controller + +The ALB Controller is a Kubernetes deployment that orchestrates configuration and deployment of Application Gateway for Containers. It uses both ARM and configuration APIs to propagate configuration to the Application Gateway for Containers Azure deployment. After installing it in a cluster, it will apply a set of CRDs to the cluster: + +- ApplicationLoadBalancer +- BackendLoadBalancingPolicy +- BackendTLSPolicy +- FrontendTLSPolicy +- HealthCheckPolicy +- IngressExtension +- RoutePolicy +- WebApplicationFirewallPolicy + +View the architecture of Application Gateway with Containers in the image below: + +![Application Gateway for Containers architecture](https://learn.microsoft.com/en-us/azure/application-gateway/for-containers/media/overview/application-gateway-for-containers-kubernetes-conceptual.png) + +#### Enable the ALB Controller AKS Add-on + +The simplest way to install the ALB controller is via the AKS add-on. The add-on automatically handles: + +- Creating a managed identity (`applicationloadbalancer-`) with the required role assignments (Reader, Network Contributor, AppGw for Containers Configuration Manager) scoped to the managed cluster resource group. +- Configuring a federated identity credential for workload identity. +- Creating a delegated subnet (`aks-appgateway`) in the cluster's virtual network. + +Enable the add-on on your existing cluster: + +```bash +az aks update --name ${AKS_NAME} --resource-group ${RG_NAME} --enable-gateway-api --enable-application-load-balancer +``` + +:::tip +For a new cluster, you can pass `--enable-gateway-api --enable-application-load-balancer` directly to `az aks create`. +::: + +Verify the ALB Controller pods are running in the `kube-system` namespace: + +```bash +kubectl get pods -n kube-system | grep alb-controller +``` + +You should see two `alb-controller` pods in `Running` state. + +Verify GatewayClass `azure-alb-external` is installed on your cluster. You should see that the GatewayClass has a condition that reads `Valid` GatewayClass: + +```bash +kubectl get gatewayclass azure-alb-external -o yaml +``` + +Now that you have successfully installed an ALB Controller on your cluster, you can provision the Application Gateway For Containers resources in Azure. + +:::note +If you prefer a manual installation using Helm (for example, to customise the controller namespace or version), refer to the [Helm-based deployment guide](https://learn.microsoft.com/en-us/azure/application-gateway/for-containers/quickstart-deploy-application-gateway-for-containers-alb-controller-helm). +::: + + +### Provision a (managed) Application Gateway for Containers + +In this deployment strategy, ALB Controller deployed in Kubernetes is responsible for the lifecycle of the Application Gateway for Containers resource and its sub resources. ALB Controller creates an Application Gateway for Containers resource when an ApplicationLoadBalancer custom resource is defined on the cluster. The service lifecycle is based on the lifecycle of the custom resource. + + +#### Retrieve the auto-provisioned subnet + +The AKS add-on automatically created a delegated subnet named `aks-appgateway` in the cluster's virtual network. Retrieve its resource ID: + +```bash +MC_RG_NAME=$(az aks show --resource-group ${RG_NAME} --name ${AKS_NAME} --query "nodeResourceGroup" -o tsv) +CLUSTER_SUBNET_ID=$(az vmss list --resource-group $MC_RG_NAME --query '[0].virtualMachineProfile.networkProfile.networkInterfaceConfigurations[0].ipConfigurations[0].subnet.id' -o tsv) +read -d '' VNET_NAME VNET_RG_NAME VNET_ID <<< $(az network vnet show --ids $CLUSTER_SUBNET_ID --query '[name, resourceGroup, id]' -o tsv) +ALB_SUBNET_ID=$(az network vnet subnet show --name aks-appgateway --resource-group $VNET_RG_NAME --vnet-name $VNET_NAME --query '[id]' --output tsv) +``` + +:::note +The add-on also assigned all the required permissions (Reader, Network Contributor, AppGw for Containers Configuration Manager) to the managed identity it created, so no manual role assignments are needed. +::: + + +#### Create an Application Load Balancer + +When you create an ApplicationLoadBalancer (with API alb.networking.azure.io/v1), the ALB controller will create an Application Gateway for Containers resource in Azure. Let's first create a namespace: + +```bash +kubectl create ns alb-test-infra +``` + +Now create an Application Load Balancer in the newly created namespace: + +```yaml +kubectl apply -f - <` with ``, but you must be able to resolve the address, or to pass the "Host" http header. You can test the access to the application: + +```bash +curl http:// + +# if using a custom domain +curl http:// +# or +curl http:// -H "Host: " +``` + +Or open your browser and navigate to http://$MY_FRONTEND_ADDRESS: + +![Blue Service](./assets/agc-canary-blue-service.png) + +## Expose an application over HTTPS + +In the previous section you learnt how to expose your Kubernetes workloads through HTTP with Application Gateway for Containers. While the previous method allows you to access your applications, you are doing so in an insecure way. In order to secure your application traffic, it is necessary to expose it through HTTPS (which requires the use of SSL/TLS certificates). + +### Install and configure Cert-Manager + +[Cert-Manager](https://cert-manager.io/) is a powerful and extensible X.509 certificate controller for Kubernetes workloads, which obtains certificates from a variety of Issuers, both public or private, and ensure the certificates are valid and up-to-date. It will also attempt to renew certificates at a configured time before expiry. For the purposes of this lab, we have cert-manager configure certificates issued from Let's Encrypt to demonstrate an end-to-end deployment, where Application Gateway for Containers is providing TLS offloading. View architecture below: + +![Application Gateway for Containers and cert-manager architecture](https://learn.microsoft.com/en-us/azure/application-gateway/for-containers/media/how-to-cert-manager-lets-encrypt-gateway-api/how-to-cert-manager-lets-encrypt-gateway-api.svg#lightbox) + + +In order to use it to manage certificates for our applications exposed through Application Gateway for Containers, we first need to install it with Helm: + +```bash +helm repo add jetstack https://charts.jetstack.io --force-update +helm install \ + cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --create-namespace \ + --version v1.17.1 \ + --set config.enableGatewayAPI=true \ + --set crds.enabled=true +``` + +Create a `ClusterIssuer` resource to define how cert-manager will communicate with Let's Encrypt. For this example, an HTTP challenge is used. During challenge, cert-manager creates an `HTTPRoute` resource and corresponding pod presenting a validation endpoint to prove ownership of the domain. + +```yaml +kubectl apply -f - < + + + Welcome to Color Demo + + + + + +
+ +
+

Node IP: 10.224.0.8

+ +

POD IP: 10.244.4.209:80

+
Request Date: 10/Sep/2025:17:46:32 +0000
+
Request ID: b28542c5f70c9268809860d3a9eb1ae7
+
+
+

Additional Info:

+

Node Name: aks-usrpool1-95676513-vmss000000

+

POD Name: ngcolor-blue-7758b6fccb-v9hmb

+

Namespace: alb-test-infra

+

Service Account: default

+

CPU Request: 0

+

CPU Limit: 2

+

MEM Request: 0

+

MEM Limit: 7533256704

+
+Downward API

+

NGINX Demo Environment

+
+ + + + +``` + +--- + +## Authors + +This lab was originally developed by Carlos Mestre del Pino. He can be reached at: + +**LinkedIn:** [Carlos Mestre del Pino](https://www.linkedin.com/in/mestredelpino/) \ +**BlueSky** [@mestredelpino.com](https://bsky.app/profile/mestredelpino.com) + diff --git a/docs/networking/assets/agc-canary-blue-service.png b/docs/networking/assets/agc-canary-blue-service.png new file mode 100644 index 00000000..7d75f4d0 Binary files /dev/null and b/docs/networking/assets/agc-canary-blue-service.png differ diff --git a/docs/networking/assets/agc-canary-red-service.png b/docs/networking/assets/agc-canary-red-service.png new file mode 100644 index 00000000..e3b85354 Binary files /dev/null and b/docs/networking/assets/agc-canary-red-service.png differ diff --git a/docs/networking/assets/agc-in-portal.png b/docs/networking/assets/agc-in-portal.png new file mode 100644 index 00000000..6d96ae27 Binary files /dev/null and b/docs/networking/assets/agc-in-portal.png differ