Open Policy Agent (OPA) Validation
The Open Policy Agent (OPA) is the open-source industry standard for policy-as-code validation. It provides a general-purpose policy engine to unify policy enforcement across your stacks.
The OPA (pronounced “oh-pa”) language (Rego) is a high-level declarative language for specifying policy as code. Atmos has native support for the OPA decision-making engine to enforce policies across all the components in your stacks (e.g. for microservice configurations).
This is powerful stuff: because you can define many policies, it's possible to apply different policies depending on where a component is defined in the stacks. For example, it could validate differently based on environments or teams.
Use Cases
Use Open Policy Agent (OPA) policies to validate Atmos stacks and component configurations.
-
Validate component config (
vars
,settings
,backend
,env
,overrides
and other sections) using JSON Schema -
Check if the component config (including relations between different component variables) is correct to allow or deny component provisioning using OPA/Rego policies
Usage
Atmos validate component
command supports --schema-path
, --schema-type
and --module-paths
command line arguments.
If the arguments are not provided, Atmos will try to find and use the settings.validation
section defined in the component's YAML config.
Refer to atmos validate component CLI command for more information
Configure Component Validation
In atmos.yaml
, add the schemas
section:
atmos.yaml
In the component manifest, add
the settings.validation
section:
examples/quick-start-advanced/stacks/catalog/vpc/defaults.yaml
Add the following Rego package in the file stacks/schemas/opa/catalog/constants/constants.rego
:
examples/quick-start-advanced/stacks/schemas/opa/catalog/constants/constants.rego
Add the following OPA policy in the file stacks/schemas/opa/vpc/validate-vpc-component.rego
:
examples/quick-start-advanced/stacks/schemas/opa/vpc/validate-vpc-component.rego
Use One Policy File or Many
Atmos supports OPA policies for components validation in a single Rego file and in multiple Rego files.
As shown in the example above, you can define some Rego constants, modules and helper functions in a separate
file stacks/schemas/opa/catalog/constants/constants.rego
, and then import them into the main policy
file stacks/schemas/opa/vpc/validate-vpc-component.rego
.
You also need to specify the module_paths
attribute in the component's settings.validation
section.
The module_paths
attribute is an array of filesystem paths (folders or individual files) to the additional modules for schema validation.
Each path can be an absolute path or a path relative to schemas.opa.base_path
defined in atmos.yaml
.
If a folder is specified in module_paths
, Atmos will recursively process the folder and all its sub-folders and load all Rego files into the OPA
engine.
This allows you to separate the common OPA modules, constants and helper functions into a catalog of reusable Rego modules, and to structure your OPA policies to make them DRY.
Examples
Validate VPC Component in Stacks
Run the following commands to validate the component in the stacks:
Validate Before Provisioning
Try to run the following commands to provision the component in the stacks:
Since the OPA validation policies don't pass, Atmos does not allow provisioning the component in the stacks:
Advanced Policy Examples
examples/quick-start-advanced/stacks/schemas/opa/vpc/validate-vpc-component.rego
-
If a regex pattern in the 're_match' function contains a backslash to escape special chars (e.g. '.' or '-'), it must be escaped with another backslash when represented as a regular Go string ('\.', '\-').
-
The reason is that backslash is also used to escape special characters in Go strings like newline (\n).
-
If you want to match the backslash character itself, you'll need four slashes.
Policy Execution Context
Atmos allows enforcing custom governance rules based on metadata about Atmos commands and provides a powerful policy evaluation mechanism by passing structured metadata to OPA policies at runtime.
This metadata enables fine-grained control over when certain actions (like terraform apply
) are allowed or denied,
based on the context in which they're executed.
Policy Metadata
When Atmos runs a command, it supplies an input object to OPA policies that contains detailed contextual information, such as:
cli_args
: a list of the command line arguments and flags (e.g., executing theatmos terraform apply
command will generate the["terraform", "apply"]
list)vars
: a map of variables passed to the command, either via the stack config files or CLI flags- other contextual attributes such as the stack and component names
Policy Execution Context Example
Below is an OPA policy rule to enforce infrastructure governance during command execution.
Specifically, this rule blocks the execution of atmos terraform apply
if the variable foo
is set to the string "foo"
.
validate-component.rego
The rule checks if:
- The
cli_args
list has at least two items - The command (first item in the
cli_args
list) isterraform
- The subcommand (second item in the
cli_args
list) isapply
- The variable
foo
is set to"foo"
If all conditions are true, the rule generates an error message.
The generated error message is added to the errors
array.
Atmos interprets the presence of any messages in errors
as a policy violation and blocks the operation with the
following error: