Skip to content

Configuration

The typical configuration for CLARA is in the YAML format. Below, each available option is explained. All options with a default value are optional.

Sensitive Information & Environment Variables

Sensitive information, like usernames and passwords, don't belong into configuration files! For that reason, each configuration option can be specified by an environment variable. Instead of the actual value, the BASH-like syntax ${NAME_OF_THE_ENV_VARIABLE} can be used to specify the environment variable.

Interpolation and specifying default values is possible as well, just have a look here! There you can also find other ways to set up the configuration to be effective, like referencing and substituting other parts of the configuration to make it more DRY.

General configuration options

app.log-config
  • Type: Boolean
  • Default: false
  • Description: Whether the whole configuration that CLARA will use should be logged at startup (at the info-level).
app.block-after-finish
  • Type: Boolean
  • Default: false
  • Description: Whether the CLARA process should keep running after all exports are finished. This is useful when CLARA itself is running e.g. in Kubernetes and the Pod should not terminate because of the automatic restarts.

Configuring the aggregation

Platform: Kubernetes

aggregation.platforms.kubernetes.include-kube-namespaces
  • Type: Boolean
  • Default: false
  • Description: Whether the namespaces with the kube-prefix should also get scanned by CLARA. Must be set to true when every namespace should be scanned, even when namespaces has the *-wildcard.
aggregation.platforms.kubernetes.namespaces
  • Type: List of Strings
  • Default: empty List
  • Description: List all namespaces which CLARA should scan. To just scan all namespaces (except the kube-namespaces) set just the *-wildcard as the only element. The * needs to be in quotes.

Aggregator: Kubernetes API (optional)

aggregation.platforms.kubernetes.aggregators.kube-api.enable
  • Type: Boolean
  • Default: true
  • Description: Simple way to disable this aggregator without removing all of its associated configuration.

Aggregator: DNS (optional)

aggregation.platforms.kubernetes.aggregators.dns.enable
  • Type: Boolean
  • Default: true
  • Description: Simple way to disable this aggregator without removing all of its associated configuration.
aggregation.platforms.kubernetes.aggregators.dns.logs-since-time
  • Type: String (formatted as RFC3339, like 2024-01-01T00:00:00Z)
  • Default: empty String
  • Description: The DNS aggregator works by analyzing the logs of the Kubernetes DNS server which must be configured to log the queries. This option defines how recent the logs must be to be considered by CLARA. If this option is just an empty String (the default), all available logs will be used, which can lead to unwanted side effects, like old logs from a previous version of the deployment polluting the recovered architecture.
aggregation.platforms.kubernetes.aggregators.dns.use-logs-from-file
  • Type: Boolean
  • Default: false
  • Description: Simple way to switch if the DNS logs should be read from a file instead the Kubernetes API directly.
aggregation.platforms.kubernetes.aggregators.dns.path-to-dns-logs
  • Type: String
  • Default: empty String
  • Description: The DNS aggregator when used with files instead of the API must obtain an absolute path to the file.

Aggregator: OpenTelemetry (optional)

aggregation.platforms.kubernetes.aggregators.open-telemetry.enable
  • Type: Boolean
  • Default: true
  • Description: Simple way to disable this aggregator without removing all of its associated configuration.
aggregation.platforms.kubernetes.aggregators.open-telemetry.listen-port
  • Type: Integer (must be a valid port number)
  • Description: The port CLARA will listen to incoming spans sent by an OpenTelemetry collector.
aggregation.platforms.kubernetes.aggregators.open-telemetry.listen-duration
  • Type: String (format here)
  • Description: Amount of time CLARA should listen to incoming spans sent by an OpenTelemetry collector.

Aggregator: syft-sbom (optional)

aggregation.platforms.kubernetes.aggregators.syft-sbom.enable
  • Type: Boolean
  • Default: true
  • Description: Simple way to disable this aggregator without removing all of its associated configuration.
aggregation.platforms.kubernetes.aggregators.syft-sbom.sbom-file-path
  • Type: String (a valid relative or absolute path e.g. "sbom/")
  • Description: The path where CLARA stores the generated SPDX-JSON files.
aggregation.platforms.kubernetes.aggregators.syft-sbom.use-stored-sbom-files
  • Type: Boolean
  • Default: false
  • Description: States if the SPDX-JSON files for aggregating the libraries should be newly generated or not.

Configuring the merge

merge.comparison-strategy
  • Type: String (one of Equals, Prefix, Suffix, Contains)
  • Description: Strategy for matching names of components aggregated by different aggregators. Equals needs the same names, Prefix and Suffix need to have matching strings on the start or the end respectively, Contains needs that one string is part of the other.
merge.show-messaging-communications-directly
  • Type: Boolean
  • Description: If true, CLARA will define communications that go via a message broker directly between the components and removes the communications to the message broker. If false it show the communications via the message broker.

Configuring the filter

filter.remove-component-endpoints
  • Type: Boolean
  • Default: false
  • Description: If true, the endpoints of the components are filtered out before the export, to improve visibility in complex architectures.
filter.remove-component-versions
  • Type: Boolean
  • Default: false
  • Description: If true, the versions of the components are filtered out before the export, to reduce updates when components are often released.
filter.remove-components-by-names
  • Type: List of Strings
  • Default: empty List
  • Description: list of components that should be filtered out before the export (e.g. otel-collector-service).

Configuring the export

export.on-empty
  • Type: Boolean
  • Default: false
  • Description: If true, CLARA will export the recovered architecture using the enabled exporters, even if the architecture is completely empty. This could be useful for debugging purposes.

Exporter: GraphViz (optional)

export.exporters.graphviz.enable
  • Type: Boolean
  • Default: true
  • Description: Simple way to disable this exporter without removing all of its associated configuration.
export.exporters.graphviz.output-type
  • Type: String (one of BMP, DOT, GIF, JPG, JPEG, JSON, PDF, PNG, SVG, TIFF)
  • Description: Output format of the export. SVG is known to work well and in most situations the best choice.
export.exporters.graphviz.output-file
  • Type: String
  • Description: The file location (absolute or relative path) of the GraphViz output.
  • Example: generated/architecture.svg

Exporter: Gropius (optional)

export.exporters.gropius.enable
  • Type: Boolean
  • Default: true
  • Description: Simple way to disable this exporter without removing all of its associated configuration.
export.exporters.gropius.project-id
  • Type: String
  • Description: The ID of the Gropius-project to export the recovered architecture to.
export.exporters.gropius.graphql-backend-url
  • Type: String (a valid URL)
  • Description: The URL where CLARA can interact with the GraphQL-API of Gropius.
export.exporters.gropius.graphql-backend-authentication
export.exporters.gropius.graphql-backend-authentication.authentication-url
  • Type: String (a valid URL)
  • Description: The URL where CLARA can obtain an authentication token from the Gropius-backend via client credentials.
export.exporters.gropius.graphql-backend-authentication.client-id
  • Type: String
  • Description: The OAuth client ID for obtaining an authentication token.
export.exporters.gropius.graphql-backend-authentication.client-secret
  • Type: String
  • Description: The OAuth client ID's secret for obtaining an authentication token.
export.exporters.gropius.component-handling
  • Type: String (one of Delete or Modify)
  • Description: The mode how should be dealt with already existing components. Delete deletes and re-creates the old one, modify changes attributes.
export.exporters.gropius.export-libraries
  • Type: Boolean
  • Default: true
  • Description: Simple way to disable exporting libraries, as this is a data-intensive process and not always wanted.

A full example config

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
app:
  log-config: true
  block-after-finish: false

aggregation:
  platforms:
    kubernetes:
      include-kube-namespaces: false
      namespaces:
        - abc
        - xyz
      aggregators:
        kube-api:
          enable: true
        dns:
          enable: true
          logs-since-time: 2024-02-01T00:00:00Z
        open-telemetry:
          enable: true
          listen-port: 7878
          listen-duration: 45 minutes
        syft-sbom:
          enable: true
          sbom-file-path: sbom/
          use-stored-sbom-files: false

merge:
  comparison-strategy: Equals
  show-messaging-communications-directly: true

filter:
  remove-component-endpoints: false
  remove-components-by-names:
    - otel-collector-service

export:
  on-empty: false
  exporters:
    graphviz:
      enable: true
      output-type: SVG
      output-file: generated/architecture.svg
    gropius:
      enable: true
      project-id: aaaaaaaa-1111-bbbb-2222-cccccccccccc
      graphql-backend-url: http://my.backend.com:8080/graphql
      graphql-backend-authentication:
        authentication-url: http://my.backend.com:3000/authenticate/oauth/xxxxxxxx-1111-yyyy-2222-zzzzzzzzzzzz/token
        client-id: ${CLARA_GROPIUS_GRAPHQL_CLIENT_ID}
        client-secret: ${CLARA_GROPIUS_GRAPHQL_CLIENT_SECRET}