Vitess Cluster Administration

naftiko: "1.0.0-alpha1"

info:
  label: "Vitess Cluster Administration"
  description: >-
    Workflow capability for administering Vitess database clusters via the VTAdmin API.
    Combines cluster topology inspection, tablet management, keyspace and schema
    administration, VReplication workflow monitoring, backup auditing, and VTGate
    management into a unified interface. Used by database administrators, site reliability
    engineers, and platform engineers managing large-scale MySQL deployments on Kubernetes.
  tags:
    - Backups
    - Cluster Management
    - Cloud Native
    - CNCF
    - Database
    - Distributed Systems
    - MySQL
    - Sharding
    - Vitess
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      VTADMIN_TOKEN: VTADMIN_TOKEN
      VTADMIN_HOST: VTADMIN_HOST
      VTADMIN_PORT: VTADMIN_PORT

capability:
  consumes:
    - import: vitess-vtadmin
      location: ./shared/vitess-vtadmin.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: vitess-cluster-admin-api
      description: "Unified REST API for Vitess cluster administration and observability."
      resources:
        - path: /v1/clusters
          name: clusters
          description: "Registered Vitess clusters"
          operations:
            - method: GET
              name: get-clusters
              description: "List all registered Vitess clusters"
              call: "vitess-vtadmin.get-clusters"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/tablets
          name: tablets
          description: "VTTablet instances"
          operations:
            - method: GET
              name: get-tablets
              description: "List all VTTablet instances with cluster and shard info"
              call: "vitess-vtadmin.get-tablets"
              with:
                cluster_id: "rest.cluster_id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/tablets/{tablet}
          name: tablet
          description: "Individual tablet details"
          operations:
            - method: GET
              name: get-tablet
              description: "Get details of a specific tablet by alias"
              call: "vitess-vtadmin.get-tablet"
              with:
                tablet: "rest.tablet"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/keyspaces
          name: keyspaces
          description: "Vitess keyspaces (logical databases)"
          operations:
            - method: GET
              name: get-keyspaces
              description: "List all keyspaces across clusters"
              call: "vitess-vtadmin.get-keyspaces"
              with:
                cluster_id: "rest.cluster_id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/schemas
          name: schemas
          description: "Database schemas for all keyspaces"
          operations:
            - method: GET
              name: get-schemas
              description: "List all keyspace schemas"
              call: "vitess-vtadmin.get-schemas"
              with:
                cluster_id: "rest.cluster_id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/schemas/{cluster_id}/{keyspace}
          name: schema
          description: "Schema for a specific keyspace"
          operations:
            - method: GET
              name: get-schema
              description: "Get table definitions for a keyspace"
              call: "vitess-vtadmin.get-schema"
              with:
                cluster_id: "rest.cluster_id"
                keyspace: "rest.keyspace"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/workflows
          name: workflows
          description: "VReplication workflows"
          operations:
            - method: GET
              name: get-workflows
              description: "List all VReplication workflows"
              call: "vitess-vtadmin.get-workflows"
              with:
                cluster_id: "rest.cluster_id"
                active_only: "rest.active_only"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/backups
          name: backups
          description: "Tablet backup inventory"
          operations:
            - method: GET
              name: get-backups
              description: "List all tablet backups"
              call: "vitess-vtadmin.get-backups"
              with:
                cluster_id: "rest.cluster_id"
                keyspace: "rest.keyspace"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/cells
          name: cells
          description: "Availability zones and data centers"
          operations:
            - method: GET
              name: get-cells
              description: "List all cells across clusters"
              call: "vitess-vtadmin.get-cells"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/gates
          name: gates
          description: "VTGate proxy instances"
          operations:
            - method: GET
              name: get-gates
              description: "List all VTGate instances"
              call: "vitess-vtadmin.get-gates"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/topology/{cluster_id}
          name: topology
          description: "Full cluster topology"
          operations:
            - method: GET
              name: get-cluster-topology
              description: "Get complete topology for a cluster"
              call: "vitess-vtadmin.get-cluster-topology"
              with:
                cluster_id: "rest.cluster_id"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: vitess-cluster-admin-mcp
      transport: http
      description: "MCP server for AI-assisted Vitess cluster administration and troubleshooting."
      tools:
        - name: get-clusters
          description: "List all registered Vitess clusters and their identifiers"
          hints:
            readOnly: true
            idempotent: true
          call: "vitess-vtadmin.get-clusters"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-tablets
          description: "List all VTTablet instances with type (PRIMARY/REPLICA), shard, keyspace, and state"
          hints:
            readOnly: true
            idempotent: true
          call: "vitess-vtadmin.get-tablets"
          with:
            cluster_id: "tools.cluster_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-tablet
          description: "Get detailed information about a specific tablet including health and replication status"
          hints:
            readOnly: true
            idempotent: true
          call: "vitess-vtadmin.get-tablet"
          with:
            tablet: "tools.tablet"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-keyspaces
          description: "List all Vitess keyspaces (logical databases) and their sharding configuration"
          hints:
            readOnly: true
            idempotent: true
          call: "vitess-vtadmin.get-keyspaces"
          with:
            cluster_id: "tools.cluster_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-schemas
          description: "List database schemas for all keyspaces across clusters"
          hints:
            readOnly: true
            idempotent: true
          call: "vitess-vtadmin.get-schemas"
          with:
            cluster_id: "tools.cluster_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-schema
          description: "Get table definitions and index information for a specific keyspace"
          hints:
            readOnly: true
            idempotent: true
          call: "vitess-vtadmin.get-schema"
          with:
            cluster_id: "tools.cluster_id"
            keyspace: "tools.keyspace"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-workflows
          description: "List VReplication workflows including MoveTables, Reshard, and Materialize operations"
          hints:
            readOnly: true
            idempotent: true
          call: "vitess-vtadmin.get-workflows"
          with:
            cluster_id: "tools.cluster_id"
            active_only: "tools.active_only"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-backups
          description: "List all tablet backups to audit backup coverage and find latest backup per shard"
          hints:
            readOnly: true
            idempotent: true
          call: "vitess-vtadmin.get-backups"
          with:
            cluster_id: "tools.cluster_id"
            keyspace: "tools.keyspace"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-cells
          description: "List all cells (availability zones and data center locations) across clusters"
          hints:
            readOnly: true
            idempotent: true
          call: "vitess-vtadmin.get-cells"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-gates
          description: "List all VTGate proxy instances and their configured keyspaces"
          hints:
            readOnly: true
            idempotent: true
          call: "vitess-vtadmin.get-gates"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-cluster-topology
          description: "Get the complete topology of a Vitess cluster including all keyspaces, shards, and tablets"
          hints:
            readOnly: true
            idempotent: true
          call: "vitess-vtadmin.get-cluster-topology"
          with:
            cluster_id: "tools.cluster_id"
          outputParameters:
            - type: object
              mapping: "$."