From 6fd1076da3a9e035209a4eb0c838dbd4e3e76a5c Mon Sep 17 00:00:00 2001 From: Michael Yocca Date: Wed, 15 Jun 2022 13:19:48 -0700 Subject: [PATCH 1/7] Update run api documentation for new query parameters --- website/docs/cloud-docs/api-docs/run.mdx | 43 +++++++++++++++++++++--- 1 file changed, 38 insertions(+), 5 deletions(-) diff --git a/website/docs/cloud-docs/api-docs/run.mdx b/website/docs/cloud-docs/api-docs/run.mdx index 376f13333..58a80d276 100644 --- a/website/docs/cloud-docs/api-docs/run.mdx +++ b/website/docs/cloud-docs/api-docs/run.mdx @@ -74,7 +74,34 @@ The run state is found in `data.attributes.status`, and you can reference the fo | `discarded` | The run has been discarded. This is a final state. | | `errored` | The run has errored. This is a final state. | | `canceled` | The run has been canceled. | -| `force_canceled` | A workspace admin forcefully canceled the run. | +| `force_canceled` | A workspace admin forcefully canceled the run. + + +### Run Operations + +*Applicable for runs list query parameters* + +The run operation specifies the mode in which the terraform executed, and you can reference the following list of possible operation modes. + +| Operation | Description | +|-------------------------|----------------------------------------------------------------------------------------------------------------------------| +| `plan_only` | Indicates the run completed without an apply phase. Most commonly known as an speculative run. | +| `plan_and_apply` | Indicates the run completed with both plan and apply phases. | +| `refresh_only` | Specifies the run was instructed to execute a plan in which updates state. | +| `destroy` | Specifies the run destroyed all objects, regardless of configuration changes | +| `empty_apply` | Specifies the run performed an apply with no changes to resources. Most commonly used to upgrade terrafor state versions. | + + +### Run Sources + +*Applicable for runs list query parameters* + +| Source | Description | +|-----------------------------|-------------------------------------------------------------------------------------------------| +| `tfe-ui` | Indicates a run was queued from Terraform Cloud UI | +| `tfe-api` | Indicates a run was queued from Terraform Cloud API | +| `tfe-configuration-version` | Indicates a run was queued from a Configuration Version, triggered from a VCS provider. | + ## Create a Run @@ -303,10 +330,16 @@ curl \ This endpoint supports pagination [with standard URL query parameters](/cloud-docs/api-docs/#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. -| Parameter | Description | -|----------------|----------------------------------------------------------------------| -| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | -| `page[size]` | **Optional.** If omitted, the endpoint will return 20 runs per page. | +| Parameter | Description | +|---------------------|----------------------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 runs per page. | +| `filter[operation]` | **Optional.** Options are listed [above](/cloud-docs/api-docs/run#run-operations) | +| `filter[status]` | **Optional.** Options are listed [above](/cloud-docs/api-docs/run#run-states) | +| `filter[source]` | **Optional.** Options are listed [above](/cloud-docs/api-docs/run#run-states) | +| `search[name]` | **Optional.** Searches runs that matches the supplied username | +| `search[commit]` | **Optional.** Searches runs that matches the supplied commit sha | + ### Sample Request From 0e940ada3815d5758f39153acc0df3d378513197 Mon Sep 17 00:00:00 2001 From: Michael Yocca Date: Fri, 17 Jun 2022 16:43:28 -0700 Subject: [PATCH 2/7] pr documentation feedback --- website/docs/cloud-docs/api-docs/run.mdx | 26 +++++++++++------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/website/docs/cloud-docs/api-docs/run.mdx b/website/docs/cloud-docs/api-docs/run.mdx index 58a80d276..46e8036b1 100644 --- a/website/docs/cloud-docs/api-docs/run.mdx +++ b/website/docs/cloud-docs/api-docs/run.mdx @@ -79,9 +79,7 @@ The run state is found in `data.attributes.status`, and you can reference the fo ### Run Operations -*Applicable for runs list query parameters* - -The run operation specifies the mode in which the terraform executed, and you can reference the following list of possible operation modes. +The run operation specifies the Terraform execution mode, and you can reference the following list of possible operation modes and use them as runs list query parameters. | Operation | Description | |-------------------------|----------------------------------------------------------------------------------------------------------------------------| @@ -89,12 +87,12 @@ The run operation specifies the mode in which the terraform executed, and you ca | `plan_and_apply` | Indicates the run completed with both plan and apply phases. | | `refresh_only` | Specifies the run was instructed to execute a plan in which updates state. | | `destroy` | Specifies the run destroyed all objects, regardless of configuration changes | -| `empty_apply` | Specifies the run performed an apply with no changes to resources. Most commonly used to upgrade terrafor state versions. | +| `empty_apply` | Specifies the run performed an apply with no changes to resources. Most commonly used to upgrade terraform state versions. | ### Run Sources -*Applicable for runs list query parameters* +You can use the following sources as runs list query parameters. | Source | Description | |-----------------------------|-------------------------------------------------------------------------------------------------| @@ -330,15 +328,15 @@ curl \ This endpoint supports pagination [with standard URL query parameters](/cloud-docs/api-docs/#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. -| Parameter | Description | -|---------------------|----------------------------------------------------------------------------------------| -| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | -| `page[size]` | **Optional.** If omitted, the endpoint will return 20 runs per page. | -| `filter[operation]` | **Optional.** Options are listed [above](/cloud-docs/api-docs/run#run-operations) | -| `filter[status]` | **Optional.** Options are listed [above](/cloud-docs/api-docs/run#run-states) | -| `filter[source]` | **Optional.** Options are listed [above](/cloud-docs/api-docs/run#run-states) | -| `search[name]` | **Optional.** Searches runs that matches the supplied username | -| `search[commit]` | **Optional.** Searches runs that matches the supplied commit sha | +| Parameter | Description | +|---------------------|-------------------------------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 runs per page. | +| `filter[operation]` | **Optional.** Options are listed in [Run Operations](/cloud-docs/api-docs/run#run-operations) | +| `filter[status]` | ***Optional.** Options are listed in [Run States](/cloud-docs/api-docs/run#run-states) | +| `filter[source]` | **Optional.** Options are listed in [Run Sources](/cloud-docs/api-docs/run#run-sources) | +| `search[name]` | **Optional.** Searches runs that matches the supplied username | +| `search[commit]` | **Optional.** Searches runs that matches the supplied commit sha | ### Sample Request From 4fa43d0a7995e25aa91b35cc574ba5f1608410e0 Mon Sep 17 00:00:00 2001 From: Michael Yocca Date: Wed, 22 Jun 2022 10:29:14 -0700 Subject: [PATCH 3/7] remove extra star character --- website/docs/cloud-docs/api-docs/run.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/cloud-docs/api-docs/run.mdx b/website/docs/cloud-docs/api-docs/run.mdx index 46e8036b1..2130b75bf 100644 --- a/website/docs/cloud-docs/api-docs/run.mdx +++ b/website/docs/cloud-docs/api-docs/run.mdx @@ -333,7 +333,7 @@ This endpoint supports pagination [with standard URL query parameters](/cloud-do | `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | | `page[size]` | **Optional.** If omitted, the endpoint will return 20 runs per page. | | `filter[operation]` | **Optional.** Options are listed in [Run Operations](/cloud-docs/api-docs/run#run-operations) | -| `filter[status]` | ***Optional.** Options are listed in [Run States](/cloud-docs/api-docs/run#run-states) | +| `filter[status]` | **Optional.** Options are listed in [Run States](/cloud-docs/api-docs/run#run-states) | | `filter[source]` | **Optional.** Options are listed in [Run Sources](/cloud-docs/api-docs/run#run-sources) | | `search[name]` | **Optional.** Searches runs that matches the supplied username | | `search[commit]` | **Optional.** Searches runs that matches the supplied commit sha | From d6d794e0e5d697fee89c5ea9cbe7874d77259809 Mon Sep 17 00:00:00 2001 From: Michael Yocca <19916665+mjyocca@users.noreply.github.com> Date: Thu, 23 Jun 2022 12:19:38 -0700 Subject: [PATCH 4/7] Update website/docs/cloud-docs/api-docs/run.mdx Co-authored-by: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> --- website/docs/cloud-docs/api-docs/run.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/cloud-docs/api-docs/run.mdx b/website/docs/cloud-docs/api-docs/run.mdx index 2130b75bf..131db6393 100644 --- a/website/docs/cloud-docs/api-docs/run.mdx +++ b/website/docs/cloud-docs/api-docs/run.mdx @@ -87,7 +87,7 @@ The run operation specifies the Terraform execution mode, and you can reference | `plan_and_apply` | Indicates the run completed with both plan and apply phases. | | `refresh_only` | Specifies the run was instructed to execute a plan in which updates state. | | `destroy` | Specifies the run destroyed all objects, regardless of configuration changes | -| `empty_apply` | Specifies the run performed an apply with no changes to resources. Most commonly used to upgrade terraform state versions. | +| `empty_apply` | Specifies the run performed an apply with no changes to resources. Most commonly used to [upgrade terraform state versions](/cloud-docs/workspaces/state#upgrading-state). | ### Run Sources From 0e66724de74bf8e3f035ed4f0b3402c97440d44f Mon Sep 17 00:00:00 2001 From: Michael Yocca Date: Thu, 23 Jun 2022 12:36:29 -0700 Subject: [PATCH 5/7] pr feedback and runs list reference link --- website/docs/cloud-docs/api-docs/run.mdx | 36 ++++++++++++------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/website/docs/cloud-docs/api-docs/run.mdx b/website/docs/cloud-docs/api-docs/run.mdx index 131db6393..671aabb6b 100644 --- a/website/docs/cloud-docs/api-docs/run.mdx +++ b/website/docs/cloud-docs/api-docs/run.mdx @@ -79,20 +79,20 @@ The run state is found in `data.attributes.status`, and you can reference the fo ### Run Operations -The run operation specifies the Terraform execution mode, and you can reference the following list of possible operation modes and use them as runs list query parameters. - -| Operation | Description | -|-------------------------|----------------------------------------------------------------------------------------------------------------------------| -| `plan_only` | Indicates the run completed without an apply phase. Most commonly known as an speculative run. | -| `plan_and_apply` | Indicates the run completed with both plan and apply phases. | -| `refresh_only` | Specifies the run was instructed to execute a plan in which updates state. | -| `destroy` | Specifies the run destroyed all objects, regardless of configuration changes | +The run operation specifies the Terraform execution mode. You can reference the following list of possible operation modes and use them as [runs list](/cloud-docs/api-docs/run#list-runs-in-a-workspace) query parameters. + +| Operation | Description | +|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `plan_only` | Indicates the run completed without an apply phase. This is also called a [speculative plan](/cloud-docs/run/modes-and-options#plan-only-speculative-plan). | +| `plan_and_apply` | Indicates the run completed with both plan and apply phases. | +| `refresh_only` | Specifies the run was instructed to execute a plan in which updates state. | +| `destroy` | Specifies the run destroyed all objects, regardless of configuration changes. | | `empty_apply` | Specifies the run performed an apply with no changes to resources. Most commonly used to [upgrade terraform state versions](/cloud-docs/workspaces/state#upgrading-state). | ### Run Sources -You can use the following sources as runs list query parameters. +You can use the following sources as [runs list](/cloud-docs/api-docs/run#list-runs-in-a-workspace) query parameters. | Source | Description | |-----------------------------|-------------------------------------------------------------------------------------------------| @@ -328,15 +328,15 @@ curl \ This endpoint supports pagination [with standard URL query parameters](/cloud-docs/api-docs/#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. -| Parameter | Description | -|---------------------|-------------------------------------------------------------------------------------------------| -| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | -| `page[size]` | **Optional.** If omitted, the endpoint will return 20 runs per page. | -| `filter[operation]` | **Optional.** Options are listed in [Run Operations](/cloud-docs/api-docs/run#run-operations) | -| `filter[status]` | **Optional.** Options are listed in [Run States](/cloud-docs/api-docs/run#run-states) | -| `filter[source]` | **Optional.** Options are listed in [Run Sources](/cloud-docs/api-docs/run#run-sources) | -| `search[name]` | **Optional.** Searches runs that matches the supplied username | -| `search[commit]` | **Optional.** Searches runs that matches the supplied commit sha | +| Parameter | Description | +|---------------------|--------------------------------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 runs per page. | +| `filter[operation]` | **Optional.** Options are listed in [Run Operations](/cloud-docs/api-docs/run#run-operations). | +| `filter[status]` | **Optional.** Options are listed in [Run States](/cloud-docs/api-docs/run#run-states). | +| `filter[source]` | **Optional.** Options are listed in [Run Sources](/cloud-docs/api-docs/run#run-sources). | +| `search[name]` | **Optional.** Searches runs that matches the supplied username. | +| `search[commit]` | **Optional.** Searches runs that matches the supplied commit sha. | ### Sample Request From 009ccb4e1e0cbc413205e9b13ece1f913936fda5 Mon Sep 17 00:00:00 2001 From: Michael Yocca Date: Thu, 23 Jun 2022 12:38:13 -0700 Subject: [PATCH 6/7] add missing periods to run sources section --- website/docs/cloud-docs/api-docs/run.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/website/docs/cloud-docs/api-docs/run.mdx b/website/docs/cloud-docs/api-docs/run.mdx index 671aabb6b..75953603b 100644 --- a/website/docs/cloud-docs/api-docs/run.mdx +++ b/website/docs/cloud-docs/api-docs/run.mdx @@ -94,11 +94,11 @@ The run operation specifies the Terraform execution mode. You can reference the You can use the following sources as [runs list](/cloud-docs/api-docs/run#list-runs-in-a-workspace) query parameters. -| Source | Description | -|-----------------------------|-------------------------------------------------------------------------------------------------| -| `tfe-ui` | Indicates a run was queued from Terraform Cloud UI | -| `tfe-api` | Indicates a run was queued from Terraform Cloud API | -| `tfe-configuration-version` | Indicates a run was queued from a Configuration Version, triggered from a VCS provider. | +| Source | Description | +|-----------------------------|--------------------------------------------------------------------------------------------------| +| `tfe-ui` | Indicates a run was queued from Terraform Cloud UI. | +| `tfe-api` | Indicates a run was queued from Terraform Cloud API. | +| `tfe-configuration-version` | Indicates a run was queued from a Configuration Version, triggered from a VCS provider. | ## Create a Run From 60c4845e944110af59dfc9a7fdb623051ef86a35 Mon Sep 17 00:00:00 2001 From: Michael Yocca Date: Thu, 23 Jun 2022 12:46:15 -0700 Subject: [PATCH 7/7] fix spacing for run sources table --- website/docs/cloud-docs/api-docs/run.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/website/docs/cloud-docs/api-docs/run.mdx b/website/docs/cloud-docs/api-docs/run.mdx index 75953603b..539f8fcce 100644 --- a/website/docs/cloud-docs/api-docs/run.mdx +++ b/website/docs/cloud-docs/api-docs/run.mdx @@ -94,11 +94,11 @@ The run operation specifies the Terraform execution mode. You can reference the You can use the following sources as [runs list](/cloud-docs/api-docs/run#list-runs-in-a-workspace) query parameters. -| Source | Description | -|-----------------------------|--------------------------------------------------------------------------------------------------| -| `tfe-ui` | Indicates a run was queued from Terraform Cloud UI. | -| `tfe-api` | Indicates a run was queued from Terraform Cloud API. | -| `tfe-configuration-version` | Indicates a run was queued from a Configuration Version, triggered from a VCS provider. | +| Source | Description | +|-------------------------------|--------------------------------------------------------------------------------------------------| +| `tfe-ui` | Indicates a run was queued from Terraform Cloud UI. | +| `tfe-api` | Indicates a run was queued from Terraform Cloud API. | +| `tfe-configuration-version` | Indicates a run was queued from a Configuration Version, triggered from a VCS provider. | ## Create a Run