openapi: 3.0.0
info:
  description: >-
    This project can be used to recommend instance type groups on different
    cloud providers consisting of regular and spot/preemptible instances.

    The main goal is to provide and continuously manage a cost-effective but still stable cluster layout that's built up from a diverse set of regular and spot instances.
  title: Cluster Recommender.
  contact:
    name: Banzai Cloud
    email: info@banzaicloud.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.0.1
paths:
  /recommender/multicloud:
    post:
      description: Provides a recommended set of node pools on a given provider in a
        specific region.
      tags:
        - recommend
      summary: Provides a recommended set of node pools on a given provider in a
        specific region.
      operationId: recommendMultiCluster
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/recommendMultiClusterRequest"
        description: request params
        required: true
      responses:
        "200":
          description: recommendation response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/recommendationResponse"
  "/recommender/provider/{provider}/service/{service}/region/{region}/cluster":
    put:
      description: Provides a recommendation for a scale-out, based on a current cluster
        layout on a given provider in a specific region.
      tags:
        - recommend
      summary: Provides a recommendation for a scale-out, based on a current cluster
        layout on a given provider in a specific region.
      operationId: recommendClusterScaleOut
      parameters:
        - x-go-name: Provider
          description: provider
          name: provider
          in: path
          required: true
          schema:
            type: string
        - x-go-name: Service
          description: service
          name: service
          in: path
          required: true
          schema:
            type: string
        - x-go-name: Region
          description: region
          name: region
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/recommendClusterScaleOutRequest"
        description: request params
        required: true
      responses:
        "200":
          description: recommendation response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/recommendationResponse"
    post:
      description: Provides a recommended set of node pools on a given provider in a
        specific region.
      tags:
        - recommend
      summary: Provides a recommended set of node pools on a given provider in a
        specific region.
      operationId: recommendCluster
      parameters:
        - x-go-name: Provider
          description: provider
          name: provider
          in: path
          required: true
          schema:
            type: string
        - x-go-name: Service
          description: service
          name: service
          in: path
          required: true
          schema:
            type: string
        - x-go-name: Region
          description: region
          name: region
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/recommendClusterRequest"
        description: request params
        required: true
      responses:
        "200":
          description: recommendation response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/recommendationResponse"
servers:
  - url: /api/v1
components:
  schemas:
    ClusterRecommendationAccuracy:
      description: ClusterRecommendationAccuracy encapsulates recommendation accuracy
      type: object
      properties:
        cpu:
          description: Number of recommended cpus
          type: number
          format: double
          x-go-name: RecCpu
        masterPrice:
          description: Amount of master instance type prices in the recommended cluster
          type: number
          format: double
          x-go-name: RecMasterPrice
        memory:
          description: The summarised amount of memory in the recommended cluster
          type: number
          format: double
          x-go-name: RecMem
        nodes:
          description: Number of recommended nodes
          type: integer
          format: int64
          x-go-name: RecNodes
        regularNodes:
          description: Number of regular instance type in the recommended cluster
          type: integer
          format: int64
          x-go-name: RecRegularNodes
        regularPrice:
          description: Amount of regular instance type prices in the recommended cluster
          type: number
          format: double
          x-go-name: RecRegularPrice
        spotNodes:
          description: Number of spot instance type in the recommended cluster
          type: integer
          format: int64
          x-go-name: RecSpotNodes
        spotPrice:
          description: Amount of spot instance type prices in the recommended cluster
          type: number
          format: double
          x-go-name: RecSpotPrice
        totalPrice:
          description: Total price in the recommended cluster
          type: number
          format: double
          x-go-name: RecTotalPrice
        workerPrice:
          description: Amount of worker instance type prices in the recommended cluster
          type: number
          format: double
          x-go-name: RecWorkerPrice
        zone:
          description: Availability zone in the recommendation
          type: string
          x-go-name: RecZone
      x-go-package: github.com/banzaicloud/telescopes/pkg/recommender
    ClusterRecommendationReq:
      description: ClusterRecommendationReq encapsulates the recommendation input data
      type: object
      properties:
        allowBurst:
          description: Are burst instances allowed in recommendation
          type: boolean
          x-go-name: AllowBurst
        allowOlderGen:
          description: AllowOlderGen allow older generations of virtual machines (applies
            for EC2 only)
          type: boolean
          x-go-name: AllowOlderGen
        category:
          description: Category specifies the virtual machine category
          type: array
          items:
            type: string
          x-go-name: Category
        maxNodes:
          description: Maximum number of nodes in the recommended cluster
          type: integer
          format: int64
          x-go-name: MaxNodes
        minNodes:
          description: Minimum number of nodes in the recommended cluster
          type: integer
          format: int64
          x-go-name: MinNodes
        networkPerf:
          description: NetworkPerf specifies the network performance category
          type: array
          items:
            type: string
          x-go-name: NetworkPerf
        onDemandPct:
          description: Percentage of regular (on-demand) nodes in the recommended cluster
          type: integer
          format: int64
          x-go-name: OnDemandPct
        sameSize:
          description: If true, recommended instance types will have a similar size
          type: boolean
          x-go-name: SameSize
        sumCpu:
          description: Total number of CPUs requested for the cluster
          type: number
          format: double
          x-go-name: SumCpu
        sumGpu:
          description: Total number of GPUs requested for the cluster
          type: integer
          format: int64
          x-go-name: SumGpu
        sumMem:
          description: Total memory requested for the cluster (GB)
          type: number
          format: double
          x-go-name: SumMem
      x-go-package: github.com/banzaicloud/telescopes/pkg/recommender
    ClusterRecommendationResp:
      description: ClusterRecommendationResp encapsulates recommendation result data
      type: object
      properties:
        accuracy:
          $ref: "#/components/schemas/ClusterRecommendationAccuracy"
        nodePools:
          description: Recommended node pools
          type: array
          items:
            $ref: "#/components/schemas/NodePool"
          x-go-name: NodePools
        provider:
          description: The cloud provider
          type: string
          x-go-name: Provider
        region:
          description: Service's region
          type: string
          x-go-name: Region
        service:
          description: Provider's service
          type: string
          x-go-name: Service
        zone:
          description: Availability zone in the recommendation - a multi-zone
            recommendation means that all node pools should expand to all zones
          type: string
          x-go-name: Zone
      x-go-package: github.com/banzaicloud/telescopes/pkg/recommender
    ClusterRecommender:
      description: ClusterRecommender is the main entry point for cluster recommendation
      type: object
      x-go-package: github.com/banzaicloud/telescopes/pkg/recommender
    GetRecommendationParams:
      description: GetRecommendationParams is a placeholder for the recommendation route's
        path parameters
      type: object
      properties:
        provider:
          description: in:path
          type: string
          x-go-name: Provider
        region:
          description: in:path
          type: string
          x-go-name: Region
        service:
          description: in:path
          type: string
          x-go-name: Service
      x-go-package: github.com/banzaicloud/telescopes/internal/app/telescopes/api
    NodePool:
      description: NodePool represents a set of instances with a specific vm type
      type: object
      properties:
        role:
          description: Role in the cluster, eg. master or worker
          type: string
          x-go-name: Role
        sumNodes:
          description: Recommended number of nodes in the node pool
          type: integer
          format: int64
          x-go-name: SumNodes
        vm:
          $ref: "#/components/schemas/VirtualMachine"
        vmClass:
          description: Specifies if the recommended node pool consists of regular or
            spot/preemptible instance types
          type: string
          x-go-name: VmClass
      x-go-package: github.com/banzaicloud/telescopes/pkg/recommender
    NodePoolDesc:
      type: object
      properties:
        instanceType:
          description: Instance type of VMs in the node pool
          type: string
          x-go-name: InstanceType
        sumNodes:
          description: Number of VMs in the node pool
          type: integer
          format: int64
          x-go-name: SumNodes
        vmClass:
          description: Signals that the node pool consists of regular or spot/preemptible
            instance types
          type: string
          x-go-name: VmClass
      x-go-package: github.com/banzaicloud/telescopes/pkg/recommender
    NodePoolRecommender:
      type: object
      x-go-package: github.com/banzaicloud/telescopes/pkg/recommender
    Provider:
      type: object
      properties:
        provider:
          type: string
          x-go-name: Provider
        services:
          type: array
          items:
            type: string
          x-go-name: Services
      x-go-package: github.com/banzaicloud/telescopes/pkg/recommender
    VirtualMachine:
      description: VirtualMachine describes an instance type
      type: object
      properties:
        avgPrice:
          description: Average price of the instance (differs from on demand price in case
            of spot or preemptible instances)
          type: number
          format: double
          x-go-name: AvgPrice
        burst:
          description: Burst signals a burst type instance
          type: boolean
          x-go-name: Burst
        category:
          description: Instance type category
          type: string
          x-go-name: Category
        cpusPerVm:
          description: Number of CPUs in the instance type
          type: number
          format: double
          x-go-name: Cpus
        currentGen:
          description: CurrentGen the vm is of current generation
          type: boolean
          x-go-name: CurrentGen
        gpusPerVm:
          description: Number of GPUs in the instance type
          type: number
          format: double
          x-go-name: Gpus
        memPerVm:
          description: Available memory in the instance type (GB)
          type: number
          format: double
          x-go-name: Mem
        networkPerf:
          description: NetworkPerf holds the network performance
          type: string
          x-go-name: NetworkPerf
        networkPerfCategory:
          description: NetworkPerfCat holds the network performance category
          type: string
          x-go-name: NetworkPerfCat
        onDemandPrice:
          description: Regular price of the instance type
          type: number
          format: double
          x-go-name: OnDemandPrice
        type:
          description: Instance type
          type: string
          x-go-name: Type
        zones:
          description: Zones
          type: array
          items:
            type: string
          x-go-name: Zones
      x-go-package: github.com/banzaicloud/telescopes/pkg/recommender
    VmRecommender:
      type: object
      x-go-package: github.com/banzaicloud/telescopes/pkg/recommender
    recommendClusterRequest:
      description: SingleClusterRecommendationReq encapsulates the recommendation input data
      type: object
      properties:
        allowBurst:
          description: Are burst instances allowed in recommendation
          type: boolean
          x-go-name: AllowBurst
        allowOlderGen:
          description: AllowOlderGen allow older generations of virtual machines (applies
            for EC2 only)
          type: boolean
          x-go-name: AllowOlderGen
        category:
          description: Category specifies the virtual machine category
          type: array
          items:
            type: string
          x-go-name: Category
        excludes:
          description: Excludes is a blacklist - a slice with vm types to be excluded from
            the recommendation
          type: array
          items:
            type: string
          x-go-name: Excludes
        includes:
          description: Includes is a whitelist - a slice with vm types to be contained in
            the recommendation
          type: array
          items:
            type: string
          x-go-name: Includes
        maxNodes:
          description: Maximum number of nodes in the recommended cluster
          type: integer
          format: int64
          x-go-name: MaxNodes
        minNodes:
          description: Minimum number of nodes in the recommended cluster
          type: integer
          format: int64
          x-go-name: MinNodes
        networkPerf:
          description: NetworkPerf specifies the network performance category
          type: array
          items:
            type: string
          x-go-name: NetworkPerf
        onDemandPct:
          description: Percentage of regular (on-demand) nodes in the recommended cluster
          type: integer
          format: int64
          x-go-name: OnDemandPct
        sameSize:
          description: If true, recommended instance types will have a similar size
          type: boolean
          x-go-name: SameSize
        sumCpu:
          description: Total number of CPUs requested for the cluster
          type: number
          format: double
          x-go-name: SumCpu
        sumGpu:
          description: Total number of GPUs requested for the cluster
          type: integer
          format: int64
          x-go-name: SumGpu
        sumMem:
          description: Total memory requested for the cluster (GB)
          type: number
          format: double
          x-go-name: SumMem
        zone:
          description: Availability zone that the cluster should expand to
          type: string
          x-go-name: Zone
      x-go-name: SingleClusterRecommendationReq
      x-go-package: github.com/banzaicloud/telescopes/pkg/recommender
    recommendClusterScaleOutRequest:
      description: ClusterScaleoutRecommendationReq encapsulates the recommendation input
        data
      type: object
      properties:
        actualLayout:
          description: |-
            Description of the current cluster layout
            in:body
          type: array
          items:
            $ref: "#/components/schemas/NodePoolDesc"
          x-go-name: ActualLayout
        desiredCpu:
          description: Total desired number of CPUs in the cluster after the scale out
          type: number
          format: double
          x-go-name: DesiredCpu
        desiredGpu:
          description: Total desired number of GPUs in the cluster after the scale out
          type: integer
          format: int64
          x-go-name: DesiredGpu
        desiredMem:
          description: Total desired memory (GB) in the cluster after the scale out
          type: number
          format: double
          x-go-name: DesiredMem
        excludes:
          description: Excludes is a blacklist - a slice with vm types to be excluded from
            the recommendation
          type: array
          items:
            type: string
          x-go-name: Excludes
        onDemandPct:
          description: Percentage of regular (on-demand) nodes among the scale out nodes
          type: integer
          format: int64
          x-go-name: OnDemandPct
        zone:
          description: Availability zone to be included in the recommendation
          type: string
          x-go-name: Zone
      x-go-name: ClusterScaleoutRecommendationReq
      x-go-package: github.com/banzaicloud/telescopes/pkg/recommender
    recommendMultiClusterRequest:
      description: MultiClusterRecommendationReq encapsulates the recommendation input data
      type: object
      properties:
        allowBurst:
          description: Are burst instances allowed in recommendation
          type: boolean
          x-go-name: AllowBurst
        allowOlderGen:
          description: AllowOlderGen allow older generations of virtual machines (applies
            for EC2 only)
          type: boolean
          x-go-name: AllowOlderGen
        category:
          description: Category specifies the virtual machine category
          type: array
          items:
            type: string
          x-go-name: Category
        continents:
          type: array
          items:
            type: string
          x-go-name: Continents
        excludes:
          description: Excludes is a blacklist - a slice with vm types to be excluded from
            the recommendation
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: array
              items:
                type: string
          x-go-name: Excludes
        includes:
          description: Includes is a whitelist - a slice with vm types to be contained in
            the recommendation
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: array
              items:
                type: string
          x-go-name: Includes
        maxNodes:
          description: Maximum number of nodes in the recommended cluster
          type: integer
          format: int64
          x-go-name: MaxNodes
        minNodes:
          description: Minimum number of nodes in the recommended cluster
          type: integer
          format: int64
          x-go-name: MinNodes
        networkPerf:
          description: NetworkPerf specifies the network performance category
          type: array
          items:
            type: string
          x-go-name: NetworkPerf
        onDemandPct:
          description: Percentage of regular (on-demand) nodes in the recommended cluster
          type: integer
          format: int64
          x-go-name: OnDemandPct
        providers:
          type: array
          items:
            $ref: "#/components/schemas/Provider"
          x-go-name: Providers
        respPerService:
          description: Maximum number of response per service
          type: integer
          format: int64
          x-go-name: RespPerService
        sameSize:
          description: If true, recommended instance types will have a similar size
          type: boolean
          x-go-name: SameSize
        sumCpu:
          description: Total number of CPUs requested for the cluster
          type: number
          format: double
          x-go-name: SumCpu
        sumGpu:
          description: Total number of GPUs requested for the cluster
          type: integer
          format: int64
          x-go-name: SumGpu
        sumMem:
          description: Total memory requested for the cluster (GB)
          type: number
          format: double
          x-go-name: SumMem
      x-go-name: MultiClusterRecommendationReq
      x-go-package: github.com/banzaicloud/telescopes/pkg/recommender
    recommendationResponse:
      description: RecommendationResponse encapsulates the recommendation response
      type: object
      properties:
        accuracy:
          $ref: "#/components/schemas/ClusterRecommendationAccuracy"
        nodePools:
          description: Recommended node pools
          type: array
          items:
            $ref: "#/components/schemas/NodePool"
          x-go-name: NodePools
        provider:
          description: The cloud provider
          type: string
          x-go-name: Provider
        region:
          description: Service's region
          type: string
          x-go-name: Region
        service:
          description: Provider's service
          type: string
          x-go-name: Service
        zone:
          description: Availability zone in the recommendation - a multi-zone
            recommendation means that all node pools should expand to all zones
          type: string
          x-go-name: Zone
      x-go-name: RecommendationResponse
      x-go-package: github.com/banzaicloud/telescopes/internal/app/telescopes/api