EKS add-on

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

1. Get the name and region of the cluster that you want to install the add-on in.

   eksctl get clusters -A

2. 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>

3. 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

4. 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.

1. Get the name and region of the cluster that you want to install the add-on in.

   aws eks list-clusters --region $REGION

2. 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>

3. 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}}'

4. 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.

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

2. 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
       }
     })
   }   

3. 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