Skip to content

Commit 8832384

Browse files
author
naman-msft
committed
added new doc
1 parent 17bad14 commit 8832384

File tree

3 files changed

+514
-0
lines changed

3 files changed

+514
-0
lines changed

‎scenarios/azure-aks-docs/articles/aks/istio-deploy-addon.md

+237
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
---
2+
title: Deploy Istio-based service mesh add-on for Azure Kubernetes Service
3+
description: Deploy Istio-based service mesh add-on for Azure Kubernetes Service
4+
ms.topic: how-to
5+
ms.custom: devx-track-azurecli, innovation-engine
6+
ms.service: azure-kubernetes-service
7+
ms.date: 03/28/2024
8+
ms.author: shasb
9+
author: shashankbarsin
10+
---
11+
12+
# Deploy Istio-based service mesh add-on for Azure Kubernetes Service
13+
14+
This article shows you how to install the Istio-based service mesh add-on for Azure Kubernetes Service (AKS) cluster.
15+
16+
For more information on Istio and the service mesh add-on, see [Istio-based service mesh add-on for Azure Kubernetes Service][istio-about].
17+
18+
## Before you begin
19+
20+
* The add-on requires Azure CLI version 2.57.0 or later installed. You can run `az --version` to verify version. To install or upgrade, see [Install Azure CLI][azure-cli-install].
21+
* To find information about which Istio add-on revisions are available in a region and their compatibility with AKS cluster versions, use the command [`az aks mesh get-revisions`][az-aks-mesh-get-revisions]:
22+
23+
```azurecli-interactive
24+
az aks mesh get-revisions --location EastUS2 -o table
25+
```
26+
* In some cases, Istio CRDs from previous installations may not be automatically cleaned up on uninstall. Ensure existing Istio CRDs are deleted:
27+
28+
```text
29+
kubectl delete crd $(kubectl get crd -A | grep "istio.io" | awk '{print $1}')
30+
```
31+
It is recommend to also clean up other resources from self-managed installations of Istio such as ClusterRoles, MutatingWebhookConfigurations and ValidatingWebhookConfigurations.
32+
33+
* Note that if you choose to use any `istioctl` CLI commands, you will need to include a flag to point to the add-on installation of Istio: `--istioNamespace aks-istio-system`
34+
35+
## Install Istio add-on
36+
37+
This section includes steps to install the Istio add-on during cluster creation or enable for an existing cluster using the Azure CLI. If you want to install the add-on using Bicep, see the guide for [installing an AKS cluster with the Istio service mesh add-on using Bicep][install-aks-cluster-istio-bicep]. To learn more about the Bicep resource definition for an AKS cluster, see [Bicep managedCluster reference][bicep-aks-resource-definition].
38+
39+
### Revision selection
40+
41+
If you enable the add-on without specifying a revision, a default supported revision is installed for you.
42+
43+
To specify a revision, perform the following steps.
44+
45+
1. Use the [`az aks mesh get-revisions`][az-aks-mesh-get-revisions] command to check which revisions are available for different AKS cluster versions in a region.
46+
1. Based on the available revisions, you can include the `--revision asm-X-Y` (ex: `--revision asm-1-20`) flag in the enable command you use for mesh installation.
47+
48+
### Install mesh during cluster creation
49+
50+
To install the Istio add-on when creating the cluster, use the `--enable-azure-service-mesh` or `--enable-asm` parameter.
51+
52+
```text
53+
az group create --name ${RESOURCE_GROUP} --location ${LOCATION}
54+
```
55+
56+
```text
57+
az aks create \
58+
--resource-group ${RESOURCE_GROUP} \
59+
--name ${CLUSTER} \
60+
--enable-asm \
61+
--generate-ssh-keys
62+
```
63+
64+
### Install mesh for existing cluster
65+
66+
The following example enables Istio add-on for an existing AKS cluster:
67+
68+
> [!IMPORTANT]
69+
> You can't enable the Istio add-on on an existing cluster if an OSM add-on is already on your cluster. Uninstall the OSM add-on before installing the Istio add-on.
70+
> For more information, see [uninstall the OSM add-on from your AKS cluster][uninstall-osm-addon].
71+
> Istio add-on can only be enabled on AKS clusters of version >= 1.23.
72+
73+
```bash
74+
az aks mesh enable --resource-group ${RESOURCE_GROUP} --name ${CLUSTER}
75+
```
76+
77+
## Verify successful installation
78+
79+
To verify the Istio add-on is installed on your cluster, run the following command:
80+
81+
```azurecli-interactive
82+
az aks show --resource-group ${RESOURCE_GROUP} --name ${CLUSTER} --query 'serviceMeshProfile.mode'
83+
```
84+
85+
Confirm the output shows `Istio`.
86+
87+
Use `az aks get-credentials` to retrieve the credentials for your AKS cluster:
88+
89+
```azurecli-interactive
90+
az aks get-credentials --resource-group ${RESOURCE_GROUP} --name ${CLUSTER}
91+
```
92+
93+
Use `kubectl` to verify that `istiod` (Istio control plane) pods are running successfully:
94+
95+
```bash
96+
kubectl get pods -n aks-istio-system
97+
```
98+
99+
Confirm the `istiod` pod has a status of `Running`. For example:
100+
101+
```
102+
NAME READY STATUS RESTARTS AGE
103+
istiod-asm-1-18-74f7f7c46c-xfdtl 1/1 Running 0 2m
104+
istiod-asm-1-18-74f7f7c46c-4nt2v 1/1 Running 0 2m
105+
```
106+
107+
## Enable sidecar injection
108+
109+
To automatically install sidecar to any new pods, you need to annotate your namespaces with the revision label corresponding to the control plane revision currently installed.
110+
111+
If you're unsure which revision is installed, use:
112+
113+
```azurecli-interactive
114+
az aks show --resource-group ${RESOURCE_GROUP} --name ${CLUSTER} --query 'serviceMeshProfile.istio.revisions'
115+
```
116+
117+
Apply the revision label:
118+
119+
```bash
120+
kubectl label namespace default istio.io/rev=asm-X-Y
121+
```
122+
123+
> [!IMPORTANT]
124+
> The default `istio-injection=enabled` labeling doesn't work. Explicit versioning matching the control plane revision (ex: `istio.io/rev=asm-1-18`) is required.
125+
126+
For manual injection of sidecar using `istioctl kube-inject`, you need to specify extra parameters for `istioNamespace` (`-i`) and `revision` (`-r`). For example:
127+
128+
```text
129+
kubectl apply -f <(istioctl kube-inject -f sample.yaml -i aks-istio-system -r asm-X-Y) -n foo
130+
```
131+
132+
## Trigger sidecar injection
133+
134+
You can either deploy the sample application provided for testing, or trigger sidecar injection for existing workloads.
135+
136+
### Existing applications
137+
138+
If you have existing applications to be added to the mesh, ensure their namespaces are labeled as in the previous step, and then restart their deployments to trigger sidecar injection:
139+
140+
```text
141+
kubectl rollout restart -n <namespace> <deployment name>
142+
```
143+
144+
Verify that sidecar injection succeeded by ensuring all containers are ready and looking for the `istio-proxy` container in the `kubectl describe` output, for example:
145+
146+
```text
147+
kubectl describe pod -n namespace <pod name>
148+
```
149+
150+
The `istio-proxy` container is the Envoy sidecar. Your application is now part of the data plane.
151+
152+
### Deploy sample application
153+
154+
Use `kubectl apply` to deploy the sample application on the cluster:
155+
156+
```bash
157+
kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.18/samples/bookinfo/platform/kube/bookinfo.yaml
158+
```
159+
> [!NOTE]
160+
> Clusters using an HTTP proxy for outbound internet access will need to set up a Service Entry. For setup instructions see [HTTP proxy support in Azure Kubernetes Service](./http-proxy.md#istio-add-on-http-proxy-for-external-services)
161+
162+
Confirm several deployments and services are created on your cluster. For example:
163+
164+
```output
165+
service/details created
166+
serviceaccount/bookinfo-details created
167+
deployment.apps/details-v1 created
168+
service/ratings created
169+
serviceaccount/bookinfo-ratings created
170+
deployment.apps/ratings-v1 created
171+
service/reviews created
172+
serviceaccount/bookinfo-reviews created
173+
deployment.apps/reviews-v1 created
174+
deployment.apps/reviews-v2 created
175+
deployment.apps/reviews-v3 created
176+
service/productpage created
177+
serviceaccount/bookinfo-productpage created
178+
deployment.apps/productpage-v1 created
179+
```
180+
181+
Use `kubectl get services` to verify that the services were created successfully:
182+
183+
```bash
184+
kubectl get services
185+
```
186+
187+
Confirm the following services were deployed:
188+
189+
```output
190+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
191+
details ClusterIP 10.0.180.193 <none> 9080/TCP 87s
192+
kubernetes ClusterIP 10.0.0.1 <none> 443/TCP 15m
193+
productpage ClusterIP 10.0.112.238 <none> 9080/TCP 86s
194+
ratings ClusterIP 10.0.15.201 <none> 9080/TCP 86s
195+
reviews ClusterIP 10.0.73.95 <none> 9080/TCP 86s
196+
```
197+
198+
```bash
199+
kubectl get pods
200+
```
201+
202+
```output
203+
NAME READY STATUS RESTARTS AGE
204+
details-v1-558b8b4b76-2llld 2/2 Running 0 2m41s
205+
productpage-v1-6987489c74-lpkgl 2/2 Running 0 2m40s
206+
ratings-v1-7dc98c7588-vzftc 2/2 Running 0 2m41s
207+
reviews-v1-7f99cc4496-gdxfn 2/2 Running 0 2m41s
208+
reviews-v2-7d79d5bd5d-8zzqd 2/2 Running 0 2m41s
209+
reviews-v3-7dbcdcbc56-m8dph 2/2 Running 0 2m41s
210+
```
211+
212+
Confirm that all the pods have status of `Running` with two containers in the `READY` column. The second container (`istio-proxy`) added to each pod is the Envoy sidecar injected by Istio, and the other is the application container.
213+
214+
To test this sample application against ingress, check out [next-steps](#next-steps).
215+
216+
## Next steps
217+
218+
* [Deploy external or internal ingresses for Istio service mesh add-on][istio-deploy-ingress]
219+
* [Scale istiod and ingress gateway HPA][istio-scaling-guide]
220+
* [Collect metrics for Istio service mesh add-on workloads in Azure Managed Prometheus][istio-metrics-managed-prometheus]
221+
222+
<!--- External Links --->
223+
[install-aks-cluster-istio-bicep]: https://github.com/Azure-Samples/aks-istio-addon-bicep
224+
[uninstall-istio-oss]: https://istio.io/latest/docs/setup/install/istioctl/#uninstall-istio
225+
226+
<!--- Internal Links --->
227+
[istio-about]: istio-about.md
228+
[azure-cli-install]: /cli/azure/install-azure-cli
229+
[az-feature-register]: /cli/azure/feature#az-feature-register
230+
[az-feature-show]: /cli/azure/feature#az-feature-show
231+
[az-provider-register]: /cli/azure/provider#az-provider-register
232+
[uninstall-osm-addon]: open-service-mesh-uninstall-add-on.md
233+
[istio-deploy-ingress]: istio-deploy-ingress.md
234+
[az-aks-mesh-get-revisions]: /cli/azure/aks/mesh#az-aks-mesh-get-revisions(aks-preview)
235+
[bicep-aks-resource-definition]: /azure/templates/microsoft.containerservice/managedclusters
236+
[istio-scaling-guide]: istio-scale.md#scaling
237+
[istio-metrics-managed-prometheus]: istio-metrics-managed-prometheus.md

‎scenarios/metadata.json

+40
Original file line numberDiff line numberDiff line change
@@ -1893,5 +1893,45 @@
18931893
}
18941894
]
18951895
}
1896+
},
1897+
{
1898+
"status": "active",
1899+
"key": "azure-aks-docs/articles/aks/istio-deploy-addon.md",
1900+
"title": "Deploy Istio-based service mesh add-on for Azure Kubernetes Service",
1901+
"description": "Deploy Istio-based service mesh add-on for Azure Kubernetes Service",
1902+
"stackDetails": "",
1903+
"sourceUrl": "https://raw.githubusercontent.com/MicrosoftDocs/executable-docs/main/scenarios/azure-aks-docs/articles/aks/istio-deploy-addon.md",
1904+
"documentationUrl": "https://learn.microsoft.com/en-us/azure/aks/cost-analysis",
1905+
"nextSteps": [
1906+
{
1907+
"title": "Deploy external or internal ingresses for Istio service mesh add-on",
1908+
"url": "https://github.com/MicrosoftDocs/azure-aks-docs/blob/main/articles/aks/istio-deploy-ingress.md"
1909+
},
1910+
{
1911+
"title": "Scale istiod and ingress gateway HPA",
1912+
"url": "https://github.com/MicrosoftDocs/azure-aks-docs/blob/main/articles/aks/istio-scale.md#scaling"
1913+
},
1914+
{
1915+
"title": "Collect metrics for Istio service mesh add-on workloads in Azure Managed Prometheus",
1916+
"url": "https://github.com/MicrosoftDocs/azure-aks-docs/blob/main/articles/aks/istio-metrics-managed-prometheus.md"
1917+
}
1918+
],
1919+
"configurations": {
1920+
"permissions": [],
1921+
"configurableParams": [
1922+
{
1923+
"inputType": "textInput",
1924+
"commandKey": "RESOURCE_GROUP",
1925+
"title": "Resource Group Name",
1926+
"defaultValue": ""
1927+
},
1928+
{
1929+
"inputType": "textInput",
1930+
"commandKey": "CLUSTER",
1931+
"title": "AKS Cluster Name",
1932+
"defaultValue": ""
1933+
}
1934+
]
1935+
}
18961936
}
18971937
]

0 commit comments

Comments
 (0)