Skip to main content
logoTetrate Service ExpressVersion: Latest

Onboarding a Cluster

Before you onboard a Workload Cluster, verify that you have:

Tetrate-Managed Istio

The Cluster Onboarding process installs a Tetrate-managed Istio instance on that cluster. Remove any instances of Istio from the cluster before proceeding.

Follow either Option 1 or Option 2 to onboard the cluster. You can also use the Getting Started wizard to onboard a cluster.

Installing from your Private Registry​

  1. Register the workload cluster in TSE, using tctl​

    Create the cluster configuration cluster-1.yaml. You can choose a different cluster name, but the organization must have the value tse.

    Apply this configuration to TSE using tctl:

    cat <<EOF > cluster-1.yaml
    apiVersion: api.tsb.tetrate.io/v2
    kind: Cluster
    metadata:
        name: cluster-1
        organization: tse
    EOF

    tctl apply -f cluster-1.yaml

  2. Obtain the TSE Cluster Configuration​

    Acquire the cluster configuration for the new cluster cluster-1. This resource contains the keys, certificates, addresses and ports needed for the cluster to securely communicate with the TSE Management Plane, and should be kept secret:

    tctl x cluster-install-template cluster-1 > cluster-1-values.yaml

  3. Complete the onboarding by installing the Control Plane on the workload cluster​

    Using the configuration cluster-1-values.yaml, install the Control Plane software:

    helm install tse-cp tse/controlplane \
    --version 1.8.0+tse \
    --namespace istio-system --create-namespace \
    --timeout 5m \
    --values cluster-1-values.yaml \
    --set image.registry=${HUB}

The helm install installs an operator which then bootstraps the installation. Allow several minutes for the cluster to fully onboard onto TSE.

Optional Debugging

You can track progress by following the logs from the tsb-operator:

kubectl logs -f -n istio-system -l name=tsb-operator

What just happened?​

The onboarding process does two things:

  • Installs the TSE Control Plane component onto the workload cluster and configures it to communicate with the Management Plane
  • Installs a TSE-validated Istio instance on the workload cluster

The onboarding process deploys an operator tsb-operator-control-plane in the istio-system namespace, which bootstraps other operators. These install the necessary services, including istiod, on the workload cluster.


Tips and Troubleshooting​

Onboard Additional Clusters​

You can onboard additional clusters to TSE using the process above. Make sure to:

  • Use a unique name for each cluster
    • Replace cluster-1 above with an alternate name
  • Before running helm, ensure that kubectl is using the correct context:
    • kubectl config current-context to obtain the current context
    • kubectl config get-contexts to list available contexts
    • kubectl config use-context NAME to switch to a different context

For example, after configuring kubectl:

CLUSTER=cluster-2

cat <<EOF > ${CLUSTER}.yaml
apiVersion: api.tsb.tetrate.io/v2
kind: Cluster
metadata:
    name: ${CLUSTER}
    organization: tse
EOF

tctl apply -f ${CLUSTER}.yaml

tctl x cluster-install-template ${CLUSTER} > ${CLUSTER}-values.yaml

helm install tse-cp tse/controlplane \
    --version 1.8.0+tse \
    --namespace istio-system --create-namespace \
    --timeout 5m \
    --values ${CLUSTER}-values.yaml \
    --set image.registry=${HUB}

Running in a locked-down, non-root environment​

In some locked-down environments, the standard install profile for the TSE control plane may not be suitable. In particular, several components run as root by default, and the installation profile may need to be modified to avoid this.

Refer to the FAQ: Running the TSE control-plane in a locked-down, non-root environment for details on how to handle this situation.