policies

Policies

• lunar-config.yml -> policies

• Type: array

• Form:

  policies:
    - <policy-object>
    - <policy-object>
    - ...

Policies are used to define the rules that Lunar uses to evaluate the health of components.

Example policies definition:

policies:
  - uses: github://third-party/some-policy@v1
    on: [my-domain]
    enforcement: block-pr
  - uses: ./security-scanning
    on: [my-domain, another-domain]
    enforcement: score
  - name: Collect code coverage information
    runPython: |
      from lunar_policy import Check, Path
      with Check("codecov-check", "Verify code coverage was collected") as check:
          check.assert_true(Path(".codecov.was_run"), "Code coverage data should be collected")
    on: [another-domain]
  - name: Should have unit tests
    mainPython: ./unit-tests.py
    on: [another-domain]
    enforcement: block-pr-and-release

Policy

• lunar-config.yml -> policies.<policy-index>

• Type: object

• Forms:

  • Uses form:

    name: <policy-name>
    uses: <policy-string>
    with:
      <input-name>: <input-value>
      ...
    on: <domain-array>
    enforcement: <enforcement-level>
    initiative: <initiative-name>

  • Run form:

    name: <policy-name>
    description: <policy-description>
    run<language>: <code-string>
    on: <domain-array>
    enforcement: <enforcement-level>
    initiative: <initiative-name>

  • Main form:

    name: <policy-name>
    description: <policy-description>
    main<language>: <main-file-path>
    on: <domain-array>
    enforcement: <enforcement-level>
    initiative: <initiative-name>

Policies are used to define the rules that Lunar uses to evaluate the health of components. Policies are associated with domains and are automatically inherited by child domains.

name

• lunar-config.yml -> policies.<policy-index>.name

• Type: string

• Required for Run and Main policy forms, Optional for Uses policy form

The name field is used to specify the name of the policy. If a name is not provided in the case of a policy plugin, the name from the policy plugin is used. The name must be unique within the configuration.

uses

• lunar-config.yml -> policies.<policy-index>.uses

• Type string

• Forms

  • GitHub form: github://<owner>/<repo>@<version>

  • Local form: ./<path-to-policy>

• Required in Uses policy form

The uses field is used to import an external (plugin) policy from a GitHub repository or a local file. The policy is then associated with a domain.

with

• lunar-config.yml -> policies.<policy-index>.with

• Type: object

• Optional

The with field specifies the inputs to pass to the policy plugin. The inputs are defined in the policy's configuration file.

description

• lunar-config.yml -> policies.<policy-index>.description

• Type: string

• Optional

The description field is used to specify a description of the policy. If a description is not provided in the case of a policy plugin, the description from the policy plugin is used.

run<language>

• lunar-config.yml -> policies.<policy-index>.run<language>

• Type: string

• Required in Run policy form

Defines the command to execute when the policy is invoked. Only Python is supported. So runPython is the only valid field.

If an install.sh file is present in the same directory as lunar-config.yml or lunar-policy.yml, Lunar will run the install script before running the policy script. This script is executed only once in each environment. For ephemeral environments, the script is executed every time the environment is created (e.g. on each policy run). Lunar uses a lock file under the hood to detect if the script has previously been executed.

runPython

• lunar-config.yml -> policies.<policy-index>.runPython

• Type: string

The runPython field specifies the python policy script to run.

If a requirements.txt file is present in the same directory as lunar-config.yml or lunar-policy.yml, Lunar will install the dependencies before running the policy script.

main<language>

• lunar-config.yml -> policies.<policy-index>.main<language>

• Type: string

• Required in Main policy form

Defines the main file path used to execute when the policy is invoked. Only Python is supported. So mainPython is the only valid field.

The file path is relative to the root of the Lunar configuration repository. In the case of an external plugin definition, the path is relative to the plugin directory.

If an install.sh file is present in the same directory as lunar-config.yml or lunar-policy.yml, Lunar will run the install script before running the policy script. This script is executed only once in each environment. For ephemeral environments, the script is executed every time the environment is created (e.g. on each policy run). Lunar uses a lock file under the hood to detect if the script has previously been executed.

mainPython

• lunar-config.yml -> policies.<policy-index>.mainPython

• Type: string

The mainPython field specifies the path to the python main file to run.

If a requirements.txt file is present in the same directory as lunar-config.yml or lunar-policy.yml, Lunar will install the dependencies before running the policy script.

on

• lunar-config.yml -> policies.<policy-index>.on

• Type: array

• Required

The on field specifies the tags that the policy should be associated with. The policy will apply run when the component has one or more of the specified tags.

To associate the policy with a domain, use the tag domain:<domain-name>. For example, to associate a policy with the domain bar, which is under the domain foo, use the tag domain:foo.bar.

enforcement

• lunar-config.yml -> policies.<policy-index>.enforcement

• Type: string. One of draft, score, block-pr, block-release, block-pr-and-release

• Optional - defaults to score

The enforcement field specifies the enforcement level of the policy. It determines how the policy affects the component.

The following enforcement levels are supported:

• draft - the policy is still under development and does not affect the score, and is not enforced or shown to application teams

• score - the checks under this policy contribute to the score of the component, but do not block the development workflow

• block-pr - the checks under this policy block PRs from being merged

• block-release - the checks under this policy block releases, but not PRs. This level may be useful for checks that don't necessarily run in PRs due to performance reasons, but are nevertheless important to gate the release process.

• block-pr-and-release - the checks under this policy block both PRs and releases

When block-release or block-pr-and-release levels are used, the Lunar CLI command lunar policy ok-release <component> <git_sha> will return a non-zero exit code of 1 if the associated policy is failing for the given component. This command may be used in CD or release pipelines to prevent a deployment to production, or a release package to be published.

When block-pr or block-pr-and-release levels are used, the Lunar CLI command lunar policy ok-pr <component> <git_sha>will return a non-zero exit code of 1 if the associated policy is failing for the given component. This command may be used wherever needed to block PR merges or prevent PR deployment pipelines to staging environments.

initiative

• lunar-config.yml -> policies.<policy-index>.initiative

• Type: string

• Optional - defaults to default

The initiative field specifies the initiative that the policy belongs to. Initiatives are used to group related policies together for easier management and reporting. If not specified, the policy will be associated with the built-in "default" initiative.

For information on how to configure initiatives, see initiatives.