Install a Tetrate Istio distribution using istioctl

You can install a Tetrate Istio distribution using istioctl. This is appropriate for quick testing, as an alternative to a helm install.

New Versioning Format

TID has adopted a new versioning format. See Versioning System Update for more details. We recommend familiarizing yourself with this new format and gradually transitioning to it.

Post the TID 1.24.0 release, the old versioning scheme and its associated repository will be phased out, consolidating all users on the updated format in the new repository.

Before you begin

You need a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. Istio has a number of platform and networking/application requirements.

You will need credentials from Tetrate to access Tetrate's repository.

You also need the correct version of the istioctl tool, matching the version of Istio you plan to install.

Installation Steps

1. Determine the Tetrate Istio distribution version

   You need to determine Istio version that you want to install and set it as TAG variable

   New

   You can get a list of all the tags available by running the following command:

   curl -fSsL https://tis.tetrate.io/versions.json | \
     jq -r '.istio_distributions[] | select(.version_flavor | contains("tetrate")) | .version_flavor'

   This command will have following output

   List of available versions

   1.20.3-tetrate3
   1.20.3-tetratefips3
   1.20.3-tetrate2
   1.20.3-tetratefips2
   1.20.3-tetrate1
   1.20.3-tetratefips1
   1.20.3-tetrate0
   1.20.3-tetratefips0
   1.20.2-tetrate5
   ...

   Then set the tag as environment variable, for example we chose 1.20.3-tetrate3:

   export TAG="1.20.3-tetrate3"

   Legacy

   You can get a list of all the tags available by running the following command:

   curl -u "${TIS_USER}:${TIS_PASS}" -s https://addon-containers.istio.tetratelabs.com/v2/proxyv2/tags/list | jq

   You can also browse the tags available by searching the Tetrate public repositories and replacing the search term 1.18 with the version you want.

   Two version systems

   Tetrate container registries will have both version available during transition period

   Then set the tag as environment variable:

   export TAG=1.20.0-tetrate-v0

2. Download istioctl

   Set the correct ARCH with one of following values:

   • ARCH=linux-amd64
   • ARCH=linux-arm64
   • ARCH=linux-armv7
   • ARCH=osx-amd64
   • ARCH=osx-arm64
   • ARCH=win-amd64

   Download the istioctl binary:

   New

   export ARCH=linux-arm64
   
   mkdir -p ~/.istioctl/bin
   curl -fSsLO https://tis.tetrate.io/archives/istio-${TAG}/istioctl-${TAG}-${ARCH}.tar.gz
   tar -xvzf istioctl-${TAG}-${ARCH}.tar.gz
   cp istioctl ~/.istioctl/bin

   tip

   Alternatively, you can list down all available downloadable istioctl as follows:

   curl -fSsL https://tis.tetrate.io/versions.json | \
     jq -r --arg TAG "$TAG" '
     .istio_distributions[] |
     select(.version_flavor == $TAG) |
     .release_assets[] |
     select (.url | contains("istioctl")) |
     "\(.platform) \(.url)"'

   The output is similar to:

   List of available istioctl assets

   linux-amd64 https://tis.tetrate.io/archives/istio-1.20.3-tetrate3/istioctl-1.20.3-tetrate3-linux-amd64.tar.gz
   linux-arm64 https://tis.tetrate.io/archives/istio-1.20.3-tetrate3/istioctl-1.20.3-tetrate3-linux-arm64.tar.gz
   linux-armv7 https://tis.tetrate.io/archives/istio-1.20.3-tetrate3/istioctl-1.20.3-tetrate3-linux-armv7.tar.gz
   macos-amd64 https://tis.tetrate.io/archives/istio-1.20.3-tetrate3/istioctl-1.20.3-tetrate3-osx-amd64.tar.gz
   macos-arm64 https://tis.tetrate.io/archives/istio-1.20.3-tetrate3/istioctl-1.20.3-tetrate3-osx-arm64.tar.gz
   macos-amd64 https://tis.tetrate.io/archives/istio-1.20.3-tetrate3/istioctl-1.20.3-tetrate3-osx.tar.gz
   windows-amd64 https://tis.tetrate.io/archives/istio-1.20.3-tetrate3/istioctl-1.20.3-tetrate3-win-amd64.zip
   windows-amd64 https://tis.tetrate.io/archives/istio-1.20.3-tetrate3/istioctl-1.20.3-tetrate3-win.zip

   Legacy

   export ARCH=linux-arm64
   
   mkdir -p ~/.istioctl/bin
   curl -O https://dl.getistio.io/public/raw/files/istioctl-${TAG}-${ARCH}.tar.gz
   tar -xvzf istioctl-${TAG}-${ARCH}.tar.gz
   cp istioctl ~/.istioctl/bin

   Verify the istioctl version:

   ~/.istioctl/bin/istioctl version

3. Define the Install Version

   If you've not already done so, follow the instructions above to set the required variables correctly:

   export TIS_USER="<tis-username>"
   export TIS_PASS="<tis-password>"
   export TAG="<chosen tag>"

4. Install a new kubernetes pull secret with your credentials

   We'll create a secret named tetrate-tis-creds, using the username, password and your email address:

   kubectl create namespace istio-system
   
   kubectl create secret docker-registry tetrate-tis-creds \
       --docker-server="addon-containers.istio.tetratelabs.com" \
       --docker-username=${TIS_USER} \
       --docker-password=${TIS_PASS} \
       --docker-email="${USER}@" \
       -n istio-system

5. Install Istio

   ~/.istioctl/bin/istioctl install --set profile=default \
      --set "values.global.imagePullSecrets[-1]=tetrate-tis-creds" \
      --set tag=${TAG} \
      --set hub=addon-containers.istio.tetratelabs.com

   Expect output similar to:

   istioctl install output

   
   This will install the Istio 1.18.2 default profile with ["Istio core" "Istiod" "Ingress gateways"] components into the cluster. Proceed? (y/N) y
   ✔ Istio core installed
   ✔ Istiod installed
   ✔ Ingress gateways installed
   ✔ Installation complete
   Making this installation the default for injection and validation.

Uninstalling Istio

Uninstall the Istio installation as follows:

~/.istioctl/bin/istioctl uninstall --purge
kubectl delete ns istio-system

Next Steps

Once you have installed and validated your Tetrate Istio distribution install, you can proceed to the Istio good practices guide.