openapi: 3.1.0
info:
  title: VMware Tanzu Service Mesh Authentication Global Namespaces API
  description: The VMware Tanzu Service Mesh REST API provides programmatic management of Kubernetes clusters onboarded to Tanzu Service Mesh, global namespaces spanning multiple clusters and clouds, resource groups for policy enforcement, and service groups. Authentication uses a CSP API token exchanged for a short-lived Bearer token passed via the csp-auth-token header.
  version: v1alpha1
  contact:
    name: VMware Tanzu Support
    url: https://tanzu.vmware.com/support
  license:
    name: Proprietary
    url: https://tanzu.vmware.com/
servers:
- url: https://prod-2.nsxservicemesh.vmware.com
  description: VMware Tanzu Service Mesh Production API
tags:
- name: Global Namespaces
  description: Manage global namespaces connecting workloads across clusters
paths:
  /v1alpha1/global-namespaces:
    get:
      operationId: listGlobalNamespaces
      summary: List Global Namespaces
      description: List all global namespaces. A global namespace connects workloads across multiple clusters and clouds into one virtual unit for consistent traffic routing, connectivity, and security.
      tags:
      - Global Namespaces
      security:
      - CspAuthToken: []
      responses:
        '200':
          description: List of global namespaces
          content:
            application/json:
              schema:
                type: object
                properties:
                  global_namespaces:
                    type: array
                    items:
                      $ref: '#/components/schemas/GlobalNamespace'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createGlobalNamespace
      summary: Create Global Namespace
      description: Create a new global namespace spanning multiple clusters.
      tags:
      - Global Namespaces
      security:
      - CspAuthToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGlobalNamespaceRequest'
      responses:
        '200':
          description: Global namespace created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalNamespace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1alpha1/global-namespaces/{namespace_id}:
    get:
      operationId: getGlobalNamespace
      summary: Get Global Namespace
      description: Retrieve details for a specific global namespace.
      tags:
      - Global Namespaces
      security:
      - CspAuthToken: []
      parameters:
      - name: namespace_id
        in: path
        required: true
        schema:
          type: string
        description: Global namespace identifier
      responses:
        '200':
          description: Global namespace details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalNamespace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateGlobalNamespace
      summary: Update Global Namespace
      description: Update the configuration of a global namespace.
      tags:
      - Global Namespaces
      security:
      - CspAuthToken: []
      parameters:
      - name: namespace_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGlobalNamespaceRequest'
      responses:
        '200':
          description: Global namespace updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalNamespace'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteGlobalNamespace
      summary: Delete Global Namespace
      description: Delete a global namespace.
      tags:
      - Global Namespaces
      security:
      - CspAuthToken: []
      parameters:
      - name: namespace_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Global namespace deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or expired csp-auth-token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    GlobalNamespace:
      type: object
      description: A global namespace connecting workloads across multiple clusters.
      properties:
        id:
          type: string
          description: Global namespace identifier.
        name:
          type: string
          description: Global namespace name.
        description:
          type: string
        domain_name:
          type: string
          description: DNS domain for the global namespace.
        use_shared_gateway:
          type: boolean
          description: Whether to use a shared gateway.
        mtls_enforced:
          type: boolean
          description: Whether mTLS is enforced for inter-service communication.
        ca_type:
          type: string
          description: Certificate authority type.
          enum:
          - PreExistingCA
          - GeneratedCA
        cluster_configs:
          type: array
          description: Cluster configurations participating in this global namespace.
          items:
            $ref: '#/components/schemas/ClusterConfig'
        status:
          type: string
          description: Global namespace status.
          enum:
          - READY
          - PENDING
          - ERROR
    ClusterConfig:
      type: object
      description: Configuration for a cluster participating in a global namespace.
      properties:
        cluster_name:
          type: string
          description: Name of the cluster.
        namespaces:
          type: array
          items:
            type: string
          description: Kubernetes namespaces from this cluster to include.
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        details:
          type: string
    CreateGlobalNamespaceRequest:
      type: object
      required:
      - name
      description: Request body for creating a global namespace.
      properties:
        name:
          type: string
          description: Global namespace name.
        description:
          type: string
        domain_name:
          type: string
        mtls_enforced:
          type: boolean
          default: true
        cluster_configs:
          type: array
          items:
            $ref: '#/components/schemas/ClusterConfig'
  securitySchemes:
    CspAuthToken:
      type: apiKey
      in: header
      name: csp-auth-token
      description: Short-lived Bearer token obtained by exchanging a CSP API token via POST /csp/gateway/am/api/auth/api-tokens/authorize.
externalDocs:
  description: Tanzu Service Mesh API Documentation
  url: https://docs.vmware.com/en/VMware-Tanzu-Service-Mesh/services/api-programming-guide/GUID-6C5044B8-6950-42A6-87A5-3D88BEAE09DB.html