Documentation
¶
Overview ¶
Package lint2 provides linting functionality for Replicated resources that integrates with the replicated CLI tool resolver infrastructure.
This package enables automatic downloading and execution of linting commands for:
- Helm charts (via helm lint)
- Preflight specs (via preflight lint from troubleshoot.sh)
- Support Bundle specs (via support-bundle lint from troubleshoot.sh)
Features ¶
Common functionality across all linters:
- Resource path expansion (including glob patterns)
- Resource validation (ensuring valid structure)
- Binary resolution via tool-resolver (automatic download/caching)
- Output parsing into structured results
- Support for custom tool versions
Glob pattern support (powered by doublestar library):
- Basic patterns: * (any chars), ? (one char), [abc] (char class)
- Recursive matching: ** (matches zero or more directories)
- Brace expansion: {alt1,alt2} (matches alternatives)
- Pattern validation: Early syntax checking during config parse
Helm-specific:
- Chart directory validation (Chart.yaml presence)
- Multi-chart linting with summary results
Troubleshoot (Preflight/Support Bundle) specific:
- Multi-document YAML parsing with yaml.NewDecoder
- JSON output parsing with generic type-safe implementation
- Auto-discovery of Support Bundles from manifest files
Usage ¶
The typical workflow for any linter is:
- Load configuration using tools.ConfigParser
- Extract and validate resource paths
- Resolve tool binary (downloads if not cached)
- Execute lint command on each resource
- Parse and display results
Example - Helm Charts ¶
parser := tools.NewConfigParser()
config, err := parser.FindAndParseConfig(".")
if err != nil {
return err
}
chartPaths, err := lint2.GetChartPathsFromConfig(config)
if err != nil {
return err
}
for _, chartPath := range chartPaths {
result, err := lint2.LintChart(ctx, chartPath, helmVersion)
if err != nil {
return err
}
// Process result...
}
Example - Preflight Specs ¶
preflightPaths, err := lint2.GetPreflightPathsFromConfig(config)
if err != nil {
return err
}
for _, specPath := range preflightPaths {
result, err := lint2.LintPreflight(ctx, specPath, preflightVersion)
if err != nil {
return err
}
// Process result...
}
Example - Support Bundle Specs ¶
// Support bundles are auto-discovered from manifest files
sbPaths, err := lint2.DiscoverSupportBundlesFromManifests(config.Manifests)
if err != nil {
return err
}
for _, specPath := range sbPaths {
result, err := lint2.LintSupportBundle(ctx, specPath, sbVersion)
if err != nil {
return err
}
// Process result...
}
Package lint2 provides linting functionality for Replicated resources. It supports linting Helm charts via helm lint and Preflight specs via preflight lint. Each linter executes the appropriate tool binary and parses the output into structured results.
Index ¶
- func ContainsGlob(path string) bool
- func DiscoverChartPaths(pattern string) ([]string, error)
- func DiscoverHelmChartManifests(manifestGlobs []string) (map[string]*HelmChartManifest, error)
- func DiscoverPreflightPaths(pattern string) ([]string, error)
- func DiscoverSupportBundlePaths(pattern string) ([]string, error)
- func DiscoverSupportBundlesFromManifests(manifestGlobs []string) ([]string, error)
- func GetChartPathsFromConfig(config *tools.Config) ([]string, error)
- func GetPreflightPathsFromConfig(config *tools.Config) ([]string, error)
- func Glob(pattern string) ([]string, error)
- func GlobFiles(pattern string) ([]string, error)
- func ValidateGlobPattern(pattern string) error
- type ChartMetadata
- type ChartWithMetadata
- type DuplicateHelmChartError
- type HelmChartManifest
- type LintMessage
- type LintResult
- func LintChart(ctx context.Context, chartPath string, helmVersion string) (*LintResult, error)
- func LintPreflight(ctx context.Context, specPath string, valuesPath string, chartName string, ...) (*LintResult, error)
- func LintSupportBundle(ctx context.Context, specPath string, sbVersion string) (*LintResult, error)
- type PreflightFileResult
- type PreflightLintIssue
- type PreflightLintResult
- type PreflightWithValues
- type SupportBundleFileResult
- type SupportBundleLintIssue
- type SupportBundleLintResult
- type TroubleshootFileResult
- type TroubleshootIssue
- type TroubleshootLintResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ContainsGlob ¶
ContainsGlob checks if a path contains glob wildcards (* ? [ {). Exported for use by config parsing to detect patterns that need validation.
func DiscoverChartPaths ¶
discoverChartPaths discovers Helm chart directories from a glob pattern. This is a thin wrapper around discoverDirsByMarkerFile for backward compatibility.
Supports patterns like:
- "./charts/**" (finds all charts recursively)
- "./charts/{app,api}/**" (finds charts in specific subdirectories)
- "./pkg/**/Chart.yaml" (explicit Chart.yaml pattern)
- "./my-chart" (explicit directory path - validated strictly)
func DiscoverHelmChartManifests ¶
func DiscoverHelmChartManifests(manifestGlobs []string) (map[string]*HelmChartManifest, error)
DiscoverHelmChartManifests scans manifest glob patterns and extracts HelmChart custom resources. It returns a map keyed by "name:chartVersion" for efficient lookup during preflight rendering.
Accepts HelmChart resources with any apiVersion (validation happens in the linter).
Returns an error if:
- manifestGlobs is empty (required to find builder values for templated preflights)
- Duplicate name:chartVersion pairs are found (ambiguous builder values)
- Glob expansion fails
Silently skips:
- Files that can't be read
- Files that aren't valid YAML
- Files that don't contain kind: HelmChart
- Hidden directories (.git, .github, etc.)
func DiscoverPreflightPaths ¶
discoverPreflightPaths discovers Preflight spec files from a glob pattern. This is a thin wrapper around discoverYAMLsByKind for backward compatibility.
Supports patterns like:
- "./preflights/**" (finds all Preflight specs recursively)
- "./preflights/**/*.yaml" (explicit YAML extension)
- "./k8s/{dev,prod}/**/*.yaml" (environment-specific)
- "./preflight.yaml" (explicit file path - validated strictly)
func DiscoverSupportBundlePaths ¶
discoverSupportBundlePaths discovers Support Bundle spec files from a glob pattern. This is a thin wrapper around discoverYAMLsByKind for backward compatibility.
Supports patterns like:
- "./manifests/**" (finds all Support Bundle specs recursively)
- "./manifests/**/*.yaml" (explicit YAML extension)
- "./k8s/{dev,prod}/**/*.yaml" (environment-specific)
- "./support-bundle.yaml" (explicit file path - validated strictly)
func DiscoverSupportBundlesFromManifests ¶
DiscoverSupportBundlesFromManifests discovers support bundle spec files from manifest glob patterns. It expands the glob patterns, reads each YAML file, and identifies files containing kind: SupportBundle. This allows support bundles to be co-located with other Kubernetes manifests without explicit configuration.
func GetChartPathsFromConfig ¶
GetChartPathsFromConfig extracts and expands chart paths from config
func GetPreflightPathsFromConfig ¶
GetPreflightPathsFromConfig extracts and expands preflight spec paths from config
func Glob ¶
Glob expands glob patterns using doublestar library, which supports: - * : matches any sequence of non-separator characters - ** : matches zero or more directories (recursive) - ? : matches any single character - [abc] : matches any character in the brackets - {alt1,alt2} : matches any of the alternatives
This is a wrapper around doublestar.FilepathGlob that provides: - Drop-in replacement for filepath.Glob - Recursive ** globbing (unlike stdlib filepath.Glob) - Brace expansion {a,b,c}
func GlobFiles ¶
GlobFiles expands glob patterns returning only files (not directories). Uses WithFilesOnly() option for efficient library-level filtering. This is useful for preflight specs and manifest discovery where only files should be processed.
func ValidateGlobPattern ¶
ValidateGlobPattern checks if a pattern is valid doublestar glob syntax and does not contain path traversal attempts. This is useful for validating user input early before attempting to expand patterns. Returns an error if the pattern syntax is invalid or attempts path traversal.
Types ¶
type ChartMetadata ¶
ChartMetadata represents basic metadata from a Helm chart's Chart.yaml
func GetChartMetadata ¶
func GetChartMetadata(chartPath string) (*ChartMetadata, error)
GetChartMetadata reads Chart.yaml and returns the chart name and version
type ChartWithMetadata ¶
type ChartWithMetadata struct {
Path string // Absolute path to the chart directory
Name string // Chart name from Chart.yaml
Version string // Chart version from Chart.yaml
}
ChartWithMetadata pairs a chart path with its metadata from Chart.yaml
func GetChartsWithMetadataFromConfig ¶
func GetChartsWithMetadataFromConfig(config *tools.Config) ([]ChartWithMetadata, error)
GetChartsWithMetadataFromConfig extracts chart paths and their metadata from config This function combines GetChartPathsFromConfig with metadata extraction, reducing boilerplate for callers that need both path and metadata information (like image extraction).
type DuplicateHelmChartError ¶
type DuplicateHelmChartError struct {
ChartKey string // "name:chartVersion"
FirstFile string
SecondFile string
}
DuplicateHelmChartError is returned when multiple HelmChart manifests are found with the same name:chartVersion combination.
func (*DuplicateHelmChartError) Error ¶
func (e *DuplicateHelmChartError) Error() string
type HelmChartManifest ¶
type HelmChartManifest struct {
Name string // spec.chart.name - must match Chart.yaml name
ChartVersion string // spec.chart.chartVersion - must match Chart.yaml version
BuilderValues map[string]interface{} // spec.builder - values for air gap bundle rendering (can be nil/empty)
FilePath string // Source file path for error reporting
}
HelmChartManifest represents a parsed KOTS HelmChart custom resource. It contains the fields needed to match charts with their builder values for preflight template rendering.
func FindHelmChartManifest ¶
func FindHelmChartManifest(chartName, chartVersion string, manifests map[string]*HelmChartManifest) *HelmChartManifest
FindHelmChartManifest looks up a HelmChart manifest by chart name and version. The matching key format is "name:version" which must exactly match both the chart metadata and the HelmChart manifest's spec.chart.name and spec.chart.chartVersion. Returns nil if no matching manifest is found.
type LintMessage ¶
type LintMessage struct {
Severity string // "ERROR", "WARNING", "INFO"
Path string // File path (if provided by helm)
Message string // The lint message
}
LintMessage represents a single finding from helm lint
type LintResult ¶
type LintResult struct {
Success bool
Messages []LintMessage
}
LintResult represents the outcome of linting a chart
func LintChart ¶
LintChart executes helm lint on the given chart path and returns structured results
func LintPreflight ¶
func LintPreflight( ctx context.Context, specPath string, valuesPath string, chartName string, chartVersion string, helmChartManifests map[string]*HelmChartManifest, preflightVersion string, ) (*LintResult, error)
LintPreflight executes preflight lint with template rendering using builder values.
Template Rendering: The preflight tool uses Helm internally for template rendering, providing full support for:
- All Sprig functions (default, quote, upper, lower, trim, sha256, etc.)
- Helm template functions (include, required, tpl, toYaml, toJson, etc.)
- Flow control (if, range, with, define, template, block)
- Variables and complex pipelines
Example advanced templates:
{{- if .Values.database.enabled }}
- postgres:
uri: {{ .Values.database.uri | default "postgresql://localhost" | quote }}
{{- end }}
{{- range .Values.services }}
- http:
get:
url: {{ printf "http://%s:%d" .host (.port | int) | quote }}
{{- end }}
{{- define "app.name" -}}{{ .Values.appName }}-{{ .Values.env }}{{- end -}}
message: {{ include "app.name" . | quote }}
Known Limitation: Do not nest template actions inside quoted strings with escaped quotes. This will fail: message: "Name: {{ template \"app.name\" . }}" Use instead: message: {{ include "app.name" . | quote }}
Requirements:
- valuesPath: Path to chart values.yaml file
- chartName and chartVersion: Chart metadata for matching with HelmChart manifest
- helmChartManifests: Map of discovered HelmChart manifests containing builder values
- All preflights must have an associated chart structure and HelmChart manifest
func LintSupportBundle ¶
LintSupportBundle executes support-bundle lint on the given spec path and returns structured results
type PreflightFileResult ¶
type PreflightFileResult struct {
FilePath string `json:"filePath"`
Errors []PreflightLintIssue `json:"errors"`
Warnings []PreflightLintIssue `json:"warnings"`
Infos []PreflightLintIssue `json:"infos"`
}
type PreflightLintIssue ¶
type PreflightLintIssue struct {
Line int `json:"line"`
Column int `json:"column"`
Message string `json:"message"`
Field string `json:"field"`
}
func (PreflightLintIssue) GetColumn ¶
func (i PreflightLintIssue) GetColumn() int
func (PreflightLintIssue) GetField ¶
func (i PreflightLintIssue) GetField() string
func (PreflightLintIssue) GetLine ¶
func (i PreflightLintIssue) GetLine() int
Implement TroubleshootIssue interface for PreflightLintIssue
func (PreflightLintIssue) GetMessage ¶
func (i PreflightLintIssue) GetMessage() string
type PreflightLintResult ¶
type PreflightLintResult struct {
Results []PreflightFileResult `json:"results"`
}
PreflightLintResult represents the JSON output from preflight lint
type PreflightWithValues ¶
type PreflightWithValues struct {
SpecPath string // Path to the preflight spec file
ValuesPath string // Path to values.yaml for template rendering (required)
ChartName string // Chart name from Chart.yaml (required)
ChartVersion string // Chart version from Chart.yaml (required)
}
PreflightWithValues contains preflight spec path and associated chart/values information All fields are required - every preflight must have an associated chart structure
func GetPreflightWithValuesFromConfig ¶
func GetPreflightWithValuesFromConfig(config *tools.Config) ([]PreflightWithValues, error)
GetPreflightWithValuesFromConfig extracts preflight paths with associated chart/values information
type SupportBundleFileResult ¶
type SupportBundleFileResult struct {
FilePath string `json:"filePath"`
Errors []SupportBundleLintIssue `json:"errors"`
Warnings []SupportBundleLintIssue `json:"warnings"`
Infos []SupportBundleLintIssue `json:"infos"`
}
type SupportBundleLintIssue ¶
type SupportBundleLintIssue struct {
Line int `json:"line"`
Column int `json:"column"`
Message string `json:"message"`
Field string `json:"field"`
}
func (SupportBundleLintIssue) GetColumn ¶
func (i SupportBundleLintIssue) GetColumn() int
func (SupportBundleLintIssue) GetField ¶
func (i SupportBundleLintIssue) GetField() string
func (SupportBundleLintIssue) GetLine ¶
func (i SupportBundleLintIssue) GetLine() int
Implement TroubleshootIssue interface for SupportBundleLintIssue
func (SupportBundleLintIssue) GetMessage ¶
func (i SupportBundleLintIssue) GetMessage() string
type SupportBundleLintResult ¶
type SupportBundleLintResult struct {
Results []SupportBundleFileResult `json:"results"`
}
SupportBundleLintResult represents the JSON output from support-bundle lint This structure mirrors PreflightLintResult since both tools come from the same troubleshoot repository and share the same validation infrastructure.
type TroubleshootFileResult ¶
type TroubleshootFileResult[T TroubleshootIssue] struct { FilePath string `json:"filePath"` Errors []T `json:"errors"` Warnings []T `json:"warnings"` Infos []T `json:"infos"` }
TroubleshootFileResult represents the common structure for file-level results from troubleshoot.sh linting tools (preflight, support-bundle, etc.)
type TroubleshootIssue ¶
type TroubleshootIssue interface {
GetLine() int
GetColumn() int
GetMessage() string
GetField() string
}
TroubleshootIssue is an interface that both PreflightLintIssue and SupportBundleLintIssue satisfy, allowing common formatting logic. Both tools come from the troubleshoot.sh repository and share the same validation infrastructure and output format.
type TroubleshootLintResult ¶
type TroubleshootLintResult[T TroubleshootIssue] struct { Results []TroubleshootFileResult[T] `json:"results"` }
TroubleshootLintResult represents the common JSON structure for troubleshoot.sh linting tool output
Source Files