Skip to main content
logoTetrate Service BridgeVersion: 1.7.x

Control Plane Installation

This chart installs the TSB control plane operator to onboard a cluster. Similar to Management Plane Helm chart, it also allows you to install TSB control plane components using TSB ControlPlane CR and all the required secrets to make it fully run.

Before you start, make sure that you've:

✓ Checked the Helm installation process
Installed TSB management plane
Login to the management plane with tctl
✓ Installed yq. This will be used to help getting helm values from creating cluster response.

isolation boundaries

TSB 1.6 introduces isolation boundaries that allows you to have multiple TSB-managed Istio environments within a Kubernetes cluster, or spanning several clusters. One of the benefits of isolation boundaries is that you can perform canary upgrades of the control plane.

To enable isolation boundaries, you must update operator deployment with environment variable ISTIO_ISOLATION_BOUNDARIES=true and control plane CR to include isolationBoundaries field. For more information, see Isolation Boundaries.


Before you begin, you will need to create a cluster object in TSB to represent the cluster where you will be installing the TSB control plane. Replace <cluster-name-in-tsb> and <organization-name> with the appropriate values for your environment:

kind: Cluster
name: <cluster-name-in-tsb>
organization: <organization-name>
displayName: "App Cluster"

To create the cluster object, run the following command:

tctl apply -f cluster.yaml -o yaml | yq .spec.installTemplate.helm > cluster-cp-values.yaml

The file, cluster-cp-values.yaml, comprises the default configuration for the TSB control plane operator, including any necessary secrets for authentication with the TSB management plane. To customize your installation, you may modify this file by adding any extra configuration values you need for the TSB control plane prior to proceeding to the subsequent step.


Use the following helm install command to install TSB control plane. Make sure to replace <tsb-version> and <registry-location> with the correct values.

helm install cp tetrate-tsb-helm/controlplane \
--version <tsb-version> \
--namespace istio-system --create-namespace \
--timeout 5m \
--values cluster-cp-values.yaml \
--set image.registry=<registry-location>

Wait for the TSB control plane components to be deployed successfully. To verify that the installation was successful, you can try logging in to the TSB UI or connecting to TSB using tctl and checking the list of clusters to see if the cluster has been onboarded.


If you encounter any issues during the installation process, here are a few tips for troubleshooting:

  • Make sure that you have followed all of the steps in the correct order.
  • Double-check the configuration values in the cluster-cp-values.yaml file to ensure that they are correct.
  • Check the logs of the TSB control plane operator to see if there are any error messages or stack traces that can help diagnose the problem.
  • If you are using a private registry to host the TSB control plane operator image, make sure that you have authenticated with the registry and that the image.registry value is correct.
  • Check the cluster onboarding troubleshooting guide.


Image configuration

This is a required field. Set registry to your private registry where you have synced TSB images into and tag to TSB version that you want to deploy. Specifying only this field will install TSB control plane operator without installing other TSB components.

NameDescriptionDefault value
image.registryRegistry used to download the operator
image.tagThe tag of the operator imagesame as the Chart version

Control Plane resource configuration

This is an optional field. You can set TSB ControlPlane CR in Helm values file to make the TSB control plane fully run.

NameDescriptionDefault value
specHolds the spec section of the ControlPlane CR

Secrets configuration

This is an optional field. You can apply secrets into your cluster before installing TSB control plane or you can use Helm values to specify required secrets. Note that you can use different Helm values file if you want to separate secrets from control plane spec.


Keep in mind that these options just help with creating secrets, and they must respect the configuration provided in the TSB ManagementPlane CR, otherwise the installation will end up misconfigured.

NameDescriptionDefault value
secrets.keepEnabling this makes the generated secrets persist in the cluster after uninstalling the chart if they are no provided in future updates. (see Helm doc)false
secrets.tsb.cacertCA certificate used to verify TLS certs exposed the Management Plane (front envoy)
secrets.elasticsearch.usernameThe username to access Elasticsearch
secrets.elasticsearch.passwordThe password to access Elasticsearch
secrets.elasticsearch.cacertElasticsearch CA cert TLS used by control plane to verify TLS connection
secrets.oapTokenJWT token used to authenticate OAP against the Management Plane
secrets.otelTokenJWT token used to authenticate Otel Collector against the Management Plane
secrets.clusterServiceAccount.clusterFQNTSB FQN of the onboarded cluster resource. This will be generate tokens for all Control Plane agents.
secrets.clusterServiceAccount.JWKLiteral JWK used to generate and sign the tokens for all the Control Plane agents.
secrets.clusterServiceAccount.encodedJWKBase64-encoded JWK used to generate and sign the tokens for all the Control Plane agents.

XCP secrets configuration

XCP uses JWTs to authenticate against between Edges and Central.

If the XCP root CA (secrets.xcp.rootca) is provided it will be used to verify the TLS certs provided by XCP Central.

Also secrets.xcp.edge.token or secrets.clusterServiceAccount will be required to authenticate against XCP Central.

The following are the configuration properties allowed to be used to configure XCP authentication mode:

NameDescriptionDefault value
secrets.xcp.rootcaCA certificate of XCP components
secrets.xcp.edge.tokenJWT token used to authenticate XCP Edge against the XCP Central

Operator extended configuration

This is an optional field. You can customize TSB operator related resources like the deployment, the service or the service account using the following optional properties:

NameDescriptionDefault value
operator.deployment.affinityAffinity configuration for the pod
operator.deployment.annotationsCustom collection of annotations to add to the deployment
operator.deployment.envCustom collection of environment vars to add to the container
operator.deployment.podAnnotationsCustom collection of annotations to add to the pod
operator.deployment.replicaCountNumber of replicas managed by the deployment
operator.deployment.strategyDeployment strategy to use
operator.deployment.tolerationsToleration collection applying to the pod scheduling
operator.deployment.podSecurityContextSecurityContext properties to apply to the pod
operator.deployment.containerSecurityContextSecurityContext properties to apply to the pod's containers
operator.service.annotationsCustom collection of annotations to add to the service
operator.serviceAccount.annotationsCustom collection of annotations to add to the service account
operator.serviceAccount.imagePullSecretsCollection of secrets names required to be able to pull images from the registry
operator.pullSecretA JSON encoded Docker configuration that will be stored as an image pull secret