Download Tetrate Components

Acquire the Tetrate Tools and Images

The first step to get TSB up and running is to install our TSB CLI tool tctl. With tctl you can install (or upgrade) TSB. It also allows you to interact with the TSB API's using yaml objects. If having operated Kubernetes deployments, this will be familiar to you. It also makes it easy to integrate TSB with GitOps workflows.

Follow the instruction in the CLI reference pages to download and install tctl.

Check the tctl version

The version of tctl must match the version of TSB that you wish to install. Check your tctl version:

$ tctl version
TCTL version: 1.12.1
TSB version: <connection not configured>

Sync Tetrate Service Bridge images

Now that you have the correct version of tctl installed, you can download the needed container images and push them into your private Docker repository. The tctl tool makes this easy by providing the image-sync command, which will download the image versions matching the current version of tctl from Tetrate repository and push it into your private Docker repository. The username and apikey arguments must hold the Tetrate repository account details provided to you by Tetrate to enable the download of the container images. The registry argument must point to your private Docker registry ${HUB}.

tctl install image-sync --username <user-name> \
    --apikey <api-key> --registry ${HUB}

TIP - Using Private Registries

tctl can push images to a range of private registries, using your local Docker configuration. You will need to configure your local Docker install appropriately.

For example, with an Amazon ECR registry (full instructions):

1. Install the aws cli package

2. Add the AmazonEC2ContainerRegistryFullAccess role to a suitable IAM user, and obtain the access key and secret access key for that user

3. Authenticate the aws client with that IAM user:

   aws configure
   # AWS Access Key ID [None]: AKIA1234567890ABCDEF
   # AWS Secret Access Key [None]: ZDQxZDhjZDk41234567890ABCDEF1234567890ABCDEF
   # Default region name [None]: us-east-1
   # Default output format [None]: json

4. Get the ECR password and provide it to the docker client:

   aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin ${HUB}

The first time you run this command you will be presented with a EULA which needs to be accepted. If you run the TSB installation from CI/CD or other environment where you will not have an interactive terminal at your disposal, you can add the --accept-eula flag to the above command.

What images are required?

TSB is a microservice-type application, with a single Management Plane (MP) installation and a Control Plane (CP) installation on each workload cluster. A TSB installation is made up of the following images:

Image Name	MP	CP	Notes
bridge-migration	⬤
bridge-server	⬤
spm-central	⬤
iam-jwt	⬤
iam-server	⬤
mpc-server	⬤
n2ac-cluster-server	⬤
tcc-web-ui	⬤
teamsync-job	⬤
tetrate-openldap	⬤
tsboperator-jobs	⬤
tsboperator-server	⬤
xcp-operator	⬤	⬤
busybox	⬤	⬤	helper containers
kubectl	⬤	⬤
otelcol	⬤	⬤	required for self-observability of MP and CP
wasmfetcher-server		⬤
xcp-guard		⬤	required for identity propagation capability
xcpd		⬤
ztunnel		⬤	required for ambient
install-cni		⬤	Istio CNI plugin
onboarding-operator-server		⬤
pilot		⬤	required (main istiod image)
proxyv2		⬤
spm-agent		⬤	required for 'observed' mode only
spm-user		⬤
proxyv2 (pv version)		⬤	payload validation
composer		◯
coraza-proxy-wasm		◯
onboarding-package-istio-sidecar		◯	optional, only when mesh expansion onboarding is enabled
onboarding-plane-server		◯	optional, only when mesh expansion onboarding is enabled
onboarding-repository-server		◯	optional, only when mesh expansion onboarding is enabled
package-repository-server		◯	optional, only when mesh expansion host management is enabled
pkg-host-management-agent		◯	optional, only when mesh expansion host management is enabled
pkg-service-discovery-agent		◯	optional, only when mesh expansion host management is enabled
pkg-spm-agent		◯	optional, only when mesh expansion host management is enabled
onboarding-agent			not required, installed on onboarded VMs/ECS/etc.
tctl	◯		optional, used for debugging only
cert-manager-cainjector	◯		optional, but required in default install
cert-manager-controller	◯		optional, but required in default install
cert-manager-webhook	◯		optional, but required in default install
eck-operator	◯		optional, for embedded ElasticSearch installation
elasticsearch	◯		optional, for embedded ElasticSearch installation
etcd	◯		optional, provided if using BanyanDB for telemetry
genistio-watcher	◯
host-management-plane-server		◯	optional, experimental feature
kongextproc		◯	optional
kube-rbac-proxy		◯
kubegres	◯		optional
oapr3		◯	optional, experimental OAP RESTFul Pattern Recognition
postgres	◯		optional, for embedded PostgreSQL installation
ratelimit		◯	optional, only if using ratelimit
redis		◯	optional, only if using ratelimit
satellite		◯	optional, only if using satellite feature of SPM
service-discovery-plane-server		◯	optional, only when mesh expansion host management is enabled
swck		◯	only used by optional HPA adapter
aws-controller	◯		Used to configure AWS DNS for Gateways
banyandb	◯		optional, provided if using BanyanDB for telemetry
ngac-agent	◯		deprecated, not installed
ngac-server	◯		deprecated, not installed

Troubleshooting the image-sync

If you encounter errors when attempting to sync the images, please check the following steps:

Are you using the correct version of tctl?

Check that the tctl version corresponds to the version of TSB that you intend to install:

$ tctl version
TCTL version: 1.12.1
TSB version: <connection not configured>

Are your credentials valid?

Credentials issued by Tetrate have an expiry date; for example, credentials issued for evaluations are typically valid for 30 days. Check the documentation provided by your Tetrate contact.

Can you authenticate to the Tetrate private registry?

# Login to the Docker repository using the username and apikey
docker login containers.dl.tetrate.io

# List the docker images
tctl install image-sync --just-print

Can you pull an image from the Tetrate private registry?

This test assumes you have a local Docker repository:

IMAGE=`tctl install image-sync --just-print | head -1`
docker pull ${IMAGE}

Can you push an image to your target registry ${HUB}?

# Select a local image to tag and push (select IMAGEID and IMAGENAME)
docker images

# Tag the image
docker tag ${IMAGEID} ${HUB}/${IMAGENAME}

# Push the image to ${HUB}
docker push ${HUB}/${IMAGENAME}

Demo installations on a Kind cluster

If you are installing the demo profile in a local kind cluster, you can directly load the images in the kind node as follows:

# Loging to the Docker repository using our `username` and `apikey`
docker login containers.dl.tetrate.io

# Pull all the docker images
for i in `tctl install image-sync --just-print --raw` ; do docker pull $i ; done

# Load the images to the kind node
for i in `tctl install image-sync --just-print --raw` ; do kind load docker-image $i ; done

Installation

cluster profiles

Operating a multi-cluster TSB environment typically involves communicating with multiple Kubernetes clusters. In the documentation we do not make explicit use of kubectl config context and tctl config profiles as they are specific to your environment. Make sure that you have selected the right kubectl context and tctl profile as default or use explicit arguments to select the correct clusters when executing commands with these tools.

For installation using Helm chart, please proceed to the helm installation guide.

For installation using tctl, please proceed to the tctl installation guide.

For the demo installation procedure, please proceed to the demo installation guide.