Driver API Specification
The following Humanitec Driver API Specification must be honored by all Drivers.
openapi: 3.0.0
info:
title: 'Humanitec Driver API'
version: '0.9.3'
description: |-
This spec describes the API for Humanitec Drivers.
paths:
/{GUResID}:
get:
summary: Returns the current state of the resource.
description: |+
This request does not apply any changes and only reports the current state of the resource.
parameters:
- $ref: '#/components/parameters/GloballyUniqueResourceId'
- $ref: '#/components/parameters/HumanitecDriverCookie'
responses:
'200':
description: |+
The resource has been provisioned and in the desired state.
content:
application/json:
schema:
$ref: '#/components/schemas/OutputData'
'202':
description: |+
The resource is being provisioned, updated, or deleted. The caller should repeat the request to determine the status.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncProgressHint'
'400':
description: |+
A general and unrecoverable error has occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: |+
The resource is not found. That usually means that the resource hasn't been provisioned yet, or has been deleted already.
put:
summary: Creates or updates a resource
description: |+
The request body contains a declarative definition of the resource. There should only be one instance of a resource for a specific `GUResID`.
parameters:
- $ref: '#/components/parameters/GloballyUniqueResourceId'
- $ref: '#/components/parameters/HumanitecDriverCookie'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InputData'
responses:
'200':
description: |+
The resource was successfully provisioned, or the resource was already provisioned and in the desired state.
headers:
Set-Humanitec-Driver-Cookie:
$ref: '#/components/headers/SetHumanitecDriverCookie'
content:
application/json:
schema:
$ref: '#/components/schemas/OutputData'
'202':
description: |+
The resource is being provisioned or updated. The caller should use 'GET' request to determine the status.
headers:
Set-Humanitec-Driver-Cookie:
$ref: '#/components/headers/SetHumanitecDriverCookie'
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncProgressHint'
'400':
description: |+
A general and unrecoverable error has occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: |+
Returned if resource creation/deletion is ongoing and cannot be cancelled AND the current request would result in a different configuration for the resource.
headers:
Set-Humanitec-Driver-Cookie:
$ref: '#/components/headers/SetHumanitecDriverCookie'
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncProgressHint'
delete:
summary: Deallocates a resource.
description: |+
The resource defined by `GUResID` is deallocated. Repeated calls to deallocate an already deallocated resource is explicitly not an error.
parameters:
- $ref: '#/components/parameters/GloballyUniqueResourceId'
- $ref: '#/components/parameters/HumanitecDriverCookie'
responses:
'204':
description: |+
The resource was successfully deallocated.
'202':
description: |+
The resource is being deallocated. The caller should repeat the request to determine the status.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncProgressHint'
'400':
description: |+
A general and unrecoverable error has occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
parameters:
GloballyUniqueResourceId:
name: GUResID
in: path
description: |+
The Globally Unique Resource ID for this resource.
required: true
schema:
type: string
HumanitecDriverCookie:
name: Humanitec-Driver-Cookie
in: header
description: |+
Will be supplied on all subsequent requests with the same `GUResID`. The value will the the value of the last `Set-Humanitec-Driver-Cookie` header that was returned. This header will not be included if a previous call had an empty `Set-Humanitec-Driver-Cookie`.
The header is automatically reset for a `GUResID` once a DELETE on that `GUResID` responds with 204
required: false
schema:
description: |+
Any string less than 10kB (10240bytes) in length. To avoid potential encoding issues, it is suggested that the string should be base64 encoded.
headers:
SetHumanitecDriverCookie:
description: |+
Used to set the value of the `Humanitec-Driver-Cookie` in future requests. If the header is empty, `Humanitec-Driver-Cookie` headers will not be sent in future requests.
required: false
schema:
description: |+
Any string less than 10kB (10240bytes) in length. To avoid potential encoding issues, it is suggested that the string should be base64 encoded.
schemas:
InputData:
description: Defines the desired state of the resource being provisioned.
example:
type: postgres
resource:
extensions:
uuid-ossp:
driver:
values:
host: pgsql.databases.example.com
port: "5432"
name: "defaultdb"
secrets:
username: postgres
password: v3ry-53cr3t-p455w0rd
properties:
type:
title: Resource Type
description: The type of the resource being provisioned.
type: string
pattern: "^[a-z0-9][a-z0-9-]+[a-z0-9]$"
resource:
title: Resource Inputs
description: Parameters defined in the resource type that may optionally be used by the Driver to specify the resource. May not contain secrets.
type: object
driver:
title: Driver Inputs
description: Parameters defined in the Driver used to configure the driver. May contain secrets.
type: object
properties:
secrets:
type: object
values:
type: object
type: object
OutputData:
description: Provides outputs used to access or interact with the resource and any manifests that should be injected.
example:
id: {guresid}
type: postgres
resource:
values:
host: pgsql.databases.example.com
port: "5432"
name: "defaultdb"
secrets:
username: postgres
password: v3ry-53cr3t-p455w0rd
manifests: []
properties:
id:
title: Resource GUResID
description: The GUResID of the resource being provisioned.
type: string
type:
title: Resource Type
description: The type of the resource being provisioned.
type: string
pattern: "^[a-z0-9][a-z0-9-]+[a-z0-9]$"
resource:
title: Resource Outputs
description: These outputs are made available through the deployment set as placeholders. May contain secrets.
properties:
secrets:
type: object
additionalProperties: true
values:
type: object
additionalProperties: true
manifests:
title: Additional Manifests
description: A list of additional manifests to inject into the cluster at a particular location.
type: array
items:
type: object
properties:
location:
title: Location
type: string
enum:
- container
- volume
- namespace
- cluster
description: Where the manifest should be injected. Can be one of `container`, `volume`, `namespace` or `cluster`.
data:
title: Manifest data
description: A JSON kubernetes manifest
type: object
type: object
AsyncProgressHint:
description: |-
Used as a hint by Humanitec to optimize polling for asynchronous Driver operations. There is no guarantee that the hint will be used or if it is how it will be used. However, better estimates will in general result in less polling and faster deployments for end users.
All properties are optional, i.e. an empty object is valid.
type: object
example:
status: creating,
estimated_completion_time: "2021-02-22T09:00:00Z"
timeout_deadline: "2021-02-22T09:10:00Z"
current_time: "2021-02-22T08:55:00Z"
properties:
status:
type: string
enum: ["creating", "updating", "deleting"]
estimated_completion_time:
type: string
title: Estimated Completion Time
description: The estimated completion time of the operation. (ISO 8601 datetime string)
pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?(?:Z|[+-][0-9]{2}:?[0-9]{2}?)?$'
timeout:
type: string
title: Timeout
description: The time after which the operation can be assumed to have timed out. (ISO 8601 datetime string)
pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?(?:Z|[+-][0-9]{2}:?[0-9]{2}?)?$'
current_time:
type: string
title: Current Time
description: The current time as measured by the driver. Intended to handle clock skew. (ISO 8601 datetime string)
pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?(?:Z|[+-][0-9]{2}:?[0-9]{2}?)?$'
Error:
description: Describes an error that the Driver encountered which means it cannot complete its request.
example:
error: RES-101
message: "Driver input \"Host\" is not a string. Got integer."
properties:
error:
title: Error Code
description: A Humanitec error code. For drivers, the error code is always prefixed with `RES-1`
type: string
pattern: "$RES-1[0-9][0-9]^"
message:
title: Message
description: A human readable error message giving further context on the error.
type: string
type: object