Skip to content
Docs BETA

What a provisioner is

For platform teams. This page explains what a provisioner does, which calls it answers, and how it fits with the control plane. Read it before you register or write one.

The job

A provisioner is a service that does the work on the real resources of the types that it handles. The control plane does not create a database or a space itself. It asks a provisioner to do it.

You deploy a provisioner on its own, and you tell the control plane its address. Register a provisioner shows how.

The types that it handles

A provisioner handles one or more pairs of a category and a type. For example: category managed-resource, type postgres. The API calls the category kind.

The categories that a provisioner can handle are target, tool, deployment, managed-resource and consumed-resource. An artifact has no provisioner.

Each pair has exactly one provisioner. The control plane refuses a second registration that claims a pair which another provisioner already handles. A provisioner can handle several pairs.

A provisioner must also handle only the pairs that it was registered for. If a call names another pair, it answers that the call failed. Provisioner API reference shows the answer.

The calls that it answers

The control plane calls a provisioner with plain HTTP and JSON. Each call is for one pair and one application.

Call What it asks Changes anything?
POST /plan What would happen with these changes? No. It is a dry run.
POST /apply Make these changes. Yes. It must give the same result when it is repeated.
POST /inspect What do these resources look like now? No. The control plane uses it to find drift.
GET /operations/{operationId} How is the work that you accepted? No. Only a provisioner that accepts slow work serves it.

A call that fails because of the work is not an HTTP error. The provisioner answers 200 with the outcome failed and a reason. An HTTP error means that the call itself broke.

Slow work

Some work takes minutes, for example a pipeline run. A provisioner for such work answers 202 with an operation ID and continues the work. The control plane then asks GET /operations/{operationId} until the answer is final. Support slow work in a provisioner explains it.

Who calls whom

The control plane calls the provisioner. A provisioner never calls the control plane for the work of a plan or an apply. It does not register itself unless you set that up. Build a provisioner with the starter shows how a provisioner can register itself at start.

The catalog and the provisioner

A provisioner works on a type of the catalog. The catalog says which settings a type needs and which outputs a provisioner can report. Own the catalog of types explains the catalog.