zeabur-server-ssh

Zeabur サーバーの SSH + kubectl

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

ユーザー専用サーバーでコマンドを実行し、ZeaburOS を実行するサーバー上の Kubernetes ワークロードを kubectl でデバッグします。

kubectl を使用する前に、サーバーの種類を確認してください

• ZeaburOS サーバーでは、kubectl がプリインストールされた k3s が動作しています。このスキルの内容がすべて適用されます。
• Ubuntu — ZeaburOS を実行していないレンタルサーバーです。k3s も kubectl もありません。以下の kubectl コマンドはすべて command not found で失敗します。通常のシェルコマンドには server exec を引き続き使用できます。

レンタルで提供されるのは Ubuntu のみなので、kubectl が存在すると決めつけないでください。

CLI からマシンの種類を確認してください。確認のために SSH 接続してはいけません。

npx zeabur@latest server get <server-id> -i=false --json | jq -r .os

ZeaburOS または Ubuntu が表示されます。server list を使うと、すべてのサーバーについて同じ情報を一度に確認できます。OS 列と os フィールドに表示されます。

CLI 0.21.0 以降が必要です。os が null の場合、CLI が古いということです。npx zeabur@latest で最新バージョンを取得するか、API にフォールバックしてください（$ZAPI_CFG を定義するトークンの設定方法については、zeabur-server-rent スキルを参照してください）。

curl -sS --max-time 30 -K "$ZAPI_CFG" https://api.zeabur.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"query($id: ObjectID!) { server(_id: $id) { hasK3s } }","variables":{"id":"<server-id>"}}'

hasK3s は 3 つの状態を持ち、3 つ目の状態には注意が必要です。true は ZeaburOS、false は Ubuntu のみ、null はこのフィールドが追加される前のサーバーを表し、その場合は ZeaburOS が動作しています。したがって、判定には hasK3s === false を使用し、!hasK3s は使用しないでください。後者では古いサーバーがすべて含まれ、通常の VPS と誤って判定されます。

先に確認せずに kubectl コマンドを実行し、command not found で失敗した場合は、それも同じサインです。コマンドを再試行せず、サーバーは通常の Ubuntu VPS だとユーザーに伝えてください。kubectl が追加されるのは ZeaburOS をインストールした場合です。方法については zeabur-server-rent スキルを参照してください。

例外が 1 つあります。 上記の内容はすべて、マシンの種類に関するものです。特定のバイナリが存在するかどうかをユーザーから尋ねられた場合は、マシンを確認してください。ZeaburOS サーバーには常に kubectl がありますが、通常の Ubuntu VPS では所有者がインストールしている可能性があり、OS フィールドからは判別できません。

コマンドの実行：server exec（推奨）

サーバー上でコマンドを一度に実行します。CLI が認証情報を取得して内部で接続するため、パスワードを扱う必要はありません。特殊文字を含むパスワードもそのまま使用でき、ssh2 や sshpass も不要です。

npx zeabur@latest server exec --id <server-id> -- <command>

例：

# Single command
npx zeabur@latest server exec --id <server-id> -- sudo kubectl get pods -A -o wide

# Compound command — quote it as ONE argument so && / | stay intact
npx zeabur@latest server exec --id <server-id> -- 'echo "=== PODS ===" && sudo kubectl get pods -A && echo "=== EVENTS ===" && sudo kubectl get events -A --sort-by=.lastTimestamp | tail -20'

注意事項：

• -- の後ろはすべてリモートコマンドで、ssh host <command> のように結合されます。複合コマンド（&&、|、リダイレクトを含むもの）は、単一の引数として引用符で囲んでください。
• stdout/stderr はリアルタイムでストリームされ、リモートコマンドの 終了コードが引き継がれます（パイプラインでは 最後のステージのステータスのみが報告されます。… | tail は上流の失敗を隠すため、パイプをまたいで終了コードを判断しないでください）。
• サーバー ID がわからない場合は、先にサーバーを一覧表示してください。

  npx zeabur@latest server list -i=false
  

  （または zeabur-server-list スキルを使用してください）。

よく使う kubectl コマンド

ZeaburOS サーバーのみが対象です。 通常の Ubuntu VPS では、これらのコマンドはすべて kubectl: command not found で失敗します。前のセクションを参照してください。

これらのコマンドを server exec のコマンドとして指定します。必ず sudo kubectl を使用してください — SSH ユーザーは k3s kubeconfig に直接アクセスできない場合があります。パイプ（|）または && を含むコマンドは、単一の引数として引用符で囲む必要があります。そうしないと、ローカルシェルが分割して一部をローカルで実行します。例： server exec --id <id> -- 'sudo kubectl top pods -A --sort-by=memory | head -20'。

タスク	コマンド
すべての Pod を一覧表示	sudo kubectl get pods -A -o wide
問題のある Pod のみ表示	sudo kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded
Pod のログ	sudo kubectl logs <pod-name> -n <namespace> --tail=100
コンテナ内でコマンドを実行	sudo kubectl exec <pod-name> -n <namespace> -- <command>
ノードのリソース	sudo kubectl top nodes
Pod のリソース	sudo kubectl top pods -A --sort-by=memory | head -20
Pod の詳細を表示	sudo kubectl describe pod <pod-name> -n <namespace>
最近のイベント	sudo kubectl get events -A --sort-by=.lastTimestamp | tail -30
デプロイメントを再起動	sudo kubectl rollout restart deployment/<name> -n <namespace>

フォールバック：手動 SSH（server exec が利用できない場合のみ）

server exec が利用できない場合（古い CLI など）に限り使用してください。それ以外の場合は、 上記の server exec を優先してください。この方法では、特殊文字を含むパスワードで問題が発生しやすくなります。

手順 1：SSH 認証情報を取得する

npx zeabur@latest server ssh-info --id <server-id> -i=false

出力は JSON です：{"ip":"1.2.3.4","port":22,"username":"root","password":"xxx"}

手順 2：接続する

デフォルトでは Node.js の ssh2 メソッドを使用してください。sshpass は、利用可能であることがすでに分かっている場合にのみ使用してください。確認のために which sshpass を実行しないでください — sshpass はインストールされていないため、手順が無駄になります。

# sshpass (only if already known to be available)
sshpass -p '<password>' ssh -o StrictHostKeyChecking=no -p <port> <username>@<ip> sudo kubectl get pods -A

# Node.js ssh2 (the Zeabur agent sandbox has it pre-installed)
NODE_PATH=$([ -d /root/.global/node_modules ] && echo /root/.global/node_modules || echo /home/vercel-sandbox/.global/node_modules) node -e "
const {Client} = require('ssh2');
const c = new Client();
c.on('ready', () => {
  c.exec('<command>', (err, stream) => {
    if (err) { console.error(err); process.exit(1); }
    let out = '', errOut = '';
    stream.on('data', d => out += d);
    stream.stderr.on('data', d => errOut += d);
    stream.on('close', code => {
      if (out) console.log(out);
      if (errOut) console.error(errOut);
      c.end();
      process.exit(code);
    });
  });
}).connect({host:'<ip>', port:<port>, username:'<username>', password:'<password>'});
"

ヒント

• コマンドをまとめる：関連する確認を && でつなぎ、単一の server exec 呼び出しでまとめて実行すると、往復回数を減らせます。
• -o wide を使用する：Pod の一覧にノード名と IP が追加されるため、スケジューリングの問題を調べるのに役立ちます。
• 名前空間に注意する：Zeabur のサービスは通常、デフォルト以外の名前空間で実行されます。まず -A（すべての名前空間）で適切な名前空間を見つけ、その後 -n <namespace> で範囲を絞ります。
• まずプロジェクトのドキュメントを読む：修正を試して失敗した場合は、むやみにメトリクスを確認するのではなく、コンテナ内でコマンドを実行して README／設定を確認してください：sudo kubectl exec <pod> -n <ns> -- cat /app/README.md
• サーバー ID を見つけるには、zeabur-server-list スキルを使用してください。サーバーレベルのアクセスが不要な、より簡単なコンテナコマンドには、zeabur-service-exec スキルを使用してください。