Skip to content

Commit 3c548d5

Browse files
authored
feat(docs): document policy groups (#1489)
Signed-off-by: Jose I. Paris <jiparis@chainloop.dev>
1 parent 5915fe7 commit 3c548d5

File tree

1 file changed

+66
-0
lines changed

1 file changed

+66
-0
lines changed

docs/docs/reference/policies.mdx

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,3 +195,69 @@ For example
195195

196196
## How to write a Chainloop policy in Rego
197197
Check [this how-to](/guides/rego-policies) to know how you can write Chainloop policies in [Rego language](https://www.openpolicyagent.org/docs/latest/policy-language/#learning-rego).
198+
199+
200+
## Policy Groups
201+
202+
This feature allow operators to group related policies into one single entity that can be reused across the organization.
203+
With Policy Groups, materials and policies can be enforced in Chainloop contracts with little or no effort.
204+
205+
For example, they might want to create a "SBOM quality" group with some SBOM-related policies. The policy groups can be defined this way:
206+
```yaml
207+
# sbom-quality.yaml
208+
apiVersion: workflowcontract.chainloop.dev/v1
209+
kind: PolicyGroup
210+
metadata:
211+
name: sbom-quality
212+
description: This policy group applies a number of SBOM-related policies
213+
annotations:
214+
category: SBOM
215+
spec:
216+
inputs:
217+
- name: bannedLicenses
218+
description: comma separated list of licenses to ban
219+
required: true
220+
- name: bannedComponents
221+
description: comma separated list of components to ban
222+
required: true
223+
policies:
224+
materials:
225+
- name: sbom
226+
type: SBOM_CYCLONEDX_JSON
227+
policies:
228+
- ref: sbom-banned-licenses
229+
with:
230+
licenses: {{ inputs.bannedLicenses }}
231+
- ref: sbom-banned-components
232+
with:
233+
components: {{ inputs.bannedComponents }}
234+
```
235+
236+
### Using Policy Groups
237+
238+
This policy group could be applied to any contract:
239+
```yaml
240+
schemaVersion: v1
241+
materials: []
242+
policyGroups:
243+
- ref: file://groups/sbom-quality-group.yaml
244+
with:
245+
bannedComponents: log4j@2.14.1
246+
bannedLicenses: AGPL-1.0-only, AGPL-1.0-or-later, AGPL-3.0-only, AGPL-3.0-or-later
247+
```
248+
249+
As we introduced earlier, policy groups define both materials and policies applied to them. Once they are included to a contract,
250+
they become part of the contract. From this point of view, they can be seen as subcontracts.
251+
252+
### Policy group parameters
253+
254+
In the same way as [policies](policies#policy-arguments), groups can accept arguments, which are specified in the `inputs` section.
255+
Then those inputs can be passed down to policies using interpolation.
256+
257+
In the example above, `bannedComponents` input parameter (which is mandatory) is passed to the underlying policy with the expression `{{ inputs.banneComponents }}`
258+
```yaml
259+
- ref: sbom-banned-components
260+
with:
261+
components: {{ inputs.bannedComponents }}
262+
```
263+

0 commit comments

Comments
 (0)