northflank

Northflank

Northflank は、Northflank Cloud、ご自身のクラウド（BYOC）、またはご自身のクラスター（BYOK）上の Kubernetes でワークロードを構築、デプロイ、スケーリングするための開発者プラットフォームです。AWS、GCP、Azure、CoreWeave、オンプレミス環境にわたって、ビルド、デプロイ、リリース、自動スケーリング、災害復旧を処理します。主なプリミティブは、プロジェクト（Kubernetes 名前空間）、サービス（ステートレスワークロード）、アドオン（マネージドデータベース）、ジョブ（cron／手動実行）、シークレットグループ、ボリューム、テンプレート（IaC／GitOps）です。UI で利用できる機能はすべて、REST API、CLI、JS クライアントからも利用できます。

ベース API URL： https://api.northflank.com/v1/
認証： Authorization: Bearer <token>
レート制限： レスポンスのレート制限ヘッダーを使用してください。制限はアカウントとサーバーの設定によって異なります。

開始する前に

ユーザーが指定したインターフェースを使用し、既存の認証済みセットアップを再利用してください。MCP では、コーディングエージェント内でガイド付きワークフローを直接利用できます。プラットフォームの操作やローカル開発には CLI も適しています。インターフェースが指定されていない場合は、接続済みの MCP から始めると便利です。使用するインターフェースの前提条件を確認してください。

1. MCP： ガイド付きツールを使用して、エージェントからリソースをデプロイ、管理してください。新しいイメージ／Git アプリには deploy_app、ジョブには deploy_job を使用し、既存のリソースや高度な設定には詳細ツールを使用してください。接続の認証情報を再利用してください。
2. CLI： デプロイ、リソース管理、ローカルトンネル、exec、シェルのワークフローには、ユーザーの既存の northflank login セッションを使用してください。コマンドを使用する際は、該当するコマンドの --help を確認してください。
3. JS クライアントまたは REST： ユーザーが作成して実行し続けるコードを書く場合に使用してください。そのコードで必要な場合に限り、@northflank/js-client を確認してください。認証情報はユーザーの既存のセットアップから取得し、トークンを出力しないでください。
4. アカウントとプロジェクト： 既知のコンテキストを再利用してください。プロジェクト ID は my-project のようなスラッグです。MCP では、チームまたはワークロードのスコープが不明な場合に限り、get_auth_context を呼び出してください。自身のプロジェクトのワークロード認証情報には workload.projectId を使用し、すべてのプロジェクトを列挙しないでください。新しいプロジェクトが要求された場合は、デプロイワークフローに newProject を渡してください。

MCP が接続されていませんか？

クライアントごとのセットアップと認証については、エージェントを Northflank に接続する を参照してください。

ホスト型エンドポイントは https://mcp.northflank.com/mcp です。これは Authorization: Bearer <team API token> を使用する Streamable HTTP 方式です。チームのワークロード ID トークンもサポートされています。このセットアップでは MCP OAuth ログインは利用できません。

このスキルをインストールしても、MCP サーバーは設定されず、アカウントへのアクセス権も付与されません。ガイドに従って、ユーザーが指定したクライアントを設定できるよう支援してください。認証情報はクライアントのシークレットストレージまたはプロセス環境に保管し、チャットやコミット済みファイルには決して記載しないでください。ホスト型 MCP は CLI とは独立して設定できます。

接続後、チームまたはアクセススコープが不明な場合は、一度だけ get_auth_context を使用してください。ローテーションするワークロードトークンには、リクエスト前にマウントされたトークンを読み込むか、認証失敗後にトークンを更新するクライアントを使用してください。静的な環境変数の値ではトークンは更新されません。

MCP でデプロイする

1. デプロイに必要な情報だけを確認します。 ローカルリポジトリでは、リモート、ブランチ、HEAD、作業ツリーの状態を一度だけ確認します。関連する Dockerfile またはビルド設定と、リッスンするポートを確認します。すでに利用可能なチェックアウトをクローンしたり、アプリケーション全体をスキャンしたり、無関係なチェックを実行したりしないでください。Git デプロイではリモートの内容が使用されます。ローカルブランチをデプロイすると伝える前に、コミットされていない変更やプッシュされていない変更がないか確認してください。変更を黙って破棄したり、ユーザーの許可なくプッシュしたりしないでください。
2. コンテキストを再利用します。 既知の ID とデプロイの選択内容を保持します。まず MCP のインラインスキーマを使用します。操作が直接公開されていない場合は、search_tools で見つけて、execute_tool を通じて呼び出します。省略された制約が必要な場合に限り、get_tool_schema を要求します。返された next.tool の名前は、再検索せずに直接実行します。カタログツールがない古いサーバーでは、公開されているリソースツールを使用します。許可を得た後は、リポジトリの再確認やカタログの再取得をしないでください。
3. ツールのワークフローに従います。 新しいワークロードがサポートされている場合は、deploy_app、deploy_job、または create_database を使用します。その結果に従って、Git の許可、復旧、ステータス確認を行います。元の入力と、返されたリソース ID／セッション ID を保持します。ブラウザーが利用可能な場合は認可リンクを開き、利用できない場合はリンクを表示して待機します。ワークロード ID に必要な Git アクセスが不足している場合は、チームメンバーに付与してもらう必要があります。
4. 返されたフェーズ、次の手順、ポーリング間隔に従います。稼働中のソースリビジョンだけでは、そのコミットの特定の再ビルドがデプロイされた証拠にはなりません。アプリケーションが正常であると判断する前に、Web エンドポイントを確認します。一部の処理が失敗した場合は、既存のリソースから復旧します。作成や実行をむやみに繰り返さないでください。

接続中のサーバーが公開している場合、サービス、ジョブ、アドオンの障害には diagnose を使用します。これは、ヘルス状態、関連するインフラストラクチャイベント、デプロイリビジョン、ログ、メトリクス、BYOC ノードプールの設定を収集します。権限が不足している場合、得られる証拠は部分的になります。相関関係は手がかりとして扱い、原因が証明されたものと見なさないでください。定期的なポーリングには get_deployment_status または get_addon を使用します。

list_addon_types には、Northflank が管理するアドオンとチームのカスタムアドオンが含まれます。管理対象データベースについては、バージョン、ストレージサイズ、レプリカの選択肢を確認できます。BYOC クラスターのストレージクラスは検出しません。

破壊的な操作 — 必ず最初に確認する

重要： Northflank で破壊的な操作を実行する前に、必ず停止し、ユーザーに明示的に確認してください。以前の承認が別の操作やセッションにも引き継がれると想定せず、操作ごとに個別に確認してください。

破壊的な操作には、少なくとも次のものが含まれます。

• delete service / apiClient.delete.service — 元に戻せません。コンテナーの状態と、サービスに関連付けられた設定が失われます
• delete addon / apiClient.delete.addon — 特に注意：アドオンには永続データ（データベース、キュー、キャッシュ）が保存されています。削除すると元に戻せず、ユーザーが最近のバックアップを持っていない場合はすべてのデータが失われます。必ずアドオン名をユーザーに伝えて確認し、バックアップがあるか尋ねてください。明示的な「はい、<addon-id> を削除してください」という返答がない限り、実行してはいけません
• delete volume — 永続ディスクの内容を削除します
• delete project — プロジェクトを削除します。この MCP ツールでは、プロジェクトが空である必要があります。別のインターフェイスから再帰的に削除すると、そのリソースも削除されます
• delete secret — そのキーに依存する実行中のワークロードに支障をきたす可能性があります
• runtimeEnvironment、runtimeFiles、または ports を伴う patch secret / update secret / put secret / patch service — 送信したマップまたは配列全体が置き換えられるため、新しいキーを1つ送信すると、ほかのすべてのキーが削除されます。マップを安全に更新するの手順に従い、まず現在の値をバックアップしてください
• delete job — ジョブとその実行履歴を削除します
• delete template / リソースを破壊するテンプレートの実行、または作成対象とは異なるプロジェクトや環境に対する run template（テンプレートを参照）
• delete domain / delete dns-record
• delete cluster（BYOC/BYOK）— そのクラスター上のすべてのワークロードに影響します
• 永続状態を縮小するあらゆる patch / update（例：アドオンのレプリカ数を減らす操作。Northflank では拒否されますが、回避策として試してはいけません）
• ユーザーが開始していない実行中のジョブ、ビルド、またはパイプラインの強制キャンセル

確認のルール：

1. 削除する対象を正確な ID で示し、関連するデータや状態について説明します。
2. アドオンの場合はさらに、アドオンの種類とサイズを伝え、バックアップがなければデータを復元できないことを念押しします。
3. その特定のリソースに対する、明確な「はい」／「削除」／「進めてください」という返答を待ちます。「OK」、無応答、一般的な同意だけでは不十分です。
4. 1つの削除についてユーザーの承認を得ても、関連リソース（例：「サービスとそのアドオンとボリューム」）の削除に続けて進んではいけません。それぞれについて改めて確認してください。
5. ユーザーの目的に合う場合は、元に戻せる代替手段を優先します。たとえば、delete service の代わりに pause service を使う、削除前にアドオンのスナップショットやバックアップを作成する、などです。

CLI の基本

インストール、ログイン、コンテキストの選択

npm i -g @northflank/cli
northflank login
northflank context ls
northflank context use
northflank context use project

• northflank login はコンテキストを作成し、トークンを選択または作成するためのブラウザーを開くことがあります。
• northflank context use project|service|job を使って既定値を設定すると、以降のコマンドで ID の繰り返しを省略できます。
• northflank command-overview を使うと、コマンドツリーを確認できます。

リソースの確認

# Prompts for missing values interactively
northflank get service

# Explicit project and service
northflank get service --projectId <PROJECT_ID> --serviceId <SERVICE_ID>

CLI はデフォルトで対話型です。ID を省略すると、通常は入力を求められます。

実行中のコンテナー内でコマンドを実行する

# Interactive shell session
northflank exec service

# One-off command
northflank exec service --cmd "ls -lah /app"

# Run as a specific user
northflank exec service --user root --cmd id

ジョブにはサービスではなく northflank exec job を使います。

プライベートサービスまたはアドオンをローカルに転送する

sudo northflank forward service --projectId <PROJECT_ID> --serviceId <SERVICE_ID>
sudo northflank forward addon --projectId <PROJECT_ID> --addonId <ADDON_ID>

# If sudo path/context resolution causes issues
sudo --preserve-env=PATH,HOME bash -c 'northflank forward service --projectId <PROJECT_ID> --serviceId <SERVICE_ID>'

• ルートレス転送で問題なく、IP／ポートへのアクセスだけが必要な場合は、--skipHostnames を追加します。
• northflank forward all --projectId <PROJECT_ID> を使うと、プロジェクトのすべてのトンネルを一度に開けます。

JSON または YAML からリソースを作成または更新する

northflank create project --help
northflank create project --file ./project.yaml

--projectId や --serviceId などの CLI フラグで対象リソースを指定します。--input の JSON または --file の内容には、API リクエスト本文のみを含めます。対象 ID は本文の外に置き、SDK の parameters、data、options 構造で囲まないでください。

northflank patch service deployment --projectId my-project --serviceId my-api \
  --input '{"description":"Public API"}'

JS クライアントの基本

クライアントのセットアップ

import { ApiClient, ApiClientInMemoryContextProvider } from '@northflank/js-client';

const contextProvider = new ApiClientInMemoryContextProvider();
await contextProvider.addContext({
  name: 'default',
  token: process.env.NF_API_TOKEN,
});

// Pass true as second arg to throw on HTTP errors
const apiClient = new ApiClient(contextProvider, true);

すべてのメソッドは次のパターンに従います。

apiClient.{verb}.{resource}({ parameters, data, options })

• parameters — パスパラメーター（例：projectId、serviceId）
• data — リクエストボディ（作成／更新の場合）
• options — クエリパラメーター（フィルタリング、ページネーション用）

イメージからデプロイメントサービスを作成する

const result = await apiClient.create.service.deployment({
  parameters: { projectId: 'my-project' },
  data: {
    name: 'my-api',
    billing: { deploymentPlan: 'nf-compute-10' },
    deployment: {
      instances: 1,
      external: { imagePath: 'nginx:latest' },
      docker: { configType: 'default' },
    },
    ports: [{ name: 'http', internalPort: 80, public: true, protocol: 'HTTP' }],
  },
});
const serviceId = result.data.id; // 'my-api'

一般的なプランサイズ：nf-compute-10（0.1 vCPU／256MB）、nf-compute-50（0.5／1GB）、nf-compute-100-2（1／2GB）、nf-compute-200（2／4GB）。完全な表、GPU SKU、最新の一覧の照会方法については、Compute & GPU Plans を参照してください。

Git からビルドとデプロイを行う統合サービスを作成する

await apiClient.create.service.combined({
  parameters: { projectId: 'my-project' },
  data: {
    name: 'my-app',
    billing: { deploymentPlan: 'nf-compute-50' },
    vcsData: {
      projectUrl: 'https://github.com/org/repo',
      projectType: 'github',
      projectBranch: 'main',
    },
    buildSettings: {
      dockerfile: {
        buildEngine: 'buildkit',
        dockerFilePath: '/Dockerfile',
        dockerWorkDir: '/',
      },
    },
    deployment: { instances: 1 },
    ports: [{ name: 'app', internalPort: 3000, public: true, protocol: 'HTTP' }],
  },
});

サービスを取得／一覧表示する

// List all services in a project
const { data } = await apiClient.list.services({ parameters: { projectId: 'my-project' } });
const services = data.services;

// Get a single service
const svc = await apiClient.get.service({
  parameters: { projectId: 'my-project', serviceId: 'my-api' },
});
// Deployment rollout state: 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED'
// COMPLETED describes rollout completion, not application health or process exit.
console.log(svc.data.status.deployment?.status);
// Build state (only present for combined/build services):
// 'QUEUED' | 'PENDING' | 'STARTING' | 'BUILDING' | 'SUCCESS' | 'FAILURE' | ...
console.log(svc.data.status.build?.status);
// Pause is a separate boolean — not encoded in either status above
console.log(svc.data.servicePaused);

サービスでコマンドを実行する

// Short-lived command — returns stdout/stderr/exitCode
const result = await apiClient.exec.execServiceCommand(
  { projectId: 'my-project', serviceId: 'my-api' },
  { command: ['ls', '-lah', '/app'] },
);
console.log(result.stdOut);
console.log(result.commandResult.exitCode); // 0 = success

// Long-running / interactive session
const { exec } = apiClient;
const session = await exec.execServiceSession(
  { projectId: 'my-project', serviceId: 'my-api' },
  { shell: 'bash' },
);
session.stdErr.on('data', (chunk) => console.error(chunk));
session.stdIn.write('echo hello\n');
const result2 = await session.waitForCommandResult();

コマンド実行の詳細については、references/api/execute-command.md を参照してください。

サービスのログをストリーミングする

const logsClient = await apiClient.get.service.logTail({
  parameters: { projectId: 'my-project', serviceId: 'my-api' },
  options: { lineLimit: 20 },
});

logsClient.on('logs-received', (lines) => {
  lines.forEach((l) => console.log(`[${l.ts.toISOString()}] ${l.log}`));
});
logsClient.on('error', console.error);
await logsClient.start();
// Call await logsClient.stop() when done

サービスを一時停止／再開／再起動／削除する

const params = { parameters: { projectId: 'my-project', serviceId: 'my-api' } };

await apiClient.pause.service(params);    // stops billing, keeps config
await apiClient.resume.service(params);   // restarts from paused
await apiClient.restart.service(params);  // rolling restart (keeps running)
await apiClient.delete.service(params);   // permanent, irreversible

サービスを更新する（パッチ）

// Update image or instance count
await apiClient.patch.service.deployment({
  parameters: { projectId: 'my-project', serviceId: 'my-api' },
  data: {
    deployment: {
      instances: 3,
      external: { imagePath: 'myregistry/myapp:v2' },
    },
  },
});

アドオン（データベース）を作成する

const { data } = await apiClient.create.addon({
  parameters: { projectId: 'my-project' },
  data: {
    name: 'my-postgres',
    type: 'postgresql',    // postgresql | mongodb | mysql | redis | rabbitmq | minio | memcached
    version: '16',
    billing: {
      deploymentPlan: 'nf-compute-10',
      storage: 4096,       // MB
      replicas: 1,
    },
    tlsEnabled: true,
  },
});
const addonId = data.id; // 'my-postgres'

アドオンの認証情報を取得する

アプリケーションの接続には、アドオンリンクを設定したシークレットグループを優先してください。認証情報の値を読み取るのは、タスクで必要な場合に限ってください。ログやチャットに含めないでください。

const creds = await apiClient.get.addon.credentials({
  parameters: { projectId: 'my-project', addonId: 'my-postgres' },
});
// creds.data.username, creds.data.password, creds.data.connectionString, etc.
// Pass required credentials directly to their destination. Do not log their values.

シークレットグループを管理する

シークレットグループは、アドオンの接続文字列をサービスの環境変数にリンクしたり、任意のキーと値のシークレットを保持したりします。

// Create a secret group with a static env var and a linked addon credential
await apiClient.create.secret({
  parameters: { projectId: 'my-project' },
  data: {
    name: 'app-secrets',
    type: 'secret',              // 'secret' | 'config'
    secretType: 'environment',   // 'environment' | 'arguments' | 'environment-arguments'
    priority: 10,
    secrets: {
      variables: {
        NODE_ENV: 'production',
        API_KEY: 'supersecret',
      },
      // files: { '/etc/app.conf': { data: '<base64>' } },  // file contents must be base64
    },
    addonDependencies: [
      {
        addonId: 'my-postgres',
        keys: [
          { keyName: 'POSTGRES_URI', aliases: ['DATABASE_URL'] },
        ],
      },
    ],
    restrictions: {
      restricted: true,
      nfObjects: [{ id: 'my-api', type: 'service' }],
    },
  },
});

// List secrets in project
const { data } = await apiClient.list.secrets({ parameters: { projectId: 'my-project' } });

// Requires readValues permission. Read only values owned by this group.
const current = await apiClient.get.secret({
  parameters: { projectId: 'my-project', secretId: 'app-secrets' },
  options: { show: 'this' },
});
const variables = current.data.secrets.variables;
if (
  !variables || typeof variables !== 'object' || Array.isArray(variables) ||
  Object.values(variables).some(value =>
    typeof value !== 'string' || value === '[REDACTED]' || /^\*+$/.test(value)
  )
) {
  throw new Error('Cannot update secrets without a complete, unredacted variable map.');
}
await apiClient.patch.secret({
  parameters: { projectId: 'my-project', secretId: 'app-secrets' },
  data: {
    secrets: {
      variables: { ...variables, FEATURE_FLAG: 'true' },
    },
  },
});

マップを安全に更新する（シークレットグループとサービスの環境変数）

patch はマップ内の値をマージしません。 secrets.variables、secrets.files、サービスの runtimeEnvironment／runtimeFiles、または ports 配列を送信すると、その値全体が置き換えられます。省略したトップレベルのフィールドは変更されません。

リクエスト	A、B、C を持つシークレットグループへの影響
{ description: 'x' } を指定した patch／update	説明だけが変更されます
{ secrets: { variables: { D: '4' } } } を指定した patch／update	変数は { D } になります。A、B、C は削除されます
{ data: { D: '4' } } を指定した patch／update	不明なボディキーは無視されるため、何も変更されず、呼び出しは成功を返します
put secret（ボディ内の name でアップサート）	patch と同様ですが、省略した description と restrictions はデフォルト値にリセットされます

1. 1つのキーを追加または変更するには、show: 'this' と readValues 権限を使ってグループ自身の値を読み取ります。マスクされていない完全なマップに変更をマージして送り返してください。継承されたアドオンの値をグループにコピーしないでください。キー単位のパッチや、null による削除には対応していません。
2. シークレットまたは環境変数を一括で書き換える前に、現在のキー名を保存してください（ユーザーが許可する場合は値も保存します）。これにより、誤りを元に戻せます。失われたシークレットは Northflank から復元できません。
3. 書き込みのたびにグループを再度読み取り、シークレットをログに記録せずに、キーの集合と意図した値を確認してください。キー名だけでは、値が上書きされたことを検出できません。スペルミスや配置間違いのフィールドは黙って無視されるため、200 応答が変更の適用を証明するわけではありません。
4. 同じことが patch service deployment|combined|build にも当てはまります。runtimeEnvironment、runtimeFiles、ports は全体が置き換えられますが、deployment などのネストされたオブジェクトはフィールド単位でマージされます。POST /services/{id}/ports エンドポイントもリスト全体を置き換えます。
5. CLI の get service 出力には環境変数マップが含まれない場合があります。グループには get secret を使い、サービスレベルの runtimeEnvironment には REST または JS クライアントの get.service レスポンスを使ってください。
6. 共有認証情報には、サービスごとの runtimeEnvironment よりシークレットグループを優先してください。そうすれば、1つのサービスの更新によって共有認証情報が上書きされることはありません。

readValues 権限がない場合、API はシークレット値の代わりにアスタリスクを返します。MCP もシークレットマップをマスクします。これらのプレースホルダーを絶対に書き戻さないでください。API はそれらをリテラル値として保存します。読み取り結果がマスクされているか不完全な場合は、マージを中止してください。権限のあるユーザーによるマスクされていない読み取り、またはユーザーの信頼できるシークレットソースにある完全なマップを使用してください。同じ制限は、シークレットファイルとサービスの環境変数マップにも適用されます。

ページネーション

一覧エンドポイントはデフォルトで 50 件を返します。次の2つのオプションがあります。

// Fetch all pages automatically (multiple API calls)
const all = await apiClient.list.services.all({ parameters: { projectId: 'my-project' } });

// Manual next-page
const page1 = await apiClient.list.services({ parameters: { projectId: 'my-project' } });
if (page1.pagination?.hasNextPage) {
  const page2 = await page1.pagination.getNextPage();
}

エラー処理

// Option 1: check result.error (client does NOT throw by default)
const result = await apiClient.get.service({ parameters: { projectId, serviceId } });
if (result.error) {
  console.error(result.error.status, result.error.message);
}

// Option 2: init client with throwOnError = true
const apiClient = new ApiClient(contextProvider, true);
try {
  await apiClient.get.service({ parameters: { projectId, serviceId } });
} catch (err) {
  console.error(err);
}

レート制限ヘッダー

const { rawResponse } = await apiClient.get.service({ parameters: { projectId, serviceId } });
const remaining = rawResponse.headers.get('x-ratelimit-remaining');
const reset = rawResponse.headers.get('x-ratelimit-reset'); // seconds

コンピュートと GPU のプラン

すべてのコンピュートプラン、GPU SKU、料金、リージョンごとの GPU 提供状況を網羅した最新の表は、scripts/generate_references.js により references/plans.md に自動生成されます。Northflank が新しい SKU や料金変更を公開した後に更新するには、--plans-only --force を付けて再実行してください。基盤となるエンドポイントは公開されており、認証は不要です。

curl -s https://api.northflank.com/v1/plans   | jq '.data.plans[]   | {id, cpu: .cpuResource, ramMB: .ramResource, hr: .amountPerHour}'
curl -s https://api.northflank.com/v1/regions | jq '.data.regions[] | {id, gpus: (.gpuDevices // [] | map(.id))}'

JS クライアント／CLI での同等の操作：apiClient.list.plans({}) / apiClient.list.regions({}) および northflank list plans / northflank list regions。

コンピュートプランのスラッグ

形式：nf-compute-<cpu*100>-<ram_gb>（新しい明示形式）または nf-compute-<cpu*100>（従来形式、RAM は暗黙的）。一般的な選択肢：

• nf-compute-10 — 0.1 vCPU / 256 MB（約 $2.70/月）— サイドカー、軽量ワーカー
• nf-compute-50 — 0.5 vCPU / 1 GB（約 $12/月）— 小規模な API、cron ジョブ
• nf-compute-200 — 2 vCPU / 4 GB（約 $48/月）— 一般的な本番サービス
• nf-compute-400-16 — 4 vCPU / 16 GB（約 $144/月）— buildPlan としても有効

buildPlan で受け付けるのは 4 以上の vCPU を備えたプランのみです。省略した場合は nf-compute-400-16 がデフォルトになります。全 20 SKU については、references/plans.md を参照してください。

GPU プランのスラッグ

形式：nf-gpu-<gpuType>-<count>g。プラン ID ではアンダースコアをハイフンに置き換えます。deployment.gpu.configuration.gpuType には元の GPU タイプを指定してください。末尾の g は単位ではなく、文字そのものです。このプランには GPU に対応する CPU／RAM が含まれます。nf-compute-* プランと別の GPU を組み合わせることはありません。使用例：

data: {
  billing: { deploymentPlan: 'nf-gpu-a100-80-1g' },  // 1× A100 80GB
  deployment: {
    gpu: {
      enabled: true,
      configuration: { gpuType: 'a100-80', gpuCount: 1, timesliced: false },
    },
    storage: { shmSize: 32768 },
    // ...
  },
}

• gpuType はモデル ID です（小文字で、nvidia- のプレフィックスなし）。現在は l4-24、a100-40、a100-80、h100-80、h200-141、b200-180、rtx_pro_6000-96 があります。
• gpuCount には、モデルの countOptions に含まれる値を指定する必要があります（通常は 1, 2, 4, 8。H200 と B200 は 8 のみ）。無効な値は拒否されます。
• GPU の設定は deployment.gpu.configuration の下に指定してください。deployment.gpu.enabled: true も含めてください。billing の下に配置しても、GPU の検証は有効になりません。
• 利用可能な数はリージョンによって異なります。全リージョンの数をまとめて使うのではなく、対象リージョンの gpuDevices[].countOptions を確認してください。
• H100 の 1 基／8 基プランは nf-gpu-h100-80-1g / nf-gpu-h100-80-8g です。RTX PRO 6000 の 1 基／8 基プランは nf-gpu-rtx-pro-6000-96-1g / nf-gpu-rtx-pro-6000-96-8g です。us-central はこれらの構成に対応しています。
• 管理対象の GPU ワークロードでは、一時ストレージの指定は任意です。API は GPU のタイプと数に基づいて deployment.storage.ephemeralStorage.storageSize を設定し、指定値を上書きします。共有メモリは別の設定で、deployment.storage.shmSize の指定は任意です。管理対象 GPU では、デフォルトでシステム RAM に GPU 数の gpuCount を掛けた値が設定されます。これより小さい明示値はそのまま保持され、大きい値は上限値に制限されます。CPU および BYOC のワークロードでは、デフォルトは 64 MiB のままです。この例では 32 GiB を明示的に指定しています。割り当てと古い API のエラーについては、references/gpu-storage.md を参照してください。
• GPU の料金は、GPU ごとに 1 時間単位で、プランに含まれるコンピュート料金に加算されます。料金とリージョンごとの提供状況については、references/plans.md を参照してください。

BYOC クラスターでは、GPU ノードタイプはクラウドプロバイダーが提供します。apiClient.list.cloudProviders.nodeTypes({ options: { hasGpu: true } }) で確認し、カスタムリソースプランを定義してください（references/guides/bring-your-own-cloud.md#create-custom-resource-plans を参照）。タイムスライシングは BYOC でサポートされていますが、マネージドクラウドではサポートされていません。

Northflank が公開している GPU ベースイメージ（PyTorch、CUDA、Jupyter がインストール済み）を使う場合は、pytorch/pytorch:* からビルドするのではなく、europe-docker.pkg.dev/northflank/public/... から取得してください。

よく使われるパターン

デプロイの進行状況を追跡し、アプリケーションのヘルスを確認する

MCP を使用する場合は、get_deployment_status の次のアクションとポーリング間隔に従います。CLI または SDK を使用する場合は、期限を設定してロールアウトの状態をポーリングします。失敗または期限切れになったら停止し、確認できた状態を報告します。ポーリングのために作成処理を繰り返さないでください。

COMPLETED はロールアウトの完了を示しますが、アプリケーションのヘルスを証明するものではありません。Web アプリケーションの場合は、成功を報告する前に、エンドポイントが期待どおりの応答を返すことを確認してください。それ以外のワークロードでは、適切なアプリケーションレベルのチェックを使用してください。

自動スケーリング設定（作成／パッチデータ内）

data: {
  deployment: { instances: 1 },
  autoscaling: {
    horizontal: {
      enabled: true,
      minReplicas: 1,
      maxReplicas: 10,
      cpu: { enabled: true, thresholdPercentage: 70 },
      rps: { enabled: true, thresholdValue: 500 },
    },
  },
}

テンプレート

テンプレートは Northflank のインフラストラクチャ・アズ・コードの単位であり、ノード（プロジェクト、サービス、アドオン、ジョブ、シークレットグループ、パイプライン、アクション）の仕様です。**テンプレートを実行すると、実際のリソースに適用されます。**ドライランではなく、プロジェクトのコピーでもありません。

種類	スコープ	用途
チームテンプレート	チーム全体。プロジェクト、クラスター、サービス、データベース、パイプラインを作成できます	スタック全体のプロビジョニングまたは複製
リリースフロー	1 つのパイプラインステージ	バックアップ、ビルド、移行、プロモーションによるリリースのデプロイ
プレビュー環境（プレビューブループリント）	1 つのパイプライン	ブランチまたはプルリクエストごとの一時的な環境。クローズ時に削除

プレビューテンプレートはプレビュー環境を作成します。本番環境へのデプロイには使用しないでください。対象のテンプレートまたはターゲットが不明確な場合は、ユーザーに確認してください。

各実行でリソースノードごとに行われる処理（updateMode、デフォルトは put）：

updateMode	動作
put（デフォルト）	リソースが存在しない場合は作成し、存在する場合は仕様に従って設定を置き換えます。省略された設定可能フィールドはリセットまたはクリアされることがあります
patch	指定されたフィールドのみを更新します。リソースが存在しない場合は失敗します。配列や一部のオブジェクトでは、値全体が置き換えられる場合もあります（マップを安全に更新するを参照）
create	リソースが存在しない場合は作成し、存在する場合はスキップして既存のリソースを変更しません

• ノードの name は対象リソースを識別します。名前を変更すると、既存のリソースの隣に別のリソースが作成されます。ノードを削除しても、そのリソースは削除されません。
• プロジェクトのコンテキストはノードまたは親ワークフローから取得され、1 つのテンプレートが複数のプロジェクトに影響する場合があります。最初のノードだけでなく、すべてのノードのコンテキストを確認してください。
• 自動実行が有効な場合、UI、API、または GitOps を通じたテンプレートの変更によって実行が開始されます。GitOps をリンクしただけでは、自動実行は有効になりません。
• Northflank のドライランで確認されるのは、実行前の参照、引数、関数の解決のみです。置き換えられるリソースのプレビューは行われません。

run template を実行する前に、必ず次の手順を行います。

1. テンプレートを読み込みます：northflank get template --template <id>（または apiClient.get.template）。各ノードの種類、updateMode、プロジェクトのコンテキスト、name を一覧にします。
2. ノード名を対象プロジェクトにすでに存在するリソースと照合します。put の対象となる一致したリソースはすべて上書きされます。
3. ユーザーにテンプレート ID、種類、対象プロジェクト、作成されるリソースと置き換えられるリソースを伝え、その実行に明示的に紐づく承認を待ちます（上記の確認ルールを参照）。
4. テンプレートを別のプロジェクトを指すように編集するのではなく、テンプレートがサポートしている場合は arguments を通じてターゲットを渡します。
5. 実行後、実行ステータスを確認し、変更されたリソースを読み戻します。

await apiClient.run.template({
  parameters: { templateId: 'my-template' },
  data: {
    arguments: {
      REGION: 'europe-west',
      IMAGE: 'myapp:latest',
    },
  },
});

cron ジョブを作成する

await apiClient.create.job({
  parameters: { projectId: 'my-project' },
  data: {
    name: 'db-migrate',
    billing: { deploymentPlan: 'nf-compute-10' },
    deployment: {
      external: { imagePath: 'myapp:latest' },
      docker: { configType: 'default' },
    },
    settings: {
      cron: { schedule: '0 2 * * *' },  // present = cron job
      concurrencyPolicy: 'Forbid',
    },
    runtimeEnvironment: { MIGRATE: 'true' },
  },
});

// Run it manually now
await apiClient.start.job.run({ parameters: { projectId: 'my-project', jobId: 'db-migrate' } });

注意点

1. ID はスラッグ化された名前です — "My App" は my-api（スラッグ）になります。API 呼び出しでは表示名ではなく ID を使用してください。
2. アドオンのストレージとレプリカは、作成後に増やすことはできますが、減らすことはできません。
3. アドオンへのリンクを含むシークレットグループは、アドオンの認証情報がローテーションまたは変更されると、接続文字列を自動的に更新します。
4. ポート名は最大 8 文字で、英字で始まる必要があります。
5. レート制限は変動します — レスポンスのレート制限ヘッダーを確認し、それに応じて操作のペースを調整してください。
6. put.* メソッドはアップサートのセマンティクスを使用します — 存在しない場合は作成し、存在する場合は更新します。冪等性のある IaC に便利です。
7. 一時停止 ≠ 削除 — 一時停止したサービスはコンピューティングの課金が停止しますが、設定とボリュームは保持されます。
8. northflank exec --cmd "..." は TTY がないと出力を破棄します — CI、エージェントのハーネス、または bash -c でラップされた環境では、stdout/stderr が黙って破棄されます。出力を取得するには、（macOS/BSD）では script -q /dev/null northflank exec ...、（Linux）では script -qfc 'northflank exec ...' /dev/null でラップしてください。
9. サービスの status === "COMPLETED" は、プロセスの終了ではなくロールアウトの完了を表します。 アプリケーションが正常であることを証明するものではありません。成功を報告する前に、アプリケーションが期待どおりに応答することを確認してください。

リファレンス早見表

〜したい場合	こちらを確認
事前構築済みイメージからサービスをデプロイする	MCP deploy_app；apiClient.create.service.deployment / northflank create service deployment
Git リポジトリからサービスをビルドしてデプロイする	MCP deploy_app；apiClient.create.service.combined / northflank create service combined；references/guides/build.md
コンテナで単発コマンドまたはシェルセッションを実行する	apiClient.exec.execServiceCommand / northflank exec service；references/api/execute-command.md
サービス、ジョブ、アドオンのログを追跡または取得する	apiClient.get.service.logTail / northflank get service logs -f；references/api/log-tailing.md
プライベートサービスまたはアドオンのポートを localhost に転送する	northflank forward service；references/api/forwarding.md
マネージドデータベース（Postgres、Redis、Mongo、MySQL…）をプロビジョニングする	MCP create_database；apiClient.create.addon / northflank create addon；references/guides/databases-and-persistence.md
シークレットグループを介してデータベースの認証情報をサービスに連携する	addonDependencies を指定して apiClient.create.secret を使用 / northflank create secret；references/api/project/secrets/_index.md
cron ジョブまたは手動ジョブを作成する	MCP deploy_job；settings.cron を指定して apiClient.create.job を使用 / `northflank create job cron
オートスケーリング、レプリカ、またはリソースサイズを設定する	autoscaling.horizontal フィールド；references/guides/scale.md
コンピューティングまたは GPU プラン（サイズ、料金、リージョン）を選ぶ	references/plans.md — /v1/plans および /v1/regions から自動生成；スラッグのパターンは コンピューティング＆GPU プラン を参照
CI/CD（パイプライン、リリースフロー、プレビュー環境）を設定する	references/guides/release.md
Infrastructure as Code（テンプレート、GitOps、OpenTofu）を定義する	apiClient.create.template / northflank create template；references/guides/infrastructure-as-code.md
TLS、CDN、またはパスルーティングを使用してカスタムドメインを追加する	references/guides/domains.md；references/api/team/domains/_index.md
永続ストレージ／ボリュームをサービスにアタッチする	apiClient.create.volume / northflank create volume；references/api/project/volumes/_index.md
実行中のコンテナにファイルをアップロードまたはダウンロードする	northflank upload service file / download service file；references/api/copy-files.md
ポート、ネットワークポリシー、エグレス IP、Tailscale を設定する	references/guides/network.md
ログシンク、メトリクス、アラート、ヘルスチェックを設定する	references/guides/observe.md
GPU ワークロードを実行する	references/guides/gpu-workloads.md
AI サンドボックス／マイクロ VM を起動する	サンドボックスはサービスです — MCP deploy_app、または apiClient.create.service.deployment / northflank create service deployment を使用してください（sandbox 動詞はありません）；references/guides/sandboxes.md
独自のクラスター（AWS/GCP/Azure/CoreWeave 上の BYOC/BYOK）にデプロイする	references/guides/bring-your-own-cloud.md
チーム、RBAC、SSO/MFA、API トークンを管理する	references/guides/secure.md、references/guides/collaborate.md
リソースを一時停止、再開、再起動、または削除する	apiClient.{pause,resume,restart,delete}.service / northflank {pause,resume,restart,delete} service — 削除を実行する前に、必ず 破壊的操作 を再確認してください

リファレンスファイル

プラットフォームリファレンス

• references/api-overview.md — REST API のベース URL、認証、ページネーション、エンドポイント一覧
• references/cli.md — CLI のインストール、コンテキスト、一般的なコマンド、ファイル転送
• references/js-client.md — JS クライアントのクイックスタートと使用方法の案内
• references/plans.md — 自動生成されるコンピューティング＆GPU プランとリージョンの利用可否（/v1/plans および /v1/regions からの最新情報）

API エンドポイントのリファレンス

• references/api/_index.md — すべてのエンドポイントのマスターインデックス
• references/api/use-the-cli.md — CLI のインストール、ログイン、コンテキスト、コマンドモデル
• references/api/use-the-api.md — REST API の使用ガイド
• references/api/use-the-javascript-client.md — JS クライアントの使用ガイド
• references/api/project/services/_index.md — サービスエンドポイント
• references/api/project/addons/_index.md — アドオンエンドポイント
• references/api/project/jobs/_index.md — ジョブエンドポイント
• references/api/project/secrets/_index.md — プロジェクトのシークレットエンドポイント
• references/api/project/volumes/_index.md — ボリュームエンドポイント
• references/api/team/templates/_index.md — テンプレートエンドポイント
• references/api/team/domains/_index.md — ドメインエンドポイント
• references/api/team/projects/_index.md — プロジェクトエンドポイント
• references/api/execute-command.md — exec コマンドの詳細
• references/api/log-tailing.md — ログの追跡に関する詳細
• references/api/forwarding.md — ポートフォワーディングの詳細
• references/api/copy-files.md — ファイルのアップロード／ダウンロードに関する詳細
• references/api/retrieve-metrics.md — メトリクスの取得
• references/api/introduction.md — API／CLI／JS クライアントの概要

ハウツーガイド

• references/guides/_index.md — すべてのガイドトピックのインデックス
• references/guides/getting-started.md — 概要、最初のプロジェクト、ビルドとデプロイ、アーキテクチャパターン
• references/guides/run.md — サービス、ジョブ、デプロイソース、リージョン、SSH、コンテナアクセス
• references/guides/build.md — Dockerfile、ビルドパック、Git 統合、ビルド引数
• references/guides/scale.md — インスタンス、CPU／メモリ、ストレージ、自動スケーリング
• references/guides/release.md — CI/CD、パイプライン、リリースフロー、プレビュー環境、環境
• references/guides/databases-and-persistence.md — アドオン、ボリューム、バックアップ、HA、移行
• references/guides/secure.md — シークレット、RBAC、SSO/MFA、API アクセス、シークレットファイル
• references/guides/network.md — ポート、セキュリティポリシー、ロードバランサー、エグレス IP、Tailscale
• references/guides/observe.md — ログ、メトリクス、ヘルスチェック、アラート、ログシンク、通知
• references/guides/infrastructure-as-code.md — テンプレート、GitOps、テンプレートノード、GitHub Actions、OpenTofu
• references/guides/domains.md — ドメインの追加／検証、TLS、CDN、パスルーティング、レジストラーのガイド
• references/guides/bring-your-own-cloud.md — AWS、GCP、Azure、Civo、CoreWeave、OCI 向けの BYOC/BYOK セットアップ
• references/guides/collaborate.md — チーム、組織、RBAC、マルチテナンシーモデル
• references/guides/gpu-workloads.md — GPU のデプロイと最適化
• references/guides/sandboxes.md — AI サンドボックス、マイクロ VM、GVisor、ウォームアップ済みプール
• references/guides/production-workloads.md — 本番環境への対応、運用、リリース
• references/guides/billing.md — 支払い、請求書、クレジット、料金
• references/guides/migrate-from-heroku.md — Heroku からの移行手順
• references/guides/overview.md — Northflank の概要