openapi: 3.0.1
info:
  title: Cluster Blueprint API
  version: 2.0.0
  description: API for managing cluster blueprints and host configurations in the PCD
  contact:
    name: Platform9 Private Cloud Director Support
  x-gitbook-description-document:
    object: document
    data:
      schemaVersion: 8
    nodes:
      - object: block
        type: paragraph
        isVoid: false
        data: {}
        nodes:
          - object: text
            leaves:
              - object: leaf
                text: >-
                  API for managing cluster blueprints and host configurations in
                  the PCD
                marks: []
  x-gitbook-description-html: >-
    <p>API for managing cluster blueprints and host configurations in the
    PCD</p>
servers:
  - url: https://{host}/resmgr/v2
    description: PCD Resource Manager API v2
    variables:
      host:
        default: example.platform9.com
        description: The PCD controlplane hostname
        x-gitbook-description-html: <p>The PCD controlplane hostname</p>
    x-gitbook-description-html: <p>PCD Resource Manager API v2</p>
paths:
  /blueprint:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Blueprint"
          description: Successfully retrieved blueprints
          x-gitbook-description-html: <p>Successfully retrieved blueprints</p>
      summary: List all blueprints
      tags:
        - Blueprint
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Blueprint"
        required: true
      responses:
        "204":
          headers:
            Location:
              schema:
                type: string
              description: URL of the created resource
              x-gitbook-description-html: <p>URL of the created resource</p>
          $ref: "#/components/responses/NoContent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/Conflict"
      summary: Create a new blueprint
      tags:
        - Blueprint
  /blueprint/{clusterName}:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                default: "null"
                type: string
          description: Successfully retrieved blueprint
          x-gitbook-description-html: <p>Successfully retrieved blueprint</p>
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Retrieve a specific blueprint
      tags:
        - Blueprint
    put:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Blueprint"
        required: true
      responses:
        "204":
          $ref: "#/components/responses/NoContent"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Update an existing blueprint
      tags:
        - Blueprint
    delete:
      responses:
        "204":
          $ref: "#/components/responses/NoContent"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Delete a specific blueprint
      tags:
        - Blueprint
    parameters:
      - $ref: "#/components/parameters/clusterName"
  /hosts/{hostId}/roles/{roleName}:
    put:
      requestBody:
        description: Role specific settings; required only for persistent-storage role
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RoleUpdate"
        required: false
        x-gitbook-description-html: >-
          <p>Role specific settings; required only for persistent-storage
          role</p>
      responses:
        "200":
          description: Role assigned successfully
          x-gitbook-description-html: <p>Role assigned successfully</p>
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
      summary: Assign role to the host or update role settings
      tags:
        - Blueprint
    delete:
      responses:
        "204":
          description: Role unassigned successfully
          x-gitbook-description-html: <p>Role unassigned successfully</p>
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: Remove role from the host
      tags:
        - Blueprint
    parameters:
      - $ref: "#/components/parameters/hostId"
      - $ref: "#/components/parameters/roleName"
  /hostconfigs:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/HostConfigResponse"
          description: List of host configurations
          x-gitbook-description-html: <p>List of host configurations</p>
      summary: List host configurations
      tags:
        - Blueprint
    post:
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/HostConfigReq"
                - type: array
                  items:
                    $ref: "#/components/schemas/HostConfigReq"
        required: true
      responses:
        "200":
          headers:
            Location:
              schema:
                type: string
              description: URL of the created Resource
              x-gitbook-description-html: <p>URL of the created Resource</p>
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/HostConfigResponse"
          description: Host configuration(s) created
          x-gitbook-description-html: <p>Host configuration(s) created</p>
        "409":
          $ref: "#/components/responses/Conflict"
      summary: Create host configuration(s)
      tags:
        - Blueprint
  /hostconfigs/{hostConfigId}:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HostConfigResponse"
          description: Host configuration details
          x-gitbook-description-html: <p>Host configuration details</p>
      summary: Get host configuration
      tags:
        - Blueprint
    put:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HostConfigReq"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HostConfigResponse"
          description: Host configuration updated
          x-gitbook-description-html: <p>Host configuration updated</p>
      summary: Update host configuration
      tags:
        - Blueprint
    delete:
      responses:
        "204":
          description: Host configuration deleted
          x-gitbook-description-html: <p>Host configuration deleted</p>
      summary: Delete host configuration
      tags:
        - Blueprint
    parameters:
      - $ref: "#/components/parameters/hostConfigId"
  /hosts/{hostId}/hostconfig/{hostConfigId}:
    put:
      responses:
        "200":
          description: Host configuration assigned
          x-gitbook-description-html: <p>Host configuration assigned</p>
      summary: Assign host configuration to host
      tags:
        - Blueprint
    delete:
      responses:
        "204":
          description: Host configuration unassigned
          x-gitbook-description-html: <p>Host configuration unassigned</p>
      summary: Unassign host configuration from host
      tags:
        - Blueprint
    parameters:
      - $ref: "#/components/parameters/hostId"
      - $ref: "#/components/parameters/hostConfigId"
components:
  schemas:
    Blueprint:
      required:
        - name
      type: object
      properties:
        name:
          description: Cluster name
          type: string
          example: default
          x-gitbook-description-html: <p>Cluster name</p>
        networkingType:
          description: Defaults to OVN
          default: ovn
          enum:
            - ovn
            - ovs
          type: string
          x-gitbook-description-html: <p>Defaults to OVN</p>
        enableDistributedRouting:
          description: Enable Cluster Wide Distributed Network Routing
          default: true
          type: boolean
          x-gitbook-description-html: <p>Enable Cluster Wide Distributed Network Routing</p>
        dnsDomainName:
          description: DNS Domain Name
          type: string
          example: localdomain
          x-gitbook-description-html: <p>DNS Domain Name</p>
        virtualNetworking:
          $ref: "#/components/schemas/VirtualNetworking"
        vmHighAvailability:
          $ref: "#/components/schemas/VMHighAvailability"
        autoResourceRebalancing:
          $ref: "#/components/schemas/AutoResourceRebalancing"
        imageLibraryStorage:
          description: Library location on filesystem or Cinder volume type
          type: string
          example: /var/lib/images|lvm
          x-gitbook-description-html: <p>Library location on filesystem or Cinder volume type</p>
        vmStorage:
          description: Ephemeral Virtual Machine storage path
          type: string
          example: /var/lib/instances
          x-gitbook-description-html: <p>Ephemeral Virtual Machine storage path</p>
        storageBackends:
          $ref: "#/components/schemas/StorageBackends"
    VirtualNetworking:
      type: object
      properties:
        enabled:
          description: Enable Virtual Networking
          default: true
          type: boolean
          x-gitbook-description-html: <p>Enable Virtual Networking</p>
        underlayType:
          description: Underlay Technology
          default: vlan
          enum:
            - vlan
            - other
          type: string
          x-gitbook-description-html: <p>Underlay Technology</p>
        vnidRange:
          description: VLAN / VNID Range
          type: string
          example: "1:1000"
          x-gitbook-description-html: <p>VLAN / VNID Range</p>
    VMHighAvailability:
      type: object
      properties:
        enabled:
          description: >-
            Automatically detect host failure and recover VMs on other cluster
            hosts
          default: false
          type: boolean
          x-gitbook-description-html: >-
            <p>Automatically detect host failure and recover VMs on other
            cluster hosts</p>
    AutoResourceRebalancing:
      type: object
      properties:
        enabled:
          description: Automatically rebalance workloads across hosts in the cluster
          default: false
          type: boolean
          x-gitbook-description-html: <p>Automatically rebalance workloads across hosts in the cluster</p>
        rebalancingStrategy:
          description: >-
            Defaults to vm_workload_consolidation, other supported value is
            node_resource_consolidation
          default: vm_workload_consolidation
          enum:
            - vm_workload_consolidation
            - node_resource_consolidation
          type: string
          x-gitbook-description-html: >-
            <p>Defaults to vm_workload_consolidation, other supported value is
            node_resource_consolidation</p>
        rebalancingFrequencyMins:
          description: Rebalancing frequency
          default: 20
          maximum: 60
          minimum: 1
          type: integer
          x-gitbook-description-html: <p>Rebalancing frequency</p>
    StorageBackends:
      description: Persistent Storage Connectivity
      type: object
      additionalProperties:
        description: Volume backend name
        type: object
        additionalProperties:
          type: object
          properties:
            driver:
              description: Storage driver type
              enum:
                - NetApp
                - LVM
              type: string
              x-gitbook-description-html: <p>Storage driver type</p>
            config:
              description: Configuration distinct based on driver value
              type: object
              additionalProperties:
                description: Flexible configuration parameters based on storage driver
                type: string
                x-gitbook-description-html: >-
                  <p>Flexible configuration parameters based on storage
                  driver</p>
              x-gitbook-description-html: <p>Configuration distinct based on driver value</p>
        x-gitbook-description-html: <p>Volume backend name</p>
      x-gitbook-description-html: <p>Persistent Storage Connectivity</p>
    RoleUpdate:
      required:
        - backends
      type: object
      properties:
        backends:
          description: List of storage backends to associate with the role
          type: array
          items:
            description: List of backend names to associate with the role
            type: string
            x-gitbook-description-html: <p>List of backend names to associate with the role</p>
          x-gitbook-description-html: <p>List of storage backends to associate with the role</p>
    HostConfigReq:
      type: object
      properties:
        name:
          type: string
          example: Hypervisor-002
        mgmtInterface:
          type: string
          example: ens3
        vmConsoleInterface:
          type: string
          example: ens3
        hostLivenessInterface:
          type: string
          example: ens3
        tunnelingInterface:
          type: string
          example: ens3
        imagelibInterface:
          type: string
          example: eth0
        networkLabels:
          type: object
          example:
            physnet: ens3
        clusterName:
          type: string
          example: default
    HostConfigResponse:
      allOf:
        - $ref: "#/components/schemas/HostConfigReq"
        - type: object
          properties:
            id:
              format: uuid
              type: string
              example: 17e20369-0c70-4e33-b018-b361cad83cf5
  responses:
    Created:
      headers:
        Location:
          schema:
            type: string
          description: URL of the newly created resource
          x-gitbook-description-html: <p>URL of the newly created resource</p>
      description: Resource successfully created
      x-gitbook-description-html: <p>Resource successfully created</p>
    NoContent:
      description: Operation successful
      x-gitbook-description-html: <p>Operation successful</p>
    NotFound:
      description: Resource not found
      x-gitbook-description-html: <p>Resource not found</p>
    BadRequest:
      description: Invalid request
      x-gitbook-description-html: <p>Invalid request</p>
    Conflict:
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
      description: Operation cannot be performed in current state
      x-gitbook-description-html: <p>Operation cannot be performed in current state</p>
  parameters:
    clusterName:
      name: clusterName
      schema:
        type: string
      in: path
      required: true
    hostId:
      name: hostId
      schema:
        type: string
      in: path
      required: true
    hostConfigId:
      name: hostConfigId
      schema:
        type: string
      in: path
      required: true
    roleName:
      name: roleName
      schema:
        enum:
          - image-library
          - hypervisor
          - persistent-storage
      in: path
      required: true
  securitySchemes:
    TokenAuth:
      type: apiKey
      description: Keystone Authentication token
      name: x-auth-token
      in: header
      x-gitbook-description-html: <p>Keystone Authentication token</p>
security:
  - TokenAuth: []
