Install FIPS-validated builds of Tetrate Istio distribution

Tetrate Istio distribution FIPS images are available to Tetrate Istio Subscription customers. These images are hosted in a special FIPS repository. To access the FIPS repository, you will need a username and password, which you can obtain from your Tetrate representative.

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.

Strict FIPS Mode

See how to Configure TID in Strict FIPS Mode for more information on how to configure TID to operate in a strict FIPS-compliant mode.

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 FIPS repository. Set your credential as env variable:

export TIS_USER="<tis-username>"
export TIS_PASS="<tis-password>"

You will need to decide which variant you want to install. TIS container images are tagged with the format 1.XY.Z-variantfix-os. The below schema is valid from TIS 1.25.2 and later.

Variant

• tetratefips - DoD STIG applied to base OS, crypto modules are the most recently fully validated version. Currently only supports FIPS 140-2, cannot be used in Ambient mode in a compliant fashion.
• tetratefips-crypto-updatestream - DoD STIG applied to base OS, crypto modules are the 'update streams' of validated modules (see FedRAMP guidance). Supports FIPS 140-3, can be used with Ambient mode.

Fix

• Later versions contain fixes for OS package CVEs that have not been fixed yet in upstream Istio. You should pick the latest version available

OS

• distroless
• ubi9
• debug (ubuntu)

Tetrate recommends selecting tetratefips-crypto-updatestream-distroless images unless you have a specific need to choose a different combination. If you are undergoing a FedRAMP audit we recommend checking with your auditor before making a selection.

Installation Options

There are two ways you can install the Tetrate FIPS-validated builds:

1: Install using helm

Install by configuring your helm client to access Tetrate's FIPS repository.

→ # Install FIPS-validated Istio images using helm

2: Install using istioctl

For quick evaluations, istioctl is the easiest way to install the FIPS-validated build.

→ # Install FIPS-validated Istio images using istioctl

If necessary, follow the air-gapped environment instructions to copy the images to a private registry first.

Install FIPS-validated Istio images using helm

1. Add the Tetrate Helm Repo

   Add Tetrate's Helm repo, and verify you can see the Tetrate Istio distribution releases:

   New

   helm repo add tetratelabs https://tis.tetrate.io/charts
   helm repo update tetratelabs
   
   helm search repo tetratelabs

   Legacy

   helm repo add tetratelabs https://tetratelabs.github.io/helm-charts/
   helm repo update tetratelabs
   
   helm search repo tetratelabs

2. Define the Install Version

   You can get the latest release by using following command:

   helm search repo tetratelabs/base

   Or you can list all available releases:

   helm search repo tetratelabs/base --versions
   New

   Set $VERSION using Helm version that you want to install, for example 1.20.0+tetrate0.

   Set $TAG using App version from above helm search command replacing tetrate with tetratefips to specify FIPS build.

   export VERSION=1.20.0+tetrate0
   export TAG=1.20.0-tetratefips0

   Legacy

   Set $VERSION using Helm version that you want to install, for example 1.20.0.

   Set $TAG using App version from above helm search command replacing tetrate with tetratefips to specify FIPS build.

   export VERSION=1.20.0
   export TAG=1.20.0-tetratefips-v0

3. Install a new kubernetes pull secret with your credentials

   We'll create a secret named tetrate-fips-creds, using the username and password. Make sure that you have set the credentials as environment variable:

   export TIS_USER="<tis-username>"
   export TIS_PASS="<tis-password>"

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

4. Install the Istio Control Plane

   Create the istio-system namespace, and install Tetrate's Istio base and istiod charts. These contains the CRDs (custom resource definitions) required for the Istio install, and the istiod service:

   helm install istio-base tetratelabs/base -n istio-system \
       --set global.tag=${TAG} \
       --set global.hub="fips-containers.istio.tetratelabs.com" \
       --set "global.imagePullSecrets[0]=tetrate-fips-creds" \
       --version ${VERSION}
   
   helm install istiod tetratelabs/istiod -n istio-system \
       --set global.tag=${TAG} \
       --set global.hub="fips-containers.istio.tetratelabs.com" \
       --set "global.imagePullSecrets[0]=tetrate-fips-creds" \
       --version ${VERSION}

   After a few seconds, verify that the istio-base and istiod releases are installed and that the istiod pod is running:

   helm ls -n istio-system
   kubectl get pods -n istio-system

   Note that the helm APP VERSION reports 1.20.0-tetrate-v0 or similar because the helm chart is designed for both tetrate and tetratefips images. Verify that the istiod container is sourced from the Tetrate FIPS repository:

   kubectl describe pod -n istio-system -l "app=istiod"

5. Install Istio Gateway

   Repeat the process to install Istio Gateway into the istio-ingress namespace. Verify that the istio-ingressgateway pod is running and the istio-ingress release is installed:

   kubectl create namespace istio-ingress
   
   kubectl create secret docker-registry tetrate-fips-creds \
       --docker-server="fips-containers.istio.tetratelabs.com" \
       --docker-username=${TIS_USER} \
       --docker-password=${TIS_PASS} \
       --docker-email="${USER}@" \
       -n istio-ingress
   
   helm install istio-ingress tetratelabs/gateway -n istio-ingress \
       --set global.tag=${TAG} \
       --set global.hub="fips-containers.istio.tetratelabs.com" \
       --set "global.imagePullSecrets[0]=tetrate-fips-creds" \
       --version ${VERSION}
   
   sleep 5
   
   helm ls -n istio-ingress
   kubectl get pods -n istio-ingress

   Verify that the istio-ingressgateway container is sourced from the Tetrate FIPS repository:

   kubectl describe pod -n istio-ingress -l "app=istio-ingressgateway"

You have successfully installed Tetrate's FIPS-validated build of Tetrate Istio distribution.

For more details on the Helm installation, upgrade and removal processes, please refer to the standard Tetrate Istio distribution helm install instructions.

Install FIPS-validated Istio images using istioctl

1. Download istioctl

   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[].version_flavor'

   This command will have following output

   1.20.0-tetrate0
   1.20.0-tetratefips0
   1.19.4-tetrate0
   1.19.4-tetratefips0
   1.19.3-tetrate0
   1.19.3-tetratefips0
   1.18.5-tetrate0

   Then set the tag as environment variable:

   export TAG=1.20.0-tetratefips0

   Legacy

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

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

   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-tetratefips-v0

   Set the correct ARCH with one of following values:

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

   Download the istioctl binary:

   New

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

   Legacy

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

   Verify the binary functions:

   ~/.istioctl/bin/istioctl version

2. Install a new kubernetes pull secret with your credentials

   We'll create a secret named tetrate-fips-creds, using the username, password and your email address: Make sure that you have set the credentials as environment variable:

   export TIS_USER="<tis-username>"
   export TIS_PASS="<tis-password>"

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

3. Install Istio

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

   Expect output similar to:

   istioctl install output

   
   This will install the Istio 1.20.0 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.

4. Verify the Installation

   Run istioctl version to verify the installed Istio version:

   ~/.istioctl/bin/istioctl version
   Output from istioctl version

   client version: 1.20.0-tetratefips-v0
   control plane version: 1.20.0-tetratefips-v0
   data plane version: 1.20.0-tetratefips-v0 (1 proxies)

You have successfully installed Tetrate's FIPS-validated build of Tetrate Istio distribution.

For more details on the istioctl installation and removal processes, please refer to the standard Tetrate Istio distribution istioctl install instructions.

Operating in an Air-Gapped Environment

If your target installation cluster does not have access to the Tetrate FIPS repository, you can first copy the FIPS images to a local, private docker repository.

To copy the FIPS images

1. Login with your username and password

   Use the username and password provided by Tetrate:

   docker login fips-containers.istio.tetratelabs.com
   Username: <username>
   Password: <password>

2. Pull each image to the local machine

   Make sure to set TAG to the build and version you plan to install:

   New

   export TAG=1.20.0-tetratefips0
   export TETRATE_HUB=fips-containers.istio.tetratelabs.com
   export YOUR_HUB=registry.example.com
   export IMAGES=(install-cni istioctl operator pilot proxyv2) 
   
   for image in $IMAGES; do docker pull $TETRATE_HUB/$image:$TAG; done

   Legacy

   export TAG=1.20.0-tetratefips-v0
   export TETRATE_HUB=fips-containers.istio.tetratelabs.com
   export YOUR_HUB=registry.example.com
   export IMAGES=(install-cni istioctl operator pilot proxyv2) 
   
   for image in $IMAGES; do docker pull $TETRATE_HUB/$image:$TAG; done

3. Re-tag with your registry hostname

   for image in $IMAGES; do docker tag $TETRATE_HUB/$image:$TAG $YOUR_HUB/$image:$TAG; done

4. Push to your private registry

   docker login <customer private registry>
   Username: <username>
   Password: <password>
   
   for image in $IMAGES; do docker push $YOUR_HUB/$image:$TAG; done

Once you have copied the images to a local repository, you can use any of the methods described above, replacing the address of the Tetrate FIPS repository with your own repository.

Verification

To verify the FIPS compliance of the installed artifacts, see Verify FIPS Image.