Introduction:
In this article, we will walk through how to list all workspaces in Terraform Cloud or Enterprise using an API call. This can be particularly useful for automation, reporting, or administrative tasks.
Prerequisites:
Before making API call, ensure that you have the following:
- Terraform Cloud or Enterprise account: You need an active Terraform Cloud or Enterprise account.
- API Token: Generate a personal API token by going to your Terraform Cloud/Enterprise user settings.
-
HTTP Client: You can use tools like
curl
, Postman, or any HTTP library in your preferred programming language to make API calls.
Solution:
Step 1: Obtain Your API Token
- Log into Terraform Cloud or Enterprise.
- Go to User Settings by clicking your profile picture in the top-right corner.
- Under the API tokens section, click Create an API token.
- Copy the generated token and store it securely. You will use it for authentication in your API calls.
Step 2: Make the API Call to List Workspaces
The API endpoint for listing workspaces is structured as follows:
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
"https://<TFE-HOSTNAME>/api/v2/organizations/<ORG-NAME>/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=10"
- Replace
<ORG-NAME>
with the name of your Terraform organization. - You will need to authenticate your API call using your API token. The token should be passed as a
Bearer
token in the Authorization header. -
Page[number] and Page[size]
should be changed as per the desired result. -
Remember to percent-encode
[
as%5B
and]
as%5D
Example Response:
If successful, you will receive a JSON response that lists all the workspaces associated with the specified organization:
{
"id": "ws-sPXu2fHeiggxy615",
"type": "workspaces",
"attributes": {
"parent-data-retention-policy-info": "inherit admin policy of don't delete",
"allow-destroy-plan": true,
"auto-apply": false,
"inherits-project-auto-destroy": false,
"created-at": "2024-10-21T07:44:41.926Z",
"environment": "default",
"locked": false,
"name": "test1",
"queue-all-runs": false,
"speculative-enabled": true,
"structured-run-output-enabled": true,
"terraform-version": "1.9.2",
"working-directory": "",
"global-remote-state": true,
"updated-at": "2024-10-21T07:44:41.926Z",
"resource-count": 0,
"apply-duration-average": null,
"plan-duration-average": null,
"policy-check-failures": null,
"run-failures": null,
"workspace-kpis-runs-count": null,
"latest-change-at": "2024-10-21T07:44:41.926Z",
"operations": true,
"execution-mode": "remote",
},
"actions": {
"is-destroyable": true
},
"description": null,
"file-triggers-enabled": false,
"trigger-prefixes": [],
"trigger-patterns": [],
"assessments-enabled": false,
"last-assessment-result-at": null,
"locked-reason": "",
}
},
"relationships": {
"organization": {
"data": {
"id": "support",
"type": "organizations"
}
},
"current-state-version": {
"data": null
},
"project": {
"data": {
"id": "prj-UwWEsUigxVeqsxKh",
"type": "projects"
}
},
"links": {
"self": "/api/v2/organizations/support/workspaces/test1",
"self-html": "/app/support/workspaces/test1"
}
}
Step 3: Filter and Sort the list based on the attributes
The API endpoint can be further filtered to list the workspaces based on the attributes.
For example: To list and sort workspaces based on the attribute "latest-change-at" you can use the below
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
"https://terraform.example.com/api/v2/organizations/<ORG-NAME>/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=latest-change-at" \
| jq . \
| jq .data \
| jq -r '.[] | "\(.id) \(.attributes."latest-change-at") \(.attributes.name)"'
Conclusion:
Using the Terraform Cloud/Enterprise API to list workspaces is a powerful way to automate and manage your infrastructure more efficiently. With a simple API call, you can retrieve a complete list of all your workspaces, including metadata such as Terraform versions, creation dates, and status.
This method can be easily integrated into larger automation workflows or scripts to streamline operations and improve infrastructure management.
References:-