lunar-config.yml

Reference for lunar-config.yml — the central configuration file defining hub connection, catalogers, domains, components, collectors, initiatives, and policies.

• lunar-config.yml
• Type: YAML file
• Form:

  version: 0
  
  default_image: <default-image>
  default_image_ci_collectors: <default-image-ci>
  default_image_non_ci_collectors: <default-image-non-ci>
  default_image_policies: <default-image-policies>
  default_image_catalogers: <default-image-catalogers>
  
  image_replace:
    - from_pattern: <regex>
      to: <replacement>
    - ...
  
  hub:
    host: <hub-host>
    grpcPort: <grpc-port>
    httpPort: <http-port>
    insecure: <insecure-flag>
  
  bypass:
    max_duration: <duration>
    require_reason: <require-reason-flag>
  
  customization:
    bypass_template: <repository-relative-template-path>
    checks_template: <repository-relative-template-path>
    pr_comments:
      mode: <comment-mode>
  
  catalogers:
    - <cataloger-object>
    - <cataloger-object>
    - ...
  
  domains:
    <domain-name>: <domain-object>
    <domain-name>: <domain-object>
    ...
  
  components:
    <component-name>: <component-object>
    <component-name>: <component-object>
    ...
  
  collectors:
    - <collector-object>
    - <collector-object>
    - ...
  
  initiatives:
    - <initiative-object>
    - <initiative-object>
    - ...
  
  policies:
    - <policy-object>
    - <policy-object>
    - ...

The file lunar-config.yml is used to configure the behavior of Lunar.

It is recommended that you create a new code repository for all Lunar configuration and place this file in the root of it.

At a high-level, the file contains information about how the Lunar primitives are configured, ranging from how information is collected from the SDLC via collectors, to how components are organized into domains, and how the health of components is evaluated via policies.

Splitting the configuration

A single lunar-config.yml works well and is the typical setup. If you'd prefer to spread a larger configuration across several files — for example, one per team — you can: any *.yml / *.yaml files placed in a lunar-config.d/ directory next to lunar-config.yml are merged into it, in lexical filename order.

lunar-config.yml          # version, hub, default images
lunar-config.d/
  collectors.yml
  team-frontend.yml
  team-backend.yml

lunar-config.yml stays the entry point and holds the singleton fields (version, hub, bypass, customization, default_image*, image_replace); each fragment contributes additional sections. List sections (collectors, policies, …) are concatenated; map sections (domains, components) are unioned by key, and a key defined in more than one place is an error rather than a silent override.

version

• lunar-config.yml -> version
• Type: string
• Required

The version field is used to specify the version of the configuration file. The current version is 0.

Default Images

• lunar-config.yml -> default_image*
• Optional

These fields configure the default Docker images used to run collectors, policies, and catalogers. When set, scripts will run inside containers instead of natively on the host.

A common configuration is:

lunar-config.yml

default_image: earthly/lunar-scripts:1.0.0
default_image_ci_collectors: native

This runs most scripts in containers while keeping CI collectors native for direct access to CI environments.

For detailed documentation on default images, image resolution order, and the official earthly/lunar-scripts image, see Images.

image_replace

• lunar-config.yml -> image_replace
• Type: list
• Optional

Find/replace rules applied to image references after they are resolved, for pointing images at an internal registry mirror:

lunar-config.yml

image_replace:
  - from_pattern: ^earthly/
    to: 111122223333.dkr.ecr.us-east-1.amazonaws.com/docker.io/earthly/

See Images for the matching rules and caveats.

hub

• lunar-config.yml -> hub
• Type: object
• Required

The hub object contains configuration for the Lunar Hub server.

host

• lunar-config.yml -> hub.host
• Type: string
• Required

The host field is used to specify the host of the Lunar Hub server.

grpcPort

• lunar-config.yml -> hub.grpcPort
• Type: integer
• Required

The grpcPort field is used to specify the port of the Lunar Hub server for GRPC connections.

httpPort

• lunar-config.yml -> hub.httpPort
• Type: integer
• Required

The httpPort field is used to specify the port of the Lunar Hub server for HTTP connections.

insecure

• lunar-config.yml -> hub.insecure
• Type: boolean
• Optional
• Default: false

The insecure field is used to specify whether to use insecure HTTP connections to the Lunar Hub server.

bypass

• lunar-config.yml -> bypass
• Type: object
• Optional

The bypass object bounds the lunar policy bypass-pr / bypass-release commands.

lunar-config.yml

bypass:
  max_duration: 3d
  require_reason: true

max_duration

• lunar-config.yml -> bypass.max_duration
• Type: string
• Optional
• Default: 14d

The longest a single bypass may last. This caps --for, and is also what an omitted --for resolves to, so no bypass is ever open-ended.

Accepts Go's duration grammar extended with d (24 hours) and w (7 days) units, mixable: 36h, 3d, 2w, 1w2d. A malformed or non-positive value is rejected when the configuration is loaded, rather than when someone next tries to create a bypass.

A --for above the cap is rejected.

The cap applies to a single bypass, not to a sequence of them: renewing an expired bypass is the intended pattern.

require_reason

• lunar-config.yml -> bypass.require_reason
• Type: boolean
• Optional
• Default: true

Whether --reason is mandatory when creating a bypass. Set it to false only if the justification is being recorded somewhere else.

customization

• lunar-config.yml -> customization
• Type: object
• Optional

The customization object controls optional changes to Lunar's presentation and behavior.

For available fields, see customization.

catalogers

• lunar-config.yml -> catalogers
• Type: array
• Optional

Catalogers are used to synchronize software catalog information (such as domains, and components) with external systems.

For information on how to configure catalogers, see catalogers.

domains

• lunar-config.yml -> domains
• Type: object
• Optional

Domains are used to group related components together. Domains are hierarchical and can contain other domains.

For information on how to configure domains, see domains.

components

• lunar-config.yml -> components
• Type: object
• Optional

Components are the units of code that Lunar monitors. A component can represent either a code repository, or a subdirectory in the case of a monorepo.

Components are associated with domains and can have tags. Through the tagging system, components are associated with collectors, and policies.

For information on how to configure components, see components.

collectors

• lunar-config.yml -> collectors
• Type: array
• Required

Collectors are used to collect live information from various sources to associate with individual components.

For information on how to configure collectors, see collectors.

initiatives

• lunar-config.yml -> initiatives
• Type: array
• Optional

Initiatives are used to group components together. Initiatives are associated with domains and can have tags.

For information on how to configure initiatives, see initiatives.

policies

• lunar-config.yml -> policies
• Type: array
• Required

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

For information on how to configure policies, see policies.