Kubernetes

This section outlines the configuration options available for Kubernetes discovery.

During an initial installation, the helm chart default is to generate it’s own kubeconfig file for discovering the local cluster context, named the default context. This must be disabled and a new kubeconfig provided in order to discover additional clusters.

The supported fields for Kubernetes (block name = kubernetes) are:

Field Name	Description
kubeconfigFile	The path of the kubeconfig file to use - resolved from within the container (often under /shared)
namespaces	An explicit list of which namespaces to scan for resources. Supports both exact names and regex patterns (e.g. "prod-.*", "^(dev|staging)-.*"). Patterns containing regex metacharacters (. * + ? ^ $ [ ] { } ( ) \) are compiled as regular expressions; plain strings are matched exactly.
excludeAnnotations	User specified annotations that will skip the discovery of a resource if found
excludeLabels	User specified labels that will skip the discovery of a resource if found
contexts	A map that provides granular discovery configuration for specific contexts. Each context supports defaultNamespaceLOD, namespaceLODs, and namespaces (per-context discovery filter).
inClusterAuth	Boolean. Defaults to true, which generates a cluster-viewer credential and kubeconfig for discovering the current cluster.

Kubernetes Context Discovery Configuration

The level of detail (LOD) for namespaces in Kubernetes clusters determines how much information is indexed and processed for each namespace.

The Level of Detail Annotations can also be used to specify namespace Level of Detail, which are useful when you want to avoid updating the workspaceInfo.yaml for explicit opt-in discovery. This setting overrides all settings below.

Order of Precedence

1. Annotation on the Namespace

   • Any config.runwhen.com/lod annotation found on the namespace takes precedence over all other configured LODs.

2. Cluster Default Namespace LOD (defaultNamespaceLOD)

   • If a namespace LOD is not explicitly found in an annotation, the cluster-level defaultNamespaceLOD is used (if it exists).

   • Example:

     kubernetes:
       contexts:
         - name: aks-cl-1
           defaultNamespaceLOD: basic

   • This ensures that all namespaces within a cluster default to the specified LOD if no finer-grained settings exist.

3. Global Default LOD (defaultLOD) (Lowest Priority)

   • If no context-specific defaultNamespaceLOD is set, the global defaultLOD is applied.

   • Example:

     defaultLOD: none

   • This applies only when no other settings define the LOD.

Discovery Exclusions

In order to exclude resources from discovery, the following Kubernetes labels or annotations can be applied to the object:

• Annotation: config.runwhen.com/ignore: "true"
• Label: runwhen-local: "ignore"

Additionally, users may add custom annotations or labels into the workspaceInfo configuration file using the excludeAnnotations or excludeLabels options, such as:

cloudConfig:
  kubernetes:
    excludeAnnotations:
      config.runwhen.com/discovery: "exclude"
    excludeLabels:
      runwhen: "exclude"

Level of Detail Annotations

The following annotations can be applied to Kubernetes namespaces to specify the Level of Detail applied during discovery. This setting will override the Level of Detail configuration in the workspaceInfo file.

config.runwhen.com/lod: [none, basic, detailed]

Resource Owner Annotations

The owner of a resource can also be annotated on a Kubernetes object, allowing for easier dynamic assignment of SLX owners:

config.runwhen.com/owner: "owner@here.com"

Kubernetes Discovery Configuration Examples

The following examples highlight kubernetes discovery configuration examples, but do not include the entire workspaceInfo.yaml configuration file.

Default Installation with Limited Namespace Discovery

This configuration performs detailed discovery on only the listed namespaces (without any additional annotations):

workspaceName: "my-workspace"
defaultLOD: detailed
cloudConfig:
  kubernetes:
    kubeconfigFile: /shared/kubeconfig
    namespaces:
      - my-cool-app-namespace-1
      - another-namespace-2

This configuration performs basic discovery on only the listed namespaces (without any additional annotations):

workspaceName: "my-workspace"
defaultLOD: basic
cloudConfig:
  kubernetes:
    kubeconfigFile: /shared/kubeconfig
    namespaces:
      - my-cool-app-namespace-1
      - another-namespace-2

Regex Namespace Patterns

The namespaces list supports regex patterns alongside exact names. When a value contains regex metacharacters (. * + ? ^ $ [ ] { } ( ) \), it is compiled as a regular expression and matched with re.fullmatch. Plain strings without metacharacters are matched exactly. An empty or omitted namespaces list discovers all namespaces.

Pattern-based namespace discovery — discover all namespaces matching a pattern:

workspaceName: "my-workspace"
defaultLOD: detailed
cloudConfig:
  kubernetes:
    kubeconfigFile: /shared/kubeconfig
    namespaces:
      - prod-.*       # matches prod-us, prod-eu, prod-asia, etc.
      - ^(dev|staging)-.*  # matches dev- and staging- prefixed namespaces
      - kube-system   # exact match

Mixing exact names and regex patterns:

cloudConfig:
  kubernetes:
    namespaces:
      - default
      - kube-system
      - monitoring-.*   # matches monitoring-prod, monitoring-dev, etc.
      - .*-system$      # matches any namespace ending in -system

Per-Context Namespace Discovery Filter

When a multi-cluster kubeconfig has different namespace requirements per context, specify a namespaces list under contexts.[context-name] to override the global kubernetes.namespaces for that context only. Contexts without a per-context filter fall back to the global list.

workspaceName: "my-workspace"
defaultLOD: detailed
cloudConfig:
  kubernetes:
    kubeconfigFile: /shared/kubeconfig
    namespaces:
      - kube-system     # global: only discover kube-system by default
    contexts:
      prod-cluster:
        defaultNamespaceLOD: detailed
        namespaces:          # per-context override
          - prod-.*          # regex: discover all prod-* namespaces in prod-cluster
      dev-cluster:
        defaultNamespaceLOD: basic
        namespaces:
          - dev-.*
          - staging-.*
          - kube-system
      sandbox-cluster:
        defaultNamespaceLOD: none  # no per-context filter — falls back to global "kube-system"

Context Specific Discovery Configuration Example

In the example above, all namespaces within the sandbox-cluster-1 context will be discovered with a basic LOD.

workspaceName: "my-workspace"
defaultLOD: none
cloudConfig:
  kubernetes:
    kubeconfigFile: /shared/kubeconfig
    contexts:
      sandbox-cluster-1:
        defaultNamespaceLOD: basic