Docker to Sealos Template Converter

Overview

Convert Docker Compose files or installation docs into production-grade Sealos templates. Execute end-to-end automatically (analysis, conversion, validation, output) without asking users for missing fields.

Governance and Rule Priority

Use the following precedence to prevent rule drift:

```
SKILL.md
```
MUST rules (this file)

references/sealos-specs.md

and

references/database-templates.md

references/conversion-mappings.md

and

references/example-guide.md

If lower-priority references conflict with higher-priority MUST rules, update the lower-priority files. Do not keep conflicting examples.

Workflow

Step 1: Analyze input

Extract from Docker Compose/docs:

application services vs database services
volumes/config mounts/object storage requirements
ports, dependencies, service communication
env vars and secret usage
resource limits/requests and health checks
if official Kubernetes installation docs/manifests are available, also extract app-runtime behavior from them (bootstrap admin fields, external endpoint/protocol assumptions, health probes, startup/init flow)

Step 2: Infer metadata

Infer and normalize:

app name, title, description, categories
official URL, gitRepo, icon source
locale/i18n metadata

Step 3: Plan resources in strict order

Generate resources in this order:

Template CR
ObjectStorageBucket (if needed)
Database resources (ServiceAccount → Role → RoleBinding → Cluster → Job if needed)
App workload resources (ConfigMap → Deployment/StatefulSet → Service → Ingress)
App resource (last)

Step 4: Apply conversion rules

Apply field-level mappings from

references/conversion-mappings.md

, including:

image pinning and annotation mapping
port/service/ingress conversion
env var conversion and dependency ordering
storage conversion and vn naming (
```
scripts/path_converter.py
```
)
service-name to Kubernetes FQDN conversion
for DB URL/DSN envs (for example
```
*_DATABASE_URL
```
,
```
*_DB_URL
```
), when Kubeblocks
```
endpoint
```
is host:port, inject
```
host
```
/
```
port
```
/
```
username
```
/
```
password
```
via approved
```
secretKeyRef
```
envs and compose the final URL with
```
$(VAR)
```
expansion
edge gateway normalization: when Compose includes Traefik-like edge proxy plus business services, skip the proxy workload and expose business services via Sealos Ingress directly
TLS offload normalization for Sealos Ingress: when a business service exposes both 80 and 443, drop 443 from workload/service ports and remove in-container TLS certificate mounts (for example
```
/etc/nginx/ssl
```
,
```
/etc/ssl
```
,
```
/certs
```
) unless official Kubernetes docs explicitly require HTTPS backend-to-service traffic
prefer
```
scripts/compose_to_template.py --kompose-mode always
```
as deterministic conversion entrypoint (require
```
kompose
```
for reproducible workload shaping)
when official Kubernetes installation docs/manifests exist, perform a dual-source merge: use Compose as baseline topology, then align app-runtime semantics with official Kubernetes guidance

Step 5: Apply database strategy

PostgreSQL must follow the pinned version and structure requirements.
MySQL/MongoDB/Redis/Kafka must use templates and secret naming from
```
references/database-templates.md
```
.
Add DB init Job/initContainer when application database bootstrap requires it.
For PostgreSQL custom databases (non-
```
postgres
```
), the init Job must wait for PostgreSQL readiness before execution and create the target database idempotently.

Step 6: Generate output files

Always produce:

```
template/<app-name>/index.yaml
```
```
template/<app-name>/logo.<ext>
```
when official icon is resolvable

Step 7: Validate before output

Run validator and self-tests before delivering template output. If validation fails, fix template/rules/examples first.

MUST Rules (Condensed)

Naming and metadata

Template
```
metadata.name
```
must be hardcoded lowercase; do not use
```
${{ defaults.app_name }}
```
.
Template CR folder name must match
```
metadata.name
```
.

Template CR must include required metadata fields (

title

url

gitRepo

author

description

icon

templateType

locale

i18n

categories

Template

spec.readme

must be

https://raw.githubusercontent.com/labring-actions/templates/kb-0.9/template/<app-name>/README.md

Template

spec.i18n.zh.readme

must be

https://raw.githubusercontent.com/labring-actions/templates/kb-0.9/template/<app-name>/README_zh.md

```
icon
```
URL must point to template repo raw path for this app on
```
kb-0.9
```
branch.
```
i18n.zh.description
```
must be written in Simplified Chinese.
Omit
```
i18n.zh.title
```
when it is identical to
```
title
```
.

categories

must only use predefined values (

tool

ai

game

database

low-code

monitor

dev-ops

blog

storage

frontend

backend

App resource

App resource must use
```
spec.data.url
```
.
App resource
```
spec.displayType
```
must be
```
normal
```
.
App resource
```
spec.type
```
must be
```
link
```
.
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.

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

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

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.

When official application health checks are available, managed workloads must define
```
livenessProbe
```
,
```
readinessProbe
```
, and (for slow bootstrap apps)
```
startupProbe
```
, aligned with official endpoints/commands.

Official Kubernetes alignment

If official Kubernetes installation docs/manifests are available, conversion must reference them and align critical runtime settings before emitting template artifacts.
When official Kubernetes docs/manifests and Compose differ, prefer official Kubernetes runtime semantics for app behavior (bootstrap admin fields, external endpoint/env/protocol, health probes), unless doing so violates higher-priority Sealos MUST/security constraints.

Images and pull policy

Do not use
```
:latest
```
.
Resolve versions with
```
crane
```
: prefer an explicit version tag (for example
```
v2.2.0
```
), and fallback to digest pin only when a deterministic version tag is unavailable.
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.
All containers must explicitly set
```
imagePullPolicy: IfNotPresent
```
.

Storage

Do not use
```
emptyDir
```
.
Use persistent storage patterns (
```
volumeClaimTemplates
```
) where storage is needed.
PVC request must be
```
<= 1Gi
```
unless source spec explicitly requires less.
ConfigMap keys and volume names must follow vn naming (
```
scripts/path_converter.py
```
).

Env and secrets

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
```
.
Business containers must not use custom
```
Secret
```
or
```
secretKeyRef
```
except approved Kubeblocks database secrets and object storage 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.
When the application requires its public URL configured via a file-based config system (e.g., node-config
```
config/default.json
```
, PHP config files), create a ConfigMap containing the config file with the public URL set to
```
https://${{ defaults.app_host }}.${{ SEALOS_CLOUD_DOMAIN }}
```
, and mount it to the application's config directory. The ConfigMap must follow standard naming and label conventions.
For PostgreSQL custom databases (non-
```
postgres
```
), include
```
${{ defaults.app_name }}-pg-init
```
Job and implement startup-safe/idempotent creation logic (readiness wait + existence check before create).

Database-specific constraints

PostgreSQL version:
```
postgresql-16.4.0
```
.
PostgreSQL API:
```
apps.kubeblocks.io/v1alpha1
```
.
PostgreSQL RBAC unified naming:
```
${{ defaults.app_name }}-pg
```
.

PostgreSQL RBAC requires

app.kubernetes.io/instance

and

app.kubernetes.io/managed-by

labels.

PostgreSQL role wildcard permission requirement remains as defined in current spec.

PostgreSQL cluster must include required labels/fields (

kb.io/database: postgresql-16.4.0

clusterdefinition.kubeblocks.io/name: postgresql

clusterversion.kubeblocks.io/name: postgresql-16.4.0

clusterVersionRef: postgresql-16.4.0

disableExporter: true

enabledLogs: [running]

switchPolicy.type: Noop

serviceAccountName

MongoDB cluster must follow upgraded structure (

componentDef: mongodb

serviceVersion: 8.0.4

, labels

kb.io/database

and

app.kubernetes.io/instance

MySQL cluster must follow upgraded structure (

kb.io/database: ac-mysql-8.0.30-1

clusterDefinitionRef: apecloud-mysql

clusterVersionRef: ac-mysql-8.0.30-1

tolerations: []

Redis cluster must follow upgraded structure (

componentDef: redis-7

componentDef: redis-sentinel-7

serviceVersion: 7.2.7

, main data PVC

1Gi

, topology

replication

Database cluster component resources must use
```
limits(cpu=500m,memory=512Mi)
```
and
```
requests(cpu=50m,memory=51Mi)
```
unless source docs explicitly require otherwise.

Secret naming:

MongoDB:

${{ defaults.app_name }}-mongodb-account-root

Redis:

${{ defaults.app_name }}-redis-redis-account-default

Kafka:

${{ defaults.app_name }}-broker-account-admin

Do not use legacy naming outside supported exceptions.

Baseline runtime defaults

Unless source docs explicitly require otherwise, use:

container limits:
```
cpu=200m
```
,
```
memory=256Mi
```
container requests:
```
cpu=20m
```
,
```
memory=25Mi
```
```
revisionHistoryLimit: 1
```
```
automountServiceAccountToken: false
```

Defaults vs inputs

```
defaults
```
for generated values (
```
app_name
```
,
```
app_host
```
, random passwords/keys).
```
inputs
```
only for truly user-provided operational values (email/SMTP/external API keys, etc.).
```
inputs.description
```
must be in English.

Validation Commands

Run all checks before final response:

python scripts/path_converter.py --self-test

python scripts/test_check_consistency.py

python scripts/test_compose_to_template.py

python scripts/test_check_must_coverage.py

python scripts/check_consistency.py --skill SKILL.md --references references --rules-file references/rules-registry.yaml

python scripts/check_consistency.py --skill SKILL.md --references references --rules-file references/rules-registry.yaml --artifacts template/<app-name>/index.yaml

python scripts/check_must_coverage.py --skill SKILL.md --mapping references/must-rules-map.yaml --rules-file references/rules-registry.yaml

(CI / one-shot)

python scripts/quality_gate.py

(requires

template/*/index.yaml

by default; set

DOCKER_TO_SEALOS_ALLOW_EMPTY_ARTIFACTS=1

only for dev/debug without artifacts)

check_consistency.py

is registry-driven. Keep

references/rules-registry.yaml

in sync with implemented rules. Registry rule entries support

severity

and optional

scope.include_paths

metadata.

Output Contract

When conversion is complete, provide:

brief conversion summary
target file path (
```
template/<app-name>/index.yaml
```
)
complete template YAML
key decisions only where ambiguity existed

Reference Navigation (Progressive Loading)

Load only needed references for current task:

```
references/sealos-specs.md
```
- authoritative ordering, labels, App/Ingress/ConfigMap conventions
```
references/conversion-mappings.md
```
- Docker→Sealos field-level mappings and edge conversions
```
references/database-templates.md
```
- database templates, RBAC structures, secret naming patterns
```
references/example-guide.md
```
- examples and pattern walkthroughs (non-authoritative)
```
references/rules-registry.yaml
```
- machine-readable validation scope/rules list
```
references/must-rules-map.yaml
```
- MUST bullet to enforcement mapping (
```
rule
```
  or
```
manual
```
  ) for drift control

Script Utilities

```
scripts/path_converter.py
```
- convert paths to vn names
- self-test support for regression checks

scripts/compose_to_template.py

deterministic compose/docs-to-template generator entrypoint

supports

--kompose-mode auto|always|never

(

always

is default) to reuse

kompose convert

workload shapes

emits
```
template/<app-name>/index.yaml
```

```
scripts/test_compose_to_template.py
```
- regression tests for compose conversion behavior
```
scripts/check_consistency.py
```
- registry-driven consistency validator
```
scripts/test_check_consistency.py
```
- regression tests for validator behavior
```
scripts/check_must_coverage.py
```
- validate MUST bullet coverage mapping against registry rules
```
scripts/test_check_must_coverage.py
```
- regression tests for MUST coverage validator

Edge Policies

Never ask users for missing fields; infer from compose/docs and platform conventions.
Keep App resource in
```
spec.data.url
```
format; never use
```
spec.template
```
.
Keep App resource
```
spec.displayType: normal
```
and
```
spec.type: link
```
; do not infer alternative enum values.
Keep business-env, object storage, and DB-secret policy consistent with MUST rules.
Prefer Sealos-managed ingress over bundled edge proxies: if a Traefik gateway is only acting as ingress/front-proxy and at least one business service exists, do not emit Traefik workload resources.
Prefer gateway TLS termination in Sealos Ingress over in-container TLS: for dual-port HTTP/HTTPS workloads, keep HTTP service port and remove redundant HTTPS/certificate mounts unless official docs require HTTPS backend.
Prefer fixing references/examples over adding exceptions when conflicts appear.
If official Kubernetes installation docs/manifests exist for the target app, do not ignore them; use them to refine runtime semantics beyond Compose defaults.

docker-to-sealos

NPX Install

Tags

SKILL.md Content

Docker to Sealos Template Converter

Overview

Governance and Rule Priority

Workflow

Step 1: Analyze input

Step 2: Infer metadata

Step 3: Plan resources in strict order

Step 4: Apply conversion rules

Step 5: Apply database strategy

Step 6: Generate output files

Step 7: Validate before output

MUST Rules (Condensed)

Naming and metadata

App resource

Official Kubernetes alignment

Images and pull policy

Storage

Env and secrets

Database-specific constraints

Baseline runtime defaults

Defaults vs inputs

Validation Commands

Output Contract

Reference Navigation (Progressive Loading)

Script Utilities

Edge Policies