Manage Custom Drivers
Drivers should be simple and isolated; this means that they should be responsible for managing precisely one Resource Type per endpoint and that the Resources created should not interfere with each other.
Building blocks
When creating a Driver, you will need to consider three elements:
- How to provision the Resources
- How to store the provisioned Resource’s state
- How to handle the Resource Account(s) needed to provision the Resources
In general, Drivers are APIs that fulfil the Humanitec Driver Interface. This interface allows Humanitec to create and destroy Resources as required by Deployments.
Drivers typically call APIs associated with managed services, using the credentials provided by the Resource Accounts as necessary. Resource Accounts are identities used to provision and manage resources via Dynamic Resource Definitions. They can represent a range of identities, including cloud provider service accounts, VPN accounts, SSH accounts, and other credentials.
Understanding resource provisioning
Before you start writing a new Driver, you must understand the flows that will trigger your Driver’s API.
Creating a Resource
When deploying an Application (App), the Platform Orchestrator will evaluate the Delta and the Deployment and begin resource matching. Once the Platform Orchestrator has identified the necessary Drivers and Resource Accounts, it will contact the Drivers and supply any relevant configuration.
This process begins by issuing a PUT request to the Driver’s API.
The Driver will then need to evaluate whether it needs to create or update the resource. It does this by comparing the contents of the PUT to its internal state representation.
If the Driver responds with a 202 Accepted, the orchestrator will periodically poll it with the same data until it returns a 200 OK.
See the Humanitec Driver Interface for more information.
Updating a Resource
When redeploying (or updating) an Applications, the Platform Orchestrator follows the same process and hits the same endpoints as when handling new Deployments. This use of a common process simplifies the interface and implementation of Drivers as the Platform Orchestrator doesn’t need to differentiate between new resources and ones that already exist.
See the Humanitec Driver Interface for more information.
Deleting a Resource
When a Resource is no longer needed, the Platform Orchestrator will contact the relevant Driver with a DELETE request for the specific resource.
If the Driver responds with a 202 Accepted, the Platform Orchestrator will periodically poll the Driver until it receives a 204 No Content.
See the Humanitec Driver Interface for more information.
Tracking states
Learn how to track states of Drivers.
GUResIDs
Drivers receive a Globally Unique Resource ID (GUResID) as a path parameter, uniquely identifying the Resource that needs to be provisioned, updated, or deallocated. GUResIDs are uniquely tied to the context of a resource. This means that if a resource is deleted and recreated, it would have the same GUResID.
A Humanitec Driver must only create one instance of a Resource for a particular GUResID. How a Resource instance is defined is up to the Driver. It is critical that multiple PUT requests to the Driver with the same GUResID without intervening DELETE requests not create new instances.
Stateful and stateless Drivers
Humanitec provides a mechanism for a Driver to store a small amount of state via a cookie-like Header called the Humanitec Driver Cookie. This Cookie allows the implementation of Divers without needing to handle their own state storage.
To set the Cookie, supply a Set-Humanitec-Driver-Cookie header in the response to the PUT request. This Cookie can contain up to 10kB (10240bytes) of data, returned via a header called Humanitec-Driver-Cookieon all subsequent requests. After a successful DELETE, Humanitec automatically clears this Cookie. The Cookie can also be cleared by the Driver by sending an empty Set-Humanitec-Driver-Cookie. To avoid character encoding issues, we recommend encoding the data you wish to store in the Cookie as a base64 string.
Humanitec considers the Cookie to be a sensitive opaque blob. It is stored securely in the configured secret store.
Sync & async
Learn about synchronous and asynchronous drivers.
Synchronous Drivers
For resources that take little time to provision (i.e., under 180 seconds), we recommend building your Driver to be synchronous. Meaning that it should only return once an action has finished executing, waiting until the action (provisioning/de-provisioning) is complete before returning a response with an HTTP Status Code of either 200 for Create or Update requests or a 204 for Delete requests.
Asynchronous Drivers
Frequently, however, provisioning Resources can take a long time. For example, provisioning a new database instance or Kubernetes cluster can take tens of minutes on some platforms. Long-running HTTP requests are often subject to timeout due to underlying policies in various nodes of the TCP network.
An asynchronous Driver is fundamentally similar to the default synchronous type, except the first return to any action is an HTTP status code of 202. Humanitec will then periodically poll the Driver until a response with an HTTP status code of 200 (on Create & Update), 204 (on Delete), or a non-2xx status code is received.
An asynchronous Driver needs must be able to independently track the state of the resource being provisioned and ensure that it can handle edge cases such as:
- A resource being deallocated before provisioning is complete.
- A resource being updated while provisioning is still ongoing.
- A resource being recreated while the previous instance is deallocated.
Reference implementations
We maintain the following open source reference implementations: