> ## Documentation Index
> Fetch the complete documentation index at: https://kosli-29-automate-helm-reference-updates.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Environment Policies
> Define and enforce compliance requirements for artifact deployments across different environments.
Environment Policies enable you to define and enforce compliance requirements for artifact deployments across
different environments. With Environment Policies, you can:
* Define specific requirements for each environment (e.g, dev, staging, prod)
* Enforce consistent compliance standards across your deployment pipeline
* Prevent non-compliant artifacts from being deployed (via admission controllers)
Policies are written in YAML and are immutable (updating a policy creates a new version). They can be attached to
one or more environments, and an environment can have one or more policies attached to it.
## Create a Policy
You can create a policy via CLI or via the API. Here is a basic policy that requires provenance and specific
attestations:
```yaml prod-policy.yaml theme={"theme":"dracula"}
_schema: https://kosli.com/schemas/policy/environment/v1
artifacts: # the rules apply to artifacts in an environment snapshot
provenance:
required: true # all artifacts must have provenance
attestations:
- name: dependency-scan # all artifacts must have dependency-scan attestation
type: "*" # any attestation type
- name: unit-test # all artifacts must have unit-test attestation
type: junit # must be a 'junit' attestation type
```
You can create and manage policies using the Kosli CLI (global flags like org and api-token are omitted for brevity):
```shell theme={"theme":"dracula"}
kosli create policy prod-requirements prod-policy.yaml
```
```shell theme={"theme":"dracula"}
kosli get policy prod-requirements
```
See [kosli create policy](/client_reference/kosli_create_policy/) for usage details and examples.
Once you create a policy, you will be able to see it in the UI under `policies` in the left navigation menu.
## Declarative Policy Syntax
A Policy is declaratively defined according to the following schema:
```yaml theme={"theme":"dracula"}
_schema: https://kosli.com/schemas/policy/environment/v1
artifacts:
provenance:
required: true | false (default = false)
exceptions: (default [])
- if: ${{ expression }}
trail-compliance:
required: true | false (default = false)
exceptions: (default [])
- if: ${{ expression }}
attestations: (default [])
- if: ${{ expression }} (default = true)
name: str (default = "*") # cannot have both name and type as *
type: oneOf ['*', 'junit', 'jira', 'pull_request', 'snyk', 'sonar', 'generic', 'custom:'] (default = "*") # cannot have both name and type as *
```
### Policy Rules
A policy consists of `rules` which are applied to artifacts in an environment snapshot.
#### Provenance
When `provenance` is set to `required: true`, the artifact must be part of a Kosli Flow (i.e., it must have
provenance information).
```yaml theme={"theme":"dracula"}
artifacts:
provenance:
required: true
```
#### Trail Compliance
When `trail-compliance` is set to `required: true`, the artifact must be part of a compliant Trail in its Flow.
```yaml theme={"theme":"dracula"}
artifacts:
trail-compliance:
required: true
```
#### Specific Attestations
```yaml theme={"theme":"dracula"}
artifacts:
attestations:
- name: "*" # attestation name can be anything
type: pull-request
- name: acceptance-test
type: "*" # attestation type can be any built-in or existing custom type
- name: security-scan
type: snyk
- name: coverage-metrics
type: custom:my-coverage-metrics # custom attestation type
```
### Policy Rules Exceptions
You can add exceptions to policy rules using expressions.
```yaml theme={"theme":"dracula"}
_schema: https://kosli.com/schemas/policy/environment/v1
artifacts:
provenance:
required: true
exceptions:
# provenance is required except when one of the expressions evaluates to true
- if: ${{ expression1 }}
- if: ${{ expression2 }}
trail-compliance:
required: true
exceptions:
# trail-compliance is required except when one of the expressions evaluates to true
- if: ${{ expression1 }}
- if: ${{ expression2 }}
attestations:
- if: ${{ expression }} # this attestation is only required when expression evaluates to true
name: unit-tests
type: junit
```
#### Policy Expressions
Policy expressions allow you to create conditional rules using a simple and powerful syntax. Expressions are wrapped
in `${{ }}` and can be used in policy rules to create dynamic conditions. An expression consists of operands
and operators:
Expressions support these operators:
* Comparison: `==, !=, <, >, <=, >=`
* Logical: `and, or, not`
* List membership: `in`
Operands can be:
* Literal string
* List
* Context variable
* Function call
Contexts are built-in objects which are accessible from an expression. Expressions can access two main contexts:
* `flow` - Information about the Kosli Flow:
* `flow.name` - Name of the flow
* `flow.tags` - Flow tags (accessed via flow\.tags.tag\_name)
* `artifact` - Information about the artifact:
* `artifact.name` - Name of the artifact
* `artifact.fingerprint` - SHA256 fingerprint
Functions are helpers that can be used when constructing conditions. They may or may not accept arguments. Arguments
can be literals or context variables. Expressions can use following functions:
* `exists(arg)` : checks whether the value of arg is not None/Null
* `matches(input, regex)` : checks if input matches regex
* `${{ exists(flow) }}`
* `${{ flow.name in ["runner", 'saver', differ] }}`
* `${{ matches(artifact.name, "^datadog:.*") }}`
* `${{ flow.name == "runner" and matches(artifact.name, "^runner:.*") }}`
* `${{ flow.tags.risk-level == "high" or matches(artifact.name, "^runner:.*") }}`
* `${{ not flow.tags.risk-level == "high"}}`
* `${{ flow.tags.risk-level != "high"}}`
* `${{ flow.tags.key.with.dots == "value"}}`
* `${{ flow.tags.risk-level >= 2 }}`
* `${{ flow.name == 'prod' and (flow.tags.key_name == "value" or artifact.name == 'critical-service') }}`
* `${{ flow.name == 'HIGH-RISK' and artifact.fingerprint == "37193ba1f3da2581e93ff1a9bba523241a7982a6c01dd311494b0aff6d349462" }}`
## Attaching/Detaching Policies to/from Environments
Once you define your policies, you can attach them to environments via CLI or API:
```shell theme={"theme":"dracula"}
kosli attach-policy prod-requirements --environment=aws-production
```
To detach a policy from an environment:
```shell theme={"theme":"dracula"}
kosli detach-policy prod-requirements --environment=aws-production
```
Any attachment/detachment operation automatically triggers an evaluation of the latest environment snapshot and
creates a new one with an updated compliance state.
If you detach all attached policies from an environment, the environment compliance state will become Unknown since there are no longer any defined requirements for artifacts running in it. The environment will continue to
track snapshots, but its compliance cannot be evaluated without policies.
## Policy Enforcement Gates
Environment policies enable you to proactively block deploying a non-compliant artifact into an environment. This
can be done as a deployment gate in your delivery pipeline or as an admission controller in your environment.
Regardless of where you place your policy enforcement gate, it will be using the `assert artifact` Kosli CLI command
or its equivalent API call.
```shell theme={"theme":"dracula"}
kosli assert artifact --fingerprint=$SHA256 --environment=aws-production
```
An artifact can also be asserted directly against one or more policies.
```shell theme={"theme":"dracula"}
kosli assert artifact --fingerprint=$SHA256 --policy=has-approval,has-been-integration-tested
```