Istio Installation and Initial Setup

Last Updated: October 12, 2026 · Install pin: Istio 1.31.1

As of October 12, 2026, Istio 1.31.1 is the current 1.31 patch; it fixes a BackendTLSPolicy plaintext fallback. The Helm command examples below have been advanced from 1.31.0; that earlier chart render is not a validation of every 1.31.1 value, so render and inspect the selected chart before applying it.

This document covers how to install and initially configure Istio on an Amazon EKS cluster.

Table of Contents

1. Prerequisites
2. Choosing an Installation Method
3. Installation Using istioctl
4. Installation Using Helm
5. Declarative Installation with istioctl
6. Installation Profiles
7. Installation Verification
8. Sample Application Deployment
9. Istio Removal
10. Troubleshooting

Prerequisites

Before installing Istio, the following requirements must be met:

1. Amazon EKS Cluster

• Kubernetes version: EKS 1.34–1.37 for this Istio 1.31.1 example (reviewed October 12, 2026). Istio 1.31 supports 1.32–1.37; EKS 1.31–1.33 are in extended support and 1.34–1.37 in standard support. Check both the Istio matrix and EKS lifecycle.
• Node type: Minimum 2 worker nodes (recommended: 3 or more)
• Node size: Minimum 2 vCPU, 4GB RAM (recommended: t3.medium or larger)

These examples target Linux EC2 worker nodes. Fargate cannot run the DaemonSets/privileged networking needed by these Istio installation paths. EKS Auto Mode has a different managed networking/load-balancing model; validate its prerequisites separately.

2. kubectl Installation and Configuration

# Verify kubectl installation
kubectl version --client

# Verify EKS cluster connection
kubectl get nodes

3. Required Tools

• AWS CLI: 2.x or higher
• eksctl: (Optional) For cluster management
• Helm: a currently supported Helm 3 or Helm 4 release (minimum 3.6; see the official installation guide)

4. Cluster Resources

Illustrative planning requests, not universal minimums; size from measured load:

• Control Plane: 1 vCPU, 1.5GB RAM
• Sidecar (per pod): 0.1 vCPU, 128MB RAM

Choosing an Installation Method

Choose one supported installation path; do not run the istioctl and Helm installations on the same control plane:

Method	Advantages	Disadvantages	Recommended Use Case
istioctl	Simple and fast, provides validation features	Requires explicit reconciliation in automation	Development and production
Helm	GitOps friendly, easy version management	Configuration can be complex	Production environments, CI/CD pipelines

Installation Using istioctl

istioctl is Istio's official CLI tool and the simplest installation method.

1. Install istioctl

# Download the current 1.31 patch
curl -fsSL https://istio.io/downloadIstio | ISTIO_VERSION=1.31.1 sh -

# Add istioctl to PATH
cd istio-1.31.1
export PATH=$PWD/bin:$PATH

# Verify installation
istioctl version

2. Pre-installation Cluster Validation

# Verify cluster meets Istio installation requirements
istioctl x precheck

3. Install Istio

# Install with default profile
istioctl install --set profile=default -y

# Check installation progress
kubectl get pods -n istio-system

4. Verify Installation

# Check Istio components
kubectl get all -n istio-system

# Check istiod logs
kubectl logs -n istio-system -l app=istiod

Installation Using Helm

The 1.31.0 charts rendered during the previous review did not contain an eks platform profile. The chart examples below now pin 1.31.1, but this review did not render that patch's chart; inspect the selected chart before install. These examples omit global.platform=eks rather than assume a profile exists, and use explicit EKS prerequisites and load-balancer settings.

Helm is a Kubernetes package manager suitable for GitOps workflows.

1. Add Helm Repository

# Add Istio Helm repository
helm repo add istio https://blob.istio.io/istio-release/charts
helm repo update

2. Install istio-base

istio-base installs Istio's CRDs (Custom Resource Definitions).

# Create istio-system namespace
kubectl create namespace istio-system

# Install istio-base chart
helm install istio-base istio/base \
  -n istio-system \
  --set defaultRevision=default \
  --version 1.31.1

3. Install istiod

istiod is the Istio Control Plane.

# Install istiod chart
helm install istiod istio/istiod \
  -n istio-system \
  --version 1.31.1 \
  --wait

4. Install Istio Ingress Gateway (Optional)

# Verify the gateway namespace
kubectl get namespace istio-system

# Install Istio Ingress Gateway
helm install istio-ingressgateway istio/gateway \
  -n istio-system \
  --set labels.istio=ingressgateway \
  --set labels.app=istio-ingressgateway \
  --version 1.31.1 \
  --wait

5. Custom Installation Using values.yaml

# values.yaml
global:
  hub: docker.io/istio
  tag: 1.31.1

autoscaleEnabled: true
autoscaleMin: 2
autoscaleMax: 5
resources:
  requests:
    cpu: 500m
    memory: 2048Mi

meshConfig:
  accessLogFile: /dev/stdout

# Install using values.yaml file
helm upgrade --install istiod istio/istiod \
  -n istio-system \
  --version 1.31.1 \
  -f values.yaml \
  --wait

Declarative Installation with istioctl

The upstream in-cluster operator was deprecated in 1.23 and removed in 1.24. istioctl operator init/remove and applying an IstioOperator object to the cluster are not current installation methods. The IstioOperator file format remains supported as input to istioctl.

# istio-operator.yaml
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
  name: istio-control-plane
  namespace: istio-system
spec:
  profile: default
  meshConfig:
    accessLogFile: /dev/stdout
  components:
    pilot:
      k8s:
        resources:
          requests:
            cpu: 500m
            memory: 2Gi
          limits:
            cpu: 1000m
            memory: 4Gi
        hpaSpec:
          minReplicas: 2
          maxReplicas: 5

istioctl install -f istio-operator.yaml
kubectl rollout status deployment/istiod -n istio-system

Installation Profiles

Istio provides various profiles for different use cases.

Available Profiles

Profile	Description	Components	Recommended Use
default	Default settings for production deployment	istiod, ingress gateway	Most production environments
demo	Demonstration settings, not all features	istiod, ingress gateway, egress gateway, high trace sampling	Development and demos
minimal	Only minimal components installed	istiod only	Resource-constrained environments
remote	For remote cluster in multi-cluster environment	-	Multi-cluster setup
empty	No default configuration	-	Complete custom setup
preview	Includes experimental features	Various experimental features	Test environments
ambient	Sidecarless L4 mesh	istiod, CNI, ztunnel; L7 waypoints configured separately	Ambient deployments

The component list applies to istioctl. Helm requires installing each chart separately; a profile does not install other charts.

Check Profiles

helm show values istio/istiod --version 1.31.1
istioctl manifest generate --set profile=default > default.yaml
istioctl manifest generate --set profile=demo > demo.yaml
diff -u default.yaml demo.yaml

Installation by Profile

# Install with demo profile
istioctl install --set profile=demo -y

# Install with minimal profile
istioctl install --set profile=minimal -y

Customizing Profiles

# Modify specific settings based on profile
istioctl install --set profile=default \
  --set meshConfig.accessLogFile=/dev/stdout \
  --set components.pilot.k8s.resources.requests.memory=2Gi \
  -y

Installation Verification

1. Check Control Plane

# Check all resources in istio-system namespace
kubectl get all -n istio-system

# Check istiod status
kubectl get deployment istiod -n istio-system

# Check istiod logs
kubectl logs -n istio-system -l app=istiod --tail=100

2. Check Istio Version

# Control Plane version
istioctl version

# Or
kubectl get pods -n istio-system -o yaml | grep image:

3. Validate Istio Configuration

# Check Istio installation status
kubectl rollout status deployment/istiod -n istio-system
istioctl proxy-status

# Analyze Istio configuration
istioctl analyze -A

4. Check Webhooks

# Check MutatingWebhookConfiguration
kubectl get mutatingwebhookconfiguration

# Check ValidatingWebhookConfiguration
kubectl get validatingwebhookconfiguration

Sample Application Deployment

Istio includes a sample application called Bookinfo.

Run these commands from the extracted istio-1.31.1 directory with the default namespace selected (kubectl config set-context --current --namespace=default). For Helm, install the optional gateway above first. The dashboard commands later require separately installed telemetry addons.

1. Enable Automatic Sidecar Injection for Namespace

# Add label to default namespace
kubectl label namespace default istio-injection=enabled --overwrite

# Verify label
kubectl get namespace -L istio-injection

Existing pods need recreation after changing injection labels. Use a namespace without a conflicting istio.io/rev or ambient label.

2. Deploy Bookinfo Application

# Deploy Bookinfo application
kubectl apply -f samples/bookinfo/platform/kube/bookinfo.yaml

# Check pods (each pod should have 2 containers)
kubectl get pods

# Check services
kubectl get services

3. Verify Application Access

# Test productpage service
kubectl exec "$(kubectl get pod -l app=ratings -o jsonpath='{.items[0].metadata.name}')" \
  -c ratings -- curl -sS productpage:9080/productpage | grep -o "<title>.*</title>"

4. Configure Ingress Gateway

# Create Bookinfo Gateway
cat <<'EOF' > bookinfo-gateway.yaml
apiVersion: networking.istio.io/v1
kind: Gateway
metadata:
  name: bookinfo-gateway
  namespace: default
spec:
  selector:
    istio: ingressgateway
  servers:
  - port:
      number: 80
      name: http
      protocol: HTTP
    hosts:
    - "*"
---
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: bookinfo
  namespace: default
spec:
  hosts:
  - "*"
  gateways:
  - bookinfo-gateway
  http:
  - route:
    - destination:
        host: productpage
        port:
          number: 9080
EOF
kubectl apply -f bookinfo-gateway.yaml

# Check Gateway
kubectl get gateway.networking.istio.io

# Check VirtualService
kubectl get virtualservice

5. Configure External Access

# Get Ingress Gateway External IP
export INGRESS_HOST=$(kubectl -n istio-system get service istio-ingressgateway \
  -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')

export INGRESS_PORT=$(kubectl -n istio-system get service istio-ingressgateway \
  -o jsonpath='{.spec.ports[?(@.name=="http2")].port}')

export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT

# Access application
echo "http://$GATEWAY_URL/productpage"

# Access in browser or verify with curl
curl -s "http://$GATEWAY_URL/productpage" | grep -o "<title>.*</title>"

Istio Removal

These cleanup commands are for a disposable lab. Purging removes shared mesh resources; remove injected workloads or restart them without injection before uninstalling a live mesh. Helm uninstall retains CRDs.

Removal Using istioctl

# Remove sample application
kubectl delete -f samples/bookinfo/platform/kube/bookinfo.yaml
kubectl delete -f bookinfo-gateway.yaml

# Remove Istio
istioctl uninstall --purge -y

# Remove istio-system namespace
kubectl delete namespace istio-system

# Remove Istio label
kubectl label namespace default istio-injection-

Removal Using Helm

# Remove Ingress Gateway
helm delete istio-ingressgateway -n istio-system

# Remove istiod
helm delete istiod -n istio-system

# Remove istio-base
helm delete istio-base -n istio-system

# Remove namespaces
kubectl delete namespace istio-system

Troubleshooting

Common Issues

1. Sidecar Auto-Injection Failure

Symptom: Envoy sidecar is not injected into pod

Solution:

# Check namespace label
kubectl get namespace -L istio-injection

# Add label if missing
kubectl label namespace default istio-injection=enabled --overwrite

# Check Webhook
kubectl get mutatingwebhookconfiguration

2. istiod Pod Not Starting

Symptom: istiod pod is in Pending or CrashLoopBackOff state

Solution:

# Check pod status
kubectl get pods -n istio-system

# Check pod events
kubectl describe pod -n istio-system -l app=istiod

# Check logs
kubectl logs -n istio-system -l app=istiod

# Check resources
kubectl top nodes
kubectl describe nodes

3. Ingress Gateway Not Receiving External IP

Symptom: LoadBalancer type service is in Pending state

Solution:

# Check service status
kubectl get svc -n istio-system istio-ingressgateway

# Check AWS Load Balancer Controller
kubectl get deployment -n kube-system aws-load-balancer-controller

# Check events
kubectl describe svc -n istio-system istio-ingressgateway

Debugging Tools

istioctl analyze

# Analyze entire cluster
istioctl analyze -A

# Analyze specific namespace
istioctl analyze -n default

istioctl proxy-status

# Check all proxy status
istioctl proxy-status

# Check specific pod proxy status
istioctl proxy-status <POD_NAME>.<NAMESPACE>

istioctl dashboard

# Launch Kiali dashboard
istioctl dashboard kiali

# Launch Grafana dashboard
istioctl dashboard grafana

# Launch Prometheus dashboard
istioctl dashboard prometheus

# Envoy admin interface
istioctl dashboard envoy <POD_NAME>.<NAMESPACE>

Log Collection

# Control Plane logs
kubectl logs -n istio-system -l app=istiod

# Ingress Gateway logs
kubectl logs -n istio-system -l app=istio-ingressgateway

# Envoy logs for specific pod
kubectl logs <POD_NAME> -c istio-proxy

# Save all Istio-related logs to file
istioctl bug-report

Next Steps

Istio installation is complete! Now refer to the following documents to start using Istio:

1. Basic Concepts: Understand Istio core concepts and architecture
2. Traffic Management: Learn Gateway, VirtualService, DestinationRule
3. Security: Configure mTLS, authentication, authorization

References

• Istio Official Installation Guide

• Istio Profile Documentation

• Istio EKS platform guidance

• Istio Troubleshooting Guide

• EKS Fargate restrictions

• Istio 1.31 release and artifact migration