CUDO Compute Clusters API

openapi: 3.2.0
info:
  description: The CUDO Compute API is organized around REST. Our API uses predictable resource-oriented URLs, accepts and returns JSON-encoded requests and responses, and uses standard HTTP response codes, authentication, and verbs where possible.
  title: CUDO Compute service Clusters API
  version: 1.0.0
servers:
- url: https://rest.compute.cudo.org/
security:
- bearerAuth: []
tags:
- description: 'Clusters are high-performance computing environments that can be used to run large-scale parallel and distributed applications.


    Related guide: Clusters'
  name: Clusters
paths:
  /v1/clusters/data-centers/{dataCenterId}/machine-types/{machineTypeId}:
    get:
      description: Gets the details of a cluster machine type.
      operationId: GetClusterMachineType
      parameters:
      - in: path
        name: dataCenterId
        required: true
        schema:
          type: string
      - in: path
        name: machineTypeId
        required: true
        schema:
          type: string
      - description: Return custom prices for a specific project.
        in: query
        name: projectId
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetClusterMachineTypeResponse'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
          description: An unexpected error response.
      summary: Get a cluster machine type
      tags:
      - Clusters
  /v1/clusters/machine-types:
    get:
      description: Lists the types of cluster machines that can be provisioned.
      operationId: ListClusterMachineTypes
      parameters:
      - in: query
        name: pageNumber
        schema:
          format: int32
          type: integer
      - in: query
        name: pageSize
        schema:
          format: int32
          type: integer
      - description: Return custom prices for a specific project.
        in: query
        name: projectId
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListClusterMachineTypesResponse'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
          description: An unexpected error response.
      summary: List cluster machine types
      tags:
      - Clusters
  /v1/projects/{projectId}/cluster-machines/{id}:
    delete:
      description: Removes a machine from a cluster. All data on the machine will be lost.
      operationId: DeleteClusterMachine
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
          description: An unexpected error response.
      summary: Delete a cluster machine
      tags:
      - Clusters
    patch:
      description: Updates a machine in a cluster.
      operationId: UpdateClusterMachine
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                architecture:
                  readOnly: true
                  type: string
                cpuCores:
                  format: int32
                  readOnly: true
                  type: integer
                cpuModel:
                  readOnly: true
                  type: string
                cpuSpeedMhz:
                  format: int32
                  readOnly: true
                  type: integer
                createBy:
                  readOnly: true
                  type: string
                createTime:
                  format: date-time
                  readOnly: true
                  type: string
                dataCenterId:
                  readOnly: true
                  type: string
                diskSizeGib:
                  format: int32
                  readOnly: true
                  type: integer
                disks:
                  format: int32
                  readOnly: true
                  type: integer
                externalIpAddress:
                  readOnly: true
                  type: string
                gpuModelId:
                  readOnly: true
                  type: string
                gpus:
                  format: int32
                  readOnly: true
                  type: integer
                internalIpAddress:
                  readOnly: true
                  type: string
                machineTypeId:
                  readOnly: true
                  type: string
                memoryGib:
                  format: int32
                  readOnly: true
                  type: integer
                powerState:
                  $ref: '#/components/schemas/MachinePowerState'
                priceHr:
                  $ref: '#/components/schemas/Decimal'
                state:
                  $ref: '#/components/schemas/ClusterMachine.State'
                volumeIds:
                  items:
                    type: string
                  type: array
              title: Update cluster machine params
              type: object
        description: Update cluster machine params
        required: true
        x-originalParamName: clusterMachine
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterMachine'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
          description: An unexpected error response.
      summary: Update a cluster machine
      tags:
      - Clusters
  /v1/projects/{projectId}/cluster-machines/{id}:reboot:
    post:
      description: Reboots a machine in a cluster.
      operationId: RebootClusterMachine
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
          description: An unexpected error response.
      summary: Reboot a cluster machine
      tags:
      - Clusters
  /v1/projects/{projectId}/cluster-machines/{id}:rename:
    post:
      description: Renames a machine in a cluster. This can be useful if you are assigning specific roles to machines in the cluster.
      operationId: RenameClusterMachine
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - in: path
        name: id
        required: true
        schema:
          type: string
      - in: query
        name: newId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
          description: An unexpected error response.
      summary: Rename a cluster machine
      tags:
      - Clusters
  /v1/projects/{projectId}/clusters:
    get:
      description: Lists clusters within a project.
      operationId: ListClusters
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - in: query
        name: pageNumber
        schema:
          format: int32
          type: integer
      - in: query
        name: pageSize
        schema:
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListClustersResponse'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
          description: An unexpected error response.
      summary: List clusters
      tags:
      - Clusters
    post:
      description: Creates a new cluster.
      operationId: CreateCluster
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                architecture:
                  readOnly: true
                  type: string
                commitmentEndTime:
                  format: date-time
                  readOnly: true
                  type: string
                commitmentTerm:
                  $ref: '#/components/schemas/CommitmentTerm'
                cpuModel:
                  readOnly: true
                  type: string
                cpuSpeedMhz:
                  format: int32
                  readOnly: true
                  type: integer
                createBy:
                  readOnly: true
                  type: string
                createTime:
                  format: date-time
                  readOnly: true
                  type: string
                customSshKeys:
                  items:
                    type: string
                  type: array
                dataCenterId:
                  type: string
                gpuModelId:
                  readOnly: true
                  type: string
                id:
                  type: string
                ipoibConfig:
                  $ref: '#/components/schemas/ClusterIPOIBConfig'
                machineCount:
                  format: int32
                  type: integer
                machinePriceHr:
                  $ref: '#/components/schemas/Decimal'
                machineTypeId:
                  type: string
                machines:
                  items:
                    $ref: '#/components/schemas/ClusterMachine'
                  readOnly: true
                  type: array
                networkType:
                  $ref: '#/components/schemas/NetworkType'
                sshKeySource:
                  $ref: '#/components/schemas/SshKeySource'
                startScript:
                  type: string
                state:
                  $ref: '#/components/schemas/Cluster.State'
                totalCpuCores:
                  format: int32
                  readOnly: true
                  type: integer
                totalDiskSizeGib:
                  format: int32
                  readOnly: true
                  type: integer
                totalGpus:
                  format: int32
                  readOnly: true
                  type: integer
                totalMachinePriceHr:
                  $ref: '#/components/schemas/Decimal'
                totalMemoryGib:
                  format: int32
                  readOnly: true
                  type: integer
                totalPriceHr:
                  $ref: '#/components/schemas/Decimal'
              required:
              - id
              - dataCenterId
              - machineTypeId
              - machineCount
              title: Create cluster params
              type: object
        description: Create cluster params
        required: true
        x-originalParamName: cluster
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
          description: An unexpected error response.
      summary: Create a cluster
      tags:
      - Clusters
  /v1/projects/{projectId}/clusters/{id}:
    delete:
      description: Deletes a cluster. All data on machines within the cluster will be lost.
      operationId: DeleteCluster
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
          description: An unexpected error response.
      summary: Delete a cluster
      tags:
      - Clusters
    get:
      description: Gets the details of a cluster.
      operationId: GetCluster
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
          description: An unexpected error response.
      summary: Get a cluster
      tags:
      - Clusters
    patch:
      description: Updates a cluster.
      operationId: UpdateCluster
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                architecture:
                  readOnly: true
                  type: string
                commitmentEndTime:
                  format: date-time
                  readOnly: true
                  type: string
                commitmentTerm:
                  $ref: '#/components/schemas/CommitmentTerm'
                cpuModel:
                  readOnly: true
                  type: string
                cpuSpeedMhz:
                  format: int32
                  readOnly: true
                  type: integer
                createBy:
                  readOnly: true
                  type: string
                createTime:
                  format: date-time
                  readOnly: true
                  type: string
                customSshKeys:
                  items:
                    type: string
                  type: array
                dataCenterId:
                  type: string
                gpuModelId:
                  readOnly: true
                  type: string
                ipoibConfig:
                  $ref: '#/components/schemas/ClusterIPOIBConfig'
                machineCount:
                  format: int32
                  type: integer
                machinePriceHr:
                  $ref: '#/components/schemas/Decimal'
                machineTypeId:
                  type: string
                machines:
                  items:
                    $ref: '#/components/schemas/ClusterMachine'
                  readOnly: true
                  type: array
                networkType:
                  $ref: '#/components/schemas/NetworkType'
                sshKeySource:
                  $ref: '#/components/schemas/SshKeySource'
                startScript:
                  type: string
                state:
                  $ref: '#/components/schemas/Cluster.State'
                totalCpuCores:
                  format: int32
                  readOnly: true
                  type: integer
                totalDiskSizeGib:
                  format: int32
                  readOnly: true
                  type: integer
                totalGpus:
                  format: int32
                  readOnly: true
                  type: integer
                totalMachinePriceHr:
                  $ref: '#/components/schemas/Decimal'
                totalMemoryGib:
                  format: int32
                  readOnly: true
                  type: integer
                totalPriceHr:
                  $ref: '#/components/schemas/Decimal'
              required:
              - dataCenterId
              - machineTypeId
              - machineCount
              title: Update cluster params
              type: object
        description: Update cluster params
        required: true
        x-originalParamName: cluster
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
          description: An unexpected error response.
      summary: Update a cluster
      tags:
      - Clusters
components:
  schemas:
    ClusterIPOIBConfig:
      properties:
        hostBits:
          description: The number of bits following the port portion that are used for the host portion of the address (e.g. 16). The maximum number of hosts will be 2 raised to the power of this value, minus 2 (for network and broadcast addresses).
          format: int32
          type: integer
        networkPrefix:
          description: The network prefix in CIDR format (e.g. "172.24.0.0/13").
          type: string
        portBits:
          description: The number of bits following the network prefix that are used for the port portion of the address (e.g. 3). The maximum number of ports per host will be 2 raised to the power of this value.
          format: int32
          type: integer
      required:
      - networkPrefix
      - portBits
      - hostBits
      type: object
    ListClustersResponse:
      properties:
        clusters:
          items:
            $ref: '#/components/schemas/Cluster'
          type: array
        pageNumber:
          format: int32
          type: integer
        pageSize:
          format: int32
          type: integer
        totalCount:
          format: int32
          type: integer
      required:
      - totalCount
      - pageNumber
      - pageSize
      type: object
    ListClusterMachineTypesResponse:
      properties:
        machineTypes:
          items:
            $ref: '#/components/schemas/MachineType'
          type: array
        pageNumber:
          format: int32
          type: integer
        pageSize:
          format: int32
          type: integer
        totalCount:
          format: int32
          type: integer
      required:
      - totalCount
      - pageNumber
      - pageSize
      type: object
    MachineTypePrice:
      properties:
        commitmentTerm:
          $ref: '#/components/schemas/CommitmentTerm'
        dataCenterId:
          type: string
        ipv4PriceHr:
          $ref: '#/components/schemas/Decimal'
        machineTypeId:
          type: string
        priceHr:
          $ref: '#/components/schemas/Decimal'
      required:
      - dataCenterId
      - machineTypeId
      - commitmentTerm
      - priceHr
      - ipv4PriceHr
      type: object
    Decimal:
      description: 'A representation of a decimal value, such as 2.5. Clients may convert values

        into language-native decimal formats, such as Java''s [BigDecimal][] or

        Python''s [decimal.Decimal][].


        [BigDecimal]:

        https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/math/BigDecimal.html

        [decimal.Decimal]: https://docs.python.org/3/library/decimal.html'
      properties:
        value:
          description: "The decimal value, as a string.\n\nThe string representation consists of an optional sign, `+` (`U+002B`)\nor `-` (`U+002D`), followed by a sequence of zero or more decimal digits\n(\"the integer\"), optionally followed by a fraction, optionally followed\nby an exponent.\n\nThe fraction consists of a decimal point followed by zero or more decimal\ndigits. The string must contain at least one digit in either the integer\nor the fraction. The number formed by the sign, the integer and the\nfraction is referred to as the significand.\n\nThe exponent consists of the character `e` (`U+0065`) or `E` (`U+0045`)\nfollowed by one or more decimal digits.\n\nServices **should** normalize decimal values before storing them by:\n\n  - Removing an explicitly-provided `+` sign (`+2.5` -> `2.5`).\n  - Replacing a zero-length integer value with `0` (`.5` -> `0.5`).\n  - Coercing the exponent character to lower-case (`2.5E8` -> `2.5e8`).\n  - Removing an explicitly-provided zero exponent (`2.5e0` -> `2.5`).\n\nServices **may** perform additional normalization based on its own needs\nand the internal decimal implementation selected, such as shifting the\ndecimal point and exponent value together (example: `2.5e-1` <-> `0.25`).\nAdditionally, services **may** preserve trailing zeroes in the fraction\nto indicate increased precision, but are not required to do so.\n\nNote that only the `.` character is supported to divide the integer\nand the fraction; `,` **should not** be supported regardless of locale.\nAdditionally, thousand separators **should not** be supported. If a\nservice does support them, values **must** be normalized.\n\nThe ENBF grammar is:\n\n    DecimalString =\n      [Sign] Significand [Exponent];\n\n    Sign = '+' | '-';\n\n    Significand =\n      Digits ['.'] [Digits] | [Digits] '.' Digits;\n\n    Exponent = ('e' | 'E') [Sign] Digits;\n\n    Digits = { '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' };\n\nServices **should** clearly document the range of supported values, the\nmaximum supported precision (total number of digits), and, if applicable,\nthe scale (number of digits after the decimal point), as well as how it\nbehaves when receiving out-of-bounds values.\n\nServices **may** choose to accept values passed as input even when the\nvalue has a higher precision or scale than the service supports, and\n**should** round the value to fit the supported scale. Alternatively, the\nservice **may** error with `400 Bad Request` (`INVALID_ARGUMENT` in gRPC)\nif precision would be lost.\n\nServices **should** error with `400 Bad Request` (`INVALID_ARGUMENT` in\ngRPC) if the service receives a value outside of the supported range."
          type: string
      type: object
    SshKeySource:
      default: SSH_KEY_SOURCE_UNKNOWN
      enum:
      - SSH_KEY_SOURCE_UNKNOWN
      - SSH_KEY_SOURCE_PROJECT
      - SSH_KEY_SOURCE_USER
      - SSH_KEY_SOURCE_NONE
      type: string
    CommitmentTerm:
      default: COMMITMENT_TERM_NONE
      enum:
      - COMMITMENT_TERM_NONE
      - COMMITMENT_TERM_1_MONTH
      - COMMITMENT_TERM_3_MONTHS
      - COMMITMENT_TERM_6_MONTHS
      - COMMITMENT_TERM_12_MONTHS
      - COMMITMENT_TERM_24_MONTHS
      - COMMITMENT_TERM_36_MONTHS
      - COMMITMENT_TERM_60_MONTHS
      type: string
    Status:
      properties:
        code:
          format: int32
          type: integer
        details:
          items:
            $ref: '#/components/schemas/Any'
          type: array
        message:
          type: string
      type: object
    NetworkType:
      default: NETWORK_TYPE_UNSPECIFIED
      enum:
      - NETWORK_TYPE_UNSPECIFIED
      - ETHERNET
      - INFINIBAND
      type: string
    Cluster:
      properties:
        architecture:
          readOnly: true
          type: string
        commitmentEndTime:
          format: date-time
          readOnly: true
          type: string
        commitmentTerm:
          $ref: '#/components/schemas/CommitmentTerm'
        cpuModel:
          readOnly: true
          type: string
        cpuSpeedMhz:
          format: int32
          readOnly: true
          type: integer
        createBy:
          readOnly: true
          type: string
        createTime:
          format: date-time
          readOnly: true
          type: string
        customSshKeys:
          items:
            type: string
          type: array
        dataCenterId:
          type: string
        gpuModelId:
          readOnly: true
          type: string
        id:
          type: string
        ipoibConfig:
          $ref: '#/components/schemas/ClusterIPOIBConfig'
        machineCount:
          format: int32
          type: integer
        machinePriceHr:
          $ref: '#/components/schemas/Decimal'
        machineTypeId:
          type: string
        machines:
          items:
            $ref: '#/components/schemas/ClusterMachine'
          readOnly: true
          type: array
        networkType:
          $ref: '#/components/schemas/NetworkType'
        projectId:
          type: string
        sshKeySource:
          $ref: '#/components/schemas/SshKeySource'
        startScript:
          type: string
        state:
          $ref: '#/components/schemas/Cluster.State'
        totalCpuCores:
          format: int32
          readOnly: true
          type: integer
        totalDiskSizeGib:
          format: int32
          readOnly: true
          type: integer
        totalGpus:
          format: int32
          readOnly: true
          type: integer
        totalMachinePriceHr:
          $ref: '#/components/schemas/Decimal'
        totalMemoryGib:
          format: int32
          readOnly: true
          type: integer
        totalPriceHr:
          $ref: '#/components/schemas/Decimal'
      required:
      - projectId
      - id
      - dataCenterId
      - machineTypeId
      - machineCount
      type: object
    GetClusterMachineTypeResponse:
      properties:
        machineType:
          $ref: '#/components/schemas/MachineType'
      required:
      - machineType
      type: object
    MachinePowerState:
      default: MACHINE_POWER_STATE_UNSPECIFIED
      enum:
      - MACHINE_POWER_STATE_UNSPECIFIED
      - 'ON'
      - 'OFF'
      - POWERING_ON
      - POWERING_OFF
      - REBOOTING
      type: string
    ClusterMachine:
      properties:
        architecture:
          readOnly: true
          type: string
        cpuCores:
          format: int32
          readOnly: true
          type: integer
        cpuModel:
          readOnly: true
          type: string
        cpuSpeedMhz:
          format: int32
          readOnly: true
          type: integer
        createBy:
          readOnly: true
          type: string
        createTime:
          format: date-time
          readOnly: true
          type: string
        dataCenterId:
          readOnly: true
          type: string
        diskSizeGib:
          format: int32
          readOnly: true
          type: integer
        disks:
          format: int32
          readOnly: true
          type: integer
        externalIpAddress:
          readOnly: true
          type: string
        gpuModelId:
          readOnly: true
          type: string
        gpus:
          format: int32
          readOnly: true
          type: integer
        id:
          readOnly: true
          type: string
        internalIpAddress:
          readOnly: true
          type: string
        machineTypeId:
          readOnly: true
          type: string
        memoryGib:
          format: int32
          readOnly: true
          type: integer
        powerState:
          $ref: '#/components/schemas/MachinePowerState'
        priceHr:
          $ref: '#/components/schemas/Decimal'
        projectId:
          readOnly: true
          type: string
        state:
          $ref: '#/components/schemas/ClusterMachine.State'
        volumeIds:
          items:
            type: string
          type: array
      type: object
    MachineType:
      properties:
        architecture:
          type: string
        cpuCores:
          format: int32
          type: integer
        cpuModel:
          type: string
        cpuSpeedMhz:
          format: int32
          type: integer
        dataCenterId:
          description: The data center in which this machine type is available.
          type: string
        diskSizeGib:
          format: int32
          type: integer
        disks:
          format: int32
          type: integer
        gpuModelId:
          type: string
        gpus:
          format: int32
          type: integer
        id:
          description: The unique identifier for this machine type within the data center.
          type: string
        machinesFree:
          description: The number of machines available for deployment.
          format: int32
          readOnly: true
          type: integer
        memoryGib:
          format: int32
          type: integer
        networkType:
          $ref: '#/components/schemas/NetworkType'
        prices:
          description: The list of prices available for this machine type for varying commitment terms.
          items:
            $ref: '#/components/schemas/MachineTypePrice'
          readOnly: true
          type: array
      required:
      - dataCenterId
      - id
      - architecture
      - cpuCores
      - cpuSpeedMhz
      - cpuModel
      - memoryGib
      - disks
      - diskSizeGib
      - gpus
      - networkType
      type: object
    Cluster.State:
      default: STATE_UNSPECIFIED
      enum:
      - STATE_UNSPECIFIED
      - CREATING
      - ACTIVE
      - UPDATING
      - DELETING
      - FAILED
      type: string
    Any:
      additionalProperties: {}
      properties:
        '@type':
          type: string
      type: object
    ClusterMachine.State:
      default: STATE_UNSPECIFIED
      enum:
      - STATE_UNSPECIFIED
      - CREATING
      - ACTIVE
      - DELETING
      - FAILED
      type: string
  securitySchemes:
    bearerAuth:
      description: API key authentication. API keys should be passed using the format `Bearer API_KEY`.
      in: header
      name: Authorization
      type: apiKey
x-provenance:
  method: harvested
  publisher: CUDO Compute
  source: https://docs.cudocompute.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)