zeabur-template-deploy

Zeabur テンプレートのデプロイ

Zeabur CLI の実行には、必ず npx zeabur@latest を使用してください。 zeabur を直接実行したり、ほかの方法でインストールしたりしないでください。npx が利用できない場合は、先に Node.js をインストールしてください。

CLI を使って、Zeabur のテンプレートやマーケットプレイスの事前構築済みサービスをデプロイします。CLI の自動化では、必ず非対話モード（-i=false）を使用してください。

まだプロジェクトがない場合は、デプロイする前に zeabur-project-create スキルを使ってプロジェクトを作成してください。

事前構築済みサービス（MongoDB、PostgreSQL、Redis など）のデプロイ

Zeabur テンプレートのマーケットプレイスで利用できる一般的なサービスの場合、カスタムテンプレート YAML ファイルは作成しないでください。テンプレートコードを検索し、-c を使って直接デプロイしてください。

# 1. Search for the template by keyword
npx zeabur@latest template search mongodb -i=false --json

# 2. Deploy by template code (from the "Code" field in search results)
npx zeabur@latest template deploy -i=false \
  -c <TEMPLATE_CODE> \
  --project-id <project-id>

例：MongoDB のデプロイ

# Search returns code "KXL04P" for MongoDB
npx zeabur@latest template search mongodb -i=false --json

# Deploy directly by code
npx zeabur@latest template deploy -i=false \
  -c KXL04P \
  --project-id abc123

応用：デプロイ前に取得してカスタマイズする

デプロイ前にテンプレート YAML を変更する必要がある場合（環境変数の調整、イメージタグの変更、サービスの追加など）は、まず template get --raw で取得して編集し、その後 -f を使ってデプロイしてください。

# 1. Fetch the raw YAML
npx zeabur@latest template get -c KXL04P --raw > template.yaml

# 2. Edit template.yaml as needed

# 3. Deploy the customized template
npx zeabur@latest template deploy -i=false \
  -f template.yaml \
  --project-id <project-id>

カスタムテンプレートのデプロイ

完全なカスタムテンプレートや複数サービスのテンプレートには、テンプレート YAML ファイルを使用してください。

npx zeabur@latest template deploy -i=false \
  -f template.yaml \
  --project-id <project-id> \
  --var KEY1=value1 \
  --var KEY2=value2

フラグ

フラグ	説明
-f, --file	テンプレートファイル（ローカルパスまたは URL）
-c, --code	テンプレートコード（マーケットプレイスのテンプレートを直接デプロイします。-f とは併用できません）
--project-id	デプロイ先のプロジェクト ID
--var	テンプレート変数（繰り返し指定できます。例：--var KEY=value）
--skip-validation	テンプレートの検証をスキップします
-i=false	非対話モード（必ず使用してください）

非対話モード

-i=false を使用する場合、必須のテンプレート変数はすべて --var フラグで指定する必要があります。

変数が不足している場合、CLI に役立つエラーメッセージが表示されます。

Error: missing required variables in non-interactive mode:
  --var PUBLIC_DOMAIN=<value>  (Enter your domain prefix)
  --var DB_NAME=<value>  (Database name)

例

変数を指定してデプロイする

npx zeabur@latest template deploy -i=false \
  -f https://example.com/template.yaml \
  --project-id abc123 \
  --var PUBLIC_DOMAIN=myapp \
  --var [email protected]

ローカルファイルをデプロイする

npx zeabur@latest template deploy -i=false \
  -f zeabur-template-myapp.yaml \
  --project-id abc123 \
  --var PUBLIC_DOMAIN=myapp

必須変数を確認する

テンプレート変数は、YAML の spec.variables セクションで定義されています。

spec:
  variables:
    - key: PUBLIC_DOMAIN
      type: DOMAIN
      name: Domain
      description: Enter your domain prefix
    - key: DB_NAME
      type: STRING
      name: Database Name
      description: Database name

テンプレート YAML ファイルの作成や編集には、zeabur-template スキルを使用してください。

既知の制限事項

カスタム PREBUILT テンプレート YAML：内部 DNS に登録されない場合があります

カスタムテンプレート YAML ファイル（-f template.yaml）でデプロイされた template: PREBUILT のサービスは、Zeabur の内部 DNS（*.zeabur.internal）に登録されない場合があります。そのため、同じプロジェクト内のほかのサービスからホスト名で接続できないことがあります。詳しくは zeabur/cli#204 を参照してください。

回避策：データベースサービス（PostgreSQL、MySQL、Redis）には、カスタム YAML ファイルの代わりにマーケットプレイスのテンプレートコード（-c <CODE>）を使用してください。マーケットプレイスのテンプレートは、内部 DNS に正しく登録されます。

# RECOMMENDED — deploy via marketplace code (has internal DNS)
npx zeabur@latest template search postgresql -i=false --json
npx zeabur@latest template deploy -i=false -c <CODE> --project-id <id>

# NOT RECOMMENDED — custom YAML may lack internal DNS
npx zeabur@latest template deploy -i=false -f my-pg.yaml --project-id <id>

カスタムテンプレート YAML のスキーマ：spec のネスト

テンプレート YAML では、spec.services[].source ではなく spec.services[].spec.source が必要です。

# CORRECT
spec:
  services:
    - name: my-service
      template: PREBUILT
      spec:                    # <-- required nesting
        source:
          image: postgres:17

# WRONG — will fail with "missing property 'spec'"
spec:
  services:
    - name: my-service
      template: PREBUILT
      source:                  # <-- missing spec wrapper
        image: postgres:17

よくある問題

問題	解決策
対話プロンプトが停止する	--project-id フラグと --var フラグを指定し、必ず -i=false を使用してください
変数不足のエラー	必須の --var フラグをすべて追加してください
${REF} を含む変数	リテラル値を使うか、デプロイ後にダッシュボードで設定してください
DOMAIN 型の検証	ドメインの利用可能性は自動的に確認されます
missing property 'spec'	source／ports／env を spec: の下に配置してください（二重にネストします）
ほかのサービスから DB に接続できない	データベースにはカスタム YAML（-f）ではなく、マーケットプレイスのコード（-c）を使用してください