Command Palette

Search for a command to run...

GitHubGitHub

Istio Installation Guide

Install Istio 1.31 with istioctl, choose the right configuration profile, enable sidecar or ambient mode, install the observability add-ons and verify the mesh.

Istio is a service mesh that connects, secures, observes and controls your services. This guide installs Istio 1.31 with istioctl, the recommended installation method.

Prerequisites

  • A Kubernetes cluster (1.30 or newer — check the Istio compatibility matrix for the exact range)
  • kubectl configured against that cluster
  • Cluster-admin privileges to install the control plane
  • 8 GB RAM and 4 CPU cores available for the control plane
  • The istioctl binary on your workstation (or on the node you run commands from)

Installing the istioctl CLI

The CLI is identical on every operating system — download the archive, extract it and put istioctl on your PATH:

# Download the latest release (1.31.x)
curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.31.2 sh -
 
# Move the binary into place
sudo cp istio-1.31.2/bin/istioctl /usr/local/bin/
sudo chmod +x /usr/local/bin/istioctl
 
# Verify
istioctl version --remote=false

On Windows, download the archive from the Istio releases page, extract it and add the bin folder to your PATH.

# Check that the cluster is reachable and compatible before you install anything
istioctl x precheck

Installing the Control Plane

Sidecar Mode (Default)

# Install the default profile — recommended for production
istioctl install --set profile=default -y
 
# Verify the control plane
istioctl verify-install
kubectl get pods -n istio-system

Choosing a Profile

Profiles are curated sets of Helm values. istioctl and helm share the same profiles.

ProfileUse it for
defaultProduction deployments and primary clusters in a multicluster mesh
demoLearning and the Bookinfo sample app — enables high tracing and access logging, so do not benchmark with it
minimalControl plane only; you install the data plane components separately
ambientAmbient mode (ztunnel based data plane)
remoteA remote cluster managed by an external or primary control plane
emptyNothing at all — a base for a fully custom configuration
previewExperimental features; stability and performance are not guaranteed
# List the available profiles
istioctl profile list
 
# Inspect what a profile contains before installing it
istioctl profile dump default
 
# Install a different profile
istioctl install --set profile=demo -y

Platform-specific profiles (gke, eks, openshift, k3d, k3s, microk8s, minikube) tune the chart for that environment:

istioctl install --set profile=default --set values.platform.minikube=true -y

Ambient Mode

# Install the ambient profile (istiod + CNI + ztunnel)
istioctl install --set profile=ambient -y
 
# Verify
kubectl get pods -n istio-system
kubectl get daemonset -n istio-system

Review Before You Install

For production it is worth generating the manifest and reading it before it touches the cluster:

# Generate the manifest for the default profile
istioctl manifest generate --set profile=default > istio.yaml
 
# Review, then apply it yourself
kubectl apply -f istio.yaml

Enabling the Data Plane

Sidecar Injection (Sidecar Mode)

Label the namespaces that should receive a sidecar. Prefer the istio.io/rev label, because it pins workloads to a specific control plane revision:

# Create a dedicated namespace for the mesh
kubectl create namespace bookinfo
 
# Label it for sidecar injection
kubectl label namespace bookinfo istio-injection=enabled
 
# Or pin it to a revision
kubectl label namespace bookinfo istio.io/rev=default
 
# Confirm the label took effect
kubectl get namespace bookinfo --show-labels

Existing pods are not modified — restart them so the sidecar is injected:

kubectl rollout restart deployment/<name> -n <namespace>

Manual injection is available for pods you cannot label:

istioctl kube-inject -f deployment.yaml > deployment-with-sidecar.yaml

Ambient Mode

In ambient mode you label the pod instead of the namespace:

# Label the namespace as part of the mesh
kubectl label namespace bookinfo istio.io/dataplane-mode=ambient
 
# Or opt a single pod in
kubectl label pod <pod-name> istio.io/dataplane-mode=ambient

A waypoint proxy provides L7 features (request routing, retries, authorization) on top of the L4 ambient data plane:

istioctl waypoint apply --enroll-namespace -n bookinfo

Installing the Observability Add-ons

# Install Prometheus, Grafana, Kiali and Jaeger
kubectl apply -f samples/addons/prometheus.yaml
kubectl apply -f samples/addons/grafana.yaml
kubectl apply -f samples/addons/kiali.yaml
kubectl apply -f samples/addons/jaeger.yaml
 
# Open a dashboard
istioctl dashboard kiali

Verifying the Installation

# The control plane pods should be Running
kubectl get pods -n istio-system
 
# The Istio CRDs should be registered
kubectl get crd | grep istio
 
# Analyse the mesh for misconfiguration
istioctl analyze -A
 
# Check that the sidecar is actually injected
istioctl check-inject <pod-name> -n <namespace>
 
# Inspect the proxy configuration of a running pod
istioctl proxy-status
istioctl proxy-config all <pod-name>.<namespace>
 
# Confirm mTLS is enforced between workloads
istioctl x describe pod <pod-name> -n <namespace>

Configuration Examples

Traffic Management

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: reviews-route
spec:
  hosts:
    - reviews
  http:
    - route:
        - destination:
            host: reviews
            subset: v1
          weight: 75
        - destination:
            host: reviews
            subset: v2
          weight: 25

Security Policies

apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
  namespace: istio-system
spec:
  mtls:
    mode: STRICT

Telemetry

apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: mesh-default
  namespace: istio-system
spec:
  tracing:
    - randomSamplingPercentage: 100.0
      customTags:
        environment:
          literal:
            value: production

Troubleshooting

Best Practices

  1. Install with the default profile in production and add explicit overrides only where you need them:

    istioctl install --set profile=default --set values.pilot.resources.requests.cpu=500m -y

  2. Use revisions for safe upgrades — install a second control plane and move the traffic to it gradually:

    istioctl install --set revision=canary -y
kubectl label namespace default istio.io/rev=canary

  3. Pin the Istio version in CI and upgrade one minor version at a time.

  4. Keep the mesh small — give each namespace its own label and only mesh the services that need it.

  5. Run istioctl analyze in CI to catch invalid configuration before it is applied.

  6. Enable the telemetry add-ons in production so you can see what the mesh is doing.

Next Steps

Helm

Install Helm 4 on Linux, macOS and Windows, verify the binary signature, configure repositories and learn the new Helm 4 features such as OCI digest installs and server-side apply.

Minikube

Install Minikube v1.39 on Linux, macOS and Windows, start a local Kubernetes cluster with the right driver, manage add-ons, load images and troubleshoot common failures.