RetroSearch Browse

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://developer.hashicorp.com/terraform/enterprise/api-docs/policy-sets below:

/policy-sets API reference for Terraform Enterprise | Terraform

Policy Enforcement lets you use the policy-as-code frameworks Sentinel and Open Policy Agent (OPA) to apply policy checks to HCP Terraform workspaces.

Policy sets are collections of policies that you can apply globally or to specific projects and workspaces. For each run in the selected workspaces, HCP Terraform checks the Terraform plan against the policy set.

This API provides endpoints to create, read, update, and delete policy sets in an HCP Terraform organization. To view and manage individual policies, use the Policies API.

Many of these endpoints let you create policy sets from a designated repository in a Version Control System (VCS). For more information about how to configure a policy set VCS repository, refer to Sentinel Policy Set VCS Repositories and OPA Policy Set VCS Repositories.

Instead of connecting HCP Terraform to a VCS repository, you can use the the Policy Set Versions endpoint to create an entire policy set from a tar.gz file.

Interacting with policy sets requires permission to manage policies. (More about permissions.)

POST /organizations/:organization_name/policy-sets

Parameter Description :organization_name The organization to create the policy set in. The organization must already exist in the system, and the token authenticating the API request must have permission to manage policies. (More about permissions.) 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 "policy-sets". data.attributes.name string The name of the policy set. Can include letters, numbers, -, and _. data.attributes.description string null Text describing the policy set's purpose. This field supports Markdown and appears in the HCP Terraform UI. data.attributes.global boolean false Whether HCP Terraform should automatically apply this policy set to all of an organization's workspaces. data.attributes.kind string sentinel The policy-as-code framework associated with the policy. Valid values are sentinel and opa. data.attributes.overridable boolean false Whether or not users can override this policy when it fails during a run. Valid for sentinel policies only if agent-enabled is set to true. data.attributes.vcs-repo object null VCS repository information. When present, HCP Terraform sources the policies and configuration from the specified VCS repository. This attribute and policies relationships are mutually exclusive, and you cannot use them simultaneously. data.attributes.vcs-repo.branch string null The branch of the VCS repository where HCP Terraform should retrieve the policy set. If empty, HCP Terraform uses the default branch. data.attributes.vcs-repo.identifier string The VCS repository identifier in the format <namespace>/<repo>. For example, hashicorp/my-policy-set. The format for Azure DevOps is <org>/<project>/_git/<repo>. data.attributes.vcs-repo.oauth-token-id string The OAuth Token ID HCP Terraform should use to connect to the VCS host. This value must not be specified if github-app-installation-id is specified. data.attributes.vcs-repo.github-app-installation-id string The VCS Connection GitHub App Installation to use. Find this ID on the account settings page. Requires previously authorizing the GitHub App and generating a user-to-server token. Manage the token from Account Settings within HCP Terraform. You can not specify this value if oauth-token-id is specified. data.attributes.vcs-repo.ingress-submodules boolean false Whether HCP Terraform should instantiate repository submodules when retrieving the policy set. data.attributes.policies-path string null The VCS repository subdirectory that contains the policies for this policy set. HCP Terraform ignores files and directories outside of this sub-path and does not update the policy set when those files change. This attribute is only valid when you specify a VCS repository for the policy set. data.relationships.projects.data[] array[object] [] A list of resource identifier objects that defines which projects are associated with the policy set. These objects must contain id and type properties, and the type property must be projects. For example, { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }. You can only specify this attribute when data.attributes.global is false. data.relationships.workspaces.data[] array[object] [] A list of resource identifier objects that defines which workspaces are associated with the policy set. These objects must contain id and type properties, and the type property must be workspaces. For example, { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }. Obtain workspace IDs from the workspace's settings page or the Show Workspace endpoint. You can only specify this attribute when data.attributes.global is false. data.relationships.workspace-exclusions.data[] array[object] [] A list of resource identifier objects specifying which workspaces HCP Terraform excludes from a policy set's enforcement. These objects must contain id and type properties, and the type property must be workspaces. For example, { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" }. data.relationships.policies.data[] array[object] [] A list of resource identifier objects that defines which policies are members of the policy set. These objects must contain id and type properties, and the type property must be policies. For example, { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }. data.attributes.agent-enabled boolean false Only valid for sentinel policy sets. Whether this policy set should run as a policy evaluation in the HCP Terraform agent. data.attributes.policy-tool-version string latest The version of the tool that HCP Terraform uses to evaluate policies. You can only set a policy tool version for 'sentinel' policy sets if agent-enabled is true. Sample Payload

{
  "data": {
    "type": "policy-sets",
    "attributes": {
      "name": "production",
      "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
      "global": false,
      "kind": "sentinel",
      "agent-enabled": true,
      "policy-tool-version": "0.23.0",
      "overridable": true,
      "policies-path": "/policy-sets/foo",
      "vcs-repo": {
        "branch": "main",
        "identifier": "hashicorp/my-policy-sets",
        "ingress-submodules": false,
        "oauth-token-id": "ot-7Fr9d83jWsi8u23A"
      }
    },
    "relationships": {
      "projects": {
        "data": [
          { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }
        ]
      },
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
        ]
      },
      "workspace-exclusions": {
        "data": [
          { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" }
        ]
      }
    }
  }
}

Sample payload with individual policy relationships

{
  "data": {
    "type": "policy-sets",
    "attributes": {
      "name": "production",
      "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
      "kind": "sentinel",
      "global": false,
      "agent-enabled": true,
      "policy-tool-version": "0.23.0",
      "overridable": true
    },
    "relationships": {
      "policies": {
        "data": [
          { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }
        ]
      },
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
        ]
      }
    }
  }
}

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/policy-sets

Sample Response

{
  "data": {
    "id":"polset-3yVQZvHzf5j3WRJ1",
    "type":"policy-sets",
    "attributes": {
      "name": "production",
      "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
      "kind": "sentinel",
      "global": false,
      "agent-enabled": true,
      "policy-tool-version": "0.23.0",
      "overridable": true,
      "workspace-count": 1,
      "policies-path": "/policy-sets/foo",
      "versioned": true,
      "vcs-repo": {
        "branch": "main",
        "identifier": "hashicorp/my-policy-sets",
        "ingress-submodules": false,
        "oauth-token-id": "ot-7Fr9d83jWsi8u23A"
      },
      "created-at": "2018-09-11T18:21:21.784Z",
      "updated-at": "2018-09-11T18:21:21.784Z"
    },
    "relationships": {
      "organization": {
        "data": { "id": "my-organization", "type": "organizations" }
      },
      "projects": {
        "data": [
          { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }
        ]
      },      
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
        ]
      },
      "workspace-exclusions": {
        "data": [
          { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" }
        ]
      },
    },
    "links": {
      "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1"
    }
  }
}

Sample response with individual policy relationships

{
  "data": {
    "id":"polset-3yVQZvHzf5j3WRJ1",
    "type":"policy-sets",
    "attributes": {
      "name": "production",
      "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
      "kind": "sentinel",
      "global": false,
      "agent-enabled": true,
      "policy-tool-version": "0.23.0",
      "overridable": true,
      "policy-count": 1,
      "workspace-count": 1,
      "versioned": false,
      "created-at": "2018-09-11T18:21:21.784Z",
      "updated-at": "2018-09-11T18:21:21.784Z"
    },
    "relationships": {
      "organization": {
        "data": { "id": "my-organization", "type": "organizations" }
      },
      "policies": {
        "data": [
          { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }
        ]
      },
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
        ]
      }
    },
    "links": {
      "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1"
    }
  }
}

GET /organizations/:organization_name/policy-sets

Parameter Description :organization_name The organization to list policy sets for. Query Parameters

This endpoint supports pagination with standard URL query parameters; remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter Description filter[versioned] Optional. Allows filtering policy sets based on whether they are versioned (VCS-managed or API-managed), or use individual policy relationships. Accepts a boolean true/false value. A true value returns versioned sets, and a false value returns sets with individual policy relationships. If omitted, all policy sets are returned. filter[kind] Optional. If specified, restricts results to those with the matching policy kind value. Valid values are sentinel and opa. include Optional. Enables you to include related resource data. Value must be a comma-separated list containing one or more of projects, workspaces, workspace-exclusions, policies, newest_version, or current_version. See the relationships section for details. page[number] Optional. If omitted, the endpoint will return the first page. page[size] Optional. If omitted, the endpoint will return 20 policy sets per page. search[name] Optional. Allows searching the organization's policy sets by name. Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/organizations/my-organization/policy-sets

Sample Response

{
  "data": [
    {
      "id":"polset-3yVQZvHzf5j3WRJ1",
      "type":"policy-sets",
      "attributes": {
        "name": "production",
        "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
        "kind": "sentinel",
        "global": false,
        "agent-enabled": true,
        "policy-tool-version": "0.23.0",
        "overridable": true,
        "workspace-count": 1,
        "policies-path": "/policy-sets/foo",
        "versioned": true,
        "vcs-repo": {
          "branch": "main",
          "identifier": "hashicorp/my-policy-sets",
          "ingress-submodules": false,
          "oauth-token-id": "ot-7Fr9d83jWsi8u23A"
        },
        "created-at": "2018-09-11T18:21:21.784Z",
        "updated-at": "2018-09-11T18:21:21.784Z"
      },
      "relationships": {
        "organization": {
          "data": { "id": "my-organization", "type": "organizations" }
        },
        "projects": {
          "data": [
            { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }
          ]
        },        
        "workspaces": {
          "data": [
            { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
          ]
        },
        "workspace-exclusions": {
          "data": [
            { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" }
          ]
        },
      },
      "links": {
        "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1"
      }
    }
  ]
}

Sample response with individual policy relationships

{
  "data": [
    {
      "id":"polset-3yVQZvHzf5j3WRJ1",
      "type":"policy-sets",
      "attributes": {
        "name": "production",
        "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
        "kind": "sentinel",
        "global": false,
        "agent-enabled": true,
        "policy-tool-version": "0.23.0",
        "overridable": true,
        "policy-count": 1,
        "workspace-count": 1,
        "versioned": false,
        "created-at": "2018-09-11T18:21:21.784Z",
        "updated-at": "2018-09-11T18:21:21.784Z"
      },
      "relationships": {
        "organization": {
          "data": { "id": "my-organization", "type": "organizations" }
        },
        "policies": {
          "data": [
            { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }
          ]
        },
        "workspaces": {
          "data": [
            { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
          ]
        }
      },
      "links": {
        "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1"
      }
    },
  ]
}

GET /policy-sets/:id

Parameter Description :id The ID of the policy set to show. Refer to List Policy Sets for reference information about finding IDs. Parameter Description include Optional. Enables you to include related resource data. Value must be a comma-separated list containing one or more of projects, workspaces, workspace-exclusions, policies, newest_version, or current_version. See the relationships section for details. Sample Request

curl --request GET \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1?include=current_version

Sample Response

{
  "data": {
    "id":"polset-3yVQZvHzf5j3WRJ1",
    "type":"policy-sets",
    "attributes": {
      "name": "production",
      "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
      "kind": "sentinel",
      "global": false,
      "agent-enabled": true,
      "policy-tool-version": "0.23.0",
      "overridable": true,
      "policy-count": 0,
      "workspace-count": 1,
      "policies-path": "/policy-sets/foo",
      "versioned": true,
      "vcs-repo": {
        "branch": "main",
        "identifier": "hashicorp/my-policy-sets",
        "ingress-submodules": false,
        "oauth-token-id": "ot-7Fr9d83jWsi8u23A"
      },
      "created-at": "2018-09-11T18:21:21.784Z",
      "updated-at": "2018-09-11T18:21:21.784Z"
    },
    "relationships": {
      "organization": {
        "data": { "id": "my-organization", "type": "organizations" }
      },
      "current-version": {
        "data": {
          "id": "polsetver-m4yhbUBCgyDVpDL4",
          "type": "policy-set-versions"
        }
      },
      "projects": {
        "data": [
          { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }
        ]
      },      
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
        ]
      },
      "workspace-exclusions": {
        "data": [
          { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" }
        ]
      },
    },
    "links": {
      "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1"
    }
  },
  "included": [
    {
      "id": "polsetver-m4yhbUBCgyDVpDL4",
      "type": "policy-set-versions",
      "attributes": {
        "source": "github",
        "status": "ready",
        "status-timestamps": {
          "ready-at": "2019-06-21T21:29:48+00:00",
          "ingressing-at": "2019-06-21T21:29:47+00:00"
        },
        "error": null,
        "ingress-attributes": {
          "commit-sha": "8766a423cb902887deb0f7da4d9beaed432984bb",
          "commit-url": "https://github.com/hashicorp/my-policy-sets/commit/8766a423cb902887deb0f7da4d9beaed432984bb",
          "identifier": "hashicorp/my-policy-sets"
        },
        "created-at": "2019-06-21T21:29:47.792Z",
        "updated-at": "2019-06-21T21:29:48.887Z"
      },
      "relationships": {
        "policy-set": {
          "data": {
            "id": "polset-a2mJwtmKygrA11dh",
            "type": "policy-sets"
          }
        }
      },
      "links": {
        "self": "/api/v2/policy-set-versions/polsetver-E4S7jz8HMjBienLS"
      }
    }
  ]
}

Sample response with individual policy relationships

{
  "data": {
    "id":"polset-3yVQZvHzf5j3WRJ1",
    "type":"policy-sets",
    "attributes": {
      "name": "production",
      "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
      "kind": "sentinel",
      "global": false,
      "agent-enabled": true,
      "policy-tool-version": "0.23.0",
      "overridable": true,
      "policy-count": 1,
      "workspace-count": 1,
      "versioned": false,
      "created-at": "2018-09-11T18:21:21.784Z",
      "updated-at": "2018-09-11T18:21:21.784Z",
    },
    "relationships": {
      "organization": {
        "data": { "id": "my-organization", "type": "organizations" }
      },
      "policies": {
        "data": [
          { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }
        ]
      },
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
        ]
      }
    },
    "links": {
      "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1"
    }
  }
}

Note: The data.relationships.projects and data.relationships.workspaces refer to the projects and workspaces attached to the policy set. HCP Terraform omits these keys for policy sets marked as global, which are implicitly related to all of the organization's workspaces.

PATCH /policy-sets/:id

Parameter Description :id The ID of the policy set to update. Refer to List Policy Sets for reference information about finding IDs. 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 "policy-sets". data.attributes.name string (previous value) The name of the policy set. Can include letters, numbers, -, and _. data.attributes.description string (previous value) A description of the set's purpose. This field supports markdown and appears in the HCP Terraform UI. data.attributes.global boolean (previous value) Whether or not the policies in this set should be checked in all of the organization's workspaces or only in workspaces directly attached to the set. data.attributes.vcs-repo object (previous value) VCS repository information. When present, HCP Terraform sources the policies and configuration from the specified VCS repository instead of using definitions from HCP Terraform. Note that this option and policies relationships are mutually exclusive and may not be used simultaneously. data.attributes.vcs-repo.branch string (previous value) The branch of the VCS repo. When empty, HCP Terraform uses the VCS provider's default branch value. data.attributes.vcs-repo.identifier string (previous value) The VCS repository identifier in the the following format: <namespace>/<repo>. An example identifier in GitHub is hashicorp/my-policy-set. The format for Azure DevOps is <org>/<project>/_git/<repo>. data.attributes.vcs-repo.oauth-token-id string (previous value) The OAuth token ID to use to connect to the VCS host. data.attributes.vcs-repo.ingress-submodules boolean (previous value) Determines whether HCP Terraform instantiates repository submodules during the clone operation. data.attributes.policies-path boolean (previous value) The subdirectory of the attached VCS repository that contains the policies for this policy set. HCP Terraform ignores files and directories outside of the sub-path. Changes to the unrelated files do not update the policy set. You can only enable this option when a VCS repository is present. data.relationships.projects array[object] (previous value) An array of references to projects that the policy set should be assigned to. Sending an empty array clears all project assignments. You can only specify this attribute when data.attributes.global is false. data.relationships.workspaces array[object] (previous value) An array of references to workspaces that the policy set should be assigned to. Sending an empty array clears all workspace assignments. You can only specify this attribute when data.attributes.global is false. data.relationships.workspace-exclusions array[object] (previous value) An array of references to excluded workspaces that HCP Terraform will not enforce this policy set upon. Sending an empty array clears all exclusions assignments. data.attributes.agent-enabled boolean false Only valid for sentinel policy sets. Whether this policy set should run as a policy evaluation in the HCP Terraform agent. data.attributes.policy-tool-version string latest The version of the tool that HCP Terraform uses to evaluate policies. You can only set a policy tool version for 'sentinel' policy sets if agent-enabled is true. Sample Payload

{
  "data": {
    "type": "policy-sets",
    "attributes": {
      "name": "workspace-scoped-policy-set",
      "description": "Policies added to this policy set will be enforced on specified workspaces",
      "global": false,
      "agent-enabled": true,
      "policy-tool-version": "0.23.0"
    },
    "relationships": {
      "projects": {
        "data": [
          { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }
        ]
      },
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
        ]
      },
      "workspace-exclusions": {
        "data": [
          { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" }
        ]
      }
    }
  }
}

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/policy-sets/polset-3yVQZvHzf5j3WRJ1

Sample Response

{
  "data": {
    "id":"polset-3yVQZvHzf5j3WRJ1",
    "type":"policy-sets",
    "attributes": {
      "name": "workspace-scoped-policy-set",
      "description": "Policies added to this policy set will be enforced on specified workspaces",
      "global": false,
      "kind": "sentinel",
      "agent-enabled": true,
      "policy-tool-version": "0.23.0",
      "overridable": true,
      "policy-count": 1,
      "workspace-count": 1,
      "versioned": false,
      "created-at": "2018-09-11T18:21:21.784Z",
      "updated-at": "2018-09-11T18:21:21.784Z"
    },
    "relationships": {
      "organization": {
        "data": { "id": "my-organization", "type": "organizations" }
      },
      "policies": {
        "data": [
          { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }
        ]
      },
      "projects": {
        "data": [
          { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }
        ]
      },
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
        ]
      },
      "workspace-exclusions": {
        "data": [
          { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" }
        ]
      }
    },
    "links": {
      "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1"
    }
  }
}

POST /policy-sets/:id/relationships/policies

Parameter Description :id The ID of the policy set to add policies to. Refer to List Policy Sets for reference information about finding IDs.

Note: This endpoint may only be used when there is no VCS repository associated with the policy set.

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[] array[object] A list of resource identifier objects that defines which policies will be added to the set. These objects must contain id and type properties, and the type property must be policies (e.g. { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }). Sample Payload

{
  "data": [
    { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" },
    { "id": "pol-2HRvNs49EWPjDqT1", "type": "policies" }
  ]
}

Sample Request

curl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/policies

POST /policy-sets/:id/relationships/projects

Parameter Description :id The ID of the policy set to attach to projects. Refer to List Policy Sets for reference information about finding IDs.

Note: You can not attach global policy sets to individual projects.

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[] array[object] A list of resource identifier objects that defines which projects to attach the policy set to. These objects must contain id and type properties, and the type property must be projects (e.g. { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }). Sample Payload

{
  "data": [
    { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" },
    { "id": "prj-2HRvNs49EWPjDqT1", "type": "projects" }
  ]
}

Sample Request

curl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/projects

POST /policy-sets/:id/relationships/workspaces

Parameter Description :id The ID of the policy set to attach to workspaces. Refer to List Policy Sets for reference information about finding IDs.

Note: Policy sets marked as global cannot be attached to individual workspaces.

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[] array[object] A list of resource identifier objects that defines the workspaces the policy set will be attached to. These objects must contain id and type properties, and the type property must be workspaces (e.g. { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }). Sample Payload

{
  "data": [
    { "id": "ws-u3S5p2Uwk21keu1s", "type": "workspaces" },
    { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
  ]
}

Sample Request

curl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/workspaces

POST /policy-sets/:id/relationships/workspace-exclusions

Parameter Description :id The ID of a policy set that you want HCP Terraform to exclude from the workspaces you specify. Refer to List Policy Sets for reference information about finding IDs. Status Response Reason 204 No Content The request was successful 404 JSON API error object Policy set not found or user unauthorized to perform action 422 JSON API error object Malformed request body (one or more excluded workspaces not found, wrong types, etc.) 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[] array[object] A list of resource identifier objects that defines the excluded workspaces the policy set will be attached to. These objects must contain id and type properties, and the type property must be workspaces (e.g. { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }). Sample Payload

{
  "data": [
    { "id": "ws-u3S5p2Uwk21keu1s", "type": "workspaces" },
    { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
  ]
}

Sample Request

curl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/workspace-exclusions

DELETE /policy-sets/:id/relationships/policies

Parameter Description :id The ID of the policy set to remove policies from. Refer to List Policy Sets for reference information about finding IDs.

Note: This endpoint may only be used when there is no VCS repository associated with the policy set.

Request Body

This DELETE 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[] array[object] A list of resource identifier objects that defines which policies will be removed from the set. These objects must contain id and type properties, and the type property must be policies (e.g. { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }). Sample Payload

{
  "data": [
    { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" },
    { "id": "pol-2HRvNs49EWPjDqT1", "type": "policies" }
  ]
}

Sample Request

curl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  --request DELETE \
  --data @payload.json \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/policies

DELETE /policy-sets/:id/relationships/projects

Parameter Description :id The ID of the policy set you want to detach from the specified projects. Refer to List Policy Sets for reference information about finding IDs.

Note: You can not attach global policy sets to individual projects.

Request Body

This DELETE 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[] array[object] A list of resource identifier objects that defines the projects the policy set will be detached from. These objects must contain id and type properties, and the type property must be projects. For example, { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }. Sample Payload

{
  "data": [
    { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" },
    { "id": "prj-2HRvNs49EWPjDqT1", "type": "projects" }
  ]
}

Sample Request

curl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  --request DELETE \
  --data @payload.json \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/projects

DELETE /policy-sets/:id/relationships/workspaces

Parameter Description :id The ID of the policy set to detach from workspaces. Refer to List Policy Sets for reference information about finding IDs.

Note: Policy sets marked as global cannot be detached from individual workspaces.

Request Body

This DELETE 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[] array[object] A list of resource identifier objects that defines which workspaces the policy set will be detached from. These objects must contain id and type properties, and the type property must be workspaces (e.g. { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }). Obtain workspace IDs from the workspace settings or the Show Workspace endpoint. Sample Payload

{
  "data": [
    { "id": "ws-u3S5p2Uwk21keu1s", "type": "workspaces" },
    { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
  ]
}

Sample Request

curl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  --request DELETE \
  --data @payload.json \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/workspaces

DELETE /policy-sets/:id/relationships/workspace-exclusions

Parameter Description :id The ID of the policy set HCP Terraform should reinclude (enforce) on the specified workspaces. Refer to List Policy Sets for reference information about finding IDs. Request Body

This DELETE 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[] array[object] A list of resource identifier objects that defines which workspaces HCP Terraform should reinclude (enforce) this policy set on. These objects must contain id and type properties, and the type property must be workspaces (e.g. { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }). Obtain workspace IDs from the workspace settings or the Show Workspace endpoint. Sample Payload

{
  "data": [
    { "id": "ws-u3S5p2Uwk21keu1s", "type": "workspaces" },
    { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
  ]
}

Sample Request

curl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  --request DELETE \
  --data @payload.json \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/workspace-exclusions

DELETE /policy-sets/:id

Parameter Description :id The ID of the policy set to delete. Refer to List Policy Sets for reference information about finding IDs. Status Response Reason 204 No Content Successfully deleted the policy set 404 JSON API error object Policy set not found, or user unauthorized to perform action Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1

For versioned policy sets which have no VCS repository attached, versions of policy code may be uploaded directly to the API by creating a new policy set version and, in a subsequent request, uploading a tarball (tar.gz) of data to it.

POST /policy-sets/:id/versions

Parameter Description :id The ID of the policy set to create a new version for. Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/versions

Sample Response

{
  "data": {
    "id": "polsetver-cXciu9nQwmk9Cfrn",
    "type": "policy-set-versions",
    "attributes": {
      "source": "tfe-api",
      "status": "pending",
      "status-timestamps": {},
      "error": null,
      "created-at": "2019-06-28T23:53:15.875Z",
      "updated-at": "2019-06-28T23:53:15.875Z"
    },
    "relationships": {
      "policy-set": {
        "data": {
          "id": "polset-ws1CZBzm2h5K6ZT5",
          "type": "policy-sets"
        }
      }
    },
    "links": {
      "self": "/api/v2/policy-set-versions/polsetver-cXciu9nQwmk9Cfrn",
      "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox..."
    }
  }
}

The upload link URL in the above response is valid for one hour after creation. Make a PUT request to this URL directly, sending the policy set contents in tar.gz format as the request body. Once uploaded successfully, you can request the Show Policy Set endpoint again to verify that the status has changed from pending to ready.

PUT https://archivist.terraform.io/v1/object/<UNIQUE OBJECT ID>

The URL is provided in the upload attribute in the policy-set-versions resource.

Sample Request

In the example below, policy-set.tar.gz is the local filename of the policy set version file to upload.

curl \
  --header "Content-Type: application/octet-stream" \
  --request PUT \
  --data-binary @policy-set.tar.gz \
  https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox...

GET /policy-set-versions/:id

Parameter Description :id The ID of the policy set version to show. Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request GET \
  https://app.terraform.io/api/v2/policy-set-versions/polsetver-cXciu9nQwmk9Cfrn

Sample Response

{
  "data": {
    "id": "polsetver-cXciu9nQwmk9Cfrn",
    "type": "policy-set-versions",
    "attributes": {
      "source": "tfe-api",
      "status": "pending",
      "status-timestamps": {},
      "error": null,
      "created-at": "2019-06-28T23:53:15.875Z",
      "updated-at": "2019-06-28T23:53:15.875Z"
    },
    "relationships": {
      "policy-set": {
        "data": {
          "id": "polset-ws1CZBzm2h5K6ZT5",
          "type": "policy-sets"
        }
      }
    },
    "links": {
      "self": "/api/v2/policy-set-versions/polsetver-cXciu9nQwmk9Cfrn",
      "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox..."
    }
  }
}

The upload link URL in the above response is valid for one hour after the created_at timestamp of the policy set version. Make a PUT request to this URL directly, sending the policy set contents in tar.gz format as the request body. Once uploaded successfully, you can request the Show Policy Set Version endpoint again to verify that the status has changed from pending to ready.

The GET endpoints above can optionally return related resources for policy sets, if requested with the include query parameter. The following resource types are available:

Resource Name Description current_version The most recent successful policy set version. newest_version The most recently created policy set version, regardless of status. Note that this relationship may include an errored and unusable version, and is intended to allow checking for VCS errors. policies Individually managed policies which are associated with the policy set. projects The projects this policy set applies to. workspaces The workspaces this policy set applies to. workspace-exclusions The workspaces excluded from this policy set's enforcement.

The following resource types may be included for policy set versions:

Resource Name Description policy_set The policy set associated with the specified policy set version.

The following relationships may be present in various responses for policy sets:

Resource Name Description current-version The most recent successful policy set version. newest-version The most recently created policy set version, regardless of status. Note that this relationship may include an errored and unusable version, and is intended to allow checking for VCS errors. organization The organization associated with the specified policy set. policies Individually managed policies which are associated with the policy set. projects The projects this policy set applies to. workspaces The workspaces this policy set applies to. workspace-exclusions The workspaces excluded from this policy set's enforcement.

The following relationships may be present in various responses for policy set versions:

Resource Name Description policy-set The policy set associated with the specified policy set version.

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4