Skip to content

Files

Latest commit

deuchdeuch
Fix typo and use the KV URL of the certificate
May 31, 2022
d133705 · May 31, 2022

History

History
253 lines (183 loc) · 10.7 KB

web-app-routing.md

File metadata and controls

253 lines (183 loc) · 10.7 KB
title description services author ms.topic ms.date ms.author
Web Application Routing add-on on Azure Kubernetes Service (AKS) (Preview)
Use the Web Application Routing add-on to securely access applications deployed on Azure Kubernetes Service (AKS).
container-service
jahabibi
article
05/13/2021
jahabibi

Web Application Routing (Preview)

The Web Application Routing solution makes it easy to access applications that are deployed to your Azure Kubernetes Service (AKS) cluster. When the solution's enabled, it configures an Ingress controller in your AKS cluster, SSL termination, and Open Service Mesh (OSM) for E2E encryption of inter cluster communication. As applications are deployed, the solution also creates publicly accessible DNS names for application endpoints.

[!INCLUDE preview features callout]

Limitations

  • Web Application Routing currently doesn't support named ports in ingress backend.

Web Application Routing solution overview

The add-on deploys four components: an nginx ingress controller, Secrets Store CSI Driver, Open Service Mesh (OSM), and External-DNS controller.

  • Nginx ingress Controller: The ingress controller exposed to the internet.
  • External-DNS controller: Watches for Kubernetes Ingress resources and creates DNS A records in the cluster-specific DNS zone.
  • CSI driver: Connector used to communicate with keyvault to retrieve SSL certificates for ingress controller.
  • OSM: A lightweight, extensible, cloud native service mesh that allows users to uniformly manage, secure, and get out-of-the-box observability features for highly dynamic microservice environments.

Prerequisites

  • An Azure subscription. If you don't have an Azure subscription, you can create a free account.
  • Azure CLI installed.
  • An Azure Key Vault containing any application certificates.
  • A DNS solution.

Install the aks-preview Azure CLI extension

You also need the aks-preview Azure CLI extension version 0.5.75 or later. Install the aks-preview Azure CLI extension by using the az extension add command. Or install any available updates by using the az extension update command.

# Install the aks-preview extension
az extension add --name aks-preview

# Update the extension to make sure you have the latest version installed
az extension update --name aks-preview

Install the osm CLI

Since Web Application Routing uses OSM internally to secure intranet communication, we need to set up the osm CLI. This command-line tool contains everything needed to install and configure Open Service Mesh. The binary is available on the OSM GitHub releases page.

Deploy Web Application Routing with the Azure CLI

The Web Application Routing routing add-on can be enabled with the Azure CLI when deploying an AKS cluster. To do so, use the az aks create command with the --enable-addons argument.

az aks create --resource-group myResourceGroup --name myAKSCluster --enable-addons web_application_routing

Tip

If you want to enable multiple add-ons, provide them as a comma-separated list. For example, to enable Web Application Routing routing and monitoring, use the format --enable-addons web_application_routing,monitoring.

You can also enable Web Application Routing on an existing AKS cluster using the az aks enable-addons command. To enable Web Application Routing on an existing cluster, add the --addons parameter and specify web_application_routing as shown in the following example:

az aks enable-addons --resource-group myResourceGroup --name myAKSCluster --addons web_application_routing

Connect to your AKS cluster

To connect to the Kubernetes cluster from your local computer, you use kubectl, the Kubernetes command-line client.

If you use the Azure Cloud Shell, kubectl is already installed. You can also install it locally using the az aks install-cli command:

az aks install-cli

To configure kubectl to connect to your Kubernetes cluster, use the az aks get-credentials command. The following example gets credentials for the AKS cluster named myAKSCluster in myResourceGroup:

az aks get-credentials --resource-group myResourceGroup --name myAKSCluster

Create the application namespace

For the sample application environment, let's first create a namespace called hello-web-app-routing to run the example pods:

kubectl create namespace hello-web-app-routing

We also need to add the application namespace to the OSM control plane:

osm namespace add hello-web-app-routing

Grant permissions for Web Application Routing

Identify the Web Application Routing-associated managed identity within the cluster resource group webapprouting-<CLUSTER_NAME>. In this walkthrough, the identity is named webapprouting-myakscluster.

:::image type="content" source="media/web-app-routing/identify-msi-web-app-routing.png" alt-text="Cluster resource group in the Azure portal is shown, and the webapprouting-myakscluster user-assigned managed identity is highlighted." lightbox="media/web-app-routing/identify-msi-web-app-routing.png":::

Copy the identity's object ID:

:::image type="content" source="media/web-app-routing/msi-web-app-object-id.png" alt-text="The webapprouting-myakscluster managed identity screen in Azure portal, the identity's object ID is highlighted. " lightbox="media/web-app-routing/msi-web-app-object-id.png":::

Grant access to Azure Key Vault

Obtain the vault URI for your Azure Key Vault:

az keyvault show --resource-group myResourceGroup --name myapp-contoso

Grant GET permissions for Web Application Routing to retrieve certificates from Azure Key Vault:

az keyvault set-policy --name myapp-contoso --object-id <WEB_APP_ROUTING_MSI_OBJECT_ID>  --secret-permissions get --certificate-permissions get

Use Web Application Routing

The Web Application Routing solution may only be triggered on service resources that are annotated as follows:

annotations:
  kubernetes.azure.com/ingress-host: myapp.contoso.com
  kubernetes.azure.com/tls-cert-keyvault-uri: myapp-contoso.vault.azure.net/certificates/keyvault-certificate-name/keyvault-certificate-name-revision

These annotations in the service manifest would direct Web Application Routing to create an ingress servicing myapp.contoso.com connected to the keyvault myapp-contoso and will retrieve the keyvault-certificate-name with keyvault-certificate-name-revision

Create a file named samples-web-app-routing.yaml and copy in the following YAML. On line 29-31, update <MY_HOSTNAME> with your DNS host name and <MY_KEYVAULT_URI> with the full certficicate vault URI.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aks-helloworld  
spec:
  replicas: 1
  selector:
    matchLabels:
      app: aks-helloworld
  template:
    metadata:
      labels:
        app: aks-helloworld
    spec:
      containers:
      - name: aks-helloworld
        image: mcr.microsoft.com/azuredocs/aks-helloworld:v1
        ports:
        - containerPort: 80
        env:
        - name: TITLE
          value: "Welcome to Azure Kubernetes Service (AKS)"
---
apiVersion: v1
kind: Service
metadata:
  name: aks-helloworld
  annotations:
    kubernetes.azure.com/ingress-host: <MY_HOSTNAME>
    kubernetes.azure.com/tls-cert-keyvault-uri: <MY_KEYVAULT_URI>
spec:
  type: ClusterIP
  ports:
  - port: 80
  selector:
    app: aks-helloworld

Use the kubectl apply command to create the resources.

kubectl apply -f samples-web-app-routing.yaml -n hello-web-app-routing

The following example output shows the created resources:

deployment.apps/aks-helloworld created
service/aks-helloworld created

Verify the managed ingress was created

$ kubectl get ingress -n hello-web-app-routing

Open a web browser to <MY_HOSTNAME>, for example myapp.contoso.com and verify you see the demo application. The application may take a few minutes to appear.

Remove Web Application Routing

First, remove the associated namespace:

kubectl delete namespace hello-web-app-routing

The Web Application Routing add-on can be removed using the Azure CLI. To do so run the following command, substituting your AKS cluster and resource group name.

az aks disable-addons --addons web_application_routing  --name myAKSCluster --resource-group myResourceGroup --no-wait

When the Web Application Routing add-on is disabled, some Kubernetes resources may remain in the cluster. These resources include configMaps and secrets, and are created in the app-routing-system namespace. To maintain a clean cluster, you may want to remove these resources.

Clean up

Remove the associated Kubernetes objects created in this article using kubectl delete.

kubectl delete -f samples-web-app-routing.yaml

The example output shows Kubernetes objects have been removed.

$ kubectl delete -f samples-web-app-routing.yaml

deployment "aks-helloworld" deleted
service "aks-helloworld" deleted