openapi: 3.0.1
info:
  title: ESXi AutoInstaller
  description: 'This tools helps you install multiple ESXi hosts automatically.'
  license:
    name: CISCO SAMPLE CODE LICENSE
    url: https://github.com/CiscoDevNet/esxi-auto-installer/blob/main/LICENSE
  version: 1.0.0
externalDocs:
  description: GitHub repository
  url: https://github.com/CiscoDevNet/esxi-auto-installer
servers:
- url: /api/v1
tags:
- name: jobs
- name: logs
- name: iso
paths:
  /jobs:
    get:
      tags:
      - jobs
      summary: Returns a list of jobs.
      description: Returns a list of all the jobs and their status.
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Jobs'
    post:
      tags:
      - jobs
      summary: 'Create a new ESXi Installation job.'
      description: |
        Take installation details as json payload and create installation job per each host in 'hosts' list.<br>
        Mandatory (minimal) input data parameters:
          - iso_image
          - root_pwd
          - host_netmask
          - host_gateway
          - installmethod
          - hosts list
          - - if installmethod is "pxeboot" at least one entry with {hostname, host_ip, macaddr}
          - - if installmethod is "cimc" one entry with {hostname, host_ip, cimc_ip}
        
        In addition, if installmethod is set to "cimc" then "cimc_pwd" is required.
        cimc_usr defaults to "admin" if not supplied.

        Refer to schema definition for all parameters and default values.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobsNew'
      responses:
        '200':
          description: Successful operation - return list of job IDs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobIDs'
        '400':
          description: Failed operation, check returned error message for details
          content:
            application/json:
              schema:
                type: string
                example: "Incorrect key when trying to create a new job. Expected key: 'host_ip'"
  /jobs/{jobID}:
    get:
      tags:
      - jobs
      summary: Returns details for a specific job.
      parameters:
      - name: jobID
        in: path
        description: ID of job.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
    put:
      tags:
      - jobs
      summary: Update a job entry.
      description: |
        Updates the status of a particular job.<br>
        ```
         0: Ready to deploy
        10: Connecting to CIMC
        11: Mounting installation ISO
        15: Server is booting
        16: Installer is running
        17: Running final reboot
        18: Running cleanup tasks
        20: Finished
        25: Cancelled
        30: Error
        31: Error: Failed to login to CIMC
        32: Error: Failed to mount installation ISO
        34: Error: ESXi Installed but SSH was not enabled
        35: Error: No response after final reboot
        ```
      parameters:
      - name: jobID
        in: path
        description: ID of job.
        required: true
        schema:
          type: string
      - name: state
        in: query
        description: New job status
        required: true
        style: form
        explode: true
        schema:
          type: integer
          maximum: 35
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
  /proxmox-jobs:
    post:
      tags:
      - jobs
      summary: 'Create a new Proxmox Installation job.'
      description: |
        Take installation details as json payload and create Proxmox installation job per each host in 'hosts' list.<br>
        Mandatory (minimal) input data parameters:
          - iso_image (Proxmox ISO)
          - root_pwd
          - host_gateway
          - cidr
          - installmethod (must be "cimc")
          - hosts list with {hostname, host_ip, cimc_ip}
          - cimc_pwd
        
        cimc_usr defaults to "admin" if not supplied.

        Refer to schema definition for all parameters and default values.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProxmoxJobsNew'
      responses:
        '200':
          description: Successful operation - return list of job IDs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobIDs'
        '400':
          description: Failed operation, check returned error message for details
          content:
            application/json:
              schema:
                type: string
                example: "Incorrect key when trying to create a new job. Expected key: 'host_ip'"
  /logs/{jobID}:
    get:
      tags:
      - logs
      summary: View job logs
      parameters:
      - name: jobID
        in: path
        description: ID of job.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
                example: |
                  2022-01-01 07:07:07 GMT [INFO] Processing job ID: 172.17.20.79_1631556521.7252097, server Prefix-01-Suffix

                  2022-01-01 07:07:07 GMT [INFO] Generating kickstart file for server
                  2022-01-01 07:07:07 GMT [INFO] Generated kickstart configuration:
  /isos:
    get:
      tags:
      - iso
      summary: Get a list of available ESXi Installation ISO(s)
      description: |
        Returns a list of available installation ISOs
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IsoList'
  /proxmox-isos:
    get:
      tags:
      - iso
      summary: Get a list of available Proxmox Installation ISO(s)
      description: |
        Returns a list of available Proxmox installation ISOs from proxmox-iso directory
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example: ["proxmox-ve_9.0-1.iso", "proxmox-ve_8.2-1.iso"]
components:
  schemas:
    Jobs:
      description: "jobID is a unique string, default: {cimc_ip}_{timestamp}, eg. '192.168.0.1_1628871425.1136827'"
      type: object
      properties:
        jobID:
          $ref: '#/components/schemas/JobStatus'
    ProxmoxJobsNew:
      description: Submit new Proxmox installation job
      type: object
      required:
      - iso_image
      - root_pwd
      - host_gateway
      - cidr
      - installmethod
      - hosts
      - cimc_pwd
      properties:
        iso_image:
          type: string
          example: proxmox-ve_9.0-1.iso
        root_pwd:
          type: string
          format: password
        installmethod:
          type: string
          enum: ['cimc']
          default: 'cimc'
        cimc_usr:
          type: string
          default: 'admin'
        cimc_pwd:
          type: string
          format: password
        host_gateway:
          type: string
          example: 192.168.1.1
        cidr:
          type: string
          example: "24"
          default: "24"
        dns:
          type: string
          example: 8.8.8.8
          default: 8.8.8.8
        keyboard:
          type: string
          example: en-us
          default: en-us
        country:
          type: string
          example: us
          default: us
        timezone:
          type: string
          example: UTC
          default: UTC
        mailto:
          type: string
          format: email
          example: admin@example.com
          default: admin@example.com
        filesystem:
          type: string
          enum: ['ext4', 'xfs', 'zfs', 'btrfs']
          default: ext4
        disk_list:
          type: string
          example: /dev/sda
          default: /dev/sda
        interface:
          type: string
          example: eno1
          default: eno1
        net_filter:
          type: string
          enum: ['ID_NET_NAME_SLOT', 'ID_NET_NAME_PATH', 'ID_NET_NAME_ONBOARD', 'ID_VENDOR_ID', 'ID_MODEL_ID', 'ID_PATH', 'ID_BUS', 'ID_PCI_CLASS_FROM_DATABASE', 'ID_PCI_SUBCLASS_FROM_DATABASE']
          default: ID_NET_NAME_SLOT
        custom_script:
          type: string
          description: Optional custom bash script to run on first boot.
          example: |
            echo "Custom setup script"
            # Your custom commands here
        hosts:
          type: array
          items:
            type: object
            required:
            - hostname
            - host_ip
            - cimc_ip
            properties:
              hostname:
                type: string
                example: pve-01.example.com
              host_ip:
                type: string
                example: 192.168.1.100
              cimc_ip:
                type: string
                example: 192.168.1.10
    JobsNew:
      description: Submit new job
      type: object
      required:
      - iso_image
      - root_pwd
      - host_netmask
      - host_gateway
      - installmethod
      - hosts
      properties:
        iso_image:
          type: string
          example: VMware-ESXi-7.0.0_U2-16324942-Custom
        root_pwd:
          type: string
          format: password
        vlan:
          type: integer
          format: int32
          maximum: 4096
          default: 0
        vmnic:
          type: integer
          format: int32
        firstdisk:
          type: string
          enum: ['firstdiskfound', 'firstdisk', 'diskpath']
          default: 'firstdiskfound'
        firstdisktype:
          type: string
          enum: ['local', 'remote', 'usb']
          default: 'local'
        diskpath:
          type: string
          example: naa.6d09466044143600247aee55ca2a6405
          # examples:
          #   scsi:
          #     value: naa.6d09466044143600247aee55ca2a6405
          #   other:
          #     value: /vmfs/devices/disks/mpx.vmhba1:C0:T0:L0
        enablessh:
          type: boolean
          default: True
        clearpart:
          type: boolean
          default: False
        installmethod:
          type: string
          enum: ['pxeboot', 'cimc']
        cimc_usr:
          type: string
          default: 'admin'
        cimc_pwd:
          type: string
          format: password
        host_netmask:
          type: string
          example: 255.255.255.0
          default: 255.255.255.0
        host_gateway:
          type: string
          example: 192.168.2.1
        dns1:
          type: string
          example: 208.67.222.222
        dns2:
          type: string
          example: 207.67.220.220
        static_routes:
          type: array
          items:
            type: object
            required:
            - subnet_ip
            - cidr
            - gateway
            properties:
              subnet_ip:
                type: string
                example: 172.16.10.0
              cidr:
                type: integer
                example: 24
                minimum: 3
                maximum: 32
              gateway:
                type: string
                example: 192.168.0.251
        hosts:
          type: array
          items:
            type: object
            required:
            - hostname
            - host_ip
            properties:
              hostname:
                type: string
                example: esxi-01-hostname
              host_ip:
                type: string
                example: 192.168.2.11
              macaddr:
                type: string
                example: "aa:bb:cc:dd:ee:ff"
              cimc_ip:
                type: string
                example: 192.168.0.111
    JobStatus:
      type: object
      properties:
        hostname:
          type: "string"
          example: Prefix-01-Suffix
        host_ip:
          type: "string"
          example: "192.168.2.11"
        cimcip:
          type: "string"
          example: "192.168.0.111"
        start_time:
          type: "string"
          example: "2022-01-01 07:07:07 GMT"
        finish_time:
          type: "string"
          example: "2022-01-01 08:08:08 GMT"
        status:
          type: "string"
          example: "Installer is running"
        macaddr:
          type: "string"
          example: ""
        netmask:
          type: "string"
          example: "255.255.255.0"
        gateway:
          type: "string"
          example: "192.168.0.1"
    JobIDs:
      description: "List of job IDs"
      type: array
      items:
        type: string
      example: [ "192.168.0.1_1628871425.1136827", "192.168.0.2_1633093658.6881468" ]                
    IsoList:
      description: "List of available ISO images"
      type: array
      items:
        type: string
      example: [ "VMware-ESXi-6.5.0_U3_Installer-13932383", "VMware-ESXi-7.0.0_U2_Installer-16324942" ]