Skip to main content

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.

tip

Refer to atmos validate component CLI command for more information


# Validate 'vpc' component using OPA policy in the 'plat-ue2-prod' stack
atmos validate component vpc -s plat-ue2-prod --schema-path vpc/validate-vpc-component.rego --schema-type opa

# Validate 'vpc' component using OPA policy in the 'plat-ue2-dev' stack with additional module paths 'catalog/constants'
atmos validate component vpc -s plat-ue2-dev --schema-path vpc/validate-vpc-component.rego --schema-type opa --module-paths catalog/constants

# Validate 'vpc' component using OPA policy in the 'plat-ue2-dev' stack with additional module paths 'catalog'
atmos validate component vpc -s plat-ue2-dev --schema-path vpc/validate-vpc-component.rego --schema-type opa --module-paths catalog

# Validate 'vpc' component in the 'plat-ue2-prod' stack
atmos validate component vpc -s plat-ue2-prod

# Validate 'vpc' component in the 'plat-ue2-dev' stack
atmos validate component vpc -s plat-ue2-dev

# Validate 'vpc' component in the 'plat-ue2-dev' stack with a timeout of 15 seconds
atmos validate component vpc -s plat-ue2-dev --timeout 15

Configure Component Validation​

In atmos.yaml, add the schemas section:

atmos.yaml

# Validation schemas for OPA for validating atmos stacks and components
schemas:
  # https://www.openpolicyagent.org
  opa:
    # Can also be set using `ATMOS_SCHEMAS_OPA_BASE_PATH` ENV var, or `--schemas-opa-dir` command-line arguments
    # Supports both absolute and relative paths
    base_path: "stacks/schemas/opa"

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:

atmos validate component vpc -s plat-ue2-prod

Mapping public IPs on launch is not allowed in 'prod'. Set 'map_public_ip_on_launch' variable to 'false'

exit status 1

atmos validate component vpc -s plat-ue2-dev

In 'dev', only 2 Availability Zones are allowed
VPC name must be a valid string from 2 to 20 alphanumeric chars

exit status 1

Validate Before Provisioning​

Try to run the following commands to provision the component in the stacks:

atmos terraform apply vpc -s plat-ue2-prod
atmos terraform apply vpc -s plat-ue2-dev

Since the OPA validation policies don't pass, Atmos does not allow provisioning the component in the stacks:

atmos validate vpc --stack=plat-ue2-prod

atmos-validate-vpc-in-plat-ue2-prod

atmos validate vpc --stack=plat-ue2-dev

atmos-validate-vpc-in-plat-ue2-dev

Advanced Policy Examples​

examples/quick-start-advanced/stacks/schemas/opa/vpc/validate-vpc-component.rego


note

  • 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.