CodeCollection Configuration

CodeCollection Discovery

The workspace builder component of RunWhen Local scans public git repositories to match the available automation with the resources it discovers in your cluster or cloud provider.

Each individual git repository is considered a CodeCollection, which contains one or more CodeBundle(s). Each CodeBundle folder contains :

• SLI or Automation Task code

• Generation Rules

• Templates

See the Authors documentation for more details on CodeBundle structure.

Default CodeCollection Discovery

By default, the workspace builder scans for code bundles from a built-in/preconfigured list of standard RunWhen CodeCollections. Currently, this list is:

Changing the CodeCollection Discovery Configuration

You may want to override the default for a number of reasons:

• supplementing the built-in CodeCollections with other third-party CodeCollections

• suppressing one or more of the built-in CodeCollections

• overriding the branch used for one or more CodeCollections

• specifying a subset of the code bundles to enable for a CodeCollection

To support these use cases the CodeCollection list can be customized with a codeCollections block. This is a list of the CodeCollections to enable. A CodeCollection item in the list can be specified with either a simple string or a CodeCollection object/block with info about the target CodeCollection.

For the string specification the string is just the URL of the git repo. The string can also be the special "defaults" value, which enables all the built-in CodeCollections. This is useful if you want to enable most of the built-in CodeCollections, but suppress/blacklist some of them. If you prefix the git URL with a "!" character, then that means to exclude that CodeCollection rather than enable it. When using the string format for a CodeCollection entry the "main" branch is used. If you want to specify a different branch you need to use the object/block format.

The object block format for a CodeCollection entry is an object/dictionary with the following fields:

Only one of the branch, tag or ref fields should be specified.

The authUser and authToken fields are only necessary for non-public repos. All the RunWhen-provided CodeCollections are open source, so they don't require any credentials.

The action field lets you toggle between inclusion/whitelist and exclusion/blacklist. The most common use case will just be an explicit whitelist of included CodeCollections. Since the action field defaults to include you can just omit it for that use case.

The CodeBundles field is just a list of the names of the code bundles to enable. The codeBundle name is the directory name of the CodeBundle in the CodeBundles directory in the CodeCollection. This field is optional. If it's omitted, then all code bundles are enabled. The code bundle value can be a file glob expression like you can use is the command line shell, so you can have wildcard expressions that match multiple code bundles.

The custom CodeCollection configuration is useful for CodeCollection authors. For new third-party CodeCollections you can just add the new CodeCollection to the list. If you're developing/testing a single code bundle, you can limit the workspace builder to just that code bundle:

codeCollections:
- repoURL: https://github.com/author-account/my-custom-code-collection.git
  codeBundles:
  - my-code-bundle

If you're developing new code bundles for one of the standard RunWhen CodeCollections, then the easiest way to handle that is to fork the RunWhen repo and then stage your new code bundle code in the fork. Remember that you need to commit any changes you make to your local clone and push to the GitHub repo to make the new code accessible to the workspace builder.

CodeCollection Version Management

While the default configuration is to leverage CodeCollections from the main branches, this is mostly useful for initial setup, proof of concept, or pilot installations - in which your environment can automatically receive new CodeBundle updates in an automated manner. For production implementations, CodeCollection updates may want to be applied in a controlled manner. In this case, git tags are used to specify the CodeCollection versions that are applied to your workspace.

For example, to specify a tag and only include a few CodeCollections, the configuration may look like this:

codeCollections:
- repoURL: https://github.com/runwhen-contrib/rw-public-codecollection.git
  tag: v0.0.17
- repoURL: https://github.com/runwhen-contrib/rw-cli-codecollection.git
  tag: v0.0.24
- repoURL: https://github.com/runwhen-contrib/rw-workspace-utils.git
  tag: v0.0.3
- repoURL: https://github.com/runwhen-contrib/rw-generic-codecollection.git
  tag: v0.0.1

Excluding CodeBundles by Task Tag

Every task within a CodeBundle contains a set of tags. Some of these tags describe the type of access that they task may require, for example:

• Discovery / investigation tasks will have the access:read-only (example)

• Remediation tasks will have the tag access:read-write (example)

CodeBundles can be completely excluded by setting the taskTagExclusions list in the workspaceInfo.yaml configuration. For example;

defaultLOD: none                    # Minimal overall discovery
taskTagExclusions: 
  - "access:read-write"             # Exclude CodeBundles with read-write access tags

cloudConfig:
  kubernetes:
    contexts:
      sandbox-cluster-1: 
        defaultNamespaceLOD: detailed  # Only detailed discovery for K8s
    namespaces:
      - kube-system                    # Limited to specific namespaces
  azure:
    aksClusters:
      defaultNamespaceLOD: none        # Minimal AKS discovery
    resourceGroupLevelOfDetails:
      my-azure-rg: none    # Minimal Azure resource discovery

Overriding CodeBundle Default Configuration (configProvided)

The configProvided overrides feature allows you to broadly override template variables in runbooks or SLI CodeBundles without modifying the original templates. This is useful for customizing default values, environment-specific configurations, or testing different parameter values.

The override system works by matching CodeBundles based on repository URL, codebundle directory name, and type (sli/runbook), then applying the specified variable overrides to the generated YAML files.

For instance, to override the TIME_PERIOD_MINUTES from the default set in this SLI CodeBundle template:

overrides:
  codebundles:
    - repoURL: "https://github.com/runwhen-contrib/rw-cli-codecollection.git"
      codebundleDirectory: "azure-appservice-webapp-health"
      type: "sli"
      configProvided:
        TIME_PERIOD_MINUTES: "30"

Or to override the CONTAINER_RESTART_AGE and CONTAINER_RESTART_THRESHOLD in this taskset CodeBundle template:

overrides:
  codebundles:
    - repoURL: "https://github.com/runwhen-contrib/rw-cli-codecollection.git"
      codebundleDirectory: "azure-aks-triage"
      type: "runbook"
      configProvided:
        CONTAINER_RESTART_AGE: "45m"
        CONTAINER_RESTART_THRESHOLD: "8"