Skip to content

Commit 973cbfe

Browse files
committed
docs: add balanced linter sections for all 5 linters
Replace verbose embedded-cluster section (148 lines) with comprehensive "Linter-Specific Configuration" section covering all 5 linters (135 lines). Each linter now has consistent documentation: - Helm: Chart structure and template validation - Support Bundle: Collector spec validation - Embedded Cluster: EC config validation (trimmed from 148 to ~30 lines) - KOTS: KOTS Config manifest validation (new, ~40 lines) All sections include: - What it validates - Configuration example - Auto-discovery behavior - Key constraints (e.g., 1 config limit for EC and KOTS) KOTS section highlights: - GVK filtering distinguishes KOTS Config (kots.io) from EC Config - Multiple config error message with actionable guidance - Example KOTS Config manifest Removed platform requirements for EC (Darwin support coming soon).
1 parent d8c5911 commit 973cbfe

File tree

1 file changed

+91
-105
lines changed

1 file changed

+91
-105
lines changed

docs/lint-format.md

Lines changed: 91 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -298,151 +298,137 @@ spec:
298298
299299
**Solution:** Either add the corresponding chart to your configuration or remove the unused HelmChart manifest. Warnings are informational and won't cause linting to fail.
300300
301-
## Embedded Cluster Configuration
301+
## Linter-Specific Configuration
302302
303-
The embedded-cluster linter validates Embedded Cluster configuration files. Embedded Cluster is Replicated's solution for packaging Kubernetes and your application together as a single appliance-style installer.
303+
### Helm Linter
304304
305-
### What It Validates
305+
The Helm linter validates Helm chart structure, templates, and values files using the official `helm lint` command.
306306

307-
The embedded-cluster linter validates:
308-
- Configuration schema correctness
309-
- Kubernetes version compatibility
310-
- Extension configurations
311-
- Network and storage settings
312-
- High availability settings
313-
- Custom branding configuration
307+
**What it validates:**
308+
- Chart.yaml metadata and format
309+
- Template syntax and rendering
310+
- Values file structure
311+
- Required files and directories
312+
- Kubernetes resource validity
314313

315-
### Platform Requirements
314+
**Configuration:**
315+
```yaml
316+
repl-lint:
317+
linters:
318+
helm:
319+
enabled: true
320+
strict: false # Set to true to treat warnings as errors
321+
tools:
322+
helm: "latest" # Optional: pin to specific version (e.g., "3.14.4")
323+
```
316324

317-
**Important:** The embedded-cluster linter binary is currently only available for **Linux AMD64**.
325+
**Auto-discovery:** Automatically finds charts by locating `Chart.yaml` files in your project.
318326

319-
- ✅ **Linux (x86_64/amd64)**: Full support
320-
- ❌ **macOS**: Not currently available
321-
- ❌ **Windows**: Not currently available
322-
- ❌ **ARM64**: Not currently available
327+
---
323328

324-
If you're on an unsupported platform:
325-
- The linter will fail gracefully with a clear error message
326-
- Other linters (helm, preflight, support-bundle) will continue running
327-
- Consider running in a Linux container or CI environment
329+
### Support Bundle Linter
328330

329-
### Configuration
331+
The Support Bundle linter validates support bundle collector specs for Replicated's troubleshooting framework.
330332

331-
Enable the embedded-cluster linter in your `.replicated` file:
333+
**What it validates:**
334+
- Collector spec syntax and structure
335+
- Analyzer definitions
336+
- Output redaction rules
337+
- Kubernetes resource collectors
332338

339+
**Configuration:**
333340
```yaml
334341
repl-lint:
335-
version: 1
336342
linters:
337-
embedded-cluster:
343+
support-bundle:
338344
enabled: true
339-
strict: false # Set to true to treat warnings as errors
345+
strict: false
340346
tools:
341-
embedded-cluster: "latest" # Optional: pin to specific version
347+
support-bundle: "latest" # Optional: pin to specific version
342348
```
343349

344-
### Auto-Discovery
350+
**Auto-discovery:** Finds support bundle specs by locating files with `kind: SupportBundle` or `kind: Collector`.
345351

346-
When no `.replicated` config exists, the linter automatically discovers embedded-cluster configs by:
347-
- Finding files with `kind: Config` and `apiVersion: embeddedcluster.replicated.com/v1beta1`
348-
- Validating only 0 or 1 config exists (multiple configs are not supported)
352+
---
349353

350-
### Multiple Config Validation
354+
### Embedded Cluster Linter
351355

352-
**Only 0 or 1 embedded cluster config is allowed per project.**
356+
The Embedded Cluster linter validates Embedded Cluster configuration files for Replicated's embedded Kubernetes installer solution.
353357

354-
If multiple configs are detected:
355-
- Each config will show as failed with a clear error message
356-
- Other linters (helm, preflight, support-bundle) continue running
357-
- The linting command returns a non-zero exit code
358+
**What it validates:**
359+
- Configuration schema correctness
360+
- Kubernetes version compatibility
361+
- Extension configurations
362+
- Network and storage settings
363+
- High availability settings
358364

359-
### Example Configuration
365+
**Important constraint:** Only 0 or 1 embedded cluster config is allowed per project.
360366

361-
**Minimal `.replicated` with embedded-cluster:**
367+
**Configuration:**
362368
```yaml
363-
appId: ""
364-
appSlug: "my-app"
365-
manifests:
366-
- "./embedded-cluster/*.yaml"
367-
368369
repl-lint:
369-
version: 1
370370
linters:
371371
embedded-cluster:
372372
enabled: true
373-
strict: true
373+
strict: false
374374
tools:
375375
embedded-cluster: "latest"
376376
```
377377

378-
**Example embedded-cluster config file (ec-config.yaml):**
379-
```yaml
380-
apiVersion: embeddedcluster.replicated.com/v1beta1
381-
kind: Config
382-
metadata:
383-
name: my-app-config
384-
spec:
385-
version: "1.33+k8s-1.33"
386-
roles:
387-
controller:
388-
name: "Controller"
389-
description: "Kubernetes controller node"
390-
391-
extensions:
392-
helm:
393-
repositories:
394-
- name: my-repo
395-
url: https://charts.example.com
396-
397-
network:
398-
podCIDR: "10.244.0.0/16"
399-
serviceCIDR: "10.96.0.0/12"
400-
401-
unsupportedOverrides:
402-
k0s: |
403-
apiVersion: k0s.k0sproject.io/v1beta1
404-
kind: ClusterConfig
405-
spec:
406-
network:
407-
provider: calico
408-
```
378+
**Auto-discovery:** Finds configs by locating files with:
379+
- `kind: Config`
380+
- `apiVersion: embeddedcluster.replicated.com/v1beta1`
409381

410-
### Output Format
382+
**Multiple configs error:** If multiple configs are found, each will show as failed with a clear error message. Other linters continue running.
411383

412-
The embedded-cluster linter returns JSON output with structured validation results:
384+
---
413385

414-
```json
415-
{
416-
"files": [
417-
{
418-
"path": "embedded-cluster/config.yaml",
419-
"valid": true,
420-
"errors": [],
421-
"warnings": [],
422-
"infos": []
423-
}
424-
]
425-
}
426-
```
386+
### KOTS Linter
427387

428-
**Validation Messages:**
429-
- **errors**: Schema violations, invalid values, unsupported configurations
430-
- **warnings**: Deprecated fields, potential issues, best practice violations
431-
- **infos**: Informational messages about configuration choices
388+
The KOTS linter validates KOTS Config manifests (custom resource for application configuration UI).
432389

433-
### Troubleshooting
390+
**What it validates:**
391+
- Config schema correctness
392+
- Config group and item definitions
393+
- Field types and validation rules
394+
- Template syntax
395+
- Required vs optional fields
434396

435-
**Problem:** "embedded-cluster binaries are only available for linux-amd64"
397+
**Important constraint:** Only 0 or 1 KOTS config is allowed per project.
436398

437-
**Solution:**
438-
- Run linting in a Linux environment or Docker container
439-
- Use CI/CD on Linux runners
440-
- The error won't block other linters from running
399+
**Configuration:**
400+
```yaml
401+
repl-lint:
402+
linters:
403+
kots:
404+
enabled: true
405+
strict: false
406+
tools:
407+
kots: "latest" # Optional: pin to specific version
408+
```
441409

442-
**Problem:** "Multiple embedded cluster configs found"
410+
**Auto-discovery:** Finds KOTS Configs by locating files with:
411+
- `kind: Config`
412+
- `apiVersion: kots.io/*` (any version: v1beta1, v1beta2, v1, etc.)
443413

444-
**Solution:** Only one embedded cluster config is allowed per project. Remove duplicate configs or move them to separate projects.
414+
**GVK filtering:** The linter distinguishes KOTS Config (`kots.io`) from Embedded Cluster Config (`embeddedcluster.replicated.com`) using Group-Version-Kind filtering. Both use `kind: Config` but belong to different API groups.
445415

446-
**Problem:** Validation errors about Kubernetes version
416+
**Multiple configs error:** If multiple KOTS configs are found, each will show as failed with an actionable error message: "Remove duplicate configs or specify a single config file." Other linters continue running.
447417

448-
**Solution:** Ensure the `spec.version` field uses a supported Kubernetes version. Check the embedded-cluster documentation for supported versions.
418+
**Example KOTS Config:**
419+
```yaml
420+
apiVersion: kots.io/v1beta1
421+
kind: Config
422+
metadata:
423+
name: my-app-config
424+
spec:
425+
groups:
426+
- name: database
427+
title: Database Settings
428+
items:
429+
- name: postgres_host
430+
title: PostgreSQL Host
431+
type: text
432+
required: true
433+
default: "postgres"
434+
```

0 commit comments

Comments
 (0)