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.