docker-to-sealos

Docker から Sealos テンプレートへの変換

概要

Docker Compose ファイルまたはインストール手順を、本番環境向けの Sealos テンプレートに変換します。 不足している項目をユーザーに尋ねることなく、分析、変換、検証、出力をエンドツーエンドで自動的に実行します。

ガバナンスとルールの優先順位

ルールの逸脱を防ぐため、次の優先順位を使用します。

1. SKILL.md の MUST ルール（このファイル）
2. references/sealos-specs.md と references/database-templates.md
3. references/conversion-mappings.md と references/example-guide.md

優先順位の低い参照資料が、優先順位の高い MUST ルールと矛盾する場合は、優先順位の低いファイルを更新します。 矛盾する例は残さないでください。

ワークフロー

Step 1: 入力を分析する

Docker Compose／ドキュメントから、以下を抽出します。

• アプリケーションサービスとデータベースサービス
• ボリューム／設定マウント／オブジェクトストレージの要件
• ポート、依存関係、サービス間通信
• 環境変数とシークレットの使用状況
• リソースの上限／要求値とヘルスチェック
• 公式の Kubernetes インストール手順／マニフェストがある場合は、そこからアプリケーションのランタイム動作も抽出します（ブートストラップ管理者のフィールド、外部エンドポイント／プロトコルの前提、ヘルスプローブ、起動／初期化フロー）

Step 2: メタデータを推定する

以下を推定し、正規化します。

• アプリ名、タイトル、説明、カテゴリ
• 公式 URL、gitRepo、アイコンのソース
• ロケール／i18n メタデータ

Step 3: 厳密な順序でリソースを計画する

次の順序でリソースを生成します。

1. Template CR
2. ObjectStorageBucket（必要な場合）
3. データベースリソース（ServiceAccount → Role → RoleBinding → Cluster → 必要に応じて Job）
4. アプリのワークロードリソース（ConfigMap/Secret → Deployment/StatefulSet → Service → Ingress）
5. アプリリソース（最後）

Step 4: 変換ルールを適用する

references/conversion-mappings.md のフィールド単位のマッピングを適用します。これには以下が含まれます。

• イメージのバージョン固定とアノテーションのマッピング
• ポート／サービス／Ingress の変換
• 環境変数の変換と依存関係の順序付け
• ストレージの変換と vn の命名（scripts/path_converter.py）
• サービス名から Kubernetes FQDN への変換
• DB URL／DSN 環境変数（例：*_DATABASE_URL、*_DB_URL）について、Kubeblocks の endpoint が host:port の場合は、承認済みの secretKeyRef 環境変数を使って host／port／username／password を注入し、$(VAR) 展開で最終 URL を組み立てます
• エッジゲートウェイの正規化：Compose に Traefik のようなエッジプロキシとビジネスサービスが含まれている場合、プロキシのワークロードは省略し、Sealos Ingress を介してビジネスサービスを直接公開します
• Sealos Ingress の TLS オフロードの正規化：ビジネスサービスが 80 と 443 の両方を公開している場合、公式の Kubernetes ドキュメントでバックエンドからサービスへの HTTPS 通信が明示的に必須とされていない限り、ワークロード／サービスのポートから 443 を削除し、コンテナ内の TLS 証明書マウント（例：/etc/nginx/ssl、/etc/ssl、/certs）を削除します
• 決定的な変換エントリーポイントとして、scripts/compose_to_template.py --kompose-mode always を優先します（再現可能なワークロードの構成には kompose が必要です）
• 公式の Kubernetes インストール手順／マニフェストがある場合は、デュアルソースのマージを行います。Compose をトポロジーのベースラインとして使用し、その後、公式の Kubernetes ガイダンスに合わせてアプリケーションのランタイムセマンティクスを調整します

Step 5: データベース戦略を適用する

• PostgreSQL は、固定されたバージョンと構造の要件に従う必要があります。
• MySQL/MongoDB/Redis/Kafka は、references/database-templates.md のテンプレートとシークレットの命名規則を使用する必要があります。
• アプリケーションのデータベースのブートストラップに必要な場合は、DB init Job/initContainer を追加します。
• PostgreSQL のカスタムデータベース（postgres 以外）では、init Job は実行前に PostgreSQL の準備完了を待ち、冪等性を確保して対象データベースを作成する必要があります。

Step 6: 出力ファイルを生成する

必ず以下を生成します。

• template/<app-name>/index.yaml
• 公式アイコンを特定できる場合は template/<app-name>/logo.<ext>

Step 7: 出力前に検証する

テンプレートを出力する前に、バリデーターとセルフテストを実行します。 検証に失敗した場合は、テンプレート／ルール／例を先に修正します。

MUST ルール（要約）

命名とメタデータ

• テンプレートの metadata.name は小文字で直接指定する必要があります。${{ defaults.app_name }} は使用しないでください。
• テンプレート CR のフォルダー名は metadata.name と一致させる必要があります。
• テンプレート CR には、必須のメタデータフィールド（title、url、gitRepo、author、description、icon、templateType、locale、i18n、categories）を含める必要があります。
• テンプレートの spec.readme は https://raw.githubusercontent.com/labring-actions/templates/kb-0.9/template/<app-name>/README.md にする必要があります。
• テンプレートの spec.i18n.zh.readme は https://raw.githubusercontent.com/labring-actions/templates/kb-0.9/template/<app-name>/README_zh.md にする必要があります。
• icon の URL は、kb-0.9 ブランチにある、このアプリのテンプレートリポジトリ内の raw パスを指定する必要があります。
• i18n.zh.description は簡体字中国語で記述する必要があります。
• i18n.zh.title が title と同一の場合は省略してください。
• categories には、定義済みの値（tool、ai、game、database、low-code、monitor、dev-ops、blog、storage、frontend、backend）のみを使用してください。

アプリリソース

• アプリリソースでは spec.data.url を使用する必要があります。
• アプリリソースの spec.displayType は normal にする必要があります。
• アプリリソースの spec.type は link にする必要があります。
• アプリリソースでは spec.template を使用しないでください。
• cloud.sealos.io/app-deploy-manager ラベルの値は、リソースの metadata.name と一致させる必要があります。
• 管理対象アプリのワークロードでは、metadata.labels.app ラベルの値をリソースの metadata.name と一致させる必要があります。
• 管理対象アプリのワークロードでは、containers[*].name をワークロードの metadata.name と一致させる必要があります。
• アプリケーションの Service リソースでは、metadata.labels.app と metadata.labels.cloud.sealos.io/app-deploy-manager を定義し、両方のラベルを spec.selector.app と一致させる必要があります。
• コンポーネントスコープの ConfigMap リソースでは、metadata.labels.app と metadata.labels.cloud.sealos.io/app-deploy-manager を定義し、両方のラベルを metadata.name と一致させる必要があります。
• アプリケーションの Service リソースでは、metadata.name、metadata.labels.app、metadata.labels.cloud.sealos.io/app-deploy-manager、spec.selector.app で同じコンポーネント名を使用する必要があります。
• アプリケーションの Ingress リソースでは、metadata.name、metadata.labels.cloud.sealos.io/app-deploy-manager、バックエンドの service.name で同じコンポーネント名を使用する必要があります。
• Service の spec.ports[*].name は明示的に設定する必要があります（複数ポートのサービスでは必須です）。
• HTTP Ingress には、必須の nginx アノテーション（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）を期待されるデフォルト値とともに含める必要があります。
• アプリケーションの公式ヘルスチェックが利用できる場合、管理対象のワークロードには livenessProbe、readinessProbe、（ブートストラップに時間がかかるアプリでは）startupProbe を定義し、公式のエンドポイント／コマンドに合わせる必要があります。

Kubernetes 公式仕様との整合性

• Kubernetes 公式のインストール手順／マニフェストが利用できる場合、テンプレートの成果物を出力する前に、それらを参照し、重要なランタイム設定を整合させる必要があります。
• Kubernetes 公式のドキュメント／マニフェストと Compose の設定が異なる場合、より優先度の高い Sealos MUST／セキュリティ上の制約に違反しない限り、アプリの動作（ブートストラップ時の管理者フィールド、外部エンドポイント／環境変数／プロトコル、ヘルスプローブ）には Kubernetes 公式のランタイム仕様を優先してください。

イメージとプルポリシー

• :latest は使用しないでください。
• crane でバージョンを解決してください。明示的なバージョンタグ（例：v2.2.0）を優先し、決定的なバージョンタグが使用できない場合に限り、ダイジェスト固定を代替として使用してください。
• 可変タグ（例：:v2、:2.1、:stable）は避け、明示的なバージョンタグまたはダイジェストを使用してください。
• 管理対象ワークロードのイメージ参照は具体的な値にし、Compose 形式の変数式（例：${VAR}、${VAR:-default}）を含めないでください。テンプレートアーティファクトを出力する前に、明示的なタグまたはダイジェストに解決してください。
• アプリケーションの originImageName はコンテナイメージと一致させてください。
• 管理対象アプリのワークロードでは、アプリスコープのイメージプル Secret ${{ defaults.app_name }} を template.spec.imagePullSecrets で参照してください。
• レジストリプル Secret は、プライベート GHCR イメージ向けのローカル gh CLI 認証情報を使用して、実行時に sealos-deploy が管理します。生成されるテンプレートで、生のレジストリ認証情報入力を公開しないでください。
• すべてのコンテナで imagePullPolicy: IfNotPresent を明示的に設定してください。

ストレージ

• emptyDir は使用しないでください。
• ストレージが必要な場合は、永続ストレージパターン（volumeClaimTemplates）を使用してください。
• ソース仕様でより少ない容量が明示的に必要とされていない限り、PVC の要求容量は <= 1Gi にしてください。
• ConfigMap のキーとボリューム名は、vn の命名規則（scripts/path_converter.py）に従ってください。

環境変数とシークレット

• データベース以外の機密値・入力には、env[].value を直接使用してください。
• ビジネスコンテナでは、データベース接続フィールド（endpoint、host、port、username、password）を、承認済みの Kubeblocks データベースシークレットから env[].valueFrom.secretKeyRef で取得してください。
• ビジネスコンテナでは、承認済みの Kubeblocks データベースシークレットとオブジェクトストレージシークレットを除き、カスタムの環境変数またはボリュームの Secret 参照を使用しないでください。
• アプリスコープ専用のレジストリプル Secret は使用できます。参照には template.spec.imagePullSecrets のみを使用してください。
• データベース接続やブートストラップでは、Kubeblocks が提供するシークレットを使用できます。また、予約済みの Kubeblocks データベースシークレット名をカスタムの Secret リソースで再定義してはいけません。
• 環境変数は、参照される前に宣言してください（例：URL を構成する前にパスワードを宣言）。
• 公式のアプリ環境変数の命名規則に従い、独自のプレフィックスを作らないでください。
• アプリケーションで、ファイルベースの設定システム（例：node-config の config/default.json、PHP 設定ファイル）を通じてパブリック URL を設定する必要がある場合は、パブリック URL を https://${{ defaults.app_host }}.${{ SEALOS_CLOUD_DOMAIN }} に設定した設定ファイルを含む ConfigMap を作成し、アプリケーションの設定ディレクトリにマウントしてください。ConfigMap は標準の命名規則とラベル規則に従う必要があります。
• カスタム PostgreSQL データベース（postgres 以外）では、${{ defaults.app_name }}-pg-init Job を含め、起動時の安全性と冪等性を確保した作成ロジック（準備完了の待機と、作成前の存在確認）を実装してください。

データベース固有の制約

• PostgreSQL のバージョン：postgresql-16.4.0。
• PostgreSQL API：apps.kubeblocks.io/v1alpha1。
• PostgreSQL RBAC の統一命名規則：${{ defaults.app_name }}-pg。
• PostgreSQL RBAC には、app.kubernetes.io/instance および app.kubernetes.io/managed-by ラベルが必要です。
• PostgreSQL ロールのワイルドカード権限要件は、現在の仕様で定義されているとおりです。
• PostgreSQL クラスターには、必須のラベル／フィールド（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 クラスターは、アップグレード後の構造（componentDef: mongodb、serviceVersion: 8.0.4、ラベル kb.io/database および app.kubernetes.io/instance）に従う必要があります。
• MySQL クラスターは、アップグレード後の構造（kb.io/database: ac-mysql-8.0.30-1、clusterDefinitionRef: apecloud-mysql、clusterVersionRef: ac-mysql-8.0.30-1、tolerations: []）に従う必要があります。
• Redis クラスターは、アップグレード後の構造（componentDef: redis-7、componentDef: redis-sentinel-7、serviceVersion: 7.2.7、メインデータ PVC 1Gi、トポロジー replication）に従う必要があります。
• データベースクラスターのコンポーネントリソースには、ソースドキュメントで別途明示されていない限り、limits(cpu=500m,memory=512Mi) と requests(cpu=50m,memory=51Mi) を使用する必要があります。
• シークレットの命名：
  • MongoDB：${{ defaults.app_name }}-mongodb-account-root
  • Redis：${{ defaults.app_name }}-redis-redis-account-default
  • Kafka：${{ defaults.app_name }}-broker-account-admin
  • サポート対象の例外を除き、レガシーな命名規則は使用しないでください。

ベースラインのランタイムデフォルト

ソースドキュメントで別途明示されていない限り、以下を使用してください。

• コンテナーの上限：cpu=200m、memory=256Mi
• コンテナーのリクエスト：cpu=20m、memory=25Mi
• revisionHistoryLimit: 1
• automountServiceAccountToken: false

デフォルト値と入力値

• 生成される値（app_name、app_host、ランダムなパスワード／キー）には defaults を使用します。
• inputs は、ユーザーが実際に指定する運用上の値（メール／SMTP／外部 API キーなど）にのみ使用します。
• inputs.description は英語で記述する必要があります。

検証コマンド

最終回答の前に、すべてのチェックを実行してください。

1. python scripts/path_converter.py --self-test
2. python scripts/test_check_consistency.py
3. python scripts/test_compose_to_template.py
4. python scripts/test_check_must_coverage.py
5. python scripts/check_consistency.py --skill SKILL.md --references references --rules-file references/rules-registry.yaml
6. python scripts/check_consistency.py --skill SKILL.md --references references --rules-file references/rules-registry.yaml --artifacts template/<app-name>/index.yaml
7. python scripts/check_must_coverage.py --skill SKILL.md --mapping references/must-rules-map.yaml --rules-file references/rules-registry.yaml
8. （CI／一括実行）python scripts/quality_gate.py（デフォルトでは template/*/index.yaml が必要です。アーティファクトなしで開発／デバッグを行う場合に限り、DOCKER_TO_SEALOS_ALLOW_EMPTY_ARTIFACTS=1 を設定してください）

check_consistency.py はレジストリ駆動です。references/rules-registry.yaml を実装済みルールと同期させてください。 レジストリのルールエントリーでは、severity と、任意の scope.include_paths メタデータをサポートしています。

出力要件

変換が完了したら、以下を提示してください。

1. 簡潔な変換概要
2. 対象ファイルのパス（template/<app-name>/index.yaml）
3. テンプレート YAML の全体
4. 曖昧さがあった場合に限り、主な判断内容

参照資料の読み込み（段階的な読み込み）

現在のタスクに必要な参照資料のみを読み込みます。

• references/sealos-specs.md
  • 権威ある順序、ラベル、App／Ingress／ConfigMap の規約
• references/conversion-mappings.md
  • Docker から Sealos へのフィールド単位のマッピングと特殊な変換
• references/database-templates.md
  • データベーステンプレート、RBAC 構造、シークレット命名パターン
• references/frappe-bench.md
  • Frappe／ERPNext／HRMS／bench の変換パターン、初期化リソース、冪等なサイトのブートストラップ、よくある失敗の兆候
• references/example-guide.md
  • 例とパターンの解説（権威ある資料ではありません）
• references/rules-registry.yaml
  • 機械可読な検証対象とルールの一覧
• references/must-rules-map.yaml
  • ドリフト防止のための MUST 項目と適用ルール（rule または manual）のマッピング

スクリプトユーティリティ

• scripts/path_converter.py
  • パスを vn 名に変換します
  • リグレッションチェック用のセルフテストに対応しています
• scripts/compose_to_template.py
  • Compose／ドキュメントからテンプレートを決定論的に生成するエントリーポイント
  • --kompose-mode auto|always|never に対応しています（デフォルトは always）。kompose convert のワークロード形状を再利用します
  • template/<app-name>/index.yaml を出力します
• scripts/test_compose_to_template.py
  • Compose 変換動作のリグレッションテスト
• scripts/check_consistency.py
  • レジストリ駆動の整合性バリデーター
• scripts/test_check_consistency.py
  • バリデーター動作のリグレッションテスト
• scripts/check_must_coverage.py
  • MUST 項目の適用範囲とレジストリルールの対応を検証します
• scripts/test_check_must_coverage.py
  • MUST 適用範囲バリデーターのリグレッションテスト

特殊なポリシー

• 不足しているフィールドについてユーザーに尋ねず、Compose／ドキュメントとプラットフォームの規約から推定します。
• App リソースは spec.data.url 形式を維持し、spec.template は使用しません。
• App リソースの spec.displayType: normal と spec.type: link を維持し、別の列挙値を推定しません。
• business-env、オブジェクトストレージ、DB シークレットのポリシーは MUST ルールと整合させます。
• バンドルされたエッジプロキシより Sealos 管理の Ingress を優先します。Traefik ゲートウェイが Ingress／フロントプロキシとしてのみ機能し、ビジネスサービスが少なくとも 1 つ存在する場合、Traefik のワークロードリソースは出力しません。
• コンテナ内の TLS より Sealos Ingress でのゲートウェイ TLS 終端を優先します。HTTP／HTTPS のデュアルポートワークロードでは、HTTP サービスポートを維持し、公式ドキュメントで HTTPS バックエンドが要求されていない限り、冗長な HTTPS／証明書マウントを削除します。
• 矛盾が生じた場合は、例外の追加よりも参照先や例の修正を優先します。
• 対象アプリの公式 Kubernetes インストールドキュメント／マニフェストがある場合、それらを無視せず、Compose のデフォルトを超えてランタイムのセマンティクスを調整するために使用します。
• プロジェクトに Frappe、ERPNext、HRMS、または bench が含まれる場合、アプリのワークロードを生成する前に references/frappe-bench.md を読み込みます。