Configuration

Korrel8r loads configuration from a file or URL specified by the --config option or the KORREL8R_CONFIG environment variable.

korrel8r --config <file_or_url>

Built-in configuration

The released korrel8r container image includes default configuration at /etc/korrel8r/, mirroring the etc/korrel8r/ directory in the source repository:

/etc/korrel8r/
├── openshift-route.yaml   # Out-of-cluster: connect to stores via OpenShift routes
├── openshift-svc.yaml     # In-cluster: connect to stores via service URLs
└── rules/
    ├── all.yaml            # Includes all rule files below
    ├── k8s.yaml
    ├── alert.yaml
    ├── log.yaml
    ├── netflow.yaml
    ├── trace.yaml
    └── incident.yaml

openshift-route.yaml

Run korrel8r outside the cluster, connect to stores via routes.

openshift-svc.yaml

Run korrel8r as an in-cluster service, connect to stores via service URLs.

The default deployment uses --config=/etc/korrel8r/openshift-svc.yaml.

Custom configuration

To provide your own configuration in a cluster deployment, create a ConfigMap with your configuration file and mount it at a path that does not overwrite the built-in /etc/korrel8r/ directory. For example, mount at /etc/korrel8r/custom/:

apiVersion: v1
kind: ConfigMap
metadata:
  name: korrel8r-custom-config
data:
  korrel8r.yaml: |
    stores:
      - domain: k8s
      - domain: metric
        metric: https://my-prometheus:9090
    include:
      - /etc/korrel8r/rules/all.yaml  # Re-use all built-in rules

Mount the ConfigMap and point --config to it:

volumes:
  - name: custom-config
    configMap:
      name: korrel8r-custom-config
containers:
  - name: korrel8r
    command: ["korrel8r", "web", "--config=/etc/korrel8r/custom/korrel8r.yaml"]
    volumeMounts:
      - name: custom-config
        mountPath: /etc/korrel8r/custom
        readOnly: true

You can include individual built-in rule files (e.g. /etc/korrel8r/rules/k8s.yaml) instead of all.yaml if you only need a subset, or add your own rules directly in the custom configuration file.

The configuration is a YAML file with the following sections:

include

Other configuration fragments to include:

include:
  - "path_or_url"

stores

Connections to data stores:

stores:
  - domain: "domain_name"    # 1. Domain name of the store (required)
    # Domain-specific fields # 2. See Domain Reference

Every entry in the stores section has a domain field to identify the domain. Other fields depend on the domain, see the Domain Reference.

Store fields may contain templates that expand to URLs.

Example: configuring a store URL from an OpenShift Route resource:

stores:
  - domain: log
    lokiStack: >-
      {{$r := query "k8s:Route.route.openshift.io/v1:{namespace: openshift-logging, name: logging-loki}" -}}
      https://{{ (first $r).Spec.Host -}}

1. Get a list of routes in “openshift-logging” named “logging-loki”.
2. Use the .Spec.Host field of the first route as the host for the store URL.

rules

Rules to relate different classes of data:

rules:
  - name: "rule_name"          # 1. Identifies the rule in graphs and for debugging
    start:                      # 2. Start objects must belong to one of these classes
      domain: "domain_name"
      classes:
        - "class_name"
    goal:                       # 3. Goal queries retrieve one of these classes
      domain: "domain_name"
      classes:
        - "class_name"
    result:
      query: "query_template"   # 4. Go template applied with start object as context

Korrel8r comes with a comprehensive set of rules by default, but you can modify them or add your own.

A rule has the following key elements:

• A set of start classes. The rule can apply to objects belonging to one of these classes.
• A set of goal classes. The rule can generate queries for any of these classes.
• A Go template to generate a goal query from a start object.

The query template should generate a string of the form:

<domain-name>:<class-name>:<query-details>

The query-details part depends on the domain, see the Domain Reference.

statusRules

Rules that generate statuses for objects in a correlation graph:

statusRules:
  - name: "rule_name"           # 1. Identifies the rule in log output
    start:                      # 2. Start objects must belong to one of these classes
      domain: "domain_name"
      classes:                  #    Optional — omit for all classes in the domain
        - "class_name"
    status: "status_template"   # 3. Go template that outputs labels, one per line

See Statuses for details and examples.

aliases

Short-hand alias names for groups of classes:

aliases:
  - name: "alias_name"       # 1. Can be used wherever a class name is allowed
    domain: "domain_name"    # 2. Domain for classes in this alias
    classes:                  # 3. Classes belonging to this alias
      - "class_name"

templates

Named templates that can be reused from rule, status, or store templates:

templates:
  - name: "template_name"       # 1. Name used to invoke the template
    template: "template_body"   # 2. Go template body

Named templates are invoked from rule or status templates using the standard Go template syntax:

{{template "template_name" <data>}}

The <data> expression becomes . inside the named template. Use the sprig dict function to pass named parameters:

templates:
  - name: myHelper
    template: 'k8s:{{.class}}:{"namespace":"{{index .labels "namespace"}}"}'

rules:
  - name: MyRule
    start: {domain: alert}
    goal: {domain: k8s, classes: [Pod]}
    result:
      query: '{{template "myHelper" (dict "labels" .Labels "class" "Pod")}}'

Named templates defined in any configuration file (including included files) are available to all rules across all files.

About Templates

Korrel8r rules and store configuration can include Go templates. Korrel8r provides additional template functions, domains may provide additional functions – see the Domain Reference