render-blueprints

Render Blueprints（render.yaml）

Blueprint は、Render のインフラストラクチャを YAML として定義します（通常はリポジトリのルートにある render.yaml を使用します）。このスキルでは、作成、接続、プロジェクト／環境、プレビュー、検証、変更不可のフィールドに重点を置いています。詳しい情報は references/ にあります。

Blueprint を作成または変更する前に、現在の仕様の取得、検証、リポジトリとの同期、安全な作業手順について、references/blueprints.md をお読みください。

現在のコンピュートプランの用語、Plan ID、利用可否については、サンプルに含まれるプラン一覧に頼らず、references/compute-plans.md をご利用ください。

サービスにアタッチするディスクを追加または変更する前に、現在のアーキテクチャ上の制約と設定手順について、references/persistent-disks.md をお読みください。

プライベートネットワークのアドレス、ポート、またはディスカバリーホスト名を接続する前に、references/private-networking.md をお読みください。

サービス種別を選択する前、またはダッシュボード上の名称を Blueprint の構造に置き換える前に、references/service-types.md をお読みください。

使用するタイミング

ユーザーが次の操作を行う場合に、このスキルを使用します。

• render.yaml／Blueprint を作成または編集する
• データベース、プライベートサービス、Key Value をアプリの環境変数に接続する
• プロジェクトと環境を使ってサービスをグループ化する
• プルリクエスト向けのプレビュー環境を設定する
• Render のスキーマまたは CLI に対して YAML を検証する
• リソース作成後に変更可能な項目と変更不可能な項目を確認する

デプロイのエンドツーエンドのフローと MCP／CLI の操作については、render-deploy をご覧ください。Blueprint の構文以外での環境変数の戦略については、render-env-vars をご覧ください。Docker 固有の Blueprint フィールドについては、render-docker をご覧ください。

Blueprint の構造

トップレベルのキー

Key	用途
services	Web、ワーカー、cron、プライベートサービス、Key Value、静的サイト（web と runtime: static を使用）
databases	マネージド PostgreSQL インスタンス
envVarGroups	サービスにアタッチする再利用可能な環境変数セット
projects	任意のグループ化。environments とサービスのリストを含みます
previews	PR プレビュー環境のデフォルト設定

プロジェクトモデルを採用するかどうかに応じて、Blueprint ではリソースをグループ化しないパターンや、環境スコープのリストを使うパターンも利用できます。重複や命名に関する注意点は、references/common-mistakes.md をご覧ください。

最小限の例：Web + PostgreSQL

databases:
  - name: mydb
    plan: basic-256mb
    region: oregon

services:
  - type: web
    name: api
    runtime: node
    region: oregon
    plan: starter
    buildCommand: npm ci && npm run build
    startCommand: npm start
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: mydb
          property: connectionString

サービス種別

type	役割
web	パブリック HTTP サービス（静的サイトでは runtime: static を使用）
pserv	プライベートサービス（内部 HTTP／TCP。パブリックではありません）
worker	長時間実行するバックグラウンドプロセス
cron	スケジュールされたジョブ（schedule が必須）
keyvalue	マネージド Key Value（Redis 互換）。Blueprint では別名の redis も使用できます

ランタイム

一般的な runtime の値は、node、python、go、ruby、rust、elixir、docker、image、static です。

• docker：Dockerfile からビルドします（dockerfilePath、dockerContext、dockerCommand をご覧ください）。
• image：image.url と、任意の image.creds.fromRegistryCreds を指定して、ビルド済みコンテナーイメージを実行します。
• static：静的サイトです。staticPublishPath とビルド出力パスが必要です（詳細はリファレンスをご覧ください）。

サービス間の接続

変数、シークレット、シークレットファイル、環境グループを設定する前に、references/environment-variables.md をお読みください。

envVars の下にあるサービス環境変数では、シークレットをハードコードする代わりに、他のリソースから値を取得できます。環境グループの変数から、サービス、データベース、または他の環境グループを参照することはできません。

fromDatabase

databases: 内のデータベースを name で参照します。プロパティには次のものがあります。

• connectionString、connectionPoolString、host、port、user、password、database

fromService

name でサービスを参照します。一般的なプロパティは次のとおりです。

• host、port、hostport、connectionString、envVarKey

有効なプロパティは接続先のサービス種別（Key Value と pserv など）によって異なります。references/wiring-patterns.md をご覧ください。

fromGroup

envVarGroupsから、グループのnameを指定して共有変数をアタッチします。

パターンと組み合わせの詳細：references/wiring-patterns.md。

プロジェクトと環境

複数サービスのアプリでは、トップレベルのservices／databasesをフラットに定義するのではなく、**projects／environments**パターンを使用してください。関連するすべてのリソースを単一のRenderプロジェクトにまとめ、複数の環境（本番、ステージング）をサポートし、環境ごとに設定を適用できます。

projects:
  - name: my-app
    environments:
      - name: production
        services:
          - type: web
            name: api
            runtime: node
            plan: standard
            buildCommand: npm ci && npm run build
            startCommand: npm start
            envVars:
              - key: DATABASE_URL
                fromDatabase:
                  name: db
                  property: connectionString
              - key: REDIS_URL
                fromService:
                  type: keyvalue
                  name: cache
                  property: connectionString
              - key: API_SECRET
                sync: false

          - type: worker
            name: jobs
            runtime: node
            plan: starter
            buildCommand: npm ci
            startCommand: node worker.js
            envVars:
              - key: DATABASE_URL
                fromDatabase:
                  name: db
                  property: connectionString
              - key: REDIS_URL
                fromService:
                  type: keyvalue
                  name: cache
                  property: connectionString

          - type: keyvalue
            name: cache
            plan: starter
            maxmemoryPolicy: noeviction
            ipAllowList: [] # Internal access only

        databases:
          - name: db
            plan: basic-256mb

主なルール：

• 各環境は独自のservicesとdatabasesのリストを所有します。
• 同じリソースをルートレベルと環境内の両方で定義しないでください。
• envVarGroupsは、プロジェクト環境にスコープを限定することも、ワークスペース全体で共有することもできます。
• Proワークスペース以上では、環境分離によって環境間のプライベートネットワークトラフィックをブロックできます。

単一サービスのアプリであれば、トップレベルのservices／databasesをフラットに定義しても問題ありません。複数のサービスがある場合、ステージングと本番を分ける必要がある場合、または環境ごとに環境変数グループを適用したい場合は、projectsパターンを使用してください。

プレビュー環境

プレビューのリクエストで要件が不明確な場合は、まず希望する生成モード、保持期間、プレビュー用コンピューティングプラン、リソースを除外する必要があるかどうかを確認してください。

トップレベルのpreviewsでBlueprintのプレビュー環境を制御します。

• previews.generation：off（デフォルト）、manual、またはautomatic
• previews.expireAfterDays：N日後にプレビュースタックを自動削除します

プレビュー環境とサービスプレビューを混同しないでください。

• トップレベルのpreviews.generation: automaticを設定すると、Blueprintのプレビュー環境が作成され、そのBlueprintで宣言されたリソースが含まれます。
• サービスレベルのpreviews.generationは、そのサービス独自のプレビューを制御します。Blueprintのプレビュー環境を上書きしたり、その環境からサービスを除外したりするものではありません。指定できる値はmanualまたはautomaticのみです。独立したサービスプレビューを無効にするには、この項目を省略します。
• コンピューティングサービスでは、previews.planとpreviews.numInstancesを使って、プレビュー環境のインスタンスサイズを指定します。Key ValueとPostgresでは、代わりにpreviewPlanを使用します。

ワーカーなどのリソースをBlueprintのプレビュー環境から完全に除外する必要がある場合は、サービスレベルのプレビュー生成は除外の仕組みではないことを説明してください。その要件には、Blueprintまたはアプリケーションのアーキテクチャで対応する必要があります。その他の制限事項として、オートスケーリングの動作、sync: false変数、データベースプランの互換性があります。詳細はreferences/preview-environments.mdを参照してください。

不変フィールド

重要： リソースの作成後に変更できないフィールドがあります。編集が拒否されたり、リソースを置き換える必要が生じたりする場合があります。

サービス

• type：変更できません（例：webからworker）。
• runtime：変更できません（例：nodeからdocker）。

データベース

作成後に変更できません。

• name（このコンテキストでは、論理的なBlueprint／データベース識別子）
• databaseName
• user
• region
• postgresMajorVersion

その他のフィールド（ディスク、HA、レプリカ）は、事前に慎重に計画してください。スケール可能なフィールドと再作成が必要なフィールドについては、Renderのドキュメントを参照してください。

主要フィールド（クイックマップ）

領域	フィールド
プラン	plan；コンピュートサービスの previews.plan；Key Value/Postgres の previewPlan
ビルド／実行	buildCommand、startCommand、preDeployCommand、rootDir
デプロイ	autoDeployTrigger：commit、checksPass、または off
ライフサイクル	maxShutdownDelaySeconds：1～300、デフォルト 30
HTTP	healthCheckPath、domains
ストレージ	disk（name、mountPath、sizeGB）
スケーリング	scaling / numInstances（参考資料を参照）
モノレポ	buildFilter（paths、ignoredPaths）
Docker	dockerfilePath、dockerContext、dockerCommand、registryCredential；ビルド済みイメージの image.url / image.creds

使用を避けるべき非推奨名：env（runtime を使用）、redis（keyvalue を使用）、autoDeploy（autoDeployTrigger を使用）、previewsEnabled、pullRequestPreviewsEnabled。references/common-mistakes.md で説明されている、適切なトップレベルまたはサービスレベルの previews.generation への置き換えを使用してください。

参考資料

ドキュメント	内容
references/blueprints.md	現行の Blueprint 仕様、スキーマ、検証、リポジトリ同期、安全なワークフロー
references/compute-plans.md	現行のコンピュートプラン用語、プラン ID の確認方法、利用可能性、変更時の動作
references/environment-variables.md	現行の環境変数ドキュメント、シークレット、グループ、プラットフォーム変数、安全な変更
references/persistent-disks.md	サービスに接続するディスクの制約、現行のドキュメント、サイズ設定、スナップショット、Blueprint ワークフロー
references/private-networking.md	プライベートネットワークの範囲、アドレス、Blueprint の参照、確認方法、ポート、分離
references/service-types.md	サービス種別の選択、実行モデル、Blueprint の命名
references/field-reference.md	サービス種別、データベース、グループ、プロジェクト、プレビュー、スケーリング、ディスク、静的サイト、Key Value の YAML フィールド
references/wiring-patterns.md	fromDatabase / fromService / fromGroup の例と、複合的な接続パターン
references/common-mistakes.md	ブランチとプレビュー、buildFilter、レプリカ、重複、プレビューのプラン、接続時のミス
references/preview-environments.md	previews.generation、有効期限、previews.plan、previewPlan、ディスク、PR ワークフロー

関連スキル

• render-deploy — デプロイの流れ、Blueprint と直接作成の比較、MCP／ディープリンク
• render-env-vars — 環境変数の方針、シークレット、ダッシュボードと Blueprint
• render-docker — Dockerfile ベースのサービスとイメージ実行時の注意点

現行ドキュメントの取得

このスキルで現行の Render ドキュメントを参照するよう指示された場合は、次の手順に従ってください。

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

複数の参考資料が必要なタスクでは、それぞれにこの手順を適用し、確認済みのドキュメントと利用できないドキュメントを区別してください。