fix(docker-to-sealos): omit pull secrets for public images (#34)

Allow public-image workloads to omit imagePullSecrets while still rejecting custom pull secret references when imagePullSecrets are declared. Update the converter, consistency rule, documentation, and tests to match the Sealos template behavior.

Author: yangchuansheng

skills/docker-to-sealos/SKILL.md

@@ -140,7 +140,7 @@ If validation fails, fix template/rules/examples first.
 - Avoid floating tags (for example `:v2`, `:2.1`, `:stable`); use an explicit version tag or digest.
 - Managed workload image references must be concrete and must not contain Compose-style variable expressions (for example `${VAR}`, `${VAR:-default}`); resolve to explicit tag or digest before emitting template artifacts.
 - Application `originImageName` must match container image.
-- Managed app workloads must reference the app-scoped image pull Secret `${{ defaults.app_name }}` via `template.spec.imagePullSecrets`.
+- Public-image managed app workloads must omit `template.spec.imagePullSecrets`; private-registry workloads may reference only the app-scoped pull Secret `${{ defaults.app_name }}`.
 - The registry pull Secret is runtime-managed by `sealos-deploy` using local `gh` CLI credentials for private GHCR images; do not expose raw registry credential inputs in generated templates.
 - All containers must explicitly set `imagePullPolicy: IfNotPresent`.
 
@@ -156,7 +156,7 @@ If validation fails, fix template/rules/examples first.
 - Non-database sensitive values/inputs use direct `env[].value`.
 - Business containers must source database connection fields (`endpoint`, `host`, `port`, `username`, `password`) from approved Kubeblocks database secrets via `env[].valueFrom.secretKeyRef`; exception: Redis `host`/`port` may use Sealos Redis Service FQDN and `6379` when the Redis secret only exposes credentials, and MongoDB connection URLs may use the Sealos MongoDB Service FQDN plus `27017` when the MongoDB secret exposes credentials only.
 - Business containers must not use custom env/volume `Secret` references except approved Kubeblocks database secrets and object storage secrets.
-- A dedicated app-scoped registry pull Secret is allowed and should be referenced only through `template.spec.imagePullSecrets`.
+- A dedicated app-scoped registry pull Secret is allowed only for private-registry images and must be referenced only through `template.spec.imagePullSecrets`; public images must not add pull secrets.
 - Database connection/bootstrap may use Kubeblocks-provided secrets, and reserved Kubeblocks database secret names must not be redefined by custom `Secret` resources.
 - Env vars must be declared before referenced (for example password before URL composition).
 - Follow official app env var naming; do not invent prefixes.

skills/docker-to-sealos/references/conversion-mappings.md

@@ -103,16 +103,14 @@ spec:
   template:
     spec:
       automountServiceAccountToken: false
-      imagePullSecrets:
-        - name: ${{ defaults.app_name }}
       containers:
         - name: ${{ defaults.app_name }}
           image: nginx:1.27.2
           imagePullPolicy: IfNotPresent  # Must be set
 ```
 
 Notes:
-- Always reference the app-scoped image pull Secret `${{ defaults.app_name }}`.
+- Omit `imagePullSecrets` for public images. For private-registry images, reference only the app-scoped image pull Secret `${{ defaults.app_name }}`.
 - `sealos-deploy` should create or refresh that Secret automatically from local `gh` CLI credentials when deploying private GHCR images.
 - Reusable templates should not expose raw registry credential inputs as user-facing form fields.
 
@@ -138,8 +136,6 @@ spec:
   template:
     spec:
       automountServiceAccountToken: false
-      imagePullSecrets:
-        - name: ${{ defaults.app_name }}
       containers:
         - name: ${{ defaults.app_name }}
           ports:
@@ -251,8 +247,6 @@ spec:
   template:
     spec:
       automountServiceAccountToken: false
-      imagePullSecrets:
-        - name: ${{ defaults.app_name }}
       containers:
         - name: ${{ defaults.app_name }}
           env:
@@ -369,8 +363,6 @@ spec:
   template:
     spec:
       automountServiceAccountToken: false
-      imagePullSecrets:
-        - name: ${{ defaults.app_name }}
       containers:
         - name: ${{ defaults.app_name }}
           volumeMounts:

skills/docker-to-sealos/references/example-guide.md

@@ -263,8 +263,6 @@ spec:
         app: ${{ defaults.app_name }}
     spec:
       automountServiceAccountToken: false
-      imagePullSecrets:
-        - name: ${{ defaults.app_name }}
       containers:
         - name: ${{ defaults.app_name }}
           image: yidadaa/chatgpt-next-web:v2.12.4

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

@@ -132,7 +132,7 @@ must_rules:
     enforcement:
       type: rule
       target: R015
-  - must: "Managed app workloads must reference the app-scoped image pull Secret `${{ defaults.app_name }}` via `template.spec.imagePullSecrets`."
+  - must: "Public-image managed app workloads must omit `template.spec.imagePullSecrets`; private-registry workloads may reference only the app-scoped pull Secret `${{ defaults.app_name }}`."
     enforcement:
       type: rule
       target: R035
@@ -172,7 +172,7 @@ must_rules:
     enforcement:
       type: rule
       target: R007
-  - must: "A dedicated app-scoped registry pull Secret is allowed and should be referenced only through `template.spec.imagePullSecrets`."
+  - must: "A dedicated app-scoped registry pull Secret is allowed only for private-registry images and must be referenced only through `template.spec.imagePullSecrets`; public images must not add pull secrets."
     enforcement:
       type: rule
       target: R035

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

@@ -119,7 +119,7 @@ rules:
     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.
+    description: Managed app workloads that declare imagePullSecrets must reference only the app-scoped pull secret name via template.spec.imagePullSecrets; public-image workloads may omit imagePullSecrets.
     severity: error
   - id: R011
     description: All PVC storage requests must be concrete values and less than or equal to 1Gi.

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

@@ -453,8 +453,6 @@ spec:
   template:
     spec:
       automountServiceAccountToken: false
-      imagePullSecrets:
-        - name: ${{ defaults.app_name }}
       containers:
         - name: ${{ defaults.app_name }}
           volumeMounts:
@@ -832,17 +830,17 @@ All application Deployments or StatefulSets must include the following configura
 
 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 }}`
+3. **imagePullSecrets**: Omit for public images. For private-registry images, reference only the app-scoped pull Secret `${{ defaults.app_name }}`
 4. **metadata.annotations**: Must include the following annotations:
    - `originImageName`: Original image name
    - `deploy.cloud.sealos.io/minReplicas`: Minimum replica count, typically set to `'1'`
    - `deploy.cloud.sealos.io/maxReplicas`: Maximum replica count, typically set to `'1'`
 
 Recommended registry pull Secret model:
 
-- Managed workloads reference `${{ defaults.app_name }}` in `imagePullSecrets`
-- `sealos-deploy` creates or refreshes that Secret automatically from local `gh` CLI credentials when the image is a private GHCR image
-- If the template is deployed outside `sealos-deploy`, the operator must create the Secret manually before applying the workload
+- Public-image managed workloads omit `imagePullSecrets`
+- For private GHCR images, `sealos-deploy` creates or refreshes `${{ defaults.app_name }}` from local `gh` CLI credentials and the workload may reference it through `imagePullSecrets`
+- If a private-registry template is deployed outside `sealos-deploy`, the operator must create the Secret manually before applying the workload
 
 ```yaml
 apiVersion: apps/v1
@@ -861,8 +859,6 @@ spec:
   template:
     spec:
       automountServiceAccountToken: false  # Default; only set true with evidenced Kubernetes API token need
-      imagePullSecrets:
-        - name: ${{ defaults.app_name }}
       containers:
         - name: ${{ defaults.app_name }}
           # Other container configuration...
@@ -894,8 +890,6 @@ spec:
         app: ${{ defaults.app_name }}
     spec:
       automountServiceAccountToken: false  # Disable automatic service account token mounting
-      imagePullSecrets:
-        - name: ${{ defaults.app_name }}
       containers:
         - name: ${{ defaults.app_name }}
           image: example/app:1.0.0

skills/docker-to-sealos/scripts/check_consistency_rules_app.py

@@ -1826,6 +1826,12 @@ def check_image_pull_secret_refs(context: ScanContext) -> List[Violation]:
         template_spec = get_template_spec(doc.data)
         image_pull_secrets = template_spec.get("imagePullSecrets") if isinstance(template_spec, dict) else None
 
+        # Public images should omit imagePullSecrets entirely. When a private-registry
+        # workload does declare pull secrets, only the app-scoped runtime-managed
+        # secret is allowed so templates do not depend on undeclared custom secrets.
+        if image_pull_secrets is None:
+            continue
+
         referenced_names: List[str] = []
         if isinstance(image_pull_secrets, list):
             for item in image_pull_secrets:
@@ -1835,7 +1841,7 @@ def check_image_pull_secret_refs(context: ScanContext) -> List[Violation]:
                 if isinstance(name, str) and name.strip():
                     referenced_names.append(name.strip())
 
-        if "${{ defaults.app_name }}" in referenced_names:
+        if referenced_names == ["${{ defaults.app_name }}"]:
             continue
 
         add_doc_violation(
@@ -1845,8 +1851,9 @@ def check_image_pull_secret_refs(context: ScanContext) -> List[Violation]:
             pattern=r"^\s*imagePullSecrets\s*:",
             default_pattern=r"^\s*template\s*:",
             message=(
-                "managed app workloads must reference the app-scoped image pull secret "
-                "`${{ defaults.app_name }}` via template.spec.imagePullSecrets"
+                "imagePullSecrets may be omitted for public images; if declared for "
+                "private-registry workloads, it must reference only the app-scoped "
+                "secret `${{ defaults.app_name }}`"
             ),
         )
 

skills/docker-to-sealos/scripts/compose_to_template.py

@@ -2065,7 +2065,6 @@ def build_env_entries(
 def build_workload(
     *,
     workload_name: str,
-    pull_secret_name: str,
     image: str,
     ports: Sequence[int],
     env_entries: Sequence[Dict[str, Any]],
@@ -2077,7 +2076,6 @@ def build_workload(
     kind = "StatefulSet" if is_stateful else "Deployment"
     template_spec: Dict[str, Any] = {
         "automountServiceAccountToken": False,
-        "imagePullSecrets": [{"name": pull_secret_name}],
         "containers": [
             {
                 "name": workload_name,
@@ -2319,7 +2317,6 @@ def build_documents(
             app_services = service_items[:1]
 
     db_hosts = {name: DB_FQDN_BY_TYPE[db_type] for name, db_type in db_services.items() if db_type in DB_FQDN_BY_TYPE}
-    pull_secret_name = "${{ defaults.app_name }}"
 
     docs: List[Dict[str, Any]] = []
     docs.append(build_template_resource(meta))
@@ -2369,7 +2366,6 @@ def build_documents(
         probes = build_probe_pair(service, image, ports, command_args)
         workload = build_workload(
             workload_name=workload_name,
-            pull_secret_name=pull_secret_name,
             image=image,
             ports=ports,
             env_entries=env_entries,

skills/docker-to-sealos/scripts/test_check_consistency.py

@@ -2498,7 +2498,7 @@ def test_allows_registry_pull_secret_via_image_pull_secrets(self):
         )
         self.assertFalse(any(item.rule_id in {"R007", "R035"} for item in violations))
 
-    def test_detects_missing_registry_pull_secret_reference(self):
+    def test_allows_public_image_without_image_pull_secrets(self):
         violations = self.run_checker(
             """
             ```yaml
@@ -2526,6 +2526,38 @@ def test_detects_missing_registry_pull_secret_reference(self):
             ```
             """
         )
+        self.assertFalse(any(item.rule_id == "R035" for item in violations))
+
+    def test_detects_invalid_registry_pull_secret_reference(self):
+        violations = self.run_checker(
+            """
+            ```yaml
+            apiVersion: apps/v1
+            kind: Deployment
+            metadata:
+              name: demo
+              labels:
+                app: demo
+                cloud.sealos.io/app-deploy-manager: demo
+              annotations:
+                originImageName: registry.example.com/private/demo:1.0.0
+            spec:
+              revisionHistoryLimit: 1
+              template:
+                metadata:
+                  labels:
+                    app: demo
+                spec:
+                  automountServiceAccountToken: false
+                  imagePullSecrets:
+                    - name: custom-pull-secret
+                  containers:
+                    - name: demo
+                      image: registry.example.com/private/demo:1.0.0
+                      imagePullPolicy: IfNotPresent
+            ```
+            """
+        )
         self.assertTrue(any(item.rule_id == "R035" for item in violations))
 
     def test_detects_object_storage_secret_misuse_on_non_s3_env(self):

skills/docker-to-sealos/scripts/test_compose_to_template.py

@@ -125,10 +125,7 @@ def test_generates_template_and_passes_consistency_rules(self):
                 ingress["metadata"]["labels"]["cloud.sealos.io/app-deploy-manager"],
             )
             workload = next(doc for doc in docs if doc.get("kind") == "Deployment")
-            self.assertEqual(
-                [{"name": "${{ defaults.app_name }}"}],
-                workload["spec"]["template"]["spec"]["imagePullSecrets"],
-            )
+            self.assertNotIn("imagePullSecrets", workload["spec"]["template"]["spec"])
             self.assertEqual(
                 {
                     "kubernetes.io/ingress.class": "nginx",