render-migrate-from-heroku

Heroku から Render への移行

ユーザーが提供したインベントリまたはローカルのプロジェクトファイルを使って Heroku から Render に移行し、必要に応じて MCP 経由で Heroku の最新データを取得し、不足している詳細を補います。

前提条件の確認

開始する前に、利用できるものを確認します。

1. アプリのインベントリ（必須） — ユーザーが提供した詳細情報を使用するか、Procfile、app.json、package.json、requirements.txt、Gemfile、go.mod などのローカルのプロジェクトファイルを調べます
2. Render MCP（推奨） — list_services ツールが利用可能か確認します。MCP による直接作成（ステップ 3B）と自動検証（ステップ 6）に必要です。Blueprint の手順では不要です。生成、検証、デプロイは Render CLI とダッシュボードで行います。
3. Heroku MCP（任意） — list_apps ツールが利用可能か確認します

ユーザーが依頼されたプラン、Blueprint、または移行手順に十分な情報をすでに提供している場合は、ローカルファイルや MCP を必須としないでください。Render MCP がなく、ユーザーが実際に Render の最新情報へのアクセスを必要としている場合は、references/render-access.md の Render アクセスワークフローを使用します。MCP セットアップガイドでは、Heroku 固有のセットアップについて説明しています。Heroku MCP がない場合は、提供された値を使用するか、不足している構成変数名とアドオンの詳細のみを尋ねます。

移行ワークフロー

最初から最後まで移行する場合は、該当するステップを順番に実行します。調査結果をユーザーに提示し、リソースを作成する前に確認を得てください。

Heroku のプロセスタイプを Render のサービスタイプに対応付ける前に、references/service-types.md を読んでください。

必要な範囲に絞ったワークフローを選ぶ

• 完全なインベントリ＋Blueprint の依頼： references/service-mapping.md、references/blueprint-example.md、references/blueprints.md を読み、完全な Blueprint を直接生成します。ユーザーが提供した値を再確認するためだけに、ライブツールを呼び出さないでください。
• 単一サービスの移行： 不足しているインベントリ情報を収集し、計画を提示します。ユーザーがサービスの作成を依頼し、計画を確認した後にのみ、MCP による直接作成を使用します。
• データ移行に関する質問： references/service-mapping.md と references/data-migration.md を読み、依頼がない限りライブ操作を行わずに、該当する手順を提示します。

references/service-mapping.md に記載された該当する Heroku プランの行を、その Render プランとディスク割り当ても含めて正確に使用してください。これらの移行マッピングでは、適切な場合にレガシーの Render プラン名を意図的に使用しています。記憶している現行の Plan ID に置き換えないでください。

ステップ 1：Heroku アプリのインベントリを作成する

まずローカルファイルからアプリの詳細を収集し、利用可能な場合は Heroku MCP で補足します。

1a. ローカルのプロジェクトファイルを読み取る（必ず実行）

リポジトリから以下のファイルを読み取り、ランタイム、コマンド、依存関係を特定します。

ファイル	わかること
Procfile	プロセスタイプと起動コマンド（web、worker、clock、release）
package.json	Node.js ランタイム、ビルドスクリプト、フレームワークの依存関係（Next.js、React など）
requirements.txt / Pipfile / pyproject.toml	Python ランタイム、依存関係（Django、Flask など）
Gemfile	Ruby ランタイム、依存関係（Rails、Sidekiq など）
go.mod	Go ランタイム
Cargo.toml	Rust ランタイム
app.json	宣言されたアドオン、環境変数の説明、ビルドパック
runtime.txt	固定されたランタイムバージョン
static.json	静的サイトであることを示す情報
yarn.lock / pnpm-lock.yaml	パッケージマネージャー（ビルドコマンドに影響）

これらのファイルから、以下を特定します。

• ランタイム — 依存関係ファイルから特定します（ビルドパックの対応表を参照）
• ランタイムバージョン — runtime.txt、.node-version、またはpackage.jsonのenginesから特定します。固定されている場合は、環境変数（例：PYTHON_VERSION、NODE_VERSION）として引き継ぎます。固定されていない場合は、バージョンを指定しないでください。Render のデフォルトバージョンを推測したり、記載したりしてはいけません。
• ビルドコマンド — パッケージマネージャーとフレームワークから特定します（ビルドパックの対応表を参照）
• 起動コマンド — Procfileのエントリから特定します
• プロセスタイプ — Procfileから特定します（web、worker、clock、release）
• 必要なアドオン — app.jsonのaddonsフィールドから特定するか、依存関係ファイルから推測します（例：package.jsonのpgはPostgres、redisはKey Valueを示唆します）
• 静的サイトかどうか — static.json、SPAフレームワークの依存関係、またはapp.jsonの静的ビルドパックから特定します

1b. Heroku MCP で詳細を補完する（利用可能な場合）

Heroku MCP サーバーが接続されている場合、以下のツールを呼び出して、リポジトリに記載されていない詳細を補完します。dyno のサイズとアドオンのプランスラッグは重要です。これらを基に、使用する Render のプランが決まります。

1. list_apps — 移行するアプリをユーザーに選択してもらいます（アプリ名を確認します）
2. get_app_info — リージョン、スタック、ビルドパック、設定変数名を取得します
3. list_addons — アドオンの正確なプランスラッグを取得します（例：heroku-postgresql:essential-2、heroku-redis:premium-0）。コロン以降の部分は、サービスマッピング内の特定の Render プランに対応します。
4. ps_list — 各プロセスタイプの正確な dyno サイズを取得します（例：Standard-2X、Performance-M）。各 dyno サイズは、サービスマッピング内の特定の Render プランに対応します。
5. pg_info（Postgres が存在する場合） — データサイズ（実際の使用量）とプランのディスク割り当てを取得します。プランのディスクサイズによって、Blueprint の diskSizeGB の値が決まります（サービスマッピングを参照）。

Heroku MCP が利用できない場合は、ユーザーに以下の情報を提供してもらいます。

• dyno サイズ（または heroku ps:type -a <app> を実行して、出力を貼り付けてもらいます）
• アドオンのプラン（または heroku addons -a <app> を実行して、出力を貼り付けてもらいます）
• データベース情報（または heroku pg:info -a <app> を実行して、出力を貼り付けてもらいます。プラン名、データサイズ、ディスク割り当てを取得できます）
• アプリのリージョン（us または eu）
• 設定変数名（または heroku config -a <app> --shell を実行して、出力を貼り付けてもらいます）

dyno サイズやアドオンのプランをユーザーが提供できない場合は、サービスマッピングの代替デフォルト値を使用します。コンピューティングには starter、Postgres には basic-1gb、Key Value には starter を使用します。

概要を提示する

App: [name] | Region: [region] | Runtime: [node/python/ruby/etc]
Source: [local files | local files + Heroku MCP]
Build command: [inferred from buildpack/deps]
Processes:
  web: [command from Procfile] → Render web service ([mapped-plan])
  worker: [command] → Render background worker ([mapped-plan], Blueprint only)
  clock: [command] → Render cron job ([mapped-plan])
  release: [command] → Append to build command
Add-ons:
  Heroku Postgres ([plan-slug], [disk-size]) → Render Postgres ([mapped-plan], diskSizeGB: [size])
  Heroku Key-Value Store ([plan-slug]) → Render Key Value ([mapped-plan])
Config vars: 14 total (list names, not values)

ステップ 2：事前確認

何かを作成する前に、事前確認チェックリストに沿って移行計画を検証します。主な確認項目は以下のとおりです。

• ランタイムがサポートされている（または Dockerfile が必要）
• ワーカー dyno、リリースフェーズ、静的サイトの検出
• Render に相当するものがないサードパーティ製アドオン
• Git リモートが存在し、HTTPS 形式である
• データベースのサイズ（大規模なデータベースには移行支援が必要）

サービスマッピングで Heroku の各 dyno サイズとアドオンのプランを調べ、適切な Render プランを特定します。事前確認チェックリストの移行計画表を提示し、料金が発生するリソースを明示します。最新情報はRender の料金を確認するようユーザーに案内し、何かを作成する前に確認を待ちます。

作成方法を決定する

ユーザーが事前確認の計画を承認した後、この判定ルールを適用します。デフォルトでは Blueprint を使用します。以下の条件をすべて満たす場合に限り、MCP による直接作成を使用します。

次のいずれかに該当する場合は Blueprint を使用します（デフォルト）。

• 複数のプロセスタイプがある（web + worker、web + cron など）
• データベースまたは Key Value ストアが必要
• Procfile にバックグラウンドワーカーがある
• ユーザーが Infrastructure-as-Code による設定を希望する

以下の条件をすべて満たす場合に限り、MCP による直接作成に切り替えます。

• web サービスまたは静的サイトサービスが 1 つのみ（プロセスタイプが 1 つ）
• バックグラウンドワーカーや cron ジョブがない
• データベースや Key Value ストアがない

判断に迷う場合は Blueprint を使用します。ほとんどの Heroku アプリには少なくともデータベースがあるため、大半の移行では Blueprint が適用されます。

ステップ 3A：Blueprint を生成する（複数サービス）

この方法には 3 つの段階があります。必ず作成を完了し、ローカルでの検証が対象に含まれる場合はそれを実施したうえで、適用手順を提示します。

3A-i. render.yaml を作成する

完全な render.yaml を生成します。ユーザーのリポジトリ内で作業している場合はリポジトリのルートに書き込み、それ以外の場合は回答内にファイル全体を提示します。作成する前に、references/blueprints.md に記載されている現在の仕様の取得、検証、リポジトリ同期、安全性に関するワークフローを確認します。次に、移行固有の構造には Blueprint example を使用します。

重要：必ず projects／environments パターンを使用してください。 YAML は projects: キーで始めてください。トップレベルにフラットな services: または databases: キーを使用してはいけません。これにより、移行されたすべてのリソースが単一の Render プロジェクトにまとめられます。

サービスマッピングに基づき、各サービスとデータベースの plan: フィールドに、対応する Render プランを設定してください。Heroku の dyno サイズ（ps_list から取得）とアドオンのプランスラッグ（list_addons から取得）を調べ、適切な Render プランを特定します。Heroku のプランが不明な場合は、フォールバックのデフォルト値を使用します。コンピューティングには starter、Postgres には basic-1gb、Key Value には starter を指定します。

Blueprint example に記載されているテンプレート、ルール、パターンにすべて従って YAML を生成します。重要なルールは次のとおりです。

• 必ず projects:／environments: パターンを使用してください。トップレベルにフラットな services: を使用してはいけません
• すべての plan: フィールドに、サービスマッピングに基づく値を設定してください
• Heroku のディスク割り当て量を基に、データベースに diskSizeGB を設定してください
• DATABASE_URL には fromDatabase、REDIS_URL には fromService を使用してください。接続文字列をハードコードしてはいけません
• シークレットには sync: false を指定してください

3A-ii. Blueprint を検証する

render.yaml ファイルをローカルに書き込んだ場合、デプロイ可能な状態として提示する前に検証してください。まず、Render CLI がインストールされているか確認します。

render --version

インストールされていない場合、デプロイ前のローカル検証が必要なときは、インストールを提案してください。

• macOS：brew install render
• Linux/macOS：curl -fsSL https://raw.githubusercontent.com/render-oss/cli/main/bin/install.sh | sh

CLI が利用できるようになったら、検証コマンドを実行し、出力をユーザーに表示してください。

render blueprints validate render.yaml

検証に失敗した場合は、YAML のエラーを修正して再検証してください。検証に合格するまで繰り返します。ユーザーが例のみを求めている場合、またはローカルファイルが存在しない場合は、インストールを試みたり、検証を実行したと主張したりせず、検証コマンドを提示してください。

3A-iii. デプロイ URL を提示する

ユーザーが Blueprint の適用を希望している場合は、検証に合格した後、次の手順を実行します。

1. コミットしてプッシュするようユーザーに案内します：git add render.yaml && git commit -m "Add Render migration Blueprint" && git push
2. git remote get-url origin を実行してリポジトリの URL を取得します。URL が SSH 形式（例：[email protected]:user/repo.git）の場合は、HTTPS（https://github.com/user/repo）に変換します。その後、ディープリンクを組み立てます：https://dashboard.render.com/blueprint/new?repo=<HTTPS_REPO_URL>
3. 実際に機能するディープリンクをユーザーに提示します。プレースホルダー URL を表示してはいけません。リンクを開き、sync: false のシークレットを入力して、Apply をクリックするよう案内します

デプロイ URL を省略してはいけません。 ユーザーが Render で Blueprint を適用するには、このリンクが必要です。

手順 3B：MCP による直接作成（単一サービス）

MCP 経由でリソースを作成する前に、references/render-access.md に従い、アクティブなワークスペースがユーザーの意図したものであることを確認してください。

データベースを使用しない単一サービスの移行では、MCP ツールを使って作成します。

1. Web サービス — 以下を指定して create_web_service を実行します。
   • runtime：ビルドパックのマッピングに基づく値
   • buildCommand：ビルドパックのマッピングに基づく値
   • startCommand：Procfile の web: エントリ
   • repo：ユーザーから提供された GitHub／GitLab の URL
   • region：Heroku のリージョンからマッピングした値
   • plan：サービスのマッピングを使って Heroku の dyno サイズからマッピングした値（該当しない場合は starter）
2. 静的サイト — 検出された場合は、Web サービスの代わりに create_static_site を実行します。

作成が完了したら、作成結果（サービス URL、ID）を提示してください。

手順 4：環境変数の移行

設定を確認または適用する前に、references/environment-variables.md を読み、以下の移行固有のフィルタリングと確認手順を必ず守ってください。

設定変数を収集する

最初に利用可能なソースを使用します。

1. Heroku MCP（推奨） — 手順 1b の get_app_info の結果に含まれる設定変数
2. ユーザーから提供 — heroku config -a <app> --shell の出力を貼り付けるようユーザーに依頼します
3. app.json — 変数名と説明（値はありませんが、sync: false のエントリに役立ちます）

フィルタリングと分類

自動生成された変数と Heroku 固有の変数を削除します（サービスのマッピングに全フィルターリストがあります）。

• DATABASE_URL、REDIS_URL、REDIS_TLS_URL（Render がこれらを生成します）
• HEROKU_* 変数（例：HEROKU_APP_NAME、HEROKU_SLUG_COMMIT）
• アドオンの接続文字列（PAPERTRAIL_*、SENDGRID_* など）

フィルタリング後のリストをユーザーに提示してください。確認を得る前に書き込んではいけません。

変数を適用する

Blueprint の場合（手順 3A）： 環境変数は各サービスの render.yaml にすでに埋め込まれています（シークレットではない値はインラインで指定し、シークレットは sync: false としてマークして、Blueprint の適用時にユーザーが入力できるようにします）。別途 MCP を呼び出す必要はありません。手順 5 に進んでください。

MCP の場合（手順 3B）： 現在の update_environment_variables オペレーションを確認し、コレクションに対するパッチか置換かを確かめてから、無関係なキーを保持しつつ、確認済みの変数のみを適用します。

手順 5：データの移行

データ移行ガイドに従って、Postgres と Key Value のデータを移行します。このガイドでは、手順 5a から 5e までを詳しく説明しています。移行の流れは以下のとおりです。

1. 移行前の確認 — list_postgres_instances() と list_key_value() で Render リソースがプロビジョニング済みであることを確認し、ソース DB のサイズを確認します。Render CLI（render --version）、pg_dump、pg_restore がインストールされていることも確認します
2. 接続文字列を収集する — Heroku Postgres の接続文字列は pg_credentials（MCP）またはユーザーが貼り付ける CLI の出力から取得します。Key Value の場合は ID からダッシュボードへのディープリンクを作成します。
3. Postgres の移行 — サイズに応じて 2 つの方法があります。2 GB 未満では render psql を使います（Render の接続文字列は不要です）。2～50 GBでは、ダッシュボードの外部接続文字列を使って pg_dump -Fc と pg_restore を実行します（より高速で、圧縮され、並列リストアが可能です）。
4. Key Value — 通常はスキップします（一時的なキャッシュのため）。永続データがある場合は、ダッシュボードで提供される Render URL を使い、redis-cli でダンプ／リストアします。
5. データの検証 — query_render_postgres でスキーマと行数を確認し、MCP が利用可能な場合は Heroku のソースと比較します。

手順 6：移行の検証

ユーザーがデータベースの移行完了を確認したら、以下のチェックを順番に実行します。最初の失敗で停止し、問題を修正して再デプロイしてから続行してください。

1. デプロイステータスを確認する

list_deploys(serviceId: "<service-id>", limit: 1)

status: "live" であることを確認します。ステータスが failed の場合は、直ちにビルドログとランタイムログを確認してください。

2. サービスのヘルス状態を確認する

ヘルスエンドポイント（または /）にアクセスし、200 レスポンスが返ることを確認します。ヘルスエンドポイントがない場合は、アプリが localhost ではなく 0.0.0.0:$PORT にバインドされていることを確認します。

3. エラーログを確認する

list_logs(resource: ["<service-id>"], level: ["error"], limit: 50)

環境変数の不足、接続拒否、モジュールが見つからないエラー、ポートのバインドエラーなど、明確な失敗の兆候を探します。

4. 環境変数とポートのバインドを確認する

必要な環境変数がすべて設定されていることを確認します。特に、Blueprint の適用時に sync: false としてマークされたシークレットを確認します。アプリが 0.0.0.0:$PORT にバインドされていることを確認します。

5. リソースのメトリクスを確認する

get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["http_request_count", "cpu_usage", "memory_usage"]
)

選択したプランで、CPU とメモリが想定範囲内であることを確認します。

6. データベースへの接続を確認する

query_render_postgres(postgresId: "<postgres-id>", sql: "SELECT count(*) FROM <key_table>")

主要なテーブルに対して読み取り専用クエリを実行し、データが正しく復元されたことを確認します。可能であれば、Heroku のデータベースと行数を比較します。

すべてのチェックに合格した後、ヘルス状態の概要を提示します。

ステップ 7：DNS の切り替え（手動）

ユーザーに次の操作を案内します。

1. ドメインの CNAME を [service-name].onrender.com に向ける
2. 古い Heroku の DNS エントリを削除または更新する
3. 伝播を待つ

ロールバック計画

移行がどの段階で失敗しても、次のように対応します。

• サービスは作成されたが動作しない：Render のダッシュボードからサービスを削除できます（MCP サーバーでは意図的に削除をサポートしていません）。メンテナンスモードが有効になるまでは、Heroku アプリに変更はありません。
• 環境変数が正しくない：references/environment-variables.md に従い、現在の更新操作がパッチ方式か置換方式かを確認して、意図したキーのみを修正します。
• データベースの移行に失敗した：Render Postgres は削除して再作成できます。ダンプ中、Heroku データベースは読み取り専用のため、データは失われません。Heroku で maintenance_off が呼び出されると、元のアプリは完全に稼働状態に戻ります。
• DNS をすでに変更した：CNAME を Heroku に戻し、Heroku のメンテナンスモードを無効にします。

重要な原則：ユーザーが明示的に DNS を切り替えるまで、Heroku は完全に機能し続けます。 最後のステップまでは、移行によって既存環境に変更は加わりません。

エラー処理

• サービスの作成に失敗した場合：エラーを表示し、修正方法（無効なプラン、不正なリポジトリ URL など）を提案します
• 環境変数の移行が一部失敗した場合：成功した項目と失敗した項目を示します
• Heroku の認証エラーが発生した場合：heroku login を実行するか、HEROKU_API_KEY を確認するよう案内します
• Render の認証エラーが発生した場合：MCP の設定で Render API キーを確認します

最新のドキュメントの取得

このスキルで最新の Render ドキュメントを参照するよう指示された場合は、必ず次の手順に従います。

1. 利用可能な URL 取得ツールまたは HTTP クライアント（curl など）を使って、リンク先の Markdown ドキュメントを直接取得します。ドキュメントの代わりにウェブ検索の要約を使ってはいけません。
2. 取得が成功し、期待されるドキュメントが返されたことを確認してから、内容を読みます。ファイルを保存したり、パスを表示したりするだけでは不十分です。
3. リクエストに失敗した場合、またはツールで Markdown のレスポンスを読み取れない場合は、リンク先の HTML 版を開いて読みます。
4. どちらの版も取得できない場合は、最新の参照ドキュメントを利用できないことを明示し、このスキルに記載されたトピック別の代替手順に従います。安定した制約には同梱のガイダンスを使い、変更される可能性のあるプラットフォームの詳細を推測してはいけません。

複数の参照資料が必要なタスクでは、それぞれにこの手順を適用し、確認できたドキュメントと取得できなかったドキュメントを区別します。