Onboard a Cluster

To manage the microservices in your application with Tanzu Service Mesh, you must onboard the clusters where the microservices are deployed. Onboarding involves registering the cluster with Tanzu Service Mesh and installing the necessary software on the cluster.

Some companies whose internal systems don't have direct access to the Internet, use a proxy server to connect outside. If a proxy server is configured in your corporate environment, when onboarding your cluster, specify that it will connect to Tanzu Service Mesh through a proxy server. All traffic between the cluster and Tanzu Service Mesh will be routed through the proxy server and will be encrypted using Transport Layer Security (TLS). All requests that are sent from the cluster to Tanzu Service Mesh will be authorized using access tokens.

During onboarding, you need to provide the settings of the proxy configuration in your environment. The Tanzu Service Mesh client software installed on the cluster, called Tanzu Service Mesh agent, uses the proxy configuration that you provide to connect to the proxy server.

Note:

If you attached a cluster that is running behind a proxy server to Tanzu Mission Control and enabled Tanzu Service Mesh on that cluster, Tanzu Mission Control automatically forwards the proxy configuration to Tanzu Service Mesh. The Tanzu Service Mesh agent on the cluster uses the proxy configuration to connect the cluster to Tanzu Service Mesh through the proxy server. You don't need to provide proxy configuration settings for clusters managed by Tanzu Mission Control in Tanzu Service Mesh.

If you want to first use Tanzu Service Mesh in your testing environment, you can onboard a clean cluster without microservices and namespaces and then deploy a sample application on the cluster. Connect Services Across Clusters with a Global Namespace in Using VMware Tanzu Service Mesh includes steps on how to deploy the services of a sample application on two clusters.

To secure the communications between the services in the service mesh, you can use self-signed Transport Layer Security (TLS) certificates issued by the Tanzu Service Mesh internal certificate authority or certificates issued by an external CA. Tanzu Service Mesh supports Venafi and Vault as external CAs.

To specify that the Tanzu Service Mesh internal CA is used to secure the service mesh, select the default CA label for a cluster during onboarding.

To specify that an external CA is used to secure the service mesh, select a label associated with that external CA's integration account for the cluster during onboarding. For example, to specify that Venafi is used as an external CA, select the CA label associated with a Venafi integration account for the cluster. As a result, the CA configuration from the integration account will be pushed to the services in the cluster during onboarding. You can get a CA label when you create an integration account for the external CA. For more information, see Create a Venafi Integration Account and Create a Vault CA Integration Account.

During onboarding, you can select which namespaces on your cluster are included. Including a namespace enables automatic Istio sidecar injection in the pods of that namespace. Include a namespace if you want the pods in that namespace to be part of the mesh. If you enable automatic Istio sidecar injection for a namespace, all new pods that are created in that namespace will automatically have a sidecar proxy added to them. For information about this feature called Namespace Onboarding Worklow, see Namespace Onboarding Workflow. For more information about sidecar proxy injection, also see the Istio documentation.

You can select a Cluster admin owned option to specify that you manage the labeling of namespaces for Istio sidecar injection in the cluster, and that Tanzu Service Mesh does not own namespace labeling. As a result, a cluster administrator will be able to create and manually label namespaces in the cluster as needed, without Tanzu Service Mesh overriding the manual labeling changes.

When you select the Cluster admin owned option, you delegate all responsibility for namespace labeling, including selection for inclusion, to the cluster administrator who operates the cluster. This means that the labeling of namespaces for inclusion with istio-injection=enabled is delegated to the person that manages the cluster itself. This is useful when the person operating Tanzu Service Mesh and the person on the cluster are two different people. The options for selecting namespaces for inclusion and for creating namespace inclusion rules will not be visible or available in the Tanzu Service Mesh UI if Cluster admin owned is selected. For more information about the Cluster admin owned setting and how it affects namespace labeling, see Namespace Onboarding Workflow.

Caution:

When the Cluster admin owned option is selected for a cluster, Tanzu Service Meshdelegates namespace labeling to the cluster administrator, so labeling for sidecar injection will be performed with kubectl. In this case, Tanzu Service Mesh no longer owns namespace labeling on the cluster and does not have visibility into the actual namespace labeling state.

If the Cluster admin owned option is deselected at a later stage, Tanzu Service Mesh may not have the most up-to-date state of labels on the namespaces. Consider the following example:

A user selects the Cluster admin owned option for a cluster to delegate all responsibility for namespace labeling to the cluster administrator.
The cluster administrator performs labeling on the cluster and sets istio-injection=enabled for a namespace on the cluster or removes a label that was previously set.
If at a later stage the Tanzu Service Mesh administrator deselects the Cluster admin owned option for the cluster to return control over namespace labeling to Tanzu Service Mesh, the namespace inclusions list in the Edit Cluster dialog box for the cluster may not show the most up-to-date namespace inclusion state for Istio injection.

If the Cluster admin owned option is deselected, it is up to the Tanzu Service Meshadministrator to make sure that the namespaces that need to be injected with sidecars are selected and that no labels have been accidentally removed by Tanzu Service Mesh due to lack of constant visibility of the labeling state.

In a later release, a mechanism will be provided to reconcile the inclusions list when the ownership of namespace labeling is switched back and forth between Tanzu Service Meshand the cluster administrator.

Prerequisites

Verify that your environment meets the requirements listed in Tanzu Service Mesh Environment Requirements and Supported Platforms.
If you want to install Tanzu Service Mesh only in some of the namespaces of the cluster, decide beforehand which namespaces you want to exclude from Tanzu Service Mesh.
If you want the cluster to connect to Tanzu Service Mesh through your organization's web proxy server, make sure that you know the details of the proxy configuration, such as the type of proxy in use (transparent or explicit), the protocol (HTTP or HTTPS), the host name or IP address of the proxy server, and the port number.
If your corporate proxy server is configured to use a certificate for secure TLS connections, make sure that you know the location of the certificate file. The Tanzu Service Mesh agent on the cluster will use the certificate to connect to the proxy server and trust the connection.
If you want to use an external certificate authority (CA), for example, Venafi or Vault, to secure the service mesh, create an integration account for the external CA. For more information, see Create a Venafi Integration Account and Create a Vault CA Integration Account.
Access the Tanzu Service Mesh Console.

Procedure

In the upper-left corner of the Tanzu Service Mesh Console, click Add New and then Onboard New Cluster to open the Onboard Clusters panel.

If you're onboarding your first cluster to Tanzu Service Mesh, the Onboard Clusters panel appears automatically when you finish signing up for Tanzu Service Mesh.
In the Onboard Clusters panel, enter the name that you want your cluster to have in the Tanzu Service Mesh Console, that is, the cluster display name.

The cluster display name that you enter here can be different from the name of the cluster in your environment. The cluster name can include only lowercase letters and cannot contain special characters, such as a number sign (#), at sign (@), apostrophe ('), underscore (_), and uppercase letters.

The display name is used to identify the cluster wherever data appears for the cluster in the Tanzu Service Mesh Console, including the data tables and topology views. To change the cluster display name later, edit the cluster.
(Optional) To change the default ID for the cluster, click Edit to the right of Cluster ID , enter a unique ID, and click Done.

Note:
If you enter a non-unique ID that is used by another cluster, a warning appears.

You provide the cluster ID as a required parameter in making certain calls to the Tanzu Service Mesh API. In the Tanzu Service Mesh Console UI, the cluster ID appears on the cluster details page. Change the default cluster ID if you want to give the cluster a friendly or custom ID.

You can change the cluster ID only in the Onboard Clusters panel. After the cluster is onboarded, you cannot change its ID.
(Optional) Click Add labels in the Cluster Labels field, enter Label Key and Label Value, and click Save to create new labels if you are going to connect the Tanzu Service Mesh SaaS to Avi controllers using a proxy. To change or remove a saved cluster label, click Edit Labels.

For more information, see Configure Integration with AVI.

Note:
Cluster labels are used to identify clusters that may potentially be used by Tanzu Service Mesh SaaS to connect to Avi controllers. From the Label Key drop-down menu, select Proxy Location.
To specify that a cluster administrator will own the labeling of namespaces for Istio injection in the cluster, select the Cluster admin owned check box. To be able to select namespaces for inclusion or define namespace inclusion rules for the cluster (see step 11), deselect Cluster admin owned.

Note:
After onboarding, you can change the Cluster admin owned setting for the cluster by editing the cluster configuration.
To specify that the cluster connects to Tanzu Service Mesh through your organization's web proxy server, select the Configure a proxy to connect this cluster check box and provide the following settings based on how the server is configured in your environment.

Note:
If your proxy server uses a globally trusted certificate, you don't need to provide the proxy configuration in Tanzu Service Mesh. Deselect the Configure a proxy to connect this cluster check box.

Proxy Type

Select Transparent or Explicit.

Note:
A transparent proxy deployment does not require any special configuration on the client. The proxy server intercepts all requests from the clients to destination IP addresses. The clients may not even be aware of the proxy server.

In an explicit proxy deployment, clients are explicitly configured to send requests to the proxy server. You need to configure the proxy settings, such as the proxy’s protocol, IP address, and port, on each client.

Certificate File

If you selected Transparent, you must upload the certificate file that is used to trust connections to the proxy server. The certificate file must be in PEM (.pem) format. To browse to and upload the file, click Select .PEM file.

If you selected Explicit, you can optionally provide a certificate file.

Note:
Tanzu Service Mesh supports self-signed certificates.

Protocol

Specify the protocol over which the proxy server listens: HTTP or HTTPS.

This setting is required if you selected Explicit as Proxy Type.

Host or IP Address

Enter the host name or IP address of the proxy server.

This setting is required if you selected Explicit as Proxy Type.

Port

Enter the port on which the proxy server listens.

This setting is required if you selected Explicit as Proxy Type.

Username

Optionally enter the user name that is used to authenticate with the proxy server.

This setting applies only if you selected Explicit as Proxy Type.

Password

Optionally enter the password that is used to authenticate with the proxy server. The password appears as a series of dots for security.

This setting applies only if you selected Explicit as Proxy Type.
To specify that the cluster connects to your private image registry, select the Pull Images from a custom image registry check box and select the Registry Name from drop-down. If you haven't created a registry location definition previously, click Add Image Registry and provide the necessary information.

For more information, see Customer-Owned Image Registry Support and Secret Authentication.

Important:
To be able to onboard a cluster using Tanzu Service Mesh images from your private registry, you need to mirror the required repositories from the TSM's public ECR registry located at public.ecr.aws/v6x6b8s5. For private registries that do not support mirroring, download the images from the Tanzu Service Mesh public ECR registry and push them into your private registries. Check out the list of Tanzu Service Mesh repositories to mirror and images to download. See the note under step 4 in the What to do next section.

Read more about JFrog Artifactory replication and Harbor replication.

Name

Enter your account name.

Description (optional)

Optionally provide comments about your private image registry.

Registry URL

Enter the base URL of your private image registry.

Authentication(optional)

If authentication is required for your private image registry, select Use a Secret and enter the Secret Name.

Note:
Tanzu Service Mesh does not collect usernames and passwords for customer registries. Instead you need to create the secret in each namespace that needs to pull images from Tanzu Service Mesh, including all management components and later any namespaces that need to run workloads that use a sidecar. For more information on creating the required a secret see, Customer-owned Image Registry Support and Secret Authentication.

Caution:
Once a customer image registry account has been created, it cannot be modified. If you need to change your registry details, you must delete the account and re-onboard the cluster.
(Optional) To specify that the Tanzu Service Mesh internal CA or an external CA is used to secure the service mesh installation on the cluster, do one of the following:
- To use the Tanzu Service Mesh internal CA, under Integrations, leave the TSM's default (Self-Signed) label for the cluster.
- To use an external CA, perform these steps:
1. Click Edit Integrations.
2. In the Integration Type drop-down menu, select Certificate Authority.
3. In the Label Selector drop-down menu, delete TSM Default (Self-Signed) and then select the CA label associated with the external CA's intergration account.
4. Click Save.
Note:
In a cluster, you can only use the external CA's certificates or the Tanzu Service Mesh default (self-signed) certificates, but not both together.
Click Generate Security Token to generate a security token.

This security token is used to establish a secure connection between Tanzu Service Mesh and your cluster during the onboarding.
The following kubectl commands become available under 2 Apply the registration YAML to the cluster:
- The kubectl command for applying the registration YAML file to the cluster also becomes available. This file contains the Kubernetes configuration required for the registration of the cluster with Tanzu Service Mesh.
- (Optional) If you provided the configuration settings for your proxy server, the kubectl command for applying the proxy configuration to the cluster becomes available under Then add the proxy configuration to the cluster. Running this command generates a secret that contains the provided configuration settings. The Tanzu Service Mesh agent on the cluster reads the configuration from the secret and uses it to connect to the cluster.
- The kubectl command for creating a Kubernetes secret for the security token becomes available under Then add the token to connect securely withTanzu Service Mesh.
To apply these kubectl commands to the cluster, perform the following steps:
1. Under 2 Apply the registration YAML to the cluster, click to copy the command for applying the registration YAML.
  
  Note:
  Do not close the Onboard Clusters panel.
2. Open a terminal window and set the current context to your cluster:
```
$ kubectl config use-context cluster_name
```
3. Run the copied YAML registration command.
4. (Optional) In the Onboard Clusters panel, under Then add the proxy configuration to the cluster, click to copy the command for applying the proxy configuration to the cluster and then run this command.
  
  Note:
  Perform this step only if you specified that the cluster connects to Tanzu Service Mesh through a proxy server.
5. In the Onboard Clusters panel, under Then add the token to connect securely withTanzu Service Mesh, click to copy the command for creating a secret for the security token and then run this command to establish a secure connection to Tanzu Service Meshusing the security token.
  
  The progress bar "Registering cluster with Tanzu Service Mesh" appears in the Onboard Clusters panel. Registering the cluster with Tanzu Service Mesh takes a few minutes. When the registration is complete, the Install Service Mesh button becomes available.
Under Namespace Inclusion, specify the namespaces on the cluster that you want to include for automatic Istio sidecar injection.
You can select namespaces for inclusion (the Select Namespaces option) or define namespace inclusion rules based on a namespace naming pattern (the Create Namespace Inclusion Rule option). For more information about these options, see Namespace Inclusions.

If you select the Cluster admin owned check box in step 5, the Select Namespaces and Create Namespace Inclusion Rule options become unavailable and are not shown.

Important:
If you don’t select any namespaces for automatic sidecar injection or create any namespace inclusion rules, Tanzu Service Mesh will not include any namespaces in the cluster.
Note:
- You can include only the user-defined namespaces on the cluster. The system namespaces are automatically excluded from Istio sidecar injection.
- You can add new namespace inclusions and edit existing namespace inclusions by Editing the cluster configuration.
- Including a namespace for automatic Istio sidecar injection sets the istio-injection=enabled label on the namespace.
Click Install Service Mesh to install Tanzu Service Mesh on the cluster.

An installation progress bar appears. When the installation is complete, Successfully Onboarded appears next to the cluster name.
Perform the appropriate step.
- To onboard another cluster, click Onboard Another Cluster and repeat steps 2–8.
- To close the Onboard Clusters panel and display the Tanzu Service Mesh Console, click Exit To Console.

Results

The Tanzu Service Mesh Console UI displays information about the infrastructure of the onboarded cluster and the microservices deployed there. Tanzu Service Mesh also starts monitoring and collecting infrastructure and service metrics from the cluster (such as number of nodes and services, requests per second, latency, and CPU usage). The Home page of the Tanzu Service Mesh Console provides summary information about the cluster's infrastructure, a topology view of the services in the cluster, and key metrics. For more information, see View the Summary Infrastructure and Service Information.

If you specified that the cluster connects to Tanzu Service Mesh through a corporate proxy server, you can view the provided proxy configuration settings in the Tanzu Service MeshConsole UI. For more information, see View the Proxy Configuration Settings in Using VMware Tanzu Service Mesh.

Note:

Currently, the proxy configuration that you provide in Tanzu Service Mesh cannot be edited. If the configuration of your proxy changes after the cluster is onboarded, you need to re-onboard the cluster and provide the updated configuration in the Onboard Clusters panel.

What to do next

If you have a multicluster or hybrid-cloud application, you can connect, secure, and manage the services in the application across the clusters with a global namespace. For more information, see Connect Services with a Global Namespace.

After you onboard a cluster, you may need to change the namespace exclusions that you have defined for it. For example, you have deployed a third-party service in a namespace on the cluster, and you don't want Tanzu Service Mesh to manage that service. In this example, you would edit the configuration for the cluster to add an exclusion for the namespace where the third-party service is deployed. For information about editing the configuration of a cluster, see Edit a Cluster.

You can monitor the connectivity between the cluster and Tanzu Service Mesh Software as a Service (SaaS) or, if a proxy server is used, between the cluster and the proxy server.