Install a built image on one of your servers

Change · POST /v1/tenants/{tenant}/submissions/{submission}/provision · MCP tool provision

Installs the image that this submission's build produced on a server in your own cloud account. You name the provider, the target and the server's addresses; the image always comes from this submission's finished build. Tarsana uses the provider credential you stored. This step is optional: your image is built, checked and published whether or not you install it.

Roles that can call it: deployer.

Parameters

Name	In	Required	Description
`tenant`	path	yes	Your tenant ID
`submission`	path	yes	The submission ID that `submit` returned
request body	body	yes	Your provisioning request (tarsana.provisioning-request/v1): the provider, the target and the server's addresses

Returns

A JSON object with these keys: submission, tenant, provisioning, guarantee, caller_authenticated.

Example request

curl -X POST https://api.tarsana.io/v1/tenants/acme/submissions/sha256:cdff062988d4722b2ff052c97ebefb8b571858c493ce47b159df73b1c88809b1/provision \
  -H "X-Tarsana-Access-Token: $ACCESS_TOKEN" \
  -H 'X-Tarsana-Tenant: acme' \
  -H "Content-Type: application/json" \
  --data @request.json

Example response

{
  "submission": "sha256:cdff062988d4722b2ff052c97ebefb8b571858c493ce47b159df73b1c88809b1",
  "tenant": "acme",
  "provisioning": {
    "state": "provisioned",
    "provider": "hetzner",
    "target": "1",
    "mechanism": "rescue-dd",
    "attested": true,
    "correlation_id": "selfservice.cdff0629...",
    "what": "A sentence about the installation."
  },
  "guarantee": "namespaces are separated, callers are not authenticated",
  "caller_authenticated": false
}

Errors

Code	HTTP	What it means
`invalid_parameter`	400	A value in your request does not have the expected format, for example a submission ID that is not a spec hash. Check the value against the field's description and try again.
`no_acting_tenant`	400	Your request does not say which tenant you are acting for. Send your tenant ID in the `X-Tarsana-Tenant` header, or with `--as` on the command line.
`isolation_refused`	403	This address belongs to a tenant ID you do not have access to. Check the tenant ID in the address and in your request header.
`no_such_submission`	404	You have no submission with this ID. Check the ID that `submit` returned.
`provisioning_not_configured`	503	Installing images on servers is not available on this Tarsana deployment. Contact Tarsana support if you need it.
`provisioning_request_invalid`	400	Your provisioning request is not valid: a field is missing, or a value is not supported. Correct the request and send it again.
`not_provisionable`	409	This submission has no finished build that can be installed. Check its status, and try again when its build has succeeded.
`provisioning_refused`	409	The provider cannot install this image in any of the ways your request allows. The response says why and what you can change, because sending the same request again will not help.
`provisioning_failed`	502	The installation did not complete, for example because the provider returned an error. The response says where it stopped and whether trying again can help.
`unauthenticated`	401	Your request has no credential, or one that Tarsana does not recognise. Sign in with `login`, or send a valid access token.
`forbidden`	403	Your role does not allow this operation. The response names the roles that do; ask for a credential with one of them.
`rate_limited`	429	You sent too many requests in a short time. Wait for the number of seconds in `retry_after_seconds`, then try again.
`surface_fault`	500	Something went wrong on our side. Try again later, and contact Tarsana support if it keeps happening.

View this page as Markdown