Onboard a Cluster to Tanzu Service Mesh

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.

During onboarding, you can select which namespaces on your cluster are included. Including a namespace enables automatic Istio sidecar injection in 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.

Important:

When onboarding a cluster to Tanzu Service Mesh whether it already had Istio before or it is a clean cluster, you must select which namespaces on the cluster are included for Istio sidecar injection. Old istio-injection labels on the namespaces will not carry over to Tanzu Service Mesh.

If you set namespace inclusions for a cluster in the Tanzu Service Mesh UI (during onboarding or when editing a cluster configuration) or through the API, you will not be able to manually label any namespaces on the cluster with istio-injection in Kubernetes. To take control over namespace labeling and prevent Tanzu Service Mesh from overriding the namespace labeling changes you make in Kubernetes, do the following:

1. Annotate each namespace on which you want to set the istio-injection label with allspark=disable update:

kubectl annotate ns {namespace-name} allspark=disable-update

2. Set the istio-injection label on the namespace:

kubectl label ns {namespace-name} istio-injection=enabled | disabled

Be aware that the Tanzu Service Mesh UI currently does not reflect the namespace labeling changes you make in Kubernetes if you set the override annotation. In a future release, Tanzu Service Mesh will have the ability to reflect the real-time status of namespaces and delegate control of namespace labeling to users.

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.
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 TSM SaaS to connect to Avi controller(s). Label key value should be "Proxy Location". Label value can be customized.
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 fill the necessary information.

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

Important:
To be able to onboard a cluster using TSM 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 TSM's public ECR registry and push them into your private registries. Checkout the list of TSM repositories to mirror and images to download.

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) You can integrate a Certificate Authority during cluster onboarding. In the Integrations section, choose Certificate Authority under Integration Type, and choose a label you created during Venafi integration from the Label Selector drop-down. By providing the label values accordingly, you can either use TSM's default (Self-Signed) certificate or connect an external CA account. For more information on external CA, see Configuring a Venafi Integration Account. In a cluster, you can only use the external CA or the TSM's default (Self-Signed) 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 with Tanzu 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 with Tanzu 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 Mesh using 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.
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 Mesh Console 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.