Skip to main content
logoTetrate Istio SubscriptionVersion: Next

Install FIPS sidecar in VM with Istio integration

This guide provides step-by-step instructions to install a FIPS-validated Istio in a Virtual Machine (VM) then connecting it into Istio deployment.

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.

Make sure to check Virtual Machine Architecture to understand high level architecture of Istio VM integration. This guide use single network as example. For multi network you can refer to Istio VM Installation documentation.

You will need credentials ($TIS_PASS) from Tetrate to access Tetrate's FIPS repository.

Installation Steps

  1. Download Istio release

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

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

    Download the Istio package:

    curl -fSLO --progress-bar "$TAG-$ARCH.tar.gz"
    tar -xvzf istio-$TAG-$ARCH.tar.gz && cd istio-$TAG
    export PATH=`pwd`/bin:$PATH
  2. Install Istio control plane

    You can skip installation step if you already Istio control plane running.

    Define several variables that will be used in installation process:


    Create an image pull secret to access FIPS images:

    kubectl create namespace istio-system
    kubectl create secret docker-registry $IMG_PULL_SECRET \
    --docker-server="$HUB" \
    --docker-username="$TIS_USER" \
    --docker-password="$TIS_PASS" \
    -n istio-system

    Then install Istio using istioctl:

    istioctl install \
    --set profile=default \
    --set "[-1]=$IMG_PULL_SECRET" \
    --set tag="$FIPS_TAG" \
    --set hub="$HUB" \
    --set "" \
    --set "$CLUSTER"
  3. Deploy East-West Gateway

    You need to expose control plane so VM workload can access. Deploy the East-West gateway:

    samples/multicluster/ --single-cluster | istioctl install -y -f -

    Then expose istiod via the deployed East-West gateway:

    kubectl apply -n istio-system -f samples/multicluster/expose-istiod.yaml
  4. Configure VM namespace

    Create application namespace and serviceaccount:

    kubectl create namespace "$VM_NAMESPACE"
    kubectl create serviceaccount "$VM_SERVICEACCOUNT" -n "$VM_NAMESPACE"

    Create workload group template to create VM related configurations file for next step.


    cat <<EOF > workloadgroup.yaml
    kind: WorkloadGroup
    name: "$VM_WORKLOAD"
    namespace: "$VM_NAMESPACE"
    app: "$VM_WORKLOAD"
    serviceAccount: "$VM_SERVICEACCOUNT"
    network: ""

    mkdir $WORKING_DIR
    istioctl x workload entry configure -f workloadgroup.yaml -o "$WORKING_DIR" --clusterID "$CLUSTER"
    Ingress IP

    If you see following warning

    Could not auto-detect IP for istiod.istio-system.svc/istio-system. Use --ingressIP to manually specify the Gateway address to reach istiod from the VM.

    Add --ingressIP to istioctl x workload entry configure to set hosts value with east-west gateway IP so VM in sidecar can resolve istiod correctly.

    Token duration

    By default token only valid for 1 hour (3600 seconds). If you need longer duration, you can set it with --tokenDuration specifying duration as seconds. For example --tokenDuration 7200 to set token duration to 2 hours

    Copy these files from $WORKING_DIR to Virtual machine for configuring sidecar in VM by using tools like scp. For example, following command will copy the files into vmconfig folder in your VM.

    scp -r "$WORKING_DIR" my-vm-host:~/vmconfig
  5. Install FIPS sidecar

    Install the Istio sidecar on the VM, ensuring it's FIPS-compliant.


    # For Debian-based Linux distribution.
    curl -fSsL -u ":$TIS_PASS" | sudo bash
    sudo apt-get install istio-sidecar-fips=$FIPS_DEB_PACKAGE_VERSION

    # For RPM-based Linux distribution.
    curl -fSsL -u ":$TIS_PASS" | sudo bash
    sudo yum install istio-sidecar-fips-$FIPS_RPM_PACKAGE_VERSION.x86_64

    Once you have installed a FIPS package, you can do a quick check if the installed artifacts were compiled as FIPS-compliant binaries.

    For pilot-agent, you have to see if GolangVersion:"go1.21.6 X:boringcrypto" is there in the version command output.

    pilot-agent version


    version.BuildInfo{Version:"1.20.3-tetratefips1", GitRevision:"692e556046b48ebc471205211c68a2c69e74a321", GolangVersion:"go1.21.6 X:boringcrypto", BuildStatus:"Clean", GitTag:"1.20.3"}

    Also, for the envoy binary, the correctness of the FIPS build can be verified by checking the presence of BoringSSL-FIPS in the --version output.

    envoy --version


    envoy  version: f9707e29aa0a36b1430b373d95e6c9abb5deca75/1.27.3-dev/Distribution/istio/proxy/RELEASE/BoringSSL-FIPS

    You can also download the raw files of the Linux distribution packages (.deb and .rpm). Before installing the downloaded Linux distribution package, if you have cosign installed, you can verify it first.

    You need to specify the RAW_PACKAGE_VERSION, that is <ISTIO_VERSION>-tetratefips<TIS_REVISION>, for both .deb and .rpm raw files.

    As an example, for Debian-based Linux distribution:

    RAW_PACKAGE_VERSION="$ISTIO_VERSION-tetratefips$TIS_REVISION" # here, the <TIS_REVISION> number is 1.

    curl -fSLO --progress-bar -u ":$TIS_PASS"$RAW_PACKAGE_VERSION.deb

    # Download the package "bundle".
    curl -fSLO --progress-bar -u ":$TIS_PASS"$RAW_PACKAGE_VERSION.deb.bundle
    cosign verify-blob \
    istio-sidecar-$RAW_PACKAGE_VERSION.deb \
    --bundle=istio-sidecar-$RAW_PACKAGE_VERSION.deb.bundle \
    $(curl -s


    Verified OK
  6. Start VM sidecar

    In previous step, you should have copied configuration files to your VM in ${HOME}/vmconfig folder. Copy each file into expected folders in the VM.

    # Copy root certificate
    sudo mkdir -p /etc/certs
    sudo cp vmconfig/root-cert.pem /etc/certs/root-cert.pem

    # Copy token
    sudo mkdir -p /var/run/secrets/tokens
    sudo cp vmconfig/istio-token /var/run/secrets/tokens/istio-token

    # Copy cluster env
    sudo mkdir -p /var/lib/istio/envoy
    sudo cp vmconfig/cluster.env /var/lib/istio/envoy/cluster.env

    # Copy mesh config
    sudo cp vmconfig/mesh.yaml /etc/istio/config/mesh

    # Add the istiod host
    sudo sh -c 'cat vmconfig/hosts >> /etc/hosts'

    # Transfer ownership of certs to Istio proxy
    sudo mkdir -p /etc/istio/proxy
    sudo chown -R istio-proxy \
    /var/lib/istio \
    /etc/certs \
    /etc/istio/proxy \
    /etc/istio/config \
    /var/run/secrets \

    Then start the istio service,

    sudo systemctl start istio
    sudo systemctl status istio
  7. Verification

    Verify the installation by checking the istio agent logs.

    tail -n 20 /var/log/istio/istio.log  -f


    2023-11-24T20:34:04.526262Z	info	cache	generated new workload certificate	latency=93.380184ms ttl=23h59m59.473742776s
    2023-11-24T20:34:04.526324Z info cache Root cert has changed, start rotating root cert
    2023-11-24T20:34:04.526396Z info ads XDS: Incremental Pushing ConnectedEndpoints:0 Version:
    2023-11-24T20:34:04.527091Z info cache returned workload trust anchor from cache ttl=23h59m59.472910174s
    2023-11-24T20:34:04.556059Z info xdsproxy connected to upstream XDS server: istiod.istio-system.svc:15012
    2023-11-24T20:34:04.584991Z info ads ADS: new connection for node:fips-testing.vmnsspace-1
    2023-11-24T20:34:04.585089Z info ads ADS: new connection for node:fips-testing.vmnsspace-2
    2023-11-24T20:34:04.585117Z info cache returned workload certificate from cache ttl=23h59m59.414884275s
    2023-11-24T20:34:04.585203Z info cache returned workload trust anchor from cache ttl=23h59m59.414798504s
    2023-11-24T20:34:04.585614Z info ads SDS: PUSH request for node:fips-testing.vmnsspace resources:1 size:4.0kB resource:default
    2023-11-24T20:34:04.585652Z info ads SDS: PUSH request for node:fips-testing.vmnsspace resources:1 size:1.1kB resource:ROOTCA
    2023-11-24T21:02:30.803277Z info xdsproxy connected to upstream XDS server: istiod.istio-system.svc:15012
    2023-11-24T21:32:06.989386Z info xdsproxy connected to upstream XDS server: istiod.istio-system.svc:15012
    2023-11-24T21:59:29.186988Z info xdsproxy connected to upstream XDS server: istiod.istio-system.svc:15012

    And deploy a hello-world application on the Kubernetes cluster, then try to reach the service endpoint from the VM. Since you installed TIS FIPS, you need to create image pull secret in the application namespace

    kubectl create namespace sample
    kubectl label namespace sample istio-injection=enabled

    kubectl create secret docker-registry $IMG_PULL_SECRET \
    --docker-server="$HUB" \
    --docker-username="$TIS_USER" \
    --docker-password="$TIS_PASS" \
    -n sample

    kubectl apply -n sample -f samples/helloworld/helloworld.yaml
    curl helloworld.sample.svc:5000/hello


Uninstall the Istio installation

istioctl uninstall --purge
kubectl delete ns istio-system

Cleanup the VM

sudo systemctl stop istio

# For Debian-based Linux distribution.
sudo dpkg -r istio-sidecar

# For RPM-based Linux distribution.
sudo rpm -e istio-sidecar