Policy Groups¶
The PolicyGroup resource¶
A policy group represents the collection of OPA policies stored in a VCS repository.
When linked to an environment, the policy group will participate in the policy check phase of every run in that environment.
Key path
Description
type* (string)
Available values:policy-groups
id (string)
attributes.error-message (string)
This field contains the error description when the group’s status is
errored
.attributes.name* (string)
The policy group name must be unique within the account and contain only letters, numbers, dashes
attributes.opa-version (string)
The version of Open Policy Agent to use for the policy evaluation.
If omitted, the system default version is assigned.
attributes.status (string)
Policy group current status.
fetching
- waiting for policies to be synchronized with VCS.
active
- synchronization completed, policy group is ready.
errored
- synchronization has failed. Attributeerror-message
contains the details.attributes.vcs-repo.branch (string)
Branch of a repository the policy group is associated with. If omitted, the repository default branch will be used.
attributes.vcs-repo.identifier* (string)
A reference to your VCS repository.
For GitHub, GitHub Enterprise and GitLab the format is
<org>/<repo>
. For Azure DevOps Services the format is<org>/<project>/<repo>
.attributes.vcs-repo.path (string)
The sub-directory of the VCS repository where OPA policies are stored. The
scalr-policy.hcl
file must exist in this directory. Files and directories outside this directory will be ignored during a sync from VCS, and changing them won’t trigger a policy group update.If omitted or submitted as an empty string, this defaults to the repository’s root.
relationships.account* (object)
The account this policy group belongs to.
relationships.account.data.type* (string)
Available values:accounts
relationships.account.data.id* (string)
relationships.environments (object)
List of environments this policy group is linked to.
relationships.environments.data* (array)
relationships.policies (object)
List of OPA policies this group contains.
relationships.policies.data* (array)
relationships.vcs-provider* (object)
The policy group’s VCS provider.
relationships.vcs-provider.data.type* (string)
Available values:vcs-providers
relationships.vcs-provider.data.id* (string)
relationships.vcs-revision (object)
The Git commit information when the policy group was fetched from VCS.
relationships.vcs-revision.data.type* (string)
Available values:vcs-revisions
relationships.vcs-revision.data.id* (string)
relationships.workspaces (object)
List of workspaces affected by this policy group.
relationships.workspaces.data* (array)
links.self (string)
The Policy resource¶
A policy provides details of a single OPA policy as declared in scalr-policy.hcl.
Key path
Description
type* (string)
Available values:policies
id (string)
attributes.enabled (boolean)
If set to
false
, the policy will not be evaluated during a run.attributes.enforced-level (string)
Available values:hard-mandatory
,soft-mandatory
,advisory
The policy’s enforcement level.
hard-mandatory
- cannot be overridden.
soft-mandatory
- can be overridden through an approval by account admins and other authorized roles.
advisory
- provides a warning only.attributes.name (string)
The name of the policy.
relationships.policy-group (object)
The policy group this policy belongs to.
relationships.policy-group.data.type* (string)
Available values:policy-groups
relationships.policy-group.data.id* (string)
links.self (string)
Get a Policy¶
-
GET
/api/iacp/v3/policies/{policy}
¶ Show details of a specific OPA policy.
- Parameters
policy (string) – The ID of the policy to show.
Example Request:
GET /api/iacp/v3/policies/{policy} HTTP/1.1 Host: my.scalr.io Prefer: profile=preview
- Status Codes
200 OK – Success.
403 Forbidden – User unauthorized to perform this action.
404 Not Found – User not authorized or policy not found.
4XX – Client error.
5XX – Server error.
List Policy Groups¶
-
GET
/api/iacp/v3/policy-groups
¶ This endpoint returns a list of policy groups.
- Query Parameters
filter[master-policy-group] (string) – Filter dry groups by master policy group id
filter[policy-group] (string) – Filter by policy group id
filter[environment] (string) – Environment filter
filter[account] (string) – Account filter
filter[software-version] (string) – The ID of the software version
filter[name] (string) – The policy group name filter.
include (array) – The comma-separated list of relationship paths. (Available values:
account
,environments
,policies
,vcs-provider
,vcs-revision
,workspaces
)query (string) – Query string
sort (array) – The comma-separated list of attributes. (Available values:
account
,name
,status
)page[number] (string) – Page number
page[size] (string) – Page size
Example Request:
GET /api/iacp/v3/policy-groups HTTP/1.1 Host: my.scalr.io Prefer: profile=preview
- Status Codes
200 OK –
Success.
Example Respone:
HTTP/1.1 200 OK Content-Type: application/vnd.api+json Preference-Applied: profile=preview { "data": [ { "attributes": { "error-message": null, "name": "Tags", "opa-version": "0.29.4", "status": "active", "vcs-repo": { "branch": "master", "identifier": "my_org/repo", "path": "policies/tags" } }, "id": "pgrp-svsu1tn68mhevuo", "links": { "self": "https://my.scalr.io/api/iacp/v3/policy-groups/pgrp-svsu1tn68mhevuo" }, "relationships": { "account": { "data": { "id": "acc-svrcncgh453bi8g", "type": "accounts" } }, "environments": { "data": [ { "id": "env-svrcnchebt61e30", "type": "environments" }, { "id": "env-svrdqa8d7mhaimo", "type": "environments" } ] }, "policies": { "data": [ { "id": "policy-ta3cb9im2kdck4g", "type": "policies" }, { "id": "policy-tmttegdtd1rg0fg", "type": "policies" } ] }, "vcs-provider": { "data": { "id": "vcs-svsmeap82s0tsho", "type": "vcs-providers" } }, "vcs-revision": { "data": { "id": "vrb-svsu1tn54f6brfg", "type": "vcs-revisions" } }, "workspaces": { "data": [ { "id": "ws-tmtt98uuhs7n7do", "type": "workspaces" }, { "id": "ws-tmtt9e4fn037nq8", "type": "workspaces" }, { "id": "ws-tmtt9ir5ra2ta6o", "type": "workspaces" } ] } }, "type": "policy-groups" }, { "attributes": { "error-message": "scalr-policy.hcl not found in repository", "name": "Instance types", "opa-version": "0.29.4", "status": "errored", "vcs-repo": { "branch": "master", "identifier": "Scalr/tf-revizor-fixtures", "path": "policies/instances" } }, "id": "pgrp-svsu2pkubpob58o", "links": { "self": "https://my.scalr.io/api/iacp/v3/policy-groups/pgrp-svsu2pkubpob58o" }, "relationships": { "account": { "data": { "id": "acc-svrcncgh453bi8g", "type": "accounts" } }, "environments": null, "policies": null, "vcs-provider": { "data": { "id": "vcs-svsmeap82s0tsho", "type": "vcs-providers" } }, "vcs-revision": { "data": { "id": "vrb-svsu2pkt28f32go", "type": "vcs-revisions" } }, "workspaces": null }, "type": "policy-groups" } ], "included": null, "links": { "first": "https://my.scalr.io/api/iacp/v3/policy-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20", "last": "https://my.scalr.io/api/iacp/v3/policy-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20", "next": null, "prev": null, "self": "https://my.scalr.io/api/iacp/v3/policy-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20" }, "meta": { "pagination": { "current-page": 1, "next-page": null, "prev-page": null, "total-count": 2, "total-pages": 1 } } }
403 Forbidden – User unauthorized to perform this action.
4XX – Client error.
5XX – Server error.
Create a Policy Group¶
-
POST
/api/iacp/v3/policy-groups
¶ Create a new policy group in the account.
- Query Parameters
include (array) – The comma-separated list of relationship paths. (Available values:
account
,environments
,policies
,vcs-provider
,vcs-revision
,workspaces
)
Request body:
Key path
Description
data.type* (string)
Available values:policy-groups
data.id (string)
data.attributes.name* (string)
The policy group name must be unique within the account and contain only letters, numbers, dashes
data.attributes.opa-version (string)
The version of Open Policy Agent to use for the policy evaluation.
If omitted, the system default version is assigned.
data.attributes.vcs-repo.branch (string)
Branch of a repository the policy group is associated with. If omitted, the repository default branch will be used.
data.attributes.vcs-repo.identifier* (string)
A reference to your VCS repository.
For GitHub, GitHub Enterprise and GitLab the format is
<org>/<repo>
. For Azure DevOps Services the format is<org>/<project>/<repo>
.data.attributes.vcs-repo.path (string)
The sub-directory of the VCS repository where OPA policies are stored. The
scalr-policy.hcl
file must exist in this directory. Files and directories outside this directory will be ignored during a sync from VCS, and changing them won’t trigger a policy group update.If omitted or submitted as an empty string, this defaults to the repository’s root.
data.relationships.account* (object)
The account this policy group belongs to.
data.relationships.account.data.type* (string)
Available values:accounts
data.relationships.account.data.id* (string)
data.relationships.vcs-provider* (object)
The policy group’s VCS provider.
data.relationships.vcs-provider.data.type* (string)
Available values:vcs-providers
data.relationships.vcs-provider.data.id* (string)
Example Request:
POST /api/iacp/v3/policy-groups HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": { "attributes": { "name": "Limit cost", "opa-version": "0.30.2", "vcs-repo": { "branch": "master", "identifier": "my_org/repo", "path": "policies/cost" } }, "relationships": { "account": { "data": { "id": "acc-svrcncgh453bi8g", "type": "accounts" } }, "vcs-provider": { "data": { "id": "vcs-svsmeap82s0tsho", "type": "vcs-providers" } } }, "type": "policy-groups" } }
- Status Codes
Successfully created.
Example Respone:
HTTP/1.1 201 Created Content-Type: application/vnd.api+json Preference-Applied: profile=preview { "data": { "attributes": { "error-message": null, "name": "Limit cost", "opa-version": "0.30.2", "status": "fetching", "vcs-repo": { "branch": "master", "identifier": "my_org/repo", "path": "policies/cost" } }, "id": "pgrp-tmttm6aiq13a6bo", "links": { "self": "https://my.scalr.io/api/iacp/v3/policy-groups/pgrp-tmttm6aiq13a6bo" }, "relationships": { "account": { "data": { "id": "acc-svrcncgh453bi8g", "type": "accounts" } }, "environments": null, "policies": null, "vcs-provider": { "data": { "id": "vcs-svsmeap82s0tsho", "type": "vcs-providers" } }, "vcs-revision": { "data": { "id": "vrb-tmttm7g1b4nlvqo", "type": "vcs-revisions" } }, "workspaces": null }, "type": "policy-groups" }, "included": null, "meta": null }
403 Forbidden – User unauthorized to perform this action.
404 Not Found – Relationship not found or user unauthorized to perform action.
409 Conflict – Quota exceeded error.
422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).
4XX – Client error.
5XX – Server error.
Delete a Policy Group¶
-
DELETE
/api/iacp/v3/policy-groups/{policy_group}
¶ This endpoint deletes a policy group by ID. Only an unused policy group (that is not linked to any environment) can be removed.
- Parameters
policy_group (string) – The ID of the policy group to delete.
- Status Codes
204 No Content – Deleted.
403 Forbidden – User unauthorized to perform this action.
404 Not Found – Policy group not found or user unauthorized to perform action.
409 Conflict – Can’t be deleted. The policy group is in use.
4XX – Client error.
5XX – Server error.
Get a Policy Group¶
-
GET
/api/iacp/v3/policy-groups/{policy_group}
¶ Show details of a specific policy group.
- Parameters
policy_group (string) – The ID of the policy group to show.
- Query Parameters
include (array) – The comma-separated list of relationship paths. (Available values:
account
,environments
,policies
,vcs-provider
,vcs-revision
,workspaces
)
Example Request:
GET /api/iacp/v3/policy-groups/{policy_group} HTTP/1.1 Host: my.scalr.io Prefer: profile=preview
- Status Codes
200 OK – Success.
403 Forbidden – User unauthorized to perform this action.
404 Not Found – User not authorized or policy group not found.
4XX – Client error.
5XX – Server error.
Update a Policy Group¶
-
PATCH
/api/iacp/v3/policy-groups/{policy_group}
¶ This endpoint updates a policy group by ID.
- Parameters
policy_group (string) – The ID of the policy group to update.
- Query Parameters
include (array) – The comma-separated list of relationship paths. (Available values:
account
,environments
,policies
,vcs-provider
,vcs-revision
,workspaces
)
Request body:
Key path
Description
data.type* (string)
Available values:policy-groups
data.id (string)
data.attributes.name* (string)
The policy group name must be unique within the account and contain only letters, numbers, dashes
data.attributes.opa-version (string)
The version of Open Policy Agent to use for the policy evaluation.
If omitted, the system default version is assigned.
data.attributes.vcs-repo.branch (string)
Branch of a repository the policy group is associated with. If omitted, the repository default branch will be used.
data.attributes.vcs-repo.identifier* (string)
A reference to your VCS repository.
For GitHub, GitHub Enterprise and GitLab the format is
<org>/<repo>
. For Azure DevOps Services the format is<org>/<project>/<repo>
.data.attributes.vcs-repo.path (string)
The sub-directory of the VCS repository where OPA policies are stored. The
scalr-policy.hcl
file must exist in this directory. Files and directories outside this directory will be ignored during a sync from VCS, and changing them won’t trigger a policy group update.If omitted or submitted as an empty string, this defaults to the repository’s root.
data.relationships.account* (object)
The account this policy group belongs to.
data.relationships.account.data.type* (string)
Available values:accounts
data.relationships.account.data.id* (string)
data.relationships.vcs-provider* (object)
The policy group’s VCS provider.
data.relationships.vcs-provider.data.type* (string)
Available values:vcs-providers
data.relationships.vcs-provider.data.id* (string)
Example Request:
PATCH /api/iacp/v3/policy-groups/{policy_group} HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": { "attributes": { "name": "string", "opa-version": "string", "vcs-repo": { "branch": "string", "identifier": "string", "path": "string" } }, "id": "string", "relationships": { "account": { "data": { "id": "string", "type": "accounts" } }, "vcs-provider": { "data": { "id": "string", "type": "vcs-providers" } } }, "type": "policy-groups" } }
- Status Codes
200 OK – Success.
403 Forbidden – User unauthorized to perform this action.
404 Not Found – Policy group or relationship not found, or user unauthorized to perform action.
422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).
4XX – Client error.
5XX – Server error.