openapi: 3.1.0
info:
  title: VMware Tanzu Service Mesh Authentication Clusters 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: Clusters
  description: Manage Kubernetes clusters onboarded to Tanzu Service Mesh
paths:
  /v1alpha1/clusters:
    get:
      operationId: listClusters
      summary: List Clusters
      description: Retrieve all Kubernetes clusters onboarded to Tanzu Service Mesh.
      tags:
      - Clusters
      security:
      - CspAuthToken: []
      responses:
        '200':
          description: List of clusters
          content:
            application/json:
              schema:
                type: object
                properties:
                  clusters:
                    type: array
                    items:
                      $ref: '#/components/schemas/Cluster'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1alpha1/clusters/{cluster_name}:
    get:
      operationId: getCluster
      summary: Get Cluster
      description: Retrieve details for a specific onboarded cluster.
      tags:
      - Clusters
      security:
      - CspAuthToken: []
      parameters:
      - name: cluster_name
        in: path
        required: true
        schema:
          type: string
        description: The cluster name as registered in Tanzu Service Mesh
      responses:
        '200':
          description: Cluster details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: onboardCluster
      summary: Onboard Cluster
      description: Onboard a Kubernetes cluster to Tanzu Service Mesh. This initiates the installation of the TSM agent on the cluster.
      tags:
      - Clusters
      security:
      - CspAuthToken: []
      parameters:
      - name: cluster_name
        in: path
        required: true
        schema:
          type: string
        description: Unique name for the cluster in Tanzu Service Mesh
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardClusterRequest'
      responses:
        '200':
          description: Cluster onboarding initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: removeCluster
      summary: Remove Cluster
      description: Remove a cluster from Tanzu Service Mesh management.
      tags:
      - Clusters
      security:
      - CspAuthToken: []
      parameters:
      - name: cluster_name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Cluster removal initiated
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    OnboardClusterRequest:
      type: object
      description: Request body to onboard a cluster to Tanzu Service Mesh.
      properties:
        display_name:
          type: string
          description: Human-readable name for the cluster.
        description:
          type: string
          description: Description of the cluster.
        tags:
          type: object
          additionalProperties:
            type: string
          description: Key-value tags for organizing clusters.
    Cluster:
      type: object
      description: A Kubernetes cluster onboarded to Tanzu Service Mesh.
      properties:
        name:
          type: string
          description: Cluster name in Tanzu Service Mesh.
          example: production-west
        display_name:
          type: string
          description: Human-readable cluster display name.
        state:
          type: string
          description: Current cluster state.
          enum:
          - READY
          - INSTALLING
          - OFFLINE
          - ERROR
          - REMOVING
        cloud_provider:
          type: string
          description: Cloud provider hosting the cluster.
          example: AWS
        region:
          type: string
          description: Cloud region.
          example: us-west-2
        k8s_version:
          type: string
          description: Kubernetes version.
          example: 1.29.0
        tsm_version:
          type: string
          description: TSM agent version installed on the cluster.
        namespace_count:
          type: integer
          description: Number of namespaces in the cluster.
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        details:
          type: string
  responses:
    Unauthorized:
      description: Invalid or expired csp-auth-token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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