Policy Authoring
This document is meant to assist policy authors in creating and maintaining the policy rules defined in this repository.
1. Rule annotations
Policy rules must contain certain annotations that describe additional information about the rule.
-
title
: (required) short description of the policy rule. -
description
: (required) descriptive information about the policy rule, including possible remediation steps. -
custom
: (required) object holding additional non-default rego annotations.custom.foo
means thefoo
annotation nested under this object. -
custom.short_name
: (required) unique name of the policy rule. This is used as the value of thecode
attribute when reporting failures and warnings. It is also the value used for skipping the policy rule via the EnterpriseContractPolicy. It must not contain spaces. Words must be joined by_
, e.g.snake_case
. -
custom.failure_msg
: (required) message indicating the exact cause a policy rule did not pass. It should be as informative as possible to guide users towards remediation. The message can be in the form of a string template, allowing dynamic values to provide a more meaningful message. -
custom.effective_on
: (optional) time stamp string in the RFC3339 format. Defaults to"2022-01-01T00:00:00Z"
. A non-passing policy rule is classified as a warning, instead of a failure, if the date represented in thecustom.effective_on
annotation is in the future. This is a helpful mechanism to allow the introduction of a new policy rule while allowing a certain period of time for compliance. -
custom.rule_data
: (optional) specify additional data for the policy rule. The value must be an object where each key maps to an array of strings. This is a convenient mechanism to specify information that is used in the policy rule evaluation that may not be obvious to users. For example, the policy ruledisallowed_task_step_image
only allows certain registries to be used. The list of registries is defined in the annotationscustom.rule_data.allowed_registry_prefixes
, allowing a single source of truth for policy rule evaluation and documentation. For best results, each key in thecustom.rule_data
object should be a noun. -
custom.collections
: A list of strings representing a list of rule collections that the policy rule is included in.
The annotations must be defined at the rule
scope.
2. Package annotations
Package annotations can be used to give a title and description to a package. Use the package name "policy.<kind>.collection.<collectionName>" in an otherwise empty package for collection annotations.
-
title
: (required) short description of the rule collection. -
description
: (required) descriptive information about the rule collection.
See Open Policy Agent’s documentation for further reference on annotations.