Install Istio with EKS add-on

If you use Amazon Elastic Kubernetes Service (EKS) clusters, you can install Istio by using an EKS add-on.

About the add-on

The EKS add-on reduces the amount of work for you to install, configure, and update Istio. AWS validates that the add-on works on EKS, so you can be confident in using a secure, stable release. Each Istio version has two modes: Sidecar or Ambient. If you select the Ambient mode, Istio is configured in Ambient mode out of the box, requiring no additional adjustments or changes. Your organization might encourage you to use the add-on to meet internal compliance requirements or account spending obligations. For more information, see the AWS docs.

The EKS add-on installs the open source distribution of Istio, not the enterprise-level [Solo distribution of Istio](/gloo-mesh-enterprise/2.11.x/istio/images/overview/). For multicluster management and other advanced capabilities, you can install Gloo Mesh (Gloo Platform APIs) with the Solo distribution of Istio instead.

Due to a lack of support for the Istio CNI and iptables for the Istio proxy, you cannot run Istio (and therefore Gloo Mesh (Gloo Platform APIs)) on AWS Fargate. For more information, see the Amazon EKS issue.

Before you begin

Create or use existing EKS clusters. Keep in mind the following points:
- The cluster must be able to run Istio, such as meeting the performance, and application requirements.
- The cluster must run on a supported Kubernetes version. You can enable each version of the addon on an EKS cluster that supports the corresponding version of Istio.
- The cluster name must be alphanumeric with no special characters except a hyphen (-), lowercase, and begin with a letter (not a number) to follow the Kubernetes DNS label standard.
- If you plan to use Solo Enterprise for Istio, you typically install Istio in data plane clusters that run your workloads. You don’t need to install Istio in the cluster that you plan to use for the Gloo management plane.
Install any CLI tools that you might need to work with your cluster, such as the following:
- aws cli, the Amazon Web Services command line tool.
- eksctl, the AWS EKS command line tool.
- kubectl, the Kubernetes command line tool. Download the kubectl version that is within one minor version of the Kubernetes clusters you plan to use.
- istioctl, the Istio command line tool.
- terraform, the infrastructure-as-code configuration language command line tool from HashiCorp.
If you plan to install the add-on via automation such as Terraform, you must first accept the subscription terms in the AWS Marketplace console.

Install the EKS add-on

You can install the EKS add-on via the AWS console, the eksctl or aws CLI tools, or a GitOps tool such as Terraform.

Install the EKS add-on by using the EKS console. For complete EKS add-on instructions, see the AWS docs.

Open the Amazon EKS console.
From the cluster list, select your cluster.
Click the Add-ons tab.
Click Get more add-ons.
Scroll down to the AWS Marketplace add-ons section. In the search box, enter Istio and select Solo.io as the vendor to filter the results for the Solo.io Istio Distribution add-on.
Figure: Find the Solo add-on for EKS
Figure: Find the Solo add-on for EKS
Click the checkbox for the add-on, and then click Next.
If the Status field shows Requires subscription, click the View subscription options button and follow the AWS Marketplace prompts to subscribe to the add-on.
Figure: Required subscription status
Figure: Required subscription status
When the Status displays Ready to install, select the desired Istio version to install. Note that versions with an extra 0 at the end (for example, 1.23.00 instead of 1.23.0) show that this plugin configures Istio for Ambient mode.
Figure: Configure the Solo add-on for EKS
Figure: Configure the Solo add-on for EKS
In the Optional configuration settings section, you can customize the add-on by providing a YAML snippet in the bottom window. The JSON schema displayed in the top window lists the settings available for customization. The following example demonstrates how to enable Istio request logging, disable HPA, and manually specify the number of Istiod deployment replicas:
```
meshConfig:
  accessLogFile: "/dev/stdout"
pilot:
  autoscaleEnabled: false
  replicaCount: 2     
```
Figure: YAML snippet provided to customize the add-on
Figure: YAML snippet provided to customize the add-on
After keeping the default values or adjusting them in the Optional configuration settings section, you can proceed to the next step by clicking Next
Review the add-on details, and then click Create.
Figure: Review and create the Solo add-on for EKS
Figure: Review and create the Solo add-on for EKS
From the cluster details page, click the Add-ons tab and verify that the status is Active. If the installation takes more than a few minutes, review the add-on status. Common issues include a lack of compute resources to run Istio, such as no nodes.
Figure: Active status for Solo add-on for EKS
Figure: Active status for Solo add-on for EKS

Install the EKS add-on by using the eksctl command line tool. For complete EKS add-on instructions, see the AWS docs.

Get the name and region of the cluster that you want to install the add-on in.
```
eksctl get clusters -A
```
Set the name and region of the cluster that you want to install the add-on in. Replace <your-cluster-region> and <name-of-your-EKS-cluster> with the values that you got in the previous step.
```
# Set your cluster region (for example, us-west-2)
export REGION=<your-cluster-region>

# Set the name of your EKS cluster
export CLUSTER=<name-of-your-EKS-cluster>
```
Install the add-on, replacing the cluster and region with the values that you got in the previous step. For more options, such as specific version of the add-on, run eksctl create addon --help. Note: If you include an extra 0 in the version number (such as v1.22.30-eksbuild.1 instead of v1.22.3-eksbuild.1), Istio is deployed in Ambient mode. Without the extra 0, Istio is deployed in Sidecar mode.
Sidecar mode example:
```
eksctl create addon --name solo-io_istio-distro --cluster $CLUSTER --region $REGION --version v1.22.3-eksbuild.1
```
Ambient mode example: Note the extra 0 in the version number.
```
eksctl create addon --name solo-io_istio-distro --cluster $CLUSTER --region $REGION --version v1.22.30-eksbuild.1
```
To pass more parameters, you can create a temporary configuration manifest and apply it using eksctl. For example, to enable Istio request logging in Sidecar mode, disable HPA and specify the number of istiod deployment replicas manually:
```
cat <<EOF | eksctl create addon -f -
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
  name: $CLUSTER
  region: $REGION
addons:
- name: solo-io_istio-distro
  configurationValues: |-
    meshConfig:
      accessLogFile: "/dev/stdout"
    pilot:
      autoscaleEnabled: false
      replicaCount: 2
  version: v1.22.3-eksbuild.1
EOF
```

Check that the status of the addon is ACTIVE with null issues. If the installation takes more than a few minutes, review the add-on status. Common issues include a lack of compute resources to run Istio, such as no nodes.

eksctl get addon --cluster $CLUSTER --region $REGION -oyaml

Example output:

- ConfigurationValues: |-
    meshConfig:
      accessLogFile: "/dev/stdout"
    pilot:
      autoscaleEnabled: false
      replicaCount: 2
  IAMRole: ""
  Issues: null
  Name: solo-io_istio-distro
  PodIdentityAssociations: null
  Status: ACTIVE
  Version: v1.22.3-eksbuild.1

Install the EKS add-on by using the aws command line tool. For complete AWS command line tool add-on instructions, see the AWS docs.

Get the name and region of the cluster that you want to install the add-on in.
```
aws eks list-clusters --region $REGION
```
Set the name and region of the cluster that you want to install the add-on in. Replace <your-cluster-region> and <name-of-your-EKS-cluster> with the values that you got in the previous step.
```
# Set your cluster region (for example, us-west-2)
export REGION=<your-cluster-region>

# Set the name of your EKS cluster
export CLUSTER=<name-of-your-EKS-cluster>
```

Install the add-on. Note: If you include an extra 0 in the version number (such as v1.22.30-eksbuild.1 instead of v1.22.3-eksbuild.1), Istio is deployed in Ambient mode. Without the extra 0, Istio is deployed in Sidecar mode.

Sidecar mode example:

aws eks create-addon --cluster-name $CLUSTER --region $REGION \
  --addon-name solo-io_istio-distro \
  --addon-version v1.22.3-eksbuild.1

Ambient mode example: Note the extra 0 in the version number.

aws eks create-addon --cluster-name $CLUSTER --region $REGION \
  --addon-name solo-io_istio-distro \
  --addon-version v1.22.30-eksbuild.1

To pass custom parameters to an AWS EKS add-on, convert your YAML configuration to JSON. Then, pass the JSON in the aws command, such as in the following example to enable Istio request logging in Sidecar mode, disable HPA and specify the number of istiod deployment replicas manually. Note: If the add-on is already installed, use update-addon instead of create-addon in the aws command.)

Sidecar mode with custom parameters:

aws eks create-addon --cluster-name $CLUSTER --region $REGION \
  --addon-name solo-io_istio-distro \
  --addon-version v1.22.3-eksbuild.1 \
  --configuration-values '{"meshConfig":{"accessLogFile":"/dev/stdout"},"pilot":{"autoscaleEnabled":false,"replicaCount":2}}'

Ambient mode with custom parameters: Note the extra 0 in the version number.

aws eks create-addon --cluster-name $CLUSTER --region $REGION \
  --addon-name solo-io_istio-distro \
  --addon-version v1.22.30-eksbuild.1 \
  --configuration-values '{"meshConfig":{"accessLogFile":"/dev/stdout"},"pilot":{"autoscaleEnabled":false,"replicaCount":2}}'

Check that the status of the addon is ACTIVE with empty [] in Issues section. If the installation takes more than a few minutes, review the add-on status. Common issues include a lack of compute resources to run Istio, such as no nodes.

aws eks describe-addon --cluster-name $CLUSTER --region $REGION --addon-name solo-io_istio-distro

Example output:

{
    "addon": {
        "addonName": "solo-io_istio-distro",
        "clusterName": "<...omitted...>",
        "status": "ACTIVE",
        "addonVersion": "v1.22.3-eksbuild.1",
        "health": {
            "issues": []
        },
        "addonArn": "arn:aws:eks:us-west-2:123456789012:addon/<...omitted...>/solo-io_istio-distro/48c8975b-414c-5a6b-0e52-d838c81af853",
        "createdAt": "2024-09-06TXX:XX:XX.000000-07:00",
        "modifiedAt": "2024-09-06TXX:XX:XX.000000-07:00",
        "tags": {},
        "configurationValues": "{\"meshConfig\":{\"accessLogFile\":\"/dev/stdout\"},\"pilot\":{\"autoscaleEnabled\":false,\"replicaCount\":2}}"
    }
}

Install the EKS add-on by using Terraform, such as for a GitOps pipeline.

Get the cluster name, cluster region, and EKS add-on version that you want to install.

Use the following example inside of your Terraform project, or directly by saving the example as main.tf. Replace the region, cluster_name and addon_version with the values that you previously got. The configuration_values subsection is provided as an example. Decide on the values that you want to customize, or remove the section entirely if the default values are sufficient.

provider "aws" {
  region = local.region
}

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.47"
    }
  }
}

locals {
  region        = "<your-cluster-region>"      # Replace with your cluster region (for example, us-west-2)
  cluster_name  = "<name-of-your-EKS-cluster>" # Replace with the name of your EKS cluster

  # Replace with your desired add-on version. 
  # For Sidecar mode, use the standard version format (e.g., v1.22.3-eksbuild.1).
  # For Ambient mode, add an extra '0' in the version number (e.g., v1.22.30-eksbuild.1).
  addon_version = "v1.22.3-eksbuild.1"
}

resource "aws_eks_addon" "solo-io_istio-distro" {
  cluster_name                = local.cluster_name
  addon_name                  = "solo-io_istio-distro"
  resolve_conflicts_on_update = "OVERWRITE"
  addon_version               = local.addon_version
  configuration_values = jsonencode({
    meshConfig : {
      accessLogFile : "/dev/stdout"
    },
    pilot : { 
      autoscaleEnabled : false,
      replicaCount : 2
    }
  })
}

From the directory of the main.tf file, run the Terraform commands to build the EKS add-on infrastructure.
```
terraform init
terraform plan
terraform apply -auto-approve
```

Verify your installation

After the add-on is installed, verify that Istio is working.

Verify that the istiod pod has a status of Running.

kubectl get pods -n istio-system

Example output:

NAME                      READY   STATUS    RESTARTS   AGE
istio-cni-node-5rw2f      1/1     Running   0          34s
istio-cni-node-sbj7w      1/1     Running   0          34s
istiod-569857ddc6-mhcvg   1/1     Running   0          34s

kubectl get pods -n istio-system

Example output:

NAME                      READY   STATUS    RESTARTS   AGE
istio-cni-node-cknmk      1/1     Running   0          69s
istio-cni-node-p27dn      1/1     Running   0          69s
istiod-74b684745b-m6pxh   1/1     Running   0          69s
ztunnel-75slj             1/1     Running   0          69s
ztunnel-xdhkg             1/1     Running   0          69s

Verify that istiod uses the solo-io distribution of Istio.

kubectl describe pod -n istio-system -l app=istiod | grep -i image:

Example output: Note solo-io in the image repository.

Image:         709825985650.dkr.ecr.us-east-1.amazonaws.com/solo-io/f1d618dd76/pilot:1.22.3

If you applied custom configurations, you can verify them within the related components of your EKS cluster. For instance, to confirm the meshConfig example mentioned earlier, check the configuration via the ConfigMap with the following command.
```
kubectl get configmap -n istio-system istio -o yaml | grep accessLog
```
Example output:
```
accessLogFile: /dev/stdout
```
If you customized a setting such as the number of replicas in the previous example, verify that your changes are made. For example, the following command verifies that the replicas are now set to 2.
```
kubectl describe deployments.apps -n istio-system istiod | grep Replicas:
```
Example output:
```
Replicas:               2 desired | 2 updated | 2 total | 2 available | 0 unavailable
```

Next steps

Now that Istio is installed in your cluster, review the following next steps you can take.

Service mesh management: Follow the community Istio docs to manage your service mesh. For example, you might try out the following guides:
- Test Istio by deploying the sample Bookinfo app.
- Install an Istio ingress gateway to control external traffic.
Add-on management: The EKS add-on simplifies installing Istio. When Solo releases a new version of Istio for the EKS add-on, you can upgrade to this version by following the AWS guide.
Multicluster enterprise features: Install Gloo Mesh (Gloo Platform APIs) and the Solo distribution of Istio instead. If you use the add-on to install Istio, you must repeat the installation in each workload cluster. Then, you create Istio gateways for ingress and east-west traffic, such as described in the manual Istio deployment guide.

Please share your experience about the Solo.io Istio Distribution add-on for Amazon EKS by [filling out this feedback form](https://docs.google.com/forms/d/e/1FAIpQLScT7awIucKCZ2WaL6H-zBn9vil_iXeGf2-c5a6ZC_7ECwv7mw/viewform?usp=sf_link).

Uninstall the add-on

You can uninstall the Solo distribution of Istio from by using AWS. Keep in mind that this action removes the Istio service mesh from your cluster.

For more information about removing an EKS add-on, see the AWS docs.

Remove the Solo distribution of Istio add-on for EKS.
1. Open the Amazon EKS console.
2. From the cluster list, select your cluster.
3. Click the Add-ons tab.
4. In the search box, enter solo to filter the results for the Solo.io Istio Distribution add-on.
  Figure: Find the Solo add-on for EKS
  Figure: Find the Solo add-on for EKS
5. Click the add-on, and then click Remove.
6. In the pop-up window, type the add-on name and click Remove. You can keep Istio running in your cluster but disable EKS add-on management by toggling Preserve on cluster.
  Figure: Remove the Solo add-on for EKS
  Figure: Remove the Solo add-on for EKS
Note: To keep Istio running in your cluster but turn off EKS add-on management, include the --preserve option.
eksctl delete addon --name solo-io_istio-distro --cluster $CLUSTER
Note: To keep Istio running in your cluster but turn off EKS add-on management, include the --preserve option.
aws eks delete-addon --cluster-name $CLUSTER --region $REGION --addon-name solo-io_istio-distro
terraform destroy -auto-approve
Clean up the istio-system namespace in your cluster.
```
kubectl delete namespace istio-system
```

Install Istio with Helm Add apps to the service mesh