Redactor (KOTS Only)

This topic describes how to define redactors with the Redactor custom resource.

note

Custom redactors defined with the Redactor resource apply only to installations with Replicated KOTS.

Overview

Preflight checks and support bundles include built-in redactors. These built-in redactors use regular expressions to identify and hide potentially sensitive data before it is analyzed. For example, the built-in redactors hide values that match common patterns for data sources, passwords, and user IDs that can be found in standard database connection strings. They also hide environment variables with names that begin with words like token, password, or user. To view the complete list of regex patterns for the built-in redactors, see redact.go in the open-source Troubleshoot GitHub repo.

For Replicated KOTS installations, you can also add custom redactors to support bundles using the Redactor custom resource manifest file. For example, you can redact API keys or account numbers, depending on your customer needs. For more information about redactors, see Redacting Data in the Troubleshoot documentation.

Defining Custom Redactors

You can add custom redactors for KOTS installations using the following basic Redactor custom resource manifest file (kind: Redactor):

apiVersion: troubleshoot.sh/v1beta2
kind: Redactor
metadata:
  name: sample
spec:
  redactors: []

Objects and Fields

A redactor supports two objects: fileSelector and removals. These objects specify the files the redactor applies to and how the redactions occur. For more information and examples of these fields, see KOTS Redactor Example below and Redactors in the Troubleshoot documentation.

fileSelector

The fileSelector object determines which files the redactor is applied to. If this object is omitted from the manifest file, the redactor is applied to all files. This object supports the following optional fields:

Field Name	Description
file	(Optional) Specifies a single file for redaction.
files	(Optional) Specifies multiple files for redaction.

Globbing is used to match files. For example, /my/test/glob/* matches /my/test/glob/file, but does not match /my/test/glob/subdir/file.

removals

The removals object is required and defines the redactions that occur. This object supports the following fields. At least one of these fields must be specified:

Field Name	Description
regex	(Optional) Allows a regular expression to be applied for removal and redaction on lines that immediately follow a line that matches a filter. The selector field is used to identify lines, and the redactor field specifies a regular expression that runs on the line after any line identified by selector. If selector is empty, the redactor runs on every line. Using a selector is useful for removing values from pretty-printed JSON, where the value to be redacted is pretty-printed on the line beneath another value. Matches to the regex are removed or redacted, depending on the construction of the regex. Any portion of a match not contained within a capturing group is removed entirely. The contents of capturing groups tagged mask are masked with HIDDEN. Capturing groups tagged drop are dropped.
values	(Optional) Specifies values to replace with the string HIDDEN.
yamlPath	(Optional) Specifies a .-delimited path to the items to be redacted from a YAML document. If an item in the path is the literal string *, the redactor is applied to all options at that level. Files that fail to parse as YAML or do not contain any matches are not modified. Files that do contain matches are re-rendered, which removes comments and custom formatting. Multi-document YAML is not fully supported. Only the first document is checked for matches, and if a match is found, later documents are discarded entirely.

KOTS Redactor Example

The following example shows regex and yamlPath redaction for a support bundle:

apiVersion: troubleshoot.sh/v1beta2
kind: Redactor
metadata:
  name: my-redactor-name
spec:
  redactors:
  - name: all files # as no file is specified, this redactor will run against all files
    removals:
      regex:
      - redactor: (another)(?P<mask>.*)(here) # this will replace anything between the strings `another` and `here` with `***HIDDEN***`
      - selector: 'S3_ENDPOINT' # remove the value in lines immediately following those that contain the string `S3_ENDPOINT`
        redactor: '("value": ").*(")'
      yamlPath:
      - "abc.xyz.*" # redact all items in the array at key `xyz` within key `abc` in YAML documents