Edit

Deploy Istio-based service mesh add-on for Azure Kubernetes Service (preview)

  • Article

This article shows you how to install the Istio-based service mesh add-on for Azure Kubernetes Service (AKS) cluster.

For more information on Istio and the service mesh add-on, see Istio-based service mesh add-on for Azure Kubernetes Service.

Important

AKS preview features are available on a self-service, opt-in basis. Previews are provided "as is" and "as available," and they're excluded from the service-level agreements and limited warranty. AKS previews are partially covered by customer support on a best-effort basis. As such, these features aren't meant for production use. For more information, see the following support articles:

Before you begin

Set environment variables

export CLUSTER=<cluster-name>
export RESOURCE_GROUP=<resource-group-name>
export LOCATION=<location>

Verify Azure CLI and aks-preview extension versions

The add-on requires:

  • Azure CLI version 2.44.0 or later installed. To install or upgrade, see [Install Azure CLI][install-azure-cli].
  • aks-preview Azure CLI extension of version 0.5.133 or later installed

You can run az --version to verify above versions.

To install the aks-preview extension, run the following command:

az extension add --name aks-preview

Run the following command to update to the latest version of the extension released:

az extension update --name aks-preview

Register the AzureServiceMeshPreview feature flag

Register the AzureServiceMeshPreview feature flag by using the az feature register command:

az feature register --namespace "Microsoft.ContainerService" --name "AzureServiceMeshPreview"

It takes a few minutes for the feature to register. Verify the registration status by using the az feature show command:

az feature show --namespace "Microsoft.ContainerService" --name "AzureServiceMeshPreview"

When the status reflects Registered, refresh the registration of the Microsoft.ContainerService resource provider by using the az provider register command:

az provider register --namespace Microsoft.ContainerService

Install Istio add-on at the time of cluster creation

To install the Istio add-on when creating the cluster, use the --enable-azure-service-mesh or--enable-asm parameter.

az group create --name ${RESOURCE_GROUP} --location ${LOCATION}

az aks create \
--resource-group ${RESOURCE_GROUP} \
--name ${CLUSTER} \
--enable-asm

Install Istio add-on for existing cluster

The following example enables Istio add-on for an existing AKS cluster:

Important

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. For more information, see uninstall the OSM add-on from your AKS cluster. Istio add-on can only be enabled on AKS clusters of version >= 1.23.

az aks mesh enable --resource-group ${RESOURCE_GROUP} --name ${CLUSTER}

Verify successful installation

To verify the Istio add-on is installed on your cluster, run the following command:

az aks show --resource-group ${RESOURCE_GROUP} --name ${CLUSTER}  --query 'serviceMeshProfile.mode'

Confirm the output shows Istio.

Use az aks get-credentials to the credentials for your AKS cluster:

az aks get-credentials --resource-group ${RESOURCE_GROUP} --name ${CLUSTER}

Use kubectl to verify that istiod (Istio control plane) pods are running successfully:

kubectl get pods -n aks-istio-system

Confirm the istiod pod has a status of Running. For example:

NAME                               READY   STATUS    RESTARTS   AGE
istiod-asm-1-17-74f7f7c46c-xfdtl   1/1     Running   0          2m

Enable sidecar injection

To automatically install sidecar to any new pods, annotate your namespaces:

kubectl label namespace default istio.io/rev=asm-1-17

Important

The default istio-injection=enabled labeling doesn't work. Explicit versioning (istio.io/rev=asm-1-17) is required.

For manual injection of sidecar using istioctl kube-inject, you need to specify extra parameters for istioNamespace (-i) and revision (-r). Example:

kubectl apply -f <(istioctl kube-inject -f sample.yaml -i aks-istio-system -r asm-1-17) -n foo

Deploy sample application

Use kubectl apply to deploy the sample application on the cluster:

kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.17/samples/bookinfo/platform/kube/bookinfo.yaml

Confirm several deployments and services are created on your cluster. For example:

service/details created
serviceaccount/bookinfo-details created
deployment.apps/details-v1 created
service/ratings created
serviceaccount/bookinfo-ratings created
deployment.apps/ratings-v1 created
service/reviews created
serviceaccount/bookinfo-reviews created
deployment.apps/reviews-v1 created
deployment.apps/reviews-v2 created
deployment.apps/reviews-v3 created
service/productpage created
serviceaccount/bookinfo-productpage created
deployment.apps/productpage-v1 created

Use kubectl get services to verify that the services were created successfully:

kubectl get services

Confirm the following services were deployed:

NAME          TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
details       ClusterIP   10.0.180.193   <none>        9080/TCP   87s
kubernetes    ClusterIP   10.0.0.1       <none>        443/TCP    15m
productpage   ClusterIP   10.0.112.238   <none>        9080/TCP   86s
ratings       ClusterIP   10.0.15.201    <none>        9080/TCP   86s
reviews       ClusterIP   10.0.73.95     <none>        9080/TCP   86s

kubectl get pods

Confirm that all the pods have status of Running.

NAME          TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
details-v1-558b8b4b76-2llld       2/2     Running   0          2m41s
productpage-v1-6987489c74-lpkgl   2/2     Running   0          2m40s
ratings-v1-7dc98c7588-vzftc       2/2     Running   0          2m41s
reviews-v1-7f99cc4496-gdxfn       2/2     Running   0          2m41s
reviews-v2-7d79d5bd5d-8zzqd       2/2     Running   0          2m41s
reviews-v3-7dbcdcbc56-m8dph       2/2     Running   0          2m41s

Note

Each pod has two containers, one of which is the Envoy sidecar injected by Istio and the other is the application container.

To test this sample application against ingress, check out next-steps.

Delete resources

Use kubectl delete to delete the sample application:

kubectl delete -f https://raw.githubusercontent.com/istio/istio/release-1.17/samples/bookinfo/platform/kube/bookinfo.yaml

If you don't intend to enable Istio ingress on your cluster and want to disable the Istio add-on, run the following command:

az aks mesh disable --resource-group ${RESOURCE_GROUP} --name ${CLUSTER}

Caution

Disabling the service mesh addon will completely remove the Istio control plane from the cluster.

Istio CustomResourceDefintions (CRDs) aren't be deleted by default. To clean them up, use:

kubectl delete crd $(kubectl get crd -A | grep "istio.io" | awk '{print $1}')

Use az group delete to delete your cluster and the associated resources:

az group delete --name ${RESOURCE_GROUP} --yes --no-wait

Next steps