Linter Rules

This topic describes the release linter and the linter rules.

Overview

The linter checks the manifest files in Replicated KOTS releases to ensure that there are no YAML syntax errors, that all required manifest files are present in the release to support installation with KOTS, and more.

The linter runs automatically against KOTS releases that you create in the Replicated vendor portal, and displays any error or warning messages in the vendor portal UI.

To lint manifest files from the command line, you can run the Replicated CLI replicated release lint command against the root directory of your application manifest files. You can also use the --lint flag when you create a release with the replicated release create command. For more information, see release lint and release create in the Replicated CLI section.

Linter Rules

This section lists the linter rules and the default rule levels (Info, Warn, Error). You can customize the default rule levels in the Replicated LinterConfig custom resource. For more information, see LintConfig.

allow-privilege-escalation

Description	Notifies if any manifest file has allowPrivilegeEscalation set to true.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: spec: allowPrivilegeEscalation: true

application-icon

Description	Requires an application icon.
Level	Warn
Applies To	Files with kind: Application and apiVersion: kots.io/v1beta1.
Example	Example of correct YAML for this rule: apiVersion: kots.io/v1beta1 kind: Application spec: icon: https://example.com/app-icon.png

application-spec

Description	Requires an Application custom resource manifest file. Accepted value for kind: Application
Level	Warn
Example	Example of matching YAML for this rule: apiVersion: kots.io/v1beta1 kind: Application

application-statusInformers

Description	Requires statusInformers.
Level	Warn
Applies To	Files with kind: Application and apiVersion: kots.io/v1beta1.
Example	Example of correct YAML for this rule: apiVersion: kots.io/v1beta1 kind: Application spec: statusInformers: - deployment/example-nginx

config-option-invalid-type

Description	Enforces valid types for Config items. For more information, see Items in Config.
Level	Error
Applies To	All files
Example	Correct: spec: groups: - name: authentication title: Authentication description: Configure application authentication below. - name: group_title title: Group Title items: - name: http_enabled title: HTTP Enabled type: bool # bool is a valid type Incorrect:: spec: groups: - name: authentication title: Authentication description: Configure application authentication below. - name: group_title title: Group Title items: - name: http_enabled title: HTTP Enabled type: unknown_type # unknown_type is not a valid type

config-option-is-circular

Description	Enforces that all ConfigOption items do not reference themselves.
Level	Error
Applies To	Files with kind: Config and apiVersion: kots.io/v1beta1.
Example	Incorrect: spec: groups: - name: example_settings items: - name: example_default_value type: text value: repl{{ ConfigOption "example_default_value" }}

config-option-not-found

Description	Requires all ConfigOption items to be defined in the Config custom resource manifest file.
Level	Warn
Applies To	All files

config-option-not-repeatable

Description	Enforces that sub-templated ConfigOption items must be repeatable.
Level	Error
Applies To	All files

config-option-password-type

Description	Requires ConfigOption items with any of the following names to have type set to password: password secret token
Level	Warn
Applies To	All files
Example	Example of correct YAML for this rule: spec: groups: - name: ports items: - name: my_secret type: password

config-option-when-is-invalid

Description	Enforces valid ConfigOption.when. For more information, see when in Config.
Level	Error
Applies To	Files with kind: Config and apiVersion: kots.io/v1beta1.

config-option-invalid-regex-validator

Description	Enforces valid RE2 regular expressions pattern when regex validation is present. For more information, see Validation in Config.
Level	Error
Applies To	Files with kind: Config and apiVersion: kots.io/v1beta1.
Example	Correct: spec: groups: - name: authentication title: Authentication description: Configure application authentication below. - name: jwt_file title: jwt_file type: file validation: regex: pattern: "^[A-Za-z0-9-_]+.[A-Za-z0-9-_]+.[A-Za-z0-9-_]*$" // valid RE2 regular expression message: "JWT is invalid" Incorrect: spec: groups: - name: authentication title: Authentication description: Configure application authentication below. - name: jwt_file title: jwt_file type: file validation: regex: pattern: "^/path/([A-Za-z0-9-_]+.[A-Za-z0-9-_]+.[A-Za-z0-9-_]*$" // invalid RE2 regular expression message: "JWT is invalid"

config-option-regex-validator-invalid-type

Description	Enforces valid item type when regex validation is present. Item type should be text|textarea|password|file For more information, see Validation in Config.
Level	Error
Applies To	Files with kind: Config and apiVersion: kots.io/v1beta1.
Example	Correct: spec: groups: - name: authentication title: Authentication description: Configure application authentication below. - name: jwt_file title: jwt_file type: file // valid item type validation: regex: pattern: "^[A-Za-z0-9-_]+.[A-Za-z0-9-_]+.[A-Za-z0-9-_]*$" message: "JWT is invalid" Incorrect: spec: groups: - name: authentication title: Authentication description: Configure application authentication below. - name: jwt_file title: jwt_file type: bool // invalid item type validation: regex: pattern: "^[A-Za-z0-9-_]+.[A-Za-z0-9-_]+.[A-Za-z0-9-_]*$" message: "JWT is invalid"

config-spec

Description	Requires a Config custom resource manifest file. Accepted value for kind: Config Accepted value for apiVersion: kots.io/v1beta1
Level	Warn
Example	Example of matching YAML for this rule: apiVersion: kots.io/v1beta1 kind: Config

container-image-latest-tag

Description	Notifies if any manifest file has a container image tag appended with :latest.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: spec: containers: - image: nginx:latest

container-image-local-image-name

Description	Disallows any manifest file having a container image tag that includes LocalImageName.
Level	Error
Applies To	All files
Example	Example of matching YAML for this rule: spec: containers: - image: LocalImageName

container-resource-limits

Description	Notifies if a spec.container has no resources.limits field.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: spec: containers: - name: nginx resources: requests: memory: '32Mi' cpu: '100m' # note the lack of a limit field

container-resource-requests

Description	Notifies if a spec.container has no resources.requests field.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: spec: containers: - name: nginx resources: limits: memory: '256Mi' cpu: '500m' # note the lack of a requests field

container-resources

Description	Notifies if a manifest file has no resources field.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: spec: containers: - name: nginx # note the lack of a resources field

deprecated-kubernetes-installer-version

Description	Disallows using the deprecated kURL installer apiVersion. kurl.sh/v1beta1 is deprecated. Use cluster.kurl.sh/v1beta1 instead.
Level	Warn
Applies To	Files with kind: Installer and apiVersion: kurl.sh/v1beta1.
Example	Correct: apiVersion: cluster.kurl.sh/v1beta1 kind: Installer Incorrect: apiVersion: kurl.sh/v1beta1 kind: Installer

duplicate-helm-release-name

Description	Enforces unique spec.chart.releaseName across all HelmChart custom resource manifest files.
Level	Error
Applies To	Files with kind: HelmChart and apiVersion: kots.io/v1beta1.

duplicate-kots-kind

Description	Disallows duplicate Replicated custom resources. A release can only include one of each kind of custom resource. This rule disallows inclusion of more than one file with: The same kind and apiVersion kind: Troubleshoot and any Troubleshoot apiVersion kind: Installer and any Installer apiVersion
Level	Error
Applies To	All files

hardcoded-namespace

Description	Notifies if any manifest file has a metadata.namespace set to a static field. Replicated strongly recommends not specifying a namespace to allow for flexibility when deploying into end user environments. For more information, see Managing Application Namespaces.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: metadata: name: spline-reticulator namespace: graphviz-pro

helm-archive-missing

Description	Requires that a *.tar.gz file is present that matches what is in the HelmChart custom resource manifest file.
Level	Error
Applies To	Releases with a HelmChart custom resource manifest file containing kind: HelmChart and apiVersion: kots.io/v1beta1.

helm-chart-missing

Description	Enforces that a HelmChart custom resource manifest file with kind: HelmChart is present if there is a *.tar.gz archive present.
Level	Error
Applies To	Releases with a *.tar.gz archive file present.

helm-schema-violation

Description	Runs helm lint against each Helm chart archive in the release that is referenced by a HelmChart custom resource. Uses the chart's default values merged with spec.builder values from the HelmChart custom resource. Surfaces any violations reported by Helm, including JSON schema validation errors from the chart's values.schema.json. Each top-level violation is reported as a separate finding so that individual schema errors are easier to read and address. For more information about spec.builder, see builder in HelmChart v2.
Level	Error
Applies To	Helm v3 and later chart archives (*.tar.gz) that have a matching HelmChart custom resource. HelmChart custom resources with helmVersion: v2 are skipped.

invalid-helm-release-name

Description	Enforces valid spec.chart.releaseName in the HelmChart custom resource manifest file. spec.chart.releaseName must meet the following requirements: Begin and end with a lowercase letter or number Contain only lowercase letters, numbers, periods, and hyphens (-) Contain a lowercase letter or number between any two symbols (periods or hyphens)
Level	Warn
Applies To	Files with kind: HelmChart and apiVersion: kots.io/v1beta1.
Example	Example of correct YAML for this rule: apiVersion: kots.io/v1beta1 kind: HelmChart spec: chart: releaseName: samplechart-release-1

invalid-kubernetes-installer

Description	Enforces valid Replicated kURL add-on versions. kURL add-ons included in the kURL installer must pin specific versions rather than latest or x-ranges (1.2.x).
Level	Error
Applies To	Files with kind: Installer and one of the following values for apiVersion: cluster.kurl.sh/v1beta1 kurl.sh/v1beta1
Example	Correct: apiVersion: cluster.kurl.sh/v1beta1 kind: Installer spec: kubernetes: version: 1.24.5 Incorrect: apiVersion: cluster.kurl.sh/v1beta1 kind: Installer spec: kubernetes: version: 1.24.x ekco: version: latest

invalid-min-kots-version

Description	Requires minKotsVersion in the Application custom resource to use valid Semantic Versioning. See Semantic Versioning 2.0.0. Accepts a v as an optional prefix, so both 1.0.0 and v1.0.0 are valid.
Level	Error
Applies To	Files with kind: Application and apiVersion: kots.io/v1beta1.
Example	Example of correct YAML for this rule: apiVersion: kots.io/v1beta1 kind: Application spec: minKotsVersion: 1.0.0

invalid-rendered-yaml

Description	Enforces valid YAML after rendering the manifests using the Config spec.
Level	Error
Applies To	YAML files
Example	Example Helm Chart: apiVersion: kots.io/v1beta1 kind: HelmChart metadata: name: nginx-chart spec: chart: name: nginx-chart chartVersion: 0.1.0 helmVersion: v3 useHelmInstall: true builder: {} values: image: repl{{ ConfigOption `nginx_image`}} Correct Config: apiVersion: kots.io/v1beta1 kind: Config metadata: name: nginx-config spec: groups: - name: nginx-deployment-config title: nginx deployment config items: - name: nginx_image title: image type: text default: "nginx" Resulting Rendered Helm Chart: apiVersion: kots.io/v1beta1 kind: HelmChart metadata: name: nginx-chart spec: chart: name: nginx-chart chartVersion: 0.1.0 helmVersion: v3 useHelmInstall: true builder: {} values: image: nginx Incorrect Config: apiVersion: kots.io/v1beta1 kind: Config metadata: name: nginx-config spec: groups: - name: nginx-deployment-config items: - name: nginx_image title: image type: text default: "***HIDDEN***" Resulting Lint Error: { "lintExpressions": [ { "rule": "invalid-rendered-yaml", "type": "error", "message": "yaml: did not find expected alphabetic or numeric character: image: ***HIDDEN***", "path": "nginx-chart.yaml", "positions": null } ], "isLintingComplete": false } Incorrectly Rendered Helm Chart: apiVersion: kots.io/v1beta1 kind: HelmChart metadata: name: nginx-chart spec: chart: name: nginx-chart chartVersion: 0.1.0 helmVersion: v3 useHelmInstall: true builder: {} values: image: ***HIDDEN***

invalid-target-kots-version

Description	Requires targetKotsVersion in the Application custom resource to use valid Semantic Versioning. See Semantic Versioning 2.0.0. Accepts a v as an optional prefix, so both 1.0.0 and v1.0.0 are valid.
Level	Error
Applies To	Files with kind: Application and apiVersion: kots.io/v1beta1
Example	Example of correct YAML for this rule: apiVersion: kots.io/v1beta1 kind: Application spec: targetKotsVersion: 1.0.0

invalid-type

Description	Requires that the value of a property matches that property's expected type.
Level	Error
Applies To	All files
Example	Correct: ports: - serviceName: "example" servicePort: 80 Incorrect: ports: - serviceName: "example" servicePort: "80"

invalid-yaml

Description	Enforces valid YAML.
Level	Error
Applies To	YAML files
Example	Correct: spec: kubernetes: version: 1.24.5 Incorrect: spec: kubernetes: version 1.24.x

may-contain-secrets

Description	Notifies if any manifest file may contain secrets.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: data: ENV_VAR_1: "y2X4hPiAKn0Pbo24/i5nlInNpvrL/HJhlSCueq9csamAN8g5y1QUjQnNL7btQ=="

missing-api-version-field

Description	Requires the apiVersion: field in all files.
Level	Error
Applies To	All files
Example	Example of correct YAML for this rule: apiVersion: kots.io/v1beta1

missing-kind-field

Description	Requires the kind: field in all files.
Level	Error
Applies To	All files
Example	Example of correct YAML for this rule: kind: Config

nonexistent-status-informer-object

Description	Requires that each statusInformers entry references an existing Kubernetes workload. The linter cannot evaluate statusInformers for Helm-managed resources because it does not template Helm charts during analysis. If you configure status informers for Helm-managed resources, you can ignore nonexistent-status-informer-object warnings for those workloads. To disable nonexistent-status-informer-object warnings, change the level for this rule to info or off in the LintConfig custom resource manifest file. See LintConfig in Custom Resources.
Level	Warning
Applies To	Compares statusInformer values in files with kind: Application and apiVersion: kots.io/v1beta1 to all manifests in the release.

preflight-spec

Description	Requires a Preflight custom resource manifest file with: kind: Preflight and one of the following: apiVersion: troubleshoot.replicated.com/v1beta1 apiVersion: troubleshoot.sh/v1beta2
Level	Warn
Example	Example of matching YAML for this rule: apiVersion: troubleshoot.sh/v1beta2 kind: Preflight

privileged

Description	Notifies if any manifest file has privileged set to true.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: spec: privileged: true

repeat-option-malformed-yamlpath

Description	Enforces ConfigOption yamlPath ending with square brackets denoting index position. For more information, see Repeatable Item Template Targets in Config.
Level	Error
Applies To	All files
Example	Example of correct YAML for this rule: spec: groups: - name: ports items: - name: service_port yamlPath: 'spec.ports[0]'

repeat-option-missing-template

Description	Disallows repeating Config item with undefined item.templates. For more information, see Repeatable Item Template Targets in Config.
Level	Error
Applies To	All files
Example	Example of correct YAML for this rule: spec: groups: - name: ports items: - name: service_port title: Service Port type: text repeatable: true templates: - apiVersion: v1 kind: Service name: my-service namespace: my-app yamlPath: 'spec.ports[0]' - apiVersion: v1 kind: Service name: my-service namespace: my-app

repeat-option-missing-valuesByGroup

Description	Disallows repeating Config item with undefined item.valuesByGroup. For more information, see Repeatable Items in Config.
Level	Error
Applies To	All files
Example	Example of correct YAML for this rule: spec: groups: - name: ports items: - name: service_port title: Service Port type: text repeatable: true valuesByGroup: ports: port-default-1: "80"

replicas-1

Description	Notifies if any manifest file has replicas set to 1.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: spec: replicas: 1

resource-limits-cpu

Description	Notifies if a spec.container has no resources.limits.cpu field.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: spec: containers: - name: nginx resources: limits: memory: '256Mi' # note the lack of a cpu field

resource-limits-memory

Description	Notifies if a spec.container has no resources.limits.memory field.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: spec: containers: - name: nginx resources: limits: cpu: '500m' # note the lack of a memory field

resource-requests-cpu

Description	Notifies if a spec.container has no resources.requests.cpu field.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: spec: containers: - name: nginx resources: requests: memory: '32Mi' # note the lack of a cpu field

resource-requests-memory

Description	Notifies if a spec.container has no resources.requests.memory field.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: spec: containers: - name: nginx resources: requests: cpu: '100m' # note the lack of a memory field

troubleshoot-spec

Description	Requires a Troubleshoot manifest file. Accepted values for kind: Collector SupportBundle Accepted values for apiVersion: troubleshoot.replicated.com/v1beta1 troubleshoot.sh/v1beta2
Level	Warn
Example	Example of matching YAML for this rule: apiVersion: troubleshoot.sh/v1beta2 kind: SupportBundle

troubleshoot-spec-in-chart-without-crd

Description	Notifies if a Helm chart contains a top-level kind: Preflight or kind: SupportBundle custom resource. Preflight and SupportBundle custom resources cannot be applied directly from a Helm chart — they require cluster-side CRDs that are not available in most shared clusters and that need cluster-admin permissions to install. Embed the spec in a Kubernetes Secret with the troubleshoot.sh/kind label instead. See Define preflight checks and Add and customize support bundles.
Level	Warn
Applies To	Helm chart archives in the release

volume-docker-sock

Description	Notifies if a spec.volumes has hostPath set to /var/run/docker.sock.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: spec: volumes: - hostPath: path: /var/run/docker.sock

volumes-host-paths

Description	Notifies if a spec.volumes has defined a hostPath.
Level	Info
Applies To	All files
Example	Example of matching YAML for this rule: spec: volumes: - hostPath: path: /data