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.

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. Verify these credentials with the following command:

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

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

If the credentials are valid, you will obtain a list of TAGs, corresponding to Tetrate's supported Istio versions and builds. Choose and define the TAG (for example, 1.18.2-tetratefips-v0) and VERSION (for example, 1.18.2) that matches the version and build you wish to install:

export TAG=1.18.2-tetratefips-v0
export VERSION=1.18.2

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.

2. Install using istioctl

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

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:

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

2. 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=1.18.2-tetratefips-v0
   export VERSION=1.18.2

3. Install a new kubernetes pull secret with your credentials

   We'll create a secret named tetrate-fips-creds, using the username and 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.18.2-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/istio-ingress -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

   Set the correct $TAG and ARCH in the command below. Valid values of ARCH include:

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

   Download the istioctl binary:

   export TAG=1.18.2-tetratefips-v0
   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 binary functions:

   ~/.istioctl/bin/istioctl version

2. 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>"

3. 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:

   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 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.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.

5. Verify the Installation

   Run istioctl version to verify the installed Istio version:

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

   client version: 1.18.2-tetratefips-v0
   control plane version: 1.18.2-tetratefips-v0
   data plane version: 1.18.2-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:

   export TAG=1.18.2-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.