[dmt] bump docs (#314)

Signed-off-by: Pavel Okhlopkov <[email protected]>

Author: ldmonster

pkg/linters/container/README.md

@@ -23,13 +23,13 @@ Proper container configuration is critical for cluster stability, security, and
 
 | Rule | Description | Configurable | Default |
 |------|-------------|--------------|---------|
-| [recommended-labels](#recommended-labels) | Validates required labels (module, heritage) | ✅ | enabled |
-| [namespace-labels](#namespace-labels) | Validates Prometheus watcher label on d8-* namespaces | ❌ | enabled |
-| [api-version](#api-version) | Validates API versions are not deprecated | ❌ | enabled |
-| [priority-class](#priority-class) | Validates PriorityClass is set and allowed | ❌ | enabled |
+| [object-recommended-labels](#object-recommended-labels) | Validates required labels (module, heritage) | ❌ | enabled |
+| [object-namespace-labels](#object-namespace-labels) | Validates Prometheus watcher label on d8-* namespaces | ❌ | enabled |
+| [object-api-version](#object-api-version) | Validates API versions are not deprecated | ❌ | enabled |
+| [object-priority-class](#object-priority-class) | Validates PriorityClass is set and allowed | ❌ | enabled |
 | [dns-policy](#dns-policy) | Validates DNS policy for hostNetwork pods | ✅ | enabled |
 | [controller-security-context](#controller-security-context) | Validates Pod-level security context | ✅ | enabled |
-| [revision-history-limit](#revision-history-limit) | Validates Deployment revision history limit ≤ 2 | ❌ | enabled |
+| [object-revision-history-limit](#object-revision-history-limit) | Validates Deployment revision history limit ≤ 2 | ❌ | enabled |
 | [name-duplicates](#name-duplicates) | Validates no duplicate container names | ❌ | enabled |
 | [read-only-root-filesystem](#read-only-root-filesystem) | Validates containers use read-only root filesystem | ✅ | enabled |
 | [host-network-ports](#host-network-ports) | Validates host network and host port usage | ✅ | enabled |
@@ -46,7 +46,7 @@ Proper container configuration is critical for cluster stability, security, and
 
 ## Rule Details
 
-### recommended-labels
+### object-recommended-labels
 
 **Purpose:** Ensures all Kubernetes objects have required labels for proper identification, monitoring, and management within the Deckhouse platform. These labels are used for resource tracking, metrics collection, and operational automation.
 
@@ -102,9 +102,7 @@ metadata:
 
 ---
 
-**Configuration:**
-
-### namespace-labels
+### object-namespace-labels
 
 **Purpose:** Ensures Deckhouse namespaces (prefixed with `d8-`) have the Prometheus rules watcher label enabled. This allows Prometheus to automatically discover and apply monitoring rules for the namespace.
 
@@ -178,7 +176,7 @@ metadata:
 
 ---
 
-### api-version
+### object-api-version
 
 **Purpose:** Prevents use of deprecated Kubernetes API versions that may be removed in future Kubernetes releases. This ensures module compatibility with current and future Kubernetes versions.
 
@@ -230,7 +228,7 @@ metadata:
 
 ---
 
-### priority-class
+### object-priority-class
 
 **Purpose:** Ensures all workloads have appropriate priority classes assigned for proper pod scheduling and preemption behavior. This prevents workloads from running without priority, which can cause scheduling issues.
 
@@ -474,7 +472,7 @@ linters-settings:
 
 ---
 
-### revision-history-limit
+### object-revision-history-limit
 
 **Purpose:** Limits the number of old ReplicaSets retained for each Deployment to reduce control plane resource consumption. Deckhouse doesn't use rollback functionality, so keeping many old ReplicaSets is wasteful.
 

pkg/linters/images/README.md

@@ -68,11 +68,13 @@ FROM $BASE_GOLANG_16_ALPINE
 linters-settings:
   images:
     exclude-rules:
-      skip-image-file-path-prefix:
+      skip-distroless-file-path-prefix:
         - "updater"        # Skip images/updater/
         - "legacy"         # Skip images/legacy/
 ```
 
+> Note: Currently, dockerfile rule uses the same exclusion list as distroless rule (`skip-distroless-file-path-prefix`).
+
 ---
 
 ### Distroless
@@ -247,7 +249,7 @@ Validates patch file organization, naming, and documentation.
 - ✅ Patch files are in `images/<image_name>/patches/` directory
 - ✅ Patch file names follow pattern: `XXX-<patch-name>.patch` (e.g., `001-fix-ssl.patch`)
 - ✅ Each patches directory has a `README.md` file
-- ✅ README.md documents each patch with `# XXX-<patch-name>.patch` header
+- ✅ README.md documents each patch with `# XXX-<patch-name>.patch` header (single `#`, not `##`)
 
 **Patch Directory Structure:**
 ```
@@ -271,17 +273,17 @@ images/
 ```markdown
 # Patches
 
-## 001-fix-ssl.patch
+# 001-fix-ssl.patch
 - **Issue**: SSL handshake fails with certain clients
 - **Upstream**: https://github.com/project/repo/issues/1234
 - **Status**: Waiting for upstream fix in v2.0
 
-## 002-update-config.patch
+# 002-update-config.patch
 - **Issue**: Default config incompatible with Kubernetes
 - **Upstream**: PR submitted https://github.com/project/repo/pull/5678
 - **Status**: Merged, will be in next release
 
-## 003-security-fix.patch
+# 003-security-fix.patch
 - **Issue**: CVE-2024-12345 vulnerability
 - **Upstream**: https://github.com/project/repo/security/advisories/GHSA-xxxx
 - **Status**: Backport from upstream fix
@@ -339,15 +341,11 @@ Configure the Images linter in `.dmtlint.yaml`:
 ```yaml
 linters-settings:
   images:
-    # Exclude specific image paths from dockerfile checks
+    # Exclude specific image paths from dockerfile and distroless checks
     exclude-rules:
-      skip-image-file-path-prefix:
-        - "updater"          # Skip images/updater/
-        - "legacy"           # Skip images/legacy/
-      
-      # Exclude specific image paths from distroless checks
+      # Note: Both dockerfile and distroless rules use this exclusion list
       skip-distroless-file-path-prefix:
-        - "updater"          # Skip distroless validation
+        - "updater"          # Skip images/updater/
         - "debug-tools"      # Skip for debug images
     
     # Rule-specific settings
@@ -426,11 +424,11 @@ final: false
 
 **Error:** `README.md file does not contain # 001-fix-ssl.patch`
 
-**Solution:** Add documentation to `patches/README.md`:
+**Solution:** Add documentation to `patches/README.md` with single `#` heading:
 ```markdown
 # Patches
 
-## 001-fix-ssl.patch
+# 001-fix-ssl.patch
 - **Issue**: Description of the issue
 - **Upstream**: Link to upstream issue/PR
 - **Status**: Current status

pkg/linters/images/rules/distroless.go

@@ -125,7 +125,7 @@ func isDockerfileInstructionUnacceptable(from string, final bool) (bool, string)
 	} else {
 		matched, _ := regexp.MatchString("@sha256:[A-Fa-f0-9]{64}", from)
 		if !strings.HasPrefix(from, "$BASE_") && !matched {
-			return true, "Intermediate `FROM` instructions should use one of our $BASE_ images or have `@sha526:` checksum specified"
+			return true, "Intermediate `FROM` instructions should use one of our $BASE_ images or have `@sha256:` checksum specified"
 		}
 	}
 

pkg/linters/module/README.md

@@ -32,10 +32,26 @@ Validates the `module.yaml` configuration file structure and content.
 
 **Checks:**
 - ✅ File exists and is valid YAML
-- ✅ Required fields are present (name, namespace)
+- ✅ Required fields are present:
+  - `name` - Module name (max 64 characters)
+  - `stage` - Module stage (required)
+  - `descriptions.en` - English description (required)
 - ✅ Optional fields are valid when present
 - ✅ Accessibility configuration is correct
 - ✅ Update section follows versioning rules
+- ✅ `weight` must not be zero for critical modules
+- ✅ `description` field is deprecated (use `descriptions.en` instead)
+
+#### Stage Values
+
+The `stage` field defines the module's lifecycle stage:
+
+| Stage | Description |
+|-------|-------------|
+| `Experimental` | Early development, may have breaking changes |
+| `Preview` | Feature complete but not production-ready |
+| `General Availability` | Production-ready and stable |
+| `Deprecated` | Scheduled for removal |
 
 #### Accessibility Validation
 
@@ -69,6 +85,10 @@ namespace: d8-my-module
 weight: 100
 stage: "General Availability"
 
+descriptions:
+  en: "My module provides functionality for..."
+  ru: "Мой модуль обеспечивает функциональность для..."
+
 accessibility:
   editions:
     _default:
@@ -94,7 +114,7 @@ The `update` section defines version upgrade paths for the module.
 - `to` version must be greater than `from` version
 - Versions must use `major.minor` format (no patch versions)
 - Entries must be sorted: first by `from` version ascending, then by `to` version ascending
-- No duplicate `from` versions for the same `to` version
+- No duplicate `to` versions with different `from` versions (use the earliest `from` version instead)
 
 **Example:**
 ```yaml
@@ -125,22 +145,24 @@ Validates the `oss.yaml` file containing open-source software attribution.
 - ✅ At least one project is described
 - ✅ Each project has required fields:
   - `name` - Project name
-  - `url` - Valid project URL
+  - `description` - Project description
+  - `link` - Valid project URL
   - `license` - Valid license identifier
-  - `version` (optional) - Project version
+  - `logo` (optional) - Valid logo URL
 
 **Example:**
 ```yaml
 # oss.yaml
 - name: nginx
-  url: https://nginx.org/
+  description: High performance web server
+  link: https://nginx.org/
   license: BSD-2-Clause
-  version: "1.25.3"
+  logo: https://nginx.org/nginx.png
 
 - name: prometheus
-  url: https://prometheus.io/
+  description: Monitoring system and time series database
+  link: https://prometheus.io/
   license: Apache-2.0
-  version: "2.48.0"
 ```
 
 ---
@@ -153,19 +175,20 @@ Validates OpenAPI conversion files for configuration version upgrades.
 
 **Checks:**
 - ✅ Conversion files in `openapi/conversions/` are valid
-- ✅ Version files follow naming convention: `v1.yaml`, `v2.yaml`, etc.
+- ✅ Version files follow naming convention: `v2.yaml`, `v3.yaml`, etc. (starting from v2)
 - ✅ Each conversion has human-readable descriptions (English and Russian)
-- ✅ Version numbers are sequential
+- ✅ Version numbers are sequential (starting from 2)
 - ✅ Descriptions are not empty
+- ✅ Version in filename matches version in file content
 
 **File Structure:**
 ```
 openapi/
-├── config-values.yaml          # Current config version
+├── config-values.yaml          # Current config version (must have x-config-version)
 └── conversions/
-    ├── v1.yaml                 # Conversion to version 1
-    ├── v2.yaml                 # Conversion to version 2
-    └── v3.yaml                 # Conversion to version 3
+    ├── v2.yaml                 # Conversion to version 2 (first conversion)
+    ├── v3.yaml                 # Conversion to version 3
+    └── v4.yaml                 # Conversion to version 4
 ```
 
 **Example:**
@@ -183,14 +206,17 @@ description:
 
 Validates the `.helmignore` file in the module root.
 
+**Purpose:** The `.helmignore` file prevents unnecessary files from being packaged in Helm charts, reducing chart size and improving performance.
+
 **Checks:**
 - ✅ File exists in module root
+- ✅ File is not empty (contains at least one non-comment pattern)
+- ✅ Patterns don't contain unquoted spaces
+- ✅ Patterns are not too broad (`*` or `**`)
 - ✅ Critical Helm files are NOT excluded:
   - `templates/` - Helm template directory
   - `Chart.yaml` - Helm chart metadata
 
-**Purpose:** The `.helmignore` file prevents unnecessary files from being packaged in Helm charts, reducing chart size and improving performance.
-
 **Example:**
 ```
 # .helmignore - Safe patterns
@@ -333,7 +359,8 @@ This rule automatically detects feature usage and ensures proper version constra
 | **Stage Field** | ≥ 1.68.0 | `stage` field present in `module.yaml` |
 | **Go Hooks** | ≥ 1.68.0 | `go.mod` with `module-sdk` + `app.Run()` calls |
 | **Readiness Probes** | ≥ 1.71.0 | `module-sdk ≥ 0.3` + `app.WithReadiness()` calls |
-| **Optional Modules** | ≥ 1.73.0 | `bootstrapped: false` in requirements |
+| **Module-SDK ≥ 1.3** | ≥ 1.71.0 | `module-sdk ≥ 1.3.0` in `go.mod` |
+| **Optional Modules** | ≥ 1.73.0 | `!optional` flag in module requirements |
 
 **Validation:**
 - ✅ Minimum version constraints are declared
@@ -353,6 +380,7 @@ requirements:
   kubernetes: ">= 1.28.0"      # Optional: Kubernetes requirement
   modules:                      # Optional: Module dependencies
     monitoring-ping: ">= 1.0.0"
+    optional-module: ">= 1.0.0 !optional"  # Optional module dependency (requires >= 1.73.0)
 ```
 
 **Supported Constraint Formats:**

pkg/linters/openapi/README.md

@@ -294,18 +294,18 @@ linters-settings:
 
 ### keys
 
-**Purpose:** Prevents use of banned property names in OpenAPI schemas that could cause conflicts, confusion, or violate naming conventions. This ensures consistent and safe property naming across all module configurations.
+**Purpose:** Prevents use of banned names in enum values within OpenAPI schemas. This ensures enum values don't conflict with reserved keywords or cause confusion.
 
 **Description:**
 
-Validates that OpenAPI schema property names and enum values don't use banned keywords. Banned names are typically reserved words, common mistakes, or names that could cause conflicts with Kubernetes or Deckhouse internals.
+Validates that enum values in OpenAPI schema files (specifically in CRD files in `crds/` directory) don't use banned keywords. Banned names are typically reserved words that could cause conflicts with Kubernetes or Deckhouse internals.
 
 **What it checks:**
 
-1. Scans all property names in OpenAPI schemas
-2. Checks enum values for banned names
-3. Recursively validates nested properties and arrays
-4. Reports any usage of banned keywords
+1. Scans enum fields in CRD OpenAPI schemas
+2. Checks each enum value against the banned names list
+3. Recursively validates nested structures
+4. Reports any usage of banned keywords in enum values
 
 **Why it matters:**
 
@@ -372,16 +372,19 @@ properties:
 
 **Configuration:**
 
+Define which names should be banned in enum values:
+
 ```yaml
 # .dmt.yaml
 linters-settings:
   openapi:
     exclude-rules:
       key-banned-names:
-        - "properties.legacy.properties.mode"  # Exclude specific field
+        - "default"    # Ban "default" as an enum value
+        - "type"       # Ban "type" as an enum value
 ```
 
-**Note:** The list of banned names is configured in the linter settings. Common banned names typically include:
+**Note:** The `key-banned-names` list defines which names are **not allowed** as enum values. Common banned names typically include:
 - `default` - Reserved for schema defaults
 - `type` - Reserved for OpenAPI type definitions
 - Other context-specific reserved words
@@ -663,20 +666,23 @@ linters-settings:
         - "properties.internal.properties.highAvailability"
 ```
 
-#### Key Name Exclusions
+#### Key Banned Names Configuration
 
-Configure banned property names:
+Define which property names are banned in enum values:
 
 ```yaml
 # .dmt.yaml
 linters-settings:
   openapi:
     exclude-rules:
       key-banned-names:
-        - "properties.legacy.properties.default"
-        - "properties.settings.properties.type"
+        - "default"    # Ban "default" as an enum value
+        - "type"       # Ban "type" as an enum value
+        - "name"       # Ban "name" as an enum value
 ```
 
+**Note:** This list defines which names are **not allowed** in enum values, not paths to exclude from validation.
+
 #### CRD Exclusions
 
 Exclude specific CRDs from validation:
@@ -703,7 +709,7 @@ linters-settings:
     
     # Rule-specific exclusions
     exclude-rules:
-      # Enum value exclusions
+      # Enum value exclusions (paths to exclude from enum validation)
       enum:
         - "properties.storageClass.properties.provision.items.properties.type"
         - "properties.storageClass.properties.provision.items.oneOf[*].properties.type"
@@ -713,9 +719,10 @@ linters-settings:
       ha-absolute-keys:
         - "properties.internal.properties.highAvailability"
       
-      # Banned key name exclusions
+      # Banned names in enum values (names that are not allowed)
       key-banned-names:
-        - "properties.advanced.properties.default"
+        - "default"
+        - "type"
       
       # CRD name exclusions
       crd-names: