Skip to main content

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

DescriptionNotifies if any manifest file has allowPrivilegeEscalation set to true.
LevelInfo
Applies ToAll files
Example

Example of matching YAML for this rule:

spec:
allowPrivilegeEscalation: true

application-icon

Description

Requires an application icon.

LevelWarn
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

LevelWarn
Example

Example of matching YAML for this rule:

apiVersion: kots.io/v1beta1
kind: Application

application-statusInformers

Description

Requires statusInformers.

LevelWarn
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.

LevelError
Applies ToAll 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

DescriptionEnforces that all ConfigOption items do not reference themselves.
LevelError
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.

LevelWarn
Applies ToAll files

config-option-not-repeatable

Description

Enforces that sub-templated ConfigOption items must be repeatable.

LevelError
Applies ToAll files

config-option-password-type

Description

Requires ConfigOption items with any of the following names to have type set to password:

  • password
  • secret
  • token
LevelWarn
Applies ToAll 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.

LevelError
Applies ToFiles 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.

LevelError
Applies ToFiles 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.

LevelError
Applies ToFiles 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

LevelWarn
Example

Example of matching YAML for this rule:

apiVersion: kots.io/v1beta1
kind: Config

container-image-latest-tag

DescriptionNotifies if any manifest file has a container image tag appended with :latest.
LevelInfo
Applies ToAll files
Example

Example of matching YAML for this rule:

spec:
containers:
- image: nginx:latest

container-image-local-image-name

DescriptionDisallows any manifest file having a container image tag that includes LocalImageName.
LevelError
Applies ToAll files
Example

Example of matching YAML for this rule:

spec:
containers:
- image: LocalImageName

container-resource-limits

DescriptionNotifies if a spec.container has no resources.limits field.
LevelInfo
Applies ToAll 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

DescriptionNotifies if a spec.container has no resources.requests field.
LevelInfo
Applies ToAll 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

DescriptionNotifies if a manifest file has no resources field.
LevelInfo
Applies ToAll 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.

LevelWarn
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.

LevelError
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
LevelError
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.

LevelInfo
Applies ToAll 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.

LevelError
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.

LevelError
Applies To

Releases with a *.tar.gz archive file present.

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)
LevelWarn
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).

LevelError
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.

LevelError
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.

LevelError
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.

LevelError
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.

LevelError
Applies To

All files

Example

Correct:

ports:
- serviceName: "example"
servicePort: 80

Incorrect:

ports:
- serviceName: "example"
servicePort: "80"

invalid-yaml

Description

Enforces valid YAML.

LevelError
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.
LevelInfo
Applies ToAll files
Example

Example of matching YAML for this rule:

data:
ENV_VAR_1: "y2X4hPiAKn0Pbo24/i5nlInNpvrL/HJhlSCueq9csamAN8g5y1QUjQnNL7btQ=="

missing-api-version-field

DescriptionRequires the apiVersion: field in all files.
LevelError
Applies ToAll files
Example

Example of correct YAML for this rule:

apiVersion: kots.io/v1beta1

missing-kind-field

DescriptionRequires the kind: field in all files.
LevelError
Applies ToAll 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.

LevelWarning
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
LevelWarn
Example

Example of matching YAML for this rule:

apiVersion: troubleshoot.sh/v1beta2
kind: Preflight

privileged

DescriptionNotifies if any manifest file has privileged set to true.
LevelInfo
Applies ToAll 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.

LevelError
Applies ToAll 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.

LevelError
Applies ToAll 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.

LevelError
Applies ToAll 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

DescriptionNotifies if any manifest file has replicas set to 1.
LevelInfo
Applies ToAll files
Example

Example of matching YAML for this rule:

spec:
replicas: 1

resource-limits-cpu

DescriptionNotifies if a spec.container has no resources.limits.cpu field.
LevelInfo
Applies ToAll 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

DescriptionNotifies if a spec.container has no resources.limits.memory field.
LevelInfo
Applies ToAll 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

DescriptionNotifies if a spec.container has no resources.requests.cpu field.
LevelInfo
Applies ToAll 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

DescriptionNotifies if a spec.container has no resources.requests.memory field.
LevelInfo
Applies ToAll 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
LevelWarn
Example

Example of matching YAML for this rule:

apiVersion: troubleshoot.sh/v1beta2
kind: SupportBundle

volume-docker-sock

DescriptionNotifies if a spec.volumes has hostPath set to /var/run/docker.sock.
LevelInfo
Applies ToAll files
Example

Example of matching YAML for this rule:

spec:
volumes:
- hostPath:
path: /var/run/docker.sock

volumes-host-paths

DescriptionNotifies if a spec.volumes has defined a hostPath.
LevelInfo
Applies ToAll files
Example

Example of matching YAML for this rule:

spec:
volumes:
- hostPath:
path: /data