Skip to content

Commit d285f9a

Browse files
LJSpillerLJSpiller
authored
Merge pull request #199352 from Nickomang/aks-web-app-routing
Web Application Routing public preview docs
2 parents e7e25c2 + f820f1b commit d285f9a

File tree

5 files changed

+271
-5
lines changed

5 files changed

+271
-5
lines changed

‎.openpublishing.redirection.json

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -43304,11 +43304,6 @@
4330443304
"redirect_url": "/azure/virtual-network/nat-gateway/quickstart-create-nat-gateway-cli",
4330543305
"redirect_document_id": true
4330643306
},
43307-
{
43308-
"source_path_from_root": "/articles/aks/web-app-routing.md",
43309-
"redirect_url": "/azure/aks/intro-kubernetes",
43310-
"redirect_document_id":false
43311-
},
4331243307
{
4331343308
"source_path_from_root": "/articles/private-link/private-endpoint-static-ip-powershell.md",
4331443309
"redirect_url": "/azure/private-link/create-private-endpoint-powershell",

‎articles/aks/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -467,6 +467,8 @@
467467
href: open-service-mesh-uninstall-add-on.md
468468
- name: Track releases and region availability
469469
href: release-tracker.md
470+
- name: Use Web Application Routing (preview)
471+
href: web-app-routing.md
470472
- name: Kubernetes Event-driven Autoscaler add-on (preview)
471473
href: keda.md
472474
- name: Use cluster extensions

‎articles/aks/draft.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,22 @@ You can also run the command on a specific directory using the `--destination` f
9090
az aks draft up --destination /Workspaces/ContosoAir
9191
```
9292

93+
## Use Web Application Routing with Draft to make your application accessible over the internet
94+
95+
[Web Application Routing][web-app-routing] is the easiest way to get your web application up and running in Kubernetes securely, removing the complexity of ingress controllers and certificate and DNS management while offering configuration for enterprises looking to bring their own. Web Application Routing offers a managed ingress controller based on nginx that you can use without restrictions and integrates out of the box with Open Service Mesh to secure intra-cluster communications.
96+
97+
To set up Draft with Web Application Routing, use `az aks draft update` and pass in the DNS name and Azure Key Vault-stored certificate when prompted:
98+
99+
```azure-cli-interactive
100+
az aks draft update
101+
```
102+
103+
You can also run the command on a specific directory using the `--destination` flag:
104+
105+
```azure-cli-interactive
106+
az aks draft update --destination /Workspaces/ContosoAir
107+
```
108+
93109
<!-- LINKS INTERNAL -->
94110
[deploy-cluster]: ./tutorial-kubernetes-deploy-cluster.md
95111
[az-feature-register]: /cli/azure/feature#az-feature-register

‎articles/aks/integrations.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ The below table shows the available add-ons.
2626
| ingress-appgw | Use Application Gateway Ingress Controller with your AKS cluster. | [What is Application Gateway Ingress Controller?][agic] |
2727
| open-service-mesh | Use Open Service Mesh with your AKS cluster. | [Open Service Mesh AKS add-on][osm] |
2828
| azure-keyvault-secrets-provider | Use Azure Keyvault Secrets Provider addon.| [Use the Azure Key Vault Provider for Secrets Store CSI Driver in an AKS cluster][keyvault-secret-provider] |
29+
| web_application_routing | Use a managed NGINX ingress Controller with your AKS cluster.| [Web Application Routing Overview][web-app-routing] |
2930

3031
## Extensions
3132

‎articles/aks/web-app-routing.md

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
---
2+
title: Web Application Routing add-on on Azure Kubernetes Service (AKS) (Preview)
3+
description: Use the Web Application Routing add-on to securely access applications deployed on Azure Kubernetes Service (AKS).
4+
services: container-service
5+
author: jahabibi
6+
ms.topic: article
7+
ms.date: 05/13/2021
8+
ms.author: jahabibi
9+
---
10+
11+
# Web Application Routing (Preview)
12+
13+
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](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) 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.
14+
15+
[!INCLUDE [preview features callout](./includes/preview/preview-callout.md)]
16+
17+
## Limitations
18+
19+
- Web Application Routing currently doesn't support named ports in ingress backend.
20+
21+
## Web Application Routing solution overview
22+
23+
The add-on deploys four components: an [nginx ingress controller][nginx], [Secrets Store CSI Driver][csi-driver], [Open Service Mesh (OSM)][osm], and [External-DNS][external-dns] controller.
24+
25+
- **Nginx ingress Controller**: The ingress controller exposed to the internet.
26+
- **External-dns**: Watches for Kubernetes Ingress resources and creates DNS A records in the cluster-specific DNS zone.
27+
- **CSI driver**: Connector used to communicate with keyvault to retrieve SSL certificates for ingress controller.
28+
- **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.
29+
- **External-DNS controller**: Watches for Kubernetes Ingress resources and creates DNS A records in the cluster-specific DNS zone.
30+
31+
## Prerequisites
32+
33+
- An Azure subscription. If you don't have an Azure subscription, you can create a [free account](https://azure.microsoft.com/free).
34+
- [Azure CLI installed](/cli/azure/install-azure-cli).
35+
36+
### Install the `aks-preview` Azure CLI extension
37+
38+
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][az-extension-add] command. Or install any available updates by using the [az extension update][az-extension-update] command.
39+
40+
```azurecli-interactive
41+
# Install the aks-preview extension
42+
az extension add --name aks-preview
43+
44+
# Update the extension to make sure you have the latest version installed
45+
az extension update --name aks-preview
46+
```
47+
48+
### Install the `osm` CLI
49+
50+
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][osm-release].
51+
52+
## Deploy Web Application Routing with the Azure CLI
53+
54+
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][az-aks-create] command with the `--enable-addons` argument.
55+
56+
```azurecli
57+
az aks create --resource-group myResourceGroup --name myAKSCluster --enable-addons web_application_routing
58+
```
59+
60+
> [!TIP]
61+
> 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`.
62+
63+
You can also enable Web Application Routing on an existing AKS cluster using the [az aks enable-addons][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:
64+
65+
```azurecli
66+
az aks enable-addons --resource-group myResourceGroup --name myAKSCluster --addons web_application_routing
67+
```
68+
69+
After the cluster is deployed or updated, use the [az aks show][az-aks-show] command to retrieve the DNS zone name.
70+
71+
## Connect to your AKS cluster
72+
73+
To connect to the Kubernetes cluster from your local computer, you use [kubectl][kubectl], the Kubernetes command-line client.
74+
75+
If you use the Azure Cloud Shell, `kubectl` is already installed. You can also install it locally using the `az aks install-cli` command:
76+
77+
```azurecli
78+
az aks install-cli
79+
```
80+
81+
To configure `kubectl` to connect to your Kubernetes cluster, use the [az aks get-credentials][az-aks-get-credentials] command. The following example gets credentials for the AKS cluster named *MyAKSCluster* in the *MyResourceGroup*:
82+
83+
```azurecli
84+
az aks get-credentials --resource-group MyResourceGroup --name MyAKSCluster
85+
```
86+
87+
## Create the application namespace
88+
89+
For the sample application environment, let's first create a namespace called `hello-web-app-routing` to run the example pods:
90+
91+
```bash
92+
kubectl create namespace hello-web-app-routing
93+
```
94+
95+
We also need to add the application namespace to the OSM control plane:
96+
97+
```bash
98+
osm namespace add hello-web-app-routing
99+
```
100+
101+
## Grant permissions for Web Application Routing
102+
103+
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`.
104+
105+
:::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":::
106+
107+
Copy the identity's object ID:
108+
109+
:::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":::
110+
111+
### Grant access to Azure Key Vault
112+
113+
Grant `GET` permissions for Web Application Routing to retrieve certificates from Azure Key Vault:
114+
115+
```azurecli
116+
az keyvault set-policy --name myapp-contoso --object-id <WEB_APP_ROUTING_MSI_OBJECT_ID> --secret-permissions get --certificate-permissions get
117+
```
118+
119+
## Use Web Application Routing
120+
121+
The Web Application Routing solution may only be triggered on service resources that are annotated as follows:
122+
123+
```yaml
124+
annotations:
125+
kubernetes.azure.com/ingress-host: myapp.contoso.com
126+
kubernetes.azure.com/tls-cert-keyvault-uri: myapp-contoso.vault.azure.net
127+
```
128+
129+
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`.
130+
131+
Create a file named **samples-web-app-routing.yaml** and copy in the following YAML. On line 29-31, update `<MY_HOSTNAME>` and `<MY_KEYVAULT_URI>` with the DNS zone name collected in the previous step of this article.
132+
133+
```yaml
134+
apiVersion: apps/v1
135+
kind: Deployment
136+
metadata:
137+
name: aks-helloworld
138+
spec:
139+
replicas: 1
140+
selector:
141+
matchLabels:
142+
app: aks-helloworld
143+
template:
144+
metadata:
145+
labels:
146+
app: aks-helloworld
147+
spec:
148+
containers:
149+
- name: aks-helloworld
150+
image: mcr.microsoft.com/azuredocs/aks-helloworld:v1
151+
ports:
152+
- containerPort: 80
153+
env:
154+
- name: TITLE
155+
value: "Welcome to Azure Kubernetes Service (AKS)"
156+
---
157+
apiVersion: v1
158+
kind: Service
159+
metadata:
160+
name: aks-helloworld
161+
annotations:
162+
kubernetes.azure.com/ingress-host: <MY_HOSTNAME>
163+
kubernetes.azure.com/tls-cert-keyvault-uri: <MY_KEYVAULT_URI>
164+
spec:
165+
type: ClusterIP
166+
ports:
167+
- port: 80
168+
selector:
169+
app: aks-helloworld
170+
```
171+
172+
Use the [kubectl apply][kubectl-apply] command to create the resources.
173+
174+
```bash
175+
kubectl apply -f samples-web-app-routing.yaml -n hello-web-app-routing
176+
```
177+
178+
The following example shows the created resources:
179+
180+
```bash
181+
$ kubectl apply -f samples-web-app-routing.yaml -n hello-web-app-routing
182+
183+
deployment.apps/aks-helloworld created
184+
service/aks-helloworld created
185+
```
186+
187+
## Verify the managed ingress was created
188+
189+
```bash
190+
$ kubectl get ingress -n hello-web-app-routing -n hello-web-app-routing
191+
```
192+
193+
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.
194+
195+
## Remove Web Application Routing
196+
197+
First, remove the associated namespace:
198+
199+
```bash
200+
kubectl delete namespace hello-web-app-routing
201+
```
202+
203+
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.
204+
205+
```azurecli
206+
az aks disable-addons --addons web_application_routing --name myAKSCluster --resource-group myResourceGroup --no-wait
207+
```
208+
209+
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.
210+
211+
Look for *addon-web-application-routing* resources using the following [kubectl get][kubectl-get] commands:
212+
213+
## Clean up
214+
215+
Remove the associated Kubernetes objects created in this article using `kubectl delete`.
216+
217+
```bash
218+
kubectl delete -f samples-web-app-routing.yaml
219+
```
220+
221+
The example output shows Kubernetes objects have been removed.
222+
223+
```bash
224+
$ kubectl delete -f samples-web-app-routing.yaml
225+
226+
deployment "aks-helloworld" deleted
227+
service "aks-helloworld" deleted
228+
```
229+
230+
<!-- LINKS - internal -->
231+
[az-aks-create]: /cli/azure/aks#az-aks-create
232+
[az-aks-show]: /cli/azure/aks#az-aks-show
233+
[ingress-https]: ./ingress-tls.md
234+
[az-aks-enable-addons]: /cli/azure/aks#az-aks-enable-addons
235+
[az-aks-install-cli]: /cli/azure/aks#az-aks-install-cli
236+
[az-aks-get-credentials]: /cli/azure/aks#az-aks-get-credentials
237+
[csi-driver]: https://github.com/Azure/secrets-store-csi-driver-provider-azure
238+
[az-extension-add]: /cli/azure/extension#az-extension-add
239+
[az-extension-update]: /cli/azure/extension#az-extension-update
240+
241+
<!-- LINKS - external -->
242+
[osm-release]: https://github.com/openservicemesh/osm/releases/
243+
[nginx]: https://kubernetes.github.io/ingress-nginx/
244+
[osm]: https://openservicemesh.io/
245+
[external-dns]: https://github.com/kubernetes-incubator/external-dns
246+
[kubectl]: https://kubernetes.io/docs/user-guide/kubectl/
247+
[kubectl-apply]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply
248+
[kubectl-get]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#get
249+
[kubectl-delete]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#delete
250+
[kubectl-logs]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#logs
251+
[ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/
252+
[ingress-resource]: https://kubernetes.io/docs/concepts/services-networking/ingress/#the-ingress-resource

0 commit comments

Comments
 (0)