Tetrate 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

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:

ISTIO_VERSION="1.19.4"
TAG="$ISTIO_VERSION-tetrate-v0"
ARCH="osx-amd64"
curl -fSLO --progress-bar "https://dl.getistio.io/public/raw/files/istio-$TAG-$ARCH.tar.gz"
tar -xvzf istio-$TAG-$ARCH.tar.gz && cd istio-$TAG
export PATH=`pwd`/bin:$PATH

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:

ISTIO_VERSION="1.19.4"
FIPS_TAG="$ISTIO_VERSION-tetratefips-v0"
HUB="fips-containers.istio.tetratelabs.com"
TIS_USER="your-tis-user"
TIS_PASS="your-tis-credential"
IMG_PULL_SECRET="fips-pull-secret"
CLUSTER="my-cluster"

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 "values.global.imagePullSecrets[-1]=$IMG_PULL_SECRET" \
  --set tag="$FIPS_TAG" \
  --set hub="$HUB"  \
  --set "values.global.meshID=mesh1"  \
  --set "values.global.multiCluster.clusterName=$CLUSTER"

Deploy East-West Gateway
You need to expose control plane so VM workload can access. Deploy the East-West gateway:
```
samples/multicluster/gen-eastwest-gateway.sh --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
```

Configure VM namespace

Create application namespace and serviceaccount:

VM_NAMESPACE="my-vm-namespace"
VM_SERVICEACCOUNT="vm-sa"
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.

VM_WORKLOAD="my-vm-workload"

cat <<EOF > workloadgroup.yaml
apiVersion: networking.istio.io/v1alpha3
kind: WorkloadGroup
metadata:
  name: "$VM_WORKLOAD"
  namespace: "$VM_NAMESPACE"
spec:
  metadata:
    labels:
      app: "$VM_WORKLOAD"
  template:
    serviceAccount: "$VM_SERVICEACCOUNT"
    network: ""
EOF

WORKING_DIR="`pwd`/vmconfig"
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

Install FIPS sidecar

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

TIS_PASS="your-tis-credential"
ISTIO_VERSION="1.20.3"
TIS_REVISION="1"

# For Debian-based Linux distribution.
FIPS_DEB_PACKAGE_VERSION="$ISTIO_VERSION"-tetratefips"$TIS_REVISION"
curl -fSsL -u ":$TIS_PASS" https://tis.tetrate.io/deb-fips/setup.sh | sudo bash
sudo apt-get install istio-sidecar-fips=$FIPS_DEB_PACKAGE_VERSION

# For RPM-based Linux distribution.
FIPS_RPM_PACKAGE_VERSION="$ISTIO_VERSION"_tetratefips"$TIS_REVISION"-1
curl -fSsL -u ":$TIS_PASS" https://tis.tetrate.io/rpm-fips/setup.sh | sudo bash
sudo yum install istio-sidecar-fips-$FIPS_RPM_PACKAGE_VERSION.x86_64

important

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

Output:

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

Output:

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

tip

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:

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

curl -fSLO --progress-bar -u ":$TIS_PASS" https://tis.tetrate.io/files/fips/istio-sidecar-$RAW_PACKAGE_VERSION.deb

# Download the package "bundle".
curl -fSLO --progress-bar -u ":$TIS_PASS" https://tis.tetrate.io/files/fips/istio-sidecar-$RAW_PACKAGE_VERSION.deb.bundle
cosign verify-blob \
  istio-sidecar-$RAW_PACKAGE_VERSION.deb \
  --bundle=istio-sidecar-$RAW_PACKAGE_VERSION.deb.bundle \
  $(curl -s https://tis.tetrate.io/trustee)

Output:

Verified OK

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 \
  /etc/certs/root-cert.pem

Then start the istio service,

sudo systemctl start istio
sudo systemctl status istio

Verification

Verify the installation by checking the istio agent logs.

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

Output:

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

Uninstallation

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

Before you begin​

Installation Steps​

Download Istio release​

Install Istio control plane​

Deploy East-West Gateway​

Configure VM namespace​

Install FIPS sidecar​

Start VM sidecar​

Verification​

Uninstallation​

Uninstall the Istio installation​

Cleanup the VM​

Before you begin

Installation Steps

Download Istio release

Install Istio control plane

Deploy East-West Gateway

Configure VM namespace

Install FIPS sidecar

Start VM sidecar

Verification

Uninstallation

Uninstall the Istio installation

Cleanup the VM