Control Plane Installation

This chart installs the TSB control plane operator. 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

Prerequisites

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:

apiVersion: api.tsb.tetrate.io/v2
kind: Cluster
metadata:
  name: <cluster-name-in-tsb>
  organization: <organization-name>
spec:
  displayName: "App Cluster"

To create the cluster object, run the following command:

tctl apply -f cluster.yaml

Next, you will need to create a cluster service account that will be used to authenticate the TSB control plane operator with the TSB management plane. Run the following command to create the cluster service account:

tctl install cluster-service-account \
    --cluster <cluster-name-in-tsb> \
    > cluster-service-account.jwk

Installation

Next, you will need to create a Helm values file. This file, called cluster-values.yaml, will contain the configuration for the TSB control plane operator, as well as any secrets required to authenticate with the TSB management plane.

The spec field is similar to TSB ControlPlane CR. You can customize the spec field to meet the needs of your environment. For simplicity you will include secrets also, but you can create secrets in separate steps or use separate values file to store secrets. If you are using a self-signed certificate for the TSB management plane, you will need to include the certificate authority (CA) in the secrets section of the cluster-values.yaml file.

You can find more details on the available Helm configuration in the configuration section below.

spec:
  managementPlane:
    clusterName: <cluster-name-in-tsb>
    host: <tsb-address>
    port: <tsb-port>
  telemetryStore:
    elastic:
      host: <tsb-address>
      port: <tsb-port>
      version: <elastic-version>
      selfSigned: <is-elastic-use-self-signed-certificate>

secrets:
  clusterServiceAccount:
    clusterFQN: organizations/jupiter/clusters/<cluster-name-in-tsb>
    JWK: '$JWK'

To complete the cluster-values.yaml file, you will need to include the cluster service account JWK that you created earlier. Replace $JWK with the contents of the cluster-service-account.jwk file. You can use the envsubst command to substitute the $JWK placeholder with the actual contents of the cluster-service-account.jwk file:

export JWK=$(cat cluster-service-account.jwk)  
envsubst < cluster-values.yaml > cluster-values-with-jwk.yaml

Once you have created the cluster-values-with-jwk.yaml file, you are ready to install the TSB control plane using Helm. Run the following command to install the TSB control plane in the istio-system namespace:

helm install cp tetrate-tsb-helm/controlplane \
  --namespace istio-system \
  --set image.registry=<registry-location> \
  --set image.tag=<tsb-version> \
  --set spec.hub=<registry-location> \
  --values cluster-values-with-jwk.yaml

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.

Troubleshooting

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-values-with-jwk.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 self-signed certificate for the TSB management plane, make sure that the certificate authority (CA) is included in the secrets section of the cluster-values.yaml file.
• 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 and spec.hub values in the cluster-values.yaml file are correct.
• Check the cluster onboarding troubleshooting guide.

Configuration

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.

Name	Description	Default value
image.registry	Registry used to download the operator image	containers.dl.tetrate.io
image.tag	The tag of the operator image	same 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.

Name	Description	Default value
spec	Holds 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.

warning

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.

Name	Description	Default value
secrets.keep	Enabling 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.cacert	CA certificate used to verify TLS certs exposed the Management Plane (front envoy)
secrets.elasticsearch.username	The username to access Elasticsearch
secrets.elasticsearch.password	The password to access Elasticsearch
secrets.elasticsearch.cacert	Elasticsearch CA cert TLS used by control plane to verify TLS connection
secrets.oapToken	JWT token used to authenticate OAP against the Management Plane
secrets.otelToken	JWT token used to authenticate OTel Collector against the Management Plane
secrets.clusterServiceAccount.clusterFQN	TSB FQN of the onboarded cluster resource. This will be generate tokens for all control plane agents.
secrets.clusterServiceAccount.JWK	JWK used to generate and sign the tokens for all the control plane agents.

XCP secrets configuration

XCP has two authentication configuration modes: JWT (default) and mTLS. Depending on the authentication mode, the provided certificates will be used for different purpose.

JWT mode

In JWT mode, 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.

MUTUAL TLS mode

In MUTUAL_TLS mode, XCP Edge requires certificates with a SPIFFE ID to authenticate against the XCP Central.

If secrets.xcp.autoGenerateCerts is disabled, the XCP Edge cert is expected to be provided by the user using the secrets.xcp.edge.cert and secrets.xcp.edge.key configurations.

Then, if XCP Root CA is provided, it will be used to verify TLS certs provided by XCP Central.

If secrets.xcp.autoGenerateCerts is enabled, Cert Manager is required to provide the certs to XCP Edge.

If the control plane is installed in the same cluster the Management Plane runs on, no other cert info is required, because the same Cert Manager issuers will be used to create the XCP Edge cert.

Otherwise, when the control plane is not able to use the same Management Plane issuers, the XCP Root CA and its key (secrets.xcp.rootca and secrets.xcp.rootcakey) are required to create a Cert Manager issuer to provide the cert to the Edge.

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

Name	Description	Default value
secrets.xcp.autoGenerateCerts	Enabling this will auto generate XCP Edge certificate if mTLS is enabled to authenticate to XCP Central. Requires cert-manager	false
secrets.xcp.rootca	CA certificate of XCP components
secrets.xcp.rootcakey	Key of the CA certificate of XCP components
secrets.xcp.edge.cert	Edge certificate used for mTLS with XCP Central
secrets.xcp.edge.key	Key of the Edge certificate used for mTLS with XCP Central
secrets.xcp.edge.token	JWT token used to authenticate XCP Edge against the XCP Central
secrets.xcp.authMode	Indicates the XCP authentication mode configured in order to generate the proper required secrets. Accepted values: JWT or MUTUAL_TLS	MUTUAL_TLS

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:

Name	Description	Default value
operator.deployment.affinity	Affinity configuration for the pod
operator.deployment.annotations	Custom collection of annotations to add to the deployment
operator.deployment.env	Custom collection of environment vars to add to the container
operator.deployment.podAnnotations	Custom collection of annotations to add to the pod
operator.deployment.replicaCount	Number of replicas managed by the deployment
operator.deployment.strategy	Deployment strategy to use
operator.deployment.tolerations	Toleration collection applying to the pod scheduling
operator.deployment.podSecurityContext	SecurityContext properties to apply to the pod
operator.deployment.containerSecurityContext	SecurityContext properties to apply to the pod's containers
operator.service.annotations	Custom collection of annotations to add to the service
operator.serviceAccount.annotations	Custom collection of annotations to add to the service account
operator.serviceAccount.imagePullSecrets	Collection of secrets names required to be able to pull images from the registry
operator.pullSecret	A JSON encoded Docker configuration that will be stored as an image pull secret