Skip to content

Latest commit

 

History

History
927 lines (797 loc) · 35.1 KB

no-code-provisioning.mdx

File metadata and controls

927 lines (797 loc) · 35.1 KB
Raw
page_title description
No-Code Provisioning - API Docs - HCP Terraform
Use these endpoints to control availability of no-code provisioning and designate variable values for a no-code module in your organization.

No-code provisioning API

The no-code provisioning API allows you to create, configure, and deploy Terraform modules in the no-code provisioning workflows within HCP Terraform. For more information on no-code modules, refer to Designing No-Code Ready Modules.

Enable no-code provisioning for a module

POST /organizations/:organization_name/no-code-modules

Parameter Description
:organization_name The name of the organization the module belongs to.

To deploy a module using the no-code provisioning workflow, the module must meet the following requirement:

  1. The module must exist in your organization's private registry.
  2. The module must meet the design requirements for a no-code module.
  3. You must enable no-code provisioning for the module.

You can send a POST request to the /no-code-modules endpoint to enable no-code provisioning for a specific module. You can also call this endpoint to set options for the allowed values of a variable for a no-code module in your organization.

-> Note: This endpoint can not be accessed with organization tokens. You must access it with a user token or team token.

Status Response Reason
200 JSON API document (type: "no-code-modules") Successfully enabled a module for no-code provisioning.
404 JSON API error object Not found, or the user is unauthorized to perform this action.
422 JSON API error object Malformed request body (e.g., missing attributes, wrong types, etc.).
500 JSON API error object Internal system failure.

Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path Type Default Description
data.type string Must be "no-code-modules".
data.attributes.version-pin string Latest version of the module The module version to use in no-code provisioning workflows.
data.attributes.enabled boolean false Set to true to enable no-code provisioning workflows.
data.relationships.registry-module.data.id string The ID of a module in the organization's private registry.
data.relationships.registry-module.data.type string Must be "registry-module".
data.relationships.variable-options.data[].type string Must be "variable-options".
data.relationships.variable-options.data[].attributes.variable-name string The name of a variable within the module.
data.relationships.variable-options.data[].attributes.variable-type string The data type for the variable. Can be any type supported by Terraform.
data.relationships.variable-options.data[].attributes.options Any[] A list of allowed values for the variable.

Sample Payload

{
  "data": {
    "type": "no-code-modules",
    "attributes": {
      "version-pin":  "1.0.1",
      "enabled": true
    },
    "relationships": {
      "registry-module": {
        "data": {
          "id": "mod-2aaFrmRPZs2N9epr",
          "type": "registry-module"
        }
      },
      "variable-options": {
        "data": [
          {
            "type": "variable-options",
            "attributes": {
              "variable-name": "amis",
              "variable-type": "string",
              "options": [
                "ami-1",
                "ami-2",
                "ami-3"
              ]
            }
          },
          {
            "type": "variable-options",
            "attributes": {
              "variable-name": "region",
              "variable-type": "string",
              "options": [
                "eu-north-1",
                "us-east-2",
                "us-west-1"
              ]
            }
          }
        ]
      }
    }
  }
}

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/my-organization/no-code-modules

Sample Response

{
  "data": {
    "id": "nocode-9HE91XDNY3faePn2",
    "type": "no-code-modules",
    "attributes": {
      "enabled": true,
      "version-pin": "1.0.1"
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        },
        "links": {
          "related": "/api/v2/organizations/my-organization"
        }
      },
      "registry-module": {
        "data": {
          "id": "mod-2aaFrmRPZs2N9epr",
          "type": "registry-modules"
        },
        "links": {
          "related": "/api/v2/registry-modules/mod-2aaFrmRPZs2N9epr"
        }
      },
      "variable-options": {
        "data": [
          {
            "id": "ncvaropt-fcHDfnZ1EGdRzFNC",
            "type": "variable-options"
          },
          {
            "id": "ncvaropt-dZMfdh9KBcwFjyv2",
            "type": "variable-options"
          }
        ]
      }
    },
    "links": {
      "self": "/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2"
    }
  }
}

Update no-code provisioning settings

PATCH /no-code-modules/:id

Parameter Description
:id The unique identifier of the no-code module.

Send a PATCH request to the /no-code-modules/:id endpoint to update the settings for the no-code provisioning of a module. You can update the following settings:

  • Enable or disable no-code provisioning.
  • Adjust the set of options for allowed variable values.
  • Change the module version being provisioned.
  • Change the module being provisioned.

The API call that enables no-code provisioning for a module returns that module's unique identifier.

-> Note: This endpoint cannot be accessed with organization tokens. You must access it with a user token or team token.

Status Response Reason
200 JSON API document (type: "no-code-modules") Successfully updated a no-code module.
404 JSON API error object Not found, or the user is unauthorized to perform this action.
422 JSON API error object Malformed request body (e.g., missing attributes, wrong types, etc.).
500 JSON API error object Internal system failure.

Request Body

This PATCH endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path Type Default Description
data.type string Must be "no-code-modules".
data.attributes.version-pin string Existing value The module version to use in no-code provisioning workflows.
data.attributes.enabled boolean Existing value Set to true to enable no-code provisioning workflows, or false to disable them.
data.relationships.registry-module.data.id string Existing value The ID of a module in the organization's Private Registry.
data.relationships.registry-module.data.type string Existing value Must be "registry-module".
data.relationships.variable-options.data[].id string The ID of an existing variable-options set. If provided, a new variable-options set replaces the set with this ID. If not provided, this creates a new variable-option set.
data.relationships.variable-options.data[].type string Must be "variable-options".
data.relationships.variable-options.data[].attributes.variable-name string The name of a variable within the module.
data.relationships.variable-options.data[].attributes.variable-type string The data type for the variable. Can be any type supported by Terraform.
data.relationships.variable-options.data[].attributes.options Any[] A list of allowed values for the variable.

Sample Payload

{
  "data": {
    "type": "no-code-modules",
    "attributes": {
      "enabled": false
    },
    "relationships": {
      "registry-module": {
        "data": {
          "id": "mod-zyai9dwH4VPPaVuC",
          "type": "registry-module"
        }
      },
      "variable-options": {
        "data": [
          {
            "id": "ncvaropt-fcHDfnZ1EGdRzFNC",
            "type": "variable-options",
            "attributes": {
              "variable-name": "Linux AMIs",
              "variable-type": "array",
              "options": [
                "Xenial Xerus",
                "Trusty Tahr"
              ]
            }
          },
          {
            "id": "ncvaropt-dZMfdh9KBcwFjyv2",
            "type": "variable-options",
            "attributes": {
              "variable-name": "region",
              "variable-type": "array",
              "options": [
                "eu-north-1",
                "us-east-2",
                "us-west-1"
              ]
            }
          }
        ]
      }
    }
  }
}

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2

Sample Response

{
  "data": {
    "id": "nocode-9HE91XDNY3faePn2",
    "type": "no-code-modules",
    "attributes": {
      "enabled": true,
      "version-pin": "1.0.1"
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        },
        "links": {
          "related": "/api/v2/organizations/my-organization"
        }
      },
      "registry-module": {
        "data": {
          "id": "mod-2aaFrmRPZs2N9epr",
          "type": "registry-modules"
        },
        "links": {
          "related": "/api/v2/registry-modules/mod-2aaFrmRPZs2N9epr"
        }
      },
      "variable-options": {
        "data": [
          {
            "id": "ncvaropt-fcHDfnZ1EGdRzFNC",
            "type": "variable-options"
          },
          {
            "id": "ncvaropt-dZMfdh9KBcwFjyv2",
            "type": "variable-options"
          }
        ]
      }
    },
    "links": {
      "self": "/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2"
    }
  }
}

Read a no-code module's properties

GET /no-code-modules/:id

Parameter Description
:id The unique identifier of the no-code module.

Use this API to read the details of an existing no-code module.

The API call that enables no-code provisioning for a module returns that module's unique identifier.

Status Response Reason
200 JSON API document (type: "no-code-modules") Successfully read the no-code module.
400 JSON API error object Invalid include parameter.
404 JSON API error object Not found, or the user is unauthorized to perform this action.
422 JSON API error object Malformed request body (e.g., missing attributes, wrong types, etc.).
500 JSON API error object Internal system failure.

Query Parameters

This endpoint uses our standard URL query parameters. Use HTML URL encoding syntax, such as %5B to represent [ and %5D to represent ], if your tooling does not automatically encode URLs.

Terraform returns related resources when you add the include query parameter to the request.

Parameter Description
include List related resource to include in the response.

The following resource types are available:

Resource Name Description
variable_options Module variables with a configured set of allowed values.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2?include=variable_options

Sample Response

{
  "data": {
    "id": "nocode-9HE91XDNY3faePn2",
    "type": "no-code-modules",
    "attributes": {
      "enabled": true,
      "version-pin": "1.0.1"
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        },
        "links": {
          "related": "/api/v2/organizations/my-organization"
        }
      },
      "registry-module": {
        "data": {
          "id": "mod-2aaFrmRPZs2N9epr",
          "type": "registry-modules"
        },
        "links": {
          "related": "/api/v2/registry-modules/mod-2aaFrmRPZs2N9epr"
        }
      },
      "variable-options": {
        "data": [
          {
            "id": "ncvaropt-fcHDfnZ1EGdRzFNC",
            "type": "variable-options"
          },
          {
            "id": "ncvaropt-dZMfdh9KBcwFjyv2",
            "type": "variable-options"
          }
        ]
      }
    },
    "links": {
      "self": "/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2"
    }
  },
  "included": [
    {
      "id": "ncvaropt-fcHDfnZ1EGdRzFNC",
      "type": "variable-options",
      "attributes": {
        "variable-name": "Linux AMIs",
        "variable-type": "array",
        "options": [
          "Xenial Xerus",
          "Trusty Tahr"
        ]
      },
      "relationships": {
        "no-code-allowed-module": {
          "data": {
            "id": "nocode-9HE91XDNY3faePn2",
            "type": "no-code-allowed-modules"
          }
        }
      }
    },
    {
      "id": "ncvaropt-dZMfdh9KBcwFjyv2",
      "type": "variable-options",
      "attributes": {
        "variable-name": "region",
        "variable-type": "array",
        "options": [
          "eu-north-1",
          "us-east-2",
          "us-west-1"
        ]
      },
      "relationships": {
        "no-code-allowed-module": {
          "data": {
            "id": "nocode-9HE91XDNY3faePn2",
            "type": "no-code-allowed-modules"
          }
        }
      }
    }
  ]
}

Create a no-code module workspace

This endpoint creates a workspace from a no-code module.

POST /no-code-modules/:id/workspaces

Parameter Description
:id The ID of the no-code module to provision.

Each HCP Terraform organization has a list of which modules you can use to create workspaces using no-code provisioning. You can use this API to create a workspace by selecting a no-code module to enable a no-code provisioning workflow.

-> Note: This endpoint can not be accessed with organization tokens. You must access it with a user token or team token.

Status Response Reason
200 JSON API document (type: "workspaces") Successfully created a workspace from a no-code module for no-code provisioning.
404 JSON API error object Not found, or the user is unauthorized to perform this action.
422 JSON API error object Malformed request body (e.g., missing attributes, wrong types, etc.).
500 JSON API error object Internal system failure.

Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path Type Default Description
data.type string none Must be "workspaces".
data.attributes.agent-pool-id string none Required when execution-mode is set to agent. The ID of the agent pool belonging to the workspace's organization. This value must not be specified if execution-mode is set to remote.
data.attributes.auto_apply boolean false If true, Terraform automatically applies changes when a Terraform plan is successful.
data.attributes.description string "" A description for the workspace.
data.attributes.execution-mode string none Which execution mode to use. Valid values are remote, and agent. When not provided, defaults to remote.
data.attributes.name string none The name of the workspace. You can only include letters, numbers, -, and _. Terraform uses this value to identify the workspace and must be unique in the organization.
data.attributes.source-name string none A friendly name for the application or client creating this workspace. If set, this will be displayed on the workspace as "Created via <SOURCE NAME>".
data.attributes.source-url string (nothing) A URL for the application or client creating this workspace. This can be the URL of a related resource in another app, or a link to documentation or other info about the client.
data.relationships.project.data.id string The ID of the project to create the workspace in. You must have permission to create workspaces in the project, either by organization-level permissions or team admin access to a specific project.
data.relationships.project.data.type string Must be "project".
data.relationships.vars.data[].type string Must be "vars".
data.relationships.vars.data[].attributes.key string The name of the variable.
data.relationships.vars.data[].attributes.value string "" The value of the variable.
data.relationships.vars.data[].attributes.description string The description of the variable.
data.relationships.vars.data[].attributes.category string Whether this is a Terraform or environment variable. Valid values are "terraform" or "env".
data.relationships.vars.data[].attributes.hcl boolean false Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables.
data.relationships.vars.data[].attributes.sensitive boolean false Whether the value is sensitive. If true then the variable is written once and not visible thereafter.

Sample Payload

{
  "data": {
    "type": "workspaces",
    "attributes": {
      "name":  "no-code-workspace",
      "description": "A workspace to enable the no-code provisioning workflow."
    },
    "relationships": {
      "project": {
        "data": {
          "id": "prj-yuEN6sJVra5t6XVy",
          "type": "project"
        }
      },
      "vars": {
        "data": [
          {
            "type": "vars",
            "attributes": {
              "key": "region",
              "value": "eu-central-1",
              "category": "terraform",
              "hcl": true,
              "sensitive": false,
            }
          },
          {
            "type": "vars",
            "attributes": {
              "key": "ami",
              "value": "ami‑077062",
              "category": "terraform",
              "hcl": true,
              "sensitive": false,
            }
          }
        ]
      }
    }
  }
}

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces

Sample Response

{
  "data": {
    "id": "ws-qACTToFUM5BvDKhC",
    "type": "workspaces",
    "attributes": {
      "allow-destroy-plan": true,
      "auto-apply": false,
      "auto-destroy-at": null,
      "auto-destroy-status": null,
      "created-at": "2023-09-08T10:36:04.391Z",
      "environment": "default",
      "locked": false,
      "name": "no-code-workspace",
      "queue-all-runs": false,
      "speculative-enabled": true,
      "structured-run-output-enabled": true,
      "terraform-version": "1.5.6",
      "working-directory": null,
      "global-remote-state": true,
      "updated-at": "2023-09-08T10:36:04.427Z",
      "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": "2023-09-08T10:36:04.391Z",
      "operations": true,
      "execution-mode": "remote",
      "vcs-repo": null,
      "vcs-repo-identifier": null,
      "permissions": {
        "can-update": true,
        "can-destroy": true,
        "can-queue-run": true,
        "can-read-variable": true,
        "can-update-variable": true,
        "can-read-state-versions": true,
        "can-read-state-outputs": true,
        "can-create-state-versions": true,
        "can-queue-apply": true,
        "can-lock": true,
        "can-unlock": true,
        "can-force-unlock": true,
        "can-read-settings": true,
        "can-manage-tags": true,
        "can-manage-run-tasks": true,
        "can-force-delete": true,
        "can-manage-assessments": true,
        "can-manage-ephemeral-workspaces": true,
        "can-read-assessment-results": true,
        "can-queue-destroy": true
      },
      "actions": {
        "is-destroyable": true
      },
      "description": null,
      "file-triggers-enabled": true,
      "trigger-prefixes": [],
      "trigger-patterns": [],
      "assessments-enabled": false,
      "last-assessment-result-at": null,
      "source": "tfe-module",
      "source-name": null,
      "source-url": null,
      "source-module-id": "private/my-organization/lambda/aws/1.0.9",
      "no-code-upgrade-available": false,
      "tag-names": [],
      "setting-overwrites": {
        "execution-mode": false,
        "agent-pool": false
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      },
      "current-run": {
        "data": null
      },
      "latest-run": {
        "data": null
      },
      "outputs": {
        "data": []
      },
      "remote-state-consumers": {
        "links": {
          "related": "/api/v2/workspaces/ws-qACTToFUM5BvDKhC/relationships/remote-state-consumers"
        }
      },
      "current-state-version": {
        "data": null
      },
      "current-configuration-version": {
        "data": {
          "id": "cv-vizi2p3mnrt3utgA",
          "type": "configuration-versions"
        },
        "links": {
          "related": "/api/v2/configuration-versions/cv-vizi2p3mnrt3utgA"
        }
      },
      "agent-pool": {
        "data": null
      },
      "readme": {
        "data": null
      },
      "project": {
        "data": {
          "id": "prj-yuEN6sJVra5t6XVy",
          "type": "projects"
        }
      },
      "current-assessment-result": {
        "data": null
      },
      "no-code-module-version": {
        "data": {
          "id": "nocodever-vFcQjZLs3ZHTe4TU",
          "type": "no-code-module-versions"
        }
      },
      "vars": {
        "data": []
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-organization/workspaces/no-code-workspace",
      "self-html": "/app/my-organization/workspaces/no-code-workspace"
    }
  }
}

Initiate a no-code workspace update

Upgrading a workspace's no-code provisioning settings is a multi-step process.

  1. Use this API to initiate the update. HCP Terraform starts a new plan, which describes the resources to add, update, or remove from the workspace.
  2. Poll the read workspace upgrade plan status API to wait for HCP Terraform to complete the plan.
  3. Use the confirm and apply a workspace upgrade plan API to complete the workspace upgrade.

POST /no-code-modules/:no_code_module_id/workspaces/:id/upgrade

Parameter Description
:no_code_module_id The ID of the no-code module.
:id The ID of the workspace.

Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path Type Default Description
data.type string Must be "workspaces".
data.relationships.vars.data[].type string Must be "vars".
data.relationships.vars.data[].attributes.key string The name of the variable.
data.relationships.vars.data[].attributes.value string "" The value of the variable.
data.relationships.vars.data[].attributes.description string The description of the variable.
data.relationships.vars.data[].attributes.category string Whether this is a Terraform or environment variable. Valid values are "terraform" or "env".
data.relationships.vars.data[].attributes.hcl boolean false Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables.
data.relationships.vars.data[].attributes.sensitive boolean false Whether the value is sensitive. If true then the variable is written once and not visible thereafter.

Sample Payload

{
  "data": {
    "type": "workspaces",
    "relationships": {
        "vars": {
        "data": [
          {
            "type": "vars",
            "attributes": {
              "key": "region",
              "value": "eu-central-1",
              "category": "terraform",
              "hcl": true,
              "sensitive": false,
            }
          },
          {
            "type": "vars",
            "attributes": {
              "key": "ami",
              "value": "ami‑077062",
              "category": "terraform",
              "hcl": true,
              "sensitive": false,
            }
          }
        ]
      }
    }
  }
}

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces/ws-qACTToFUM5BvDKhC/upgrade

Sample Response

{
  "data": {
    "id": "run-Cyij8ctBHM1g5xdX",
    "type": "workspace-upgrade",
    "attributes": {
      "status": "planned",
      "plan-url": "https://app.terraform.io/app/my-organization/no-code-workspace/runs/run-Cyij8ctBHM1g5xdX"
    },
    "relationships": {
      "workspace": {
        "data": {
          "id": "ws-VvKtcfueHNkR6GqP",
          "type": "workspaces"
        }
      }
    }
  }
}

Read workspace upgrade plan status

This endpoint returns the plan details and status for updating a workspace to new no-code provisioning settings.

GET /no-code-modules/:no_code_module_id/workspaces/:workspace_id/upgrade/:id

Parameter Description
:no_code_module_id The ID of the no-code module.
:workspace_id The ID of workspace.
:id The ID of update.

Returns the details of a no-code workspace update run, including the run's current state, such as pending, fetching, planning, planned, or cost_estimated. Refer to Run States and Stages for more information on the states a run can return.

Status Response Reason
200 JSON API document (type: "workspace-upgrade") Success
404 JSON API error object Workspace upgrade not found, or user unauthorized to perform action

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces/ws-qACTToFUM5BvDKhC/upgrade/run-Cyij8ctBHM1g5xdX

Sample Response

{
  "data": {
    "id": "run-Cyij8ctBHM1g5xdX",
    "type": "workspace-upgrade",
    "attributes": {
      "status": "planned_and_finished",
      "plan-url": "https://app.terraform.io/app/my-organization/no-code-workspace/runs/run-Cyij8ctBHM1g5xdX"
    },
    "relationships": {
      "workspace": {
        "data": {
          "id": "ws-VvKtcfueHNkR6GqP",
          "type": "workspaces"
        }
      }
    }
  }
}

Confirm and apply a workspace upgrade plan

Use this endpoint to confirm an update and finalize the update for a workspace to use new no-code provisioning settings.

POST /no-code-modules/:no_code_module_id/workspaces/:workspace_id/upgrade/:id

Parameter Description
:no_code_module_id The ID of the no-code module.
:workspace_id The ID of workspace.
:id The ID of update.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces/ws-qACTToFUM5BvDKhC/upgrade/run-Cyij8ctBHM1g5xdX

Sample Response

{ "Workspace update completed" }