fix(docker-to-sealos): refine app rule exceptions (#30)

Author: yangchuansheng

skills/docker-to-sealos/SKILL.md

@@ -117,11 +117,11 @@ If validation fails, fix template/rules/examples first.
 - Never use `spec.template` in App resource.
 - `cloud.sealos.io/app-deploy-manager` label value must equal resource `metadata.name`.
 - `metadata.labels.app` label value must equal resource `metadata.name` for managed app workloads.
-- `containers[*].name` must equal workload `metadata.name` for managed app workloads.
+- The primary business container name must equal workload `metadata.name` for managed app workloads; sidecar/helper containers may use distinct descriptive names.
 - Application `Service` resources must define `metadata.labels.app` and `metadata.labels.cloud.sealos.io/app-deploy-manager`, and both labels must match `spec.selector.app`.
-- Component-scoped `ConfigMap` resources must define `metadata.labels.app` and `metadata.labels.cloud.sealos.io/app-deploy-manager`, and both labels must match `metadata.name`.
+- Runtime component-scoped `ConfigMap` resources must define `metadata.labels.app` and `metadata.labels.cloud.sealos.io/app-deploy-manager`, and both labels must match `metadata.name`; bootstrap-only ConfigMaps used only by init containers to copy initial config into persistent storage must not define either label.
 - Application `Service` resources must use the same component name across `metadata.name`, `metadata.labels.app`, `metadata.labels.cloud.sealos.io/app-deploy-manager`, and `spec.selector.app`.
-- Application `Ingress` resources must use the same component name across `metadata.name`, `metadata.labels.cloud.sealos.io/app-deploy-manager`, and backend `service.name`.
+- Root-path `Ingress` resources (`pathType: Prefix`, `path: /`) must use the same component name across `metadata.name`, `metadata.labels.cloud.sealos.io/app-deploy-manager`, and backend `service.name`; non-root or non-Prefix Ingress rules may route to a different backend service.
 - Service `spec.ports[*].name` must be explicitly set (required for multi-port services).
 - HTTP Ingress must include required nginx annotations (`kubernetes.io/ingress.class`, `nginx.ingress.kubernetes.io/proxy-body-size`, `nginx.ingress.kubernetes.io/server-snippet`, `nginx.ingress.kubernetes.io/ssl-redirect`, `nginx.ingress.kubernetes.io/backend-protocol`, `nginx.ingress.kubernetes.io/client-body-buffer-size`, `nginx.ingress.kubernetes.io/proxy-buffer-size`, `nginx.ingress.kubernetes.io/proxy-send-timeout`, `nginx.ingress.kubernetes.io/proxy-read-timeout`, `nginx.ingress.kubernetes.io/configuration-snippet`) with expected defaults.
 - CronJob resources must define labels `cloud.sealos.io/cronjob`, `cronjob-launchpad-name`, and `cronjob-type`; `cloud.sealos.io/cronjob` must equal `metadata.name`, `cronjob-launchpad-name` must be `""`, and `cronjob-type` must be `image`.
@@ -188,7 +188,7 @@ Unless source docs explicitly require otherwise, use the lightweight app ladder
 - container limits: `cpu=200m`, `memory=256Mi`
 - container requests: `cpu=20m`, `memory=25Mi`
 - `revisionHistoryLimit: 1`
-- `automountServiceAccountToken: false`
+- `automountServiceAccountToken: false` by default; set it to `true` only when the application has explicit Kubernetes API/service account token requirements, evidenced by Kubernetes integration settings, `serviceAccountName`, or a `sealos.io/service-account-token-reason` workload annotation.
 
 For higher resource needs, move only to another allowed `limits` ladder entry and recompute `requests` from that `limits` value.
 

skills/docker-to-sealos/references/must-rules-map.yaml

@@ -68,23 +68,23 @@ must_rules:
     enforcement:
       type: rule
       target: R034
-  - must: "`containers[*].name` must equal workload `metadata.name` for managed app workloads."
+  - must: "The primary business container name must equal workload `metadata.name` for managed app workloads; sidecar/helper containers may use distinct descriptive names."
     enforcement:
       type: rule
       target: R028
   - must: "Application `Service` resources must define `metadata.labels.app` and `metadata.labels.cloud.sealos.io/app-deploy-manager`, and both labels must match `spec.selector.app`."
     enforcement:
       type: rule
       target: R029
-  - must: "Component-scoped `ConfigMap` resources must define `metadata.labels.app` and `metadata.labels.cloud.sealos.io/app-deploy-manager`, and both labels must match `metadata.name`."
+  - must: "Runtime component-scoped `ConfigMap` resources must define `metadata.labels.app` and `metadata.labels.cloud.sealos.io/app-deploy-manager`, and both labels must match `metadata.name`; bootstrap-only ConfigMaps used only by init containers to copy initial config into persistent storage must not define either label."
     enforcement:
       type: rule
       target: R030
   - must: "Application `Service` resources must use the same component name across `metadata.name`, `metadata.labels.app`, `metadata.labels.cloud.sealos.io/app-deploy-manager`, and `spec.selector.app`."
     enforcement:
       type: rule
       target: R029
-  - must: "Application `Ingress` resources must use the same component name across `metadata.name`, `metadata.labels.cloud.sealos.io/app-deploy-manager`, and backend `service.name`."
+  - must: "Root-path `Ingress` resources (`pathType: Prefix`, `path: /`) must use the same component name across `metadata.name`, `metadata.labels.cloud.sealos.io/app-deploy-manager`, and backend `service.name`; non-root or non-Prefix Ingress rules may route to a different backend service."
     enforcement:
       type: rule
       target: R031
@@ -240,6 +240,42 @@ must_rules:
     enforcement:
       type: rule
       target: R038
+  - must: "Do not treat a short smoke test as proof of a stable minimum memory value."
+    enforcement:
+      type: manual
+      note: "Review browser/remote desktop templates and smoke evidence before lowering memory."
+  - must: "Validate memory with a fresh deployment, not only a patched warm pod."
+    enforcement:
+      type: manual
+      note: "Requires deployment evidence outside static YAML validation."
+  - must: "Exercise cold start until readiness, a lightweight page, a real/medium page, an interactive/search page, and a 60s post-smoke stability check."
+    enforcement:
+      type: manual
+      note: "Requires runtime smoke coverage evidence."
+  - must: "If observed cgroup memory reaches more than 80% of the limit during smoke, move to the next allowed Sealos memory ladder value."
+    enforcement:
+      type: manual
+      note: "Requires runtime memory observation."
+  - must: "Keep requests derived from limits according to the Sealos resource ladder."
+    enforcement:
+      type: rule
+      target: R038
+  - must: "Bad: Chrome passes a short smoke at `512Mi` but reaches `503Mi`; shipping `512Mi` as the stable minimum is unsafe."
+    enforcement:
+      type: manual
+      note: "Negative example for reviewer guidance."
+  - must: "Good: raise to `1024Mi`, set request to `102Mi`, rerun smoke and stability checks."
+    enforcement:
+      type: manual
+      note: "Positive example for reviewer guidance."
+  - must: "limits: `cpu=200m`, `memory=1024Mi`"
+    enforcement:
+      type: manual
+      note: "Browser/remote desktop minimum; applied when source workload matches that class."
+  - must: "requests: `cpu=20m`, `memory=102Mi`"
+    enforcement:
+      type: manual
+      note: "Browser/remote desktop minimum request; applied when source workload matches that class."
   - must: "MongoDB: `${{ defaults.app_name }}-mongo-mongodb-account-root` (or `${{ defaults.app_name }}-mongodb-mongodb-account-root` when the MongoDB cluster name uses `-mongodb`)"
     enforcement:
       type: rule
@@ -268,7 +304,7 @@ must_rules:
     enforcement:
       type: rule
       target: R009
-  - must: "`automountServiceAccountToken: false`"
+  - must: "`automountServiceAccountToken: false` by default; set it to `true` only when the application has explicit Kubernetes API/service account token requirements, evidenced by Kubernetes integration settings, `serviceAccountName`, or a `sealos.io/service-account-token-reason` workload annotation."
     enforcement:
       type: rule
       target: R010

skills/docker-to-sealos/references/rules-registry.yaml

@@ -98,22 +98,22 @@ rules:
     description: Managed app workloads must define metadata.labels.app and match metadata.name.
     severity: error
   - id: R028
-    description: Managed app workload container names must exactly match metadata.name.
+    description: Managed app workloads must include a primary business container whose name exactly matches metadata.name.
     severity: error
   - id: R029
     description: Application Services must use one component name across metadata.name, labels.app, cloud.sealos.io/app-deploy-manager, and spec.selector.app.
     severity: error
   - id: R030
-    description: Component ConfigMaps must use one component name across metadata.name, labels.app, and cloud.sealos.io/app-deploy-manager.
+    description: Runtime component ConfigMaps must use one component name across metadata.name, labels.app, and cloud.sealos.io/app-deploy-manager; bootstrap-only init-copy ConfigMaps must not define either managed label.
     severity: error
   - id: R031
-    description: Application Ingress resources must use one component name across metadata.name, cloud.sealos.io/app-deploy-manager, and backend service names.
+    description: Root-path Prefix Ingress resources must use one component name across metadata.name, cloud.sealos.io/app-deploy-manager, and backend service names; non-root or non-Prefix routes may differ.
     severity: error
   - id: R009
     description: Managed app workloads must explicitly set revisionHistoryLimit to 1.
     severity: error
   - id: R010
-    description: Managed app workloads must explicitly set automountServiceAccountToken to false.
+    description: Managed app workloads must explicitly set automountServiceAccountToken to false unless Kubernetes API/service account token usage is evidenced by integration settings, serviceAccountName, or a service-account-token reason annotation.
     severity: error
   - id: R035
     description: Managed app workloads must reference the app-scoped image pull secret name via template.spec.imagePullSecrets.

skills/docker-to-sealos/references/sealos-specs.md

@@ -493,12 +493,14 @@ spec:
    - `${{ defaults.app_name }}-ml`
    - `${{ defaults.app_name }}-redis`
 5. Application Service must include `metadata.labels.app` and `metadata.labels.cloud.sealos.io/app-deploy-manager`, and `metadata.name`, both labels, and `spec.selector.app` must be exactly the same
-6. Component-level ConfigMap must include `metadata.labels.app` and `metadata.labels.cloud.sealos.io/app-deploy-manager`, and both must be consistent with `metadata.name`
-7. Application Ingress's `metadata.name` must be consistent with `metadata.labels.cloud.sealos.io/app-deploy-manager` and the backend `service.name`
+6. Runtime component-level ConfigMap must include `metadata.labels.app` and `metadata.labels.cloud.sealos.io/app-deploy-manager`, and both must be consistent with `metadata.name`; ConfigMaps used only by init containers to copy initial config into persistent storage must not include either label
+7. Root-path Ingress rules (`pathType: Prefix`, `path: /`) must keep `metadata.name` consistent with `metadata.labels.cloud.sealos.io/app-deploy-manager` and backend `service.name`; non-root or non-Prefix Ingress rules may use a distinct Ingress name and backend service
 
 ### Container Naming Rules
 
-The `containers.name` must be consistent with the `metadata.name` value.
+The primary business container name must be consistent with the workload
+`metadata.name` value. Sidecar/helper containers may use distinct descriptive
+names when they are not the main business container.
 
 ```yaml
 # Correct example
@@ -509,6 +511,7 @@ spec:
     spec:
       containers:
         - name: ${{ defaults.app_name }}  # Must be consistent with metadata.name
+        - name: metrics-sidecar          # Allowed: helper/sidecar container
 
 # Correct example for sub-components
 metadata:
@@ -827,7 +830,7 @@ This is because Kubernetes parses environment variables in the order they appear
 
 All application Deployments or StatefulSets must include the following configurations:
 
-1. **automountServiceAccountToken**: Must be set to `false` to avoid unnecessary permission exposure
+1. **automountServiceAccountToken**: Must be set to `false` to avoid unnecessary permission exposure. Set it to `true` only when the application explicitly needs the Kubernetes API/service account token, evidenced by Kubernetes integration settings, `serviceAccountName`, or `sealos.io/service-account-token-reason` in workload annotations.
 2. **revisionHistoryLimit**: Must be set to `1` to reduce resources consumed by historical revisions
 3. **imagePullSecrets**: Must reference the app-scoped image pull Secret `${{ defaults.app_name }}`
 4. **metadata.annotations**: Must include the following annotations:
@@ -857,7 +860,7 @@ spec:
   revisionHistoryLimit: 1  # Must be set to 1
   template:
     spec:
-      automountServiceAccountToken: false  # Must be set to false
+      automountServiceAccountToken: false  # Default; only set true with evidenced Kubernetes API token need
       imagePullSecrets:
         - name: ${{ defaults.app_name }}
       containers: