Terraform
Applies API
An apply represents the results of applying a Terraform Run's execution plan.
Attributes
Apply States
You'll find the apply state in data.attributes.status, as one of the following values.
| State | Description |
|---|---|
pending | The initial status of a apply once it has been created. |
managed_queued/queued | The apply has been queued, awaiting backend service capacity to run terraform. |
running | The apply is running. |
errored | The apply has errored. This is a final state. |
canceled | The apply has been canceled. This is a final state. |
finished | The apply has completed successfully. This is a final state. |
unreachable | The apply will not run. This is a final state. |
Show an apply
GET /applies/:id
| Parameter | Description |
|---|---|
id | The ID of the apply to show. |
There is no endpoint to list applies. You can find the ID for an apply in the
relationships.apply property of a run object.
| Status | Response | Reason |
|---|---|---|
| 200 | JSON API document (type: "applies") | The request was successful |
| 404 | JSON API error object | Apply not found, or user unauthorized to perform action |
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/applies/apply-47MBvjwzBG8YKc2v
Sample Response
{
"data": {
"id": "apply-47MBvjwzBG8YKc2v",
"type": "applies",
"attributes": {
"execution-details": {
"mode": "remote",
},
"status": "finished",
"status-timestamps": {
"queued-at": "2018-10-17T18:58:27+00:00",
"started-at": "2018-10-17T18:58:29+00:00",
"finished-at": "2018-10-17T18:58:37+00:00"
},
"log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg",
"resource-additions": 1,
"resource-changes": 0,
"resource-destructions": 0,
"resource-imports": 0
},
"relationships": {
"state-versions": {
"data": [
{
"id": "sv-TpnsuD3iewwsfeRD",
"type": "state-versions"
},
{
"id": "sv-Fu1n6a3TgJ1Typq9",
"type": "state-versions"
}
]
}
},
"links": {
"self": "/api/v2/applies/apply-47MBvjwzBG8YKc2v"
}
}
}
Using HCP Terraform agents
HCP Terraform agents allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure. When a workspace is set to use the agent execution mode, the apply response will include additional details about the agent pool and agent used.
{
"data": {
"id": "apply-47MBvjwzBG8YKc2v",
"type": "applies",
"attributes": {
"execution-details": {
"agent-id": "agent-S1Y7tcKxXPJDQAvq",
"agent-name": "agent_01",
"agent-pool-id": "apool-Zigq2VGreKq7nwph",
"agent-pool-name": "first-pool",
"mode": "agent",
},
"status": "finished",
"status-timestamps": {
"queued-at": "2018-10-17T18:58:27+00:00",
"started-at": "2018-10-17T18:58:29+00:00",
"finished-at": "2018-10-17T18:58:37+00:00"
},
"log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg",
"resource-additions": 1,
"resource-changes": 0,
"resource-destructions": 0,
"resource-imports": 0
},
"relationships": {
"state-versions": {
"data": [
{
"id": "sv-TpnsuD3iewwsfeRD",
"type": "state-versions"
},
{
"id": "sv-Fu1n6a3TgJ1Typq9",
"type": "state-versions"
}
]
}
},
"links": {
"self": "/api/v2/applies/apply-47MBvjwzBG8YKc2v"
}
}
}
Recover a failed state upload after applying
GET /applies/:id/errored-state
| Parameter | Description |
|---|---|
id | The ID of the apply to recover state for. |
It is possible that during the course of a Run, Terraform may fail to upload a state file. This can happen for a variety of reasons, but should be an exceptionally rare occurance. HCP Terraform agent versions greater than 1.12.0 include a fallback mechanism which attempts to upload the state directly to HCP Terraform's backend storage system in these cases. This endpoint then makes the raw data from these failed uploads available to users who are authorized to read the state contents.
| Status | Response | Reason |
|---|---|---|
| 307 | HTTP temporary redirect to state storage URL | Errored state available and user is authorized to read it |
| 404 | JSON API error object | Apply not found, errored state not uploaded, or user unauthorized to perform action |
When a 307 redirect is returned, the storage URL to the raw state file will be
present in the Location header of the response. The URL in the Location
header will expire after one minute. It is recommended for the API client to
follow the redirect immediately. Each successful request to the errored-state
endpoint will generate a new, unique storage URL with the same one minute
expiration window.
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
https://app.terraform.io/api/v2/applies/apply-47MBvjwzBG8YKc2v/errored-state
Sample Response
HTTP/1.1 307 Temporary Redirect
Content-Length: 22
Content-Type: text/plain
Location: https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg
307 Temporary Redirect