swagger.yaml

---
swagger: "2.0"
consumes:
- application/json
info:
  description: |
    This API specification describes a service for attaching, mounting and preparing container images and manipulating those containers.

    In general, higher level objects can either reference lower level objects (e.g. a mount referencing an attachment point) by a reference ID, 
    or, they can contain the full specification of those lower objects.

    If an object references another by ID, deletion of that object does not effect the underlying object.
    
    If an object defines a lower level object, that lower level object will automatically be deleted on deletion of the higher level object.

    For instance, if a container contains all of the defintions for all mount points and attachments, deletion of the container will automatically unmount
    and detach those lower objects.
  title: Image API
  version: 0.2.0
produces:
- application/json
schemes:
- http
- https
basePath: /imageapi/v1

definitions:
  id:
    description: |
      An ID is a unique numeric ID that references an object.  
      IDs are not necessarily unique across object types.
      IDs are generall readOnly and generated internally.
    type: integer
    format: int64

  name:
    description: |
      A name is a unique, user-provided identifier for an object.

      A name must consist of numbers, letters, and the symbols in the set { `.`, `-`, `_`}.
    type: string
    pattern: "^[A-Za-z0-1.\\-_]*$"

  rbd_options:
    type: object
    properties:
      fsid:
        type: string
      ip:
        type: string
        format: ipv4
        pattern: '^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$'
      share:
        type: boolean
      noshare:
        type: boolean
      crc:
        type: boolean
      nocrc:
        type: boolean
      ceph_requires_signatures:
        type: boolean
      noceph_requires_signatures:
        type: boolean
      tcp_nodelay:
        type: boolean
      notcp_nodelay:
        type: boolean
      cephx_sign_messages:
        type: boolean
      nocephx_sign_messages:
        type: boolean
      mount_timeout:
        type: integer
      osdkeepalive:
        type: integer
      osd_idle_ttl:
        type: integer
      force:
        type: boolean
      rw:
        type: boolean
      ro:
        type: boolean
      queue_depth:
        type: integer
      lock_on_read:
        type: boolean
      exclusive:
        type: boolean
      lock_timeout:
        type: integer
        format: int64
      notrim:
        type: boolean
      abort_on_full:
        type: boolean
      alloc_size:
        type: integer
      name:
        type: string
      secret:
        type: string
      namespace:
        type: string

  attach_rbd:
    description: |
      attach_rbd describes an RBD map.  To successfully map, at least one monitor, pool and image must be specified.
      Additionally, you will need options.name and options.secret specified.
    type: object
    required:
      - monitors
      - pool
      - image
    properties:
      device_id:
        description: The dev_id is the device ID in the rbd subsystem.
        type: integer
        format: int64
        readOnly: true
      #external 
      monitors:
        type: array
        items:
          type: string
          format: ipv4
          pattern: '^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$'
      pool:
        type: string
        minLength: 1
      image:
        type: string
        minLength: 1
      snapshot:
        type: string
      options:
        $ref: "#/definitions/rbd_options"
  
  attach_loopback:
    description: |
      `attach_loopback` describes a loopback device based on an available file.
      The file can live either on `/` ("root") or a mount, as specified by base.
      Path specifies the path relative to the base.
    type: object
    required:
      - path
      - base
    properties:
      path:
        type: string
        description: A unix-formatted filesystem path with `/` relative to the respective base.
      base:
        description:  |
          base determines the relative root for the path.  There are two options:
          `root` means to use the current root (`/`) as the base path.
          `mount` means to use a mount as the base path. If this is specified, `mount` must be specified as well.
        type: string
        enum: [ "root", "mount" ]
      readPartitions:
        description: |
          Should the partition table on the looback device be read?
          Addressing sub-partitions is not yet supported.
        type: boolean
        default: false
      mount:
        $ref: "#/definitions/mount"

  attach_local:
    description: |
      `attach_local` describes a block device that is locally present.
      This can be used to get a reference to a local disk, for instance.

      Local only supports finding device files on the local (root) system.
      It only takes one parameter: the path to the device file.
    type: object
    required:
      - path
    properties:
      path:
        type: string
        description: A unix-formatted filesystem path pointing to a block device file.
  
  attach_iscsi:
    description: |
      `attach_iscsi` describes an block device available as an iSCSI attachment.
      Currently, only AuthType=None is supported.
      A target are required, and should both be in IQN format.
      Host is required and can be an IP or hostname.
      If lun is not specified, it will default to lun0.
    type: object
    required:
      - initiator
      - target
      - host
    properties:
      initiator:
        type: string
        description: iSCSI initiator IQN
      target:
        type: string
        description: IQN of the iSCSI target
      lun:
        type: integer
        format: int64
        description: iSCSI lun on the target to select
        default: 0
      host:
        type: string
        description: IP or hostname of target host
      port:
        type: integer
        format: int64
        default: 3260
        description: Port where the target is listening (default 3260)
      max_comands:
        type: integer
        format: int64
        default: 128
        description: Max oustanding iSCSI commands
      queue_depth:
        type: integer
        format: int64
        default: 16
        description: Max oustanding IOs
      scheduler:
        type: string
        default: "mq-deadline"
        description: Block device scheduler

  attach:
    description: |
      Generically address attachments.  Attachments are objects that ultimately provide a block device file.    
    properties:
      id:
        $ref: "#/definitions/id"
        readOnly: true
      kind:
        type: string
        enum: [ "iscsi", "local", "loopback", "rbd" ]
        description: |
          Kind specifies the kind of attachment.  Each kind has corresponding kind-specific options.

          Currently known kinds:

          iscsi - attach an iscsi lun
          local - create an attachment reference to an existing block device (specifying a non-block device will fail)
          loopback - create a loopback device referencing a file in a mount
          rbd - attach a Ceph/RBD object

          All kinds may or may not be fully supported by the implementation.
      device_file:
        description: The device_file is the path to the system device file.
        type: string
        readOnly: true
      refs:
        type: integer
        format: int64
        readOnly: true
      iscsi:
        $ref: "#/definitions/attach_iscsi"
      local:
        $ref: "#/definitions/attach_local"
      loopback:
        $ref: "#/definitions/attach_loopback"
      rbd:
        $ref: "#/definitions/attach_rbd"

  mount_attach:
    description: |
      `mount_attach` describes an attach mount.  This must have at least attach ID associated with it, 
      and a provided filesystem type.
      
      Either `attach_id` or `attach` must be specified.  If both are specified, `attach` will be ignored.

      If `attach` is specified and `attach_id` is omitted, the specified attach will first be attached, and will be
      detached on deletion.
    required:
      - fs_type
      - attach
    properties:
      attach:
        $ref: "#/definitions/attach"
      fs_type:
        type: string
      mount_options:
        description: these mount options will be passed to the mount syscall. Supported options depend on filesystem type.
        type: array
        items:
          type: string

  mount_overlay:
    description: |
      `mount_overlay` describes an Overlayfs mount.  All mount points must be RBD ID's.
      At very least, `lower` must be specified.  If `upper` length is zero, no `upper`
      mounts will be used.  `workdir` will be assigned automatically.

      If the mounts specified in `lower` are specifications and not ID references, they
      will be recursively mounted/attached.

      Overlay mounts are identified by their uppermost `lower` ID.
    type: object
    required:
      - lower
    properties:
      # internal
      workdir:
        type: string
        readOnly: true
      upperdir:
        description: currently, upperdir is always a directory in mountDir
        type: string
        readOnly: true
      # external
      lower:
        description: This is an array of mount specifications to be used (in order) as lower mounts for the overlay.
        type: array
        items:
          $ref: "#/definitions/mount"

  mount_bind:
    description: |
      `mount_bind` describes a local bind mount. 
      Bind mounts can be relative to another mount, or to /, allowing a way to access local data.
    type: object
    required:
      - path
      - base
    properties:
      path:
        type: string
        description: A unix-formatted filesystem path with `/` relative to the respective base.
      base:
        description:  |
          base determines the relative root for the path.  There are two options:
          `root` means to use the current root (`/`) as the base path.
          `mount` means to use a mount as the base path. If this is specified, `mount` must be specified as well.
        type: string
        enum: [ "root", "mount" ]
      recursive:
        description: perform a recursive bind mount
        type: boolean
        default: false
      ro:
        description: mount read-only
        type: boolean
        default: false
      mount:
        $ref: "#/definitions/mount"
          
  mount_nfs:
    description: |
      `mount_nfs` describes an NFS mount.
    type: object
    required:
      - host
      - path
    properties:
      host:
        type: string
        description: IP or hostname for remote NFS mount
      path:
        type: string
        description: The remote path for the NFS mount
      ro:
        description: mount read-only
        type: boolean
        default: false
      version:
        description: NFS version
        type: string
        default: "4.2"
      options:
        description: |
          Options as specified in nfs(5).  General mount options won't work here.
          addr= and clientaddr= will be filled out automatically based on host.
          vers= will be filled by version
        type: array
        items:
          type: string

  mount:
    description: |
      Generically address mounts by kind and ID or definition
      Either an `mount_id` or a mount definition must be supplied.
      If both are supplied, the mount definition will be ignored.
      If `mount_id` is specified, then the kind/id will be used to reference that mount.
      If no `mount_id` is supplied a defition of type `kind` must be present.
    type: object
    properties:
      id:
        $ref: "#/definitions/id"
      kind:
        type: string
        enum: [ "attach", "bind", "nfs", "overlay", "uri" ]
        description: |
          Kind specifies the kind of mount.  Each kind has corresponding kind-specific options.

          Currently known kinds:

          attach - mount a device specified by an attachment.
          bind - bind mount a local directory
          nfs - mount an NFS filesystem
          overlay - overlay mount over an existing mount
          uri - download a file from a URI and extract it into a ramdisk mount

          All kinds may or may not be fully supported by the implementation.
      mountpoint:
        type: string
        readOnly: true
      refs:
        type: integer
        format: int64
        readOnly: true
      attach:
        $ref: "#/definitions/mount_attach"
      bind:
        $ref: "#/definitions/mount_bind"
      nfs:
        $ref: "#/definitions/mount_nfs"
      overlay:
        $ref: "#/definitions/mount_overlay"


  container_namespace:
    description: Linux namespace
    type: string
    enum: [ "cgroup", "ipc", "net", "mnt", "pid", "time", "user", "uts" ]

  container_state:
    description: Valid container states
    type: string
    # stolen straight from docker (even if we don't use them all)
    enum: [ "created",  "running", "stopping", "exited", "dead" ]

  container:
    description: |
      The `container` option describes a minimally namespaced container.

      A container is identified by a service-provided unique numeric `pid`.

      Optionally, a container can be provided with a `name`.  The name must
      be unique.  Containers can be referenced by `name` if provided.
    type: object
    required:
      - mount
      - command
    properties:
      # internal
      id:
        $ref: "#/definitions/id"
      logfile:
        type: string
        readOnly: true
      # external
      name:
        description: name is an optional identifier for the container.  Name must be unique.
        $ref: "#/definitions/name"
      mount:
        $ref: "#/definitions/mount"
      command:
        type: string
      systemd:
        type: boolean
        description: >
          When `systemd` is set to `true`, we will assume that this container will run `systemd`,
          and perform the necessary magic dance to make systemd run inside of the container.
          The default is `false`.
      state:
        description: >
          When read, this contains the current container state.
          On creation, this requests the initial state (valid options: `created` or `running`).
          The default is `created`.
        $ref: "#/definitions/container_state"
      namespaces:
        description: |
          A list of Linux namespaces to use.

          Note: This is currently unused.  All containers currently get `mnt` and `pid`.
                It's here as a placeholder for future use.
        type: array
        items:
          $ref: "#/definitions/container_namespace"
      refs:
        type: integer
        format: int64
        readOnly: true
  
  error:
    type: object
    required:
      - message
    properties:
      code:
        type: integer
        format: int64
      message:
        type: string

  
paths:

  /attach:
    get:
      description: List attachments
      parameters:
        - in: query
          name: id
          type: integer
          format: int64
          required: false
          description: ID of a single attachment to query.
        - in: query
          name: kind
          type: string
          enum: [ "iscsi", "local", "loopback", "rbd" ]
          required: false
          description: Kind of attachments to query.
      tags:
        - attachments
      operationId: list_attachments
      responses:
        200:
          description: list all attachments
          schema:
            type: array
            items:
              $ref: "#/definitions/attach"
        default:
          description: error
          schema:
            $ref: "#/definitions/error"
    post:
      description: Create a new attachment based on attach specification
      tags:
        - attachments
      operationId: attach
      parameters:
        - name: attach
          in: body
          required: true
          schema:
            $ref: "#/definitions/attach"
      responses:
        201:
          description: attach succeed
          schema:
            $ref: "#/definitions/attach"
        default:
          description: error
          schema:
            $ref: "#/definitions/error"
    delete:
      description: Detach a specified attachment.
      tags:
        - attachments
      parameters:
        - name: id
          in: query
          required: true
          type: integer
          format: int64
        - in: query
          name: force
          type: boolean
          required: false
          default: false
          description: Force deletion
      responses:
        200:
          description: Detach succeed
          schema:
            $ref: "#/definitions/attach"
        default:
          description: Detach failed
          schema:
            $ref: "#/definitions/error"

  /mount:
    get:
      parameters:
        - in: query
          name: id
          type: integer
          format: int64
          required: false
          description: ID of a single mount to query.
        - in: query
          name: kind
          type: string
          enum: [ "attach", "bind", "nfs", "overlay", "uri" ]
          required: false
          description: Kind of mounts to query.
      description: List mounts
      tags:
        - mounts
      operationId: list_mounts
      responses:
        200:
          description: list all mounts
          schema:
            type: array
            items:
              $ref: "#/definitions/mount"
        default:
          description: error
          schema:
            $ref: "#/definitions/error"
    post:
      description: Create a new mount by mount specification.
      tags:
        - mounts
      operationId: mount
      parameters:
        - name: mount
          in: body
          required: true
          schema:
            $ref: "#/definitions/mount"
      responses:
        201:
          description: mount succeed
          schema:
            $ref: "#/definitions/mount"
        default:
          description: error
          schema:
            $ref: "#/definitions/error"
    delete:
      description: Unmount a specified mount.  Note that mount reference IDs must be specified.
      tags:
        - mounts
      parameters:
        - name: id
          in: query
          required: true
          type: integer
          format: int64
          description: ID of mount to delete
        - in: query
          name: force
          type: boolean
          required: false
          default: false
          description: Force deletion
      responses:
        200:
          description: Unmount succeeded
          schema:
            $ref: "#/definitions/mount"
        default:
          description: Unmount failed
          schema:
            $ref: "#/definitions/error"
  
  /container:
    get:
      parameters:
        - in: query
          name: id
          type: integer
          format: int64
          description: Query containers by ID
          required: false
        - in: query
          name: name
          type: string
          required: false
          description: Query containers by name
        - in: query
          name: state
          type: string
          enum: [ "created",  "running", "stopping", "exited", "dead" ]
          required: false
          description: Query containers by state
      tags:
        - containers
      description: Get a list of containers
      operationId: list_containers
      responses:
        200:
          description: List of containers
          schema:
            type: array
            items:
              $ref: "#/definitions/container"
        default:
          description: error
          schema:
            $ref: "#/definitions/error"

    post:
      tags:
        - containers
      description: Create a container
      operationId: create_container
      parameters:
        - name: container
          in: body
          required: true
          schema:
            $ref: "#/definitions/container"
      responses:
        201:
          description: Container creation succeed
          schema:
            $ref: "#/definitions/container"
        default:
          description: error
          schema:
            $ref: "#/definitions/error"
    delete:
      parameters:
        - in: query
          name: id
          type: integer
          format: int64
          description: Delete by ID
          required: false
        - in: query
          name: name
          type: string
          required: false
          description: Delete by Name
        - in: query
          name: force
          type: boolean
          required: false
          default: false
          description: Force deletion
      tags:
        - containers
      description: |
        Delete a container defition.  
        Either `id` or `name` query parameter must be specified.
      operationId: delete_container
      responses:
        200:
          description: Container deleted
          schema:
            $ref: "#/definitions/container"
        default:
          description: error
          schema:
            $ref: "#/definitions/error"
    patch:
      tags:
        - containers
      parameters:
        - in: query
          name: state
          type: string
          enum: [ "running", "exited", "paused" ]
          required: true
          description: Desired container state
        - in: query
          name: id
          type: integer
          format: int64
          required: false
          description: ID of container
        - in: query
          name: name
          type: string
          required: false
          description: Name of container
      description: |
        Request a (valid) state for a container. 
        Valid states to request include: `running`, `exited`, `paused` (paused is not yet implemented)

        Either a valid Name or ID must be passed as a query parameter, along with a valid state parameter.
      operationId: set_container_state
      responses:
        200:
          description: Container state changed
          schema:
            $ref: "#/definitions/container"
        default:
          description: error
          schema:
            $ref: "#/definitions/error"