Skip to main content
logoTetrate Istio SubscriptionVersion: Next

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

Installation Options

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

1: Install using helm

2: Install 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:

    helm repo add tetratelabs https://tis.tetrate.io/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

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

    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

    Set the correct ARCH with one of following values:

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

    Download the istioctl binary:

    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:

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