Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

Installing Istio with istioctl

Install Istio on a Kubernetes cluster with istioctl or Helm, choose a profile, run pre-checks, verify the control plane, and uninstall cleanly.

There are three supported ways to install Istio: the istioctl command line tool, Helm charts, and the Istio operator-free route of applying generated manifests with GitOps tools. All three install the same components. This lesson uses istioctl because it is the quickest way to learn, and then shows the Helm equivalent that most production teams prefer.

You need a Kubernetes cluster (a local kind or minikube cluster is fine), kubectl pointing at it, and enough capacity: the default profile wants roughly 2 CPUs and 4 GB free for a small test.

None of the commands below can run in this page. They are shown as read-only text; where I describe output I describe its shape, not exact lines.

Get istioctl

Download the release archive for your OS from the Istio releases page (the project publishes a getistio-style download script and tarballs), unpack it, and put istioctl on your PATH. The archive also contains samples/ with example applications and addons. Check the client:

Terminal
istioctl version --remote=false

--remote=false prints only the client version, which is what you want before anything is installed.

Check the cluster first

Terminal
istioctl x precheck

This inspects the cluster (Kubernetes version support, permissions, conflicting installations) and prints what it finds. Fix anything it reports as an error before installing.

Profiles

A profile is a named starting set of components and settings.

Profile What it installs Use for
default istiod + ingress gateway Production starting point
demo istiod + ingress and egress gateways, high tracing and logging Learning only
minimal istiod only Add gateways yourself
remote Config for a remote cluster of a multi-cluster mesh Multi-cluster
ambient istiod, CNI, ztunnel (and no sidecars) Ambient mode, see Ambient Mode
empty Nothing Build your own
preview Experimental features Trying new things

Install the demo profile for a learning cluster:

Terminal
istioctl install --set profile=demo -y

-y skips the confirmation prompt. The command applies the manifests and waits for components to become ready. Afterwards:

Terminal
kubectl get pods -n istio-system
istioctl verify-install

You should see an istiod-... pod and, with the demo profile, istio-ingressgateway-... and istio-egressgateway-... pods in Running state.

Customising an install

You can change settings with --set or an IstioOperator file used only as an input document to istioctl (there is no operator controller needed):

YAML
# my-config.yaml
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  profile: default
  meshConfig:
    accessLogFile: /dev/stdout
    defaultConfig:
      holdApplicationUntilProxyStarts: true
  components:
    pilot:
      k8s:
        replicaCount: 2
Terminal
istioctl install -f my-config.yaml -y

accessLogFile turns on Envoy access logs to stdout. holdApplicationUntilProxyStarts delays the app container until the proxy is ready, avoiding start-up calls that fail.

Install with Helm

Helm splits Istio into charts so you can upgrade each piece separately. The standard order:

Terminal
helm repo add istio https://istio-release.storage.googleapis.com/charts
helm repo update
kubectl create namespace istio-system
helm install istio-base istio/base -n istio-system --set defaultRevision=default
helm install istiod istio/istiod -n istio-system --wait

base installs the cluster-wide custom resource definitions; istiod installs the control plane. A gateway is a third chart, istio/gateway, installed in its own namespace.

A stand-in profile explorer

Choosing a profile means knowing what it contains. This stand-in encodes the table above as data so you can ask questions of it. It is just a dictionary, not Istio's real profile engine.

Python Stand-in: which profile has what?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: a tiny readiness checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Uninstall

Terminal
istioctl uninstall --purge -y
kubectl delete namespace istio-system

--purge removes all Istio resources, including cluster-wide ones. Remove the namespace labels you added (see Sidecar Injection and Your First Mesh App) and restart pods so sidecars disappear.

Do not run --purge on a cluster shared with other teams unless you are sure nobody else uses the same control plane: it deletes the CRDs and, with them, every Istio resource in every namespace.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which profile is the recommended production starting point?

    default installs istiod and an ingress gateway with sensible settings; demo is for learning.
  2. 2. What does istioctl x precheck do?

    It checks version support, permissions and conflicts before you install.
  3. 3. In the Helm install, what does the base chart contain?

    base installs the custom resource definitions; istiod and gateway are separate charts.
  4. 4. Which setting makes the app container wait until the sidecar is ready?

    holdApplicationUntilProxyStarts orders container start so early calls do not fail.

Summary

  • Install with istioctl install --set profile=... or with Helm (base, istiod, gateway).
  • Run istioctl x precheck first, istioctl verify-install after.
  • demo is for learning, default for production, minimal and empty for custom builds, ambient for sidecar-less mode.
  • Customise through --set or an IstioOperator file used as input.
  • Uninstall with istioctl uninstall --purge carefully.

Next: Sidecar Injection and Your First Mesh App