Create a Global Namespace

You can use global namespaces in Tanzu Service Mesh to connect and secure the services in your application deployed on a single cluster or multiple clusters. This topic describes an example of how to create a global namespace and add services from two clusters to it with the Tanzu Service Mesh API.

Prerequisites

Verify that the following prerequisites are met:

You have onboarded the clusters where your services are deployed. For this example, you must onboard at least two clusters. For more information about onboarding a cluster, see Onboard a Cluster to Tanzu Service Mesh.
You know the Kubernetes namespaces in your clusters that hold the services of your application. These are the namespaces where the istio-injection=enabled label has been set to enable automatic sidecar injection.
You have an API token and an access code to authenticate your requests to the Tanzu Service Mesh API. You must use the access code in the csp-auth-token header in your requests. For information about generating an API token and getting an access code, see Authentication with the Tanzu Service Mesh REST API.

Procedure

♦Submit the following request.

POST https://{server_name}/tsm/v1alpha2/projects/default/global-namespaces

Where {server_name} is the host name of the Tanzu Service Mesh server (for example, prod-1.nsxservicemesh.vmware.com).

Request Body

{
   "name": string,
   "display_name": string,
   "domain_name": string,
   "description": string,
   "color": string,
   "mtls_enforced": boolean,
   "ca_type": string,
   "ca": string,
   "version": string,
   "match_conditions":[
      {
         "namespace":{
            "type": string,
            "match": string         
         },
         "cluster":{
            "type": string,
            "match": string         
         }
      },
      {
         "namespace":{
            "type": string,
            "match": string
         },
         "cluster":{
            "type": string,
            "match": string
         }
      }
   ]
}

Table 1. Request Body Properties
Property	Data type	Required/Optional	Description
`name`	String	Required	Internal identifier of the global namespace. This parameter has a minimum length of 2 characters, and a maximum length of 256 characters.
`display_name`	String	Optional	The name that the global namespace that will have in the Tanzu Service Mesh Console. If you don't provide a `display_name`, the value of `name` will appear for the global namespace in the Tanzu Service Mesh Console. The `display_name` can be different from the `name`.
`domain_name`	String	Required	Domain name of the global namespace. The `name` of a global namespace and its `domain_name` together form a fully qualified domain name (FQDN) that uniquely identifies that global namespace and makes it possible for the services in the global namespace to communicate with each other across clusters.
`description`	String	Optional	Description of the global namespace. You can use the description of the global namespace to indicate its purpose or distinguish it from other global namespaces.
`color`	String	Optional	Color code of the global namespace. This parameter is reserved for future use.
`mtls_enforced`	Boolean	Optional	Specifies if Tanzu Service Mesh enforces encryption of all traffic between the services in the global namespace, using Mutual Transport Layer Security authentication (mTLS). Set this parameter to `true`. If you don't include this parameter, it will be set to `true` by default.
`ca_type`	String	Optional	Type of certificate authority. Each global namespace uses a certificate authority (CA) that provisions identities for the services inside that global namespace. Set this parameter to `PreExistingCA`. If you don't include this parameter, it will be set to `PreExistingCA` by default.
`ca`	String	Optional	The certificate authority to use for the global namespace. Set this parameter to `default`. If you don't include this parameter, it will be set to `default`.
`version`	String	Optional	Version of the global namespace. Always set this parameter to `1.0`. If you don't include this parameter, it will be set to `1.0` by default.
`match_conditions[]`	List	Required	Contains pairs of `namespace` and `cluster` parameters. Each pair defines a service mapping rule that is used to select services for the global namespace. `match_conditions` must contain a least one `namespace`-`cluster` pair. See the descriptions of `namespace` and `cluster`.
`match-conditions[].namespace`	Nested object	Required	Kubernetes namespace that holds the services that you want to add to the global namespace. Inside each `namespace`, specify the name of the namespace by providing values for `type` and `match`.
`match-conditions[].namespace.type`	String	Required	Operator to use for evaluating the name of namespace. Acceptable values: `EXACT`. The name of the namespace must exactly match the value of `match`. `START_WITH`. The name of the namespace must begin with the value of `match`.
`match-conditions[].namespace.match`	String	Required	Depending on `type`, the value to evaluate the name of the namespace against. If `type` is `EXACT`, set `match` to the exact name of the namespace. If `type` to `START_WITH`, set `match` to the string with which the name must begin.
`match-conditions[].cluster`	Nested object	Required	The cluster that contains the specified Kubernetes namespace. Inside each `cluster`, specify the ID of the cluster by providing values for `type` and `match`. Important: `match` must contain the cluster ID, not the cluster display name. If `type` set to `START_WITH`, `match` can be a partial cluster ID.
`match-conditions[].cluster.type`	String	Required	Operator to use for evaluating the cluster ID. Acceptable values: `EXACT`. The cluster ID must exactly match the value of `match`. `START_WITH`. The cluster ID must begin with the value of `match`.
`match-conditions[].cluster.match`	String	Required	Depending on `type`, the value to evaluate the cluster ID against. If `type` is `EXACT`, set `match` to the exact cluster ID. If `type` to `START_WITH`, set `match` to the string with which the cluster ID must begin.

Results

If the global namespace was created successfully, the response header from the Tanzu Service Mesh REST API contains a status code of 200 global namespace created. The response includes the name and display_name of the global namespace.

Example: Request to Create a Global Namespace

Submit the following request to create a global namespace named "sample_gns" and add to the global namespace the services from the default namespace on a cluster whose name begins with "EU" and from the default namespace on a cluster whose name begins with "CA".

POST https://sample-server.servicemesh.biz/tsm/v1alpha2/projects/default/global-namespaces

Use the following properties in the request body.

{
   "name":"sample-gns",
   "display_name":"Sample global namespace",
   "domain_name":"sample.app.com",
   "description":"My global namespace",
   "mtls_enforced":true,
   "ca_type":"PreExistingCA",
   "ca":"default",
   "version":"1.0",
   "match_conditions":[
      {
         "namespace":{
            "type":"EXACT",
            "match":"default"
         },
         "cluster":{
            "type":"START_WITH",
            "match":"EU"
         }
      },
      {
         "namespace":{
            "type":"EXACT",
            "match":"default"
         },
         "cluster":{
            "type":"START_WITH",
            "match":"CA"
         }
      }
   ]
}

What to do next

To enable cross-cluster communication between the services in the global namespace, edit the Kubernetes deployment for an appropriate service to specify the domain name of the global namespace, prefixing the domain name with the name of the service with which the first service needs to communicate.

Important:

Make sure that you prefix the domain name with the name of the service that you want the service being edited to communicate with. See the following example.

For example, a sample application includes a shopping service deployed on prod-cluster1 and a catalog service deployed on prod-cluster2. Both services are added to the sample_gns global namespace with a domain name of sample.app.com. The shopping service needs to communicate with the catalog service. Specify the domain name sample.app.com in the deployment of the shopping service, prefixing the domain name with catalog: catalog.sample.app.com.

In the deployment, set the appropriate variable to catalog.sample.app.com. The catalog prefix is required for the shopping service to communicate with the catalog service.