コンテンツにスキップ
machbase-neo
JSH
サービスマネージャー

サービスマネージャー

servicectlコマンドは、サービスコントローラーを介して、長時間実行するJSHサービスを管理します。 サービス設定の読み込み、インストールと削除、開始と停止、現在の実行状態の取得を行えます。

概要

servicectlコマンドは、実行中のサービスコントローラーとJSON-RPCで通信します。 サービスを直接起動せず、以下の管理リクエストをコントローラーに渡します。

  • 設定ファイルの読み込み
  • 設定変更の適用
  • JSONファイルまたはインラインオプションによるサービスのインストール
  • サービスの開始と停止
  • サービス状態の取得
  • サービス登録の削除

コントローラーのアドレス

このコマンドには、サービスコントローラーのエンドポイントが必要です。 --controllerオプションで直接指定するか、SERVICE_CONTROLLER環境変数で渡せます。

servicectlをmachbase-neoランタイムから実行すると、ランタイムがSERVICE_CONTROLLERを自動的に 設定します。通常のJSHサービス管理では、--controllerを毎回明示する必要はないため、 以下の例では、読みやすさのために省略します。

対応するコントローラーアドレスの形式は以下のとおりです。

  • host:port
  • tcp://host:port
  • unix://path
構文
servicectl [--controller=<addr>] <command> [args...]
共通オプション
  • -c, --controller <endpoint> TCPまたはUnixソケット形式のコントローラーアドレス
  • -t, --timeout <msec> RPCのタイムアウト（ミリ秒）。既定値5000
  • -h, --help ヘルプを表示
使用例
/work > servicectl status

コマンド

servicectlコマンドは、以下のサブコマンドに対応しています。

  • read
  • update
  • reload
  • install <config.json>
  • install --name <name> --executable <path> [--arg <arg> ...] [--working-dir <dir>] [--enable] [--env KEY=VALUE ...]
  • uninstall <service_name>
  • status [service_name]
  • start <service_name>
  • stop <service_name>
  • details get <service_name> [key] [--format box|json]
  • details set <service_name> <key> <value> [--detail-type <string|number|boolean|bool|object|json>]
  • details delete <service_name> <key>

サービス設定の形式

サービス定義はJSONオブジェクトです。

{
  "name": "alpha",
  "enable": true,
  "working_dir": "/work/app",
  "environment": {
    "APP_MODE": "prod",
    "PORT": "8080"
  },
  "executable": "server.js",
  "args": ["--port", "8080"]
}

主なフィールドは以下のとおりです。

フィールド型説明
nameStringサービス名
enableBooleanサービスを有効にするかどうか
working_dirStringサービスプロセスの作業ディレクトリ
environmentObjectKEY: VALUE形式の環境変数マップ
executableString実行ファイルのパスまたはコマンド名
argsArray<String>コマンドライン引数の一覧

status

サービス一覧全体、または単一サービスの詳細を表示します。

構文
servicectl status [service_name]

サービス名を省略すると、名前、有効化状態、実行状態、PID、実行ファイルを表で出力します。

使用例: サービス一覧
/work > servicectl status
┌───────┬─────────┬─────────┬─────┬────────────┐
│ NAME  │ ENABLED │ STATUS  │ PID │ EXECUTABLE │
├───────┼─────────┼─────────┼─────┼────────────┤
│ alpha │ yes     │ running │ 101 │ echo       │
│ beta  │ no      │ stopped │ -   │ /bin/date  │
└───────┴─────────┴─────────┴─────┴────────────┘

サービス名を指定すると、作業ディレクトリ、環境変数、直近の出力行を含む詳細な状態を表示します。

使用例: 単一サービス
/work > servicectl status alpha
[alpha] ENABLED
  status: running
  exit_code: 0
  pid: 55
  start: echo [ hello, world ]
  cwd: /work
  environment:
    A=1
    B=2
  output:
    line-6
    ...
    line-25

read

コントローラーの設定ディレクトリからサービス設定ファイルを読み込み、変更状態を報告します。

構文
servicectl read

結果は1つの表で出力し、各行のSTATUS列に、 UNCHANGED、ADDED、UPDATED、REMOVED、ERROREDの状態を表示します。

この表は、servicectl statusの一覧と同じpretty box形式で表示します。

使用例
/work > servicectl read
┌────────┬───────────┬────────────┬──────────────┬─────────────┬────────────┐
│ NAME   │ STATUS    │ EXECUTABLE │ READ_ERROR   │ START_ERROR │ STOP_ERROR │
├────────┼───────────┼────────────┼──────────────┼─────────────┼────────────┤
│ alpha  │ UNCHANGED │ echo       │              │             │            │
│ beta   │ ADDED     │ node       │              │             │            │
│ old    │ REMOVED   │ sleep      │              │             │            │
│ broken │ ERRORED   │            │ invalid json │             │            │
└────────┴───────────┴────────────┴──────────────┴─────────────┴────────────┘

updateとreload

両コマンドとも、コントローラーに設定変更の適用を要求します。

  • update：読み込み済みの変更だけを適用します。追加、削除、変更されたサービスだけを反映し、他のサービスは維持します。
  • reload：設定ファイルを再読み込みし、実行中のすべてのサービスを停止して変更を反映した後、enable=trueのサービスだけを再起動します。
構文
servicectl update
servicectl reload

出力は、2つのセクションで構成されます。

  • ACTIONS: UPDATE stop、UPDATE start、RELOAD stop、RELOAD startなどの実行した操作の一覧
  • SERVICES: 適用後のサービス状態表

install

JSONファイルまたはインラインオプションでサービスをインストールします。 インストールに成功すると、コントローラーはサービス定義を/etc/services/<name>.jsonに保存します。 ファイル名は、JSONファイルのname値、または--nameオプションで決まります。

JSONファイルからのインストール

構文
servicectl install <config.json>
使用例
/work > servicectl install svc.json

たとえば、svc.jsonに"name": "alpha"が含まれている場合、設定は /etc/services/alpha.jsonに保存されます。

インラインオプションでのインストール

構文
servicectl install \
  --name <service_name> \
  --executable <path> \
  [--working-dir <dir>] \
  [--enable] \
  [--arg <arg> ...] \
  [--env KEY=VALUE ...]
インラインインストールのオプション
  • -n, --name <name> サービス名
  • -x, --executable <path> 実行ファイルのパスまたはコマンド名
  • -w, --working-dir <dir> 作業ディレクトリ
  • --enable 直ちに有効化
  • -a, --arg <arg> 実行引数を1つ追加。繰り返し指定可能
  • -e, --env KEY=VALUE 環境変数を1つ追加。繰り返し指定可能
使用例
/work > servicectl install \
  --name svc-inline \
  --executable node \
  --working-dir /work/app \
  --enable \
  --arg app.js \
  --arg --port \
  --arg 8080 \
  --env APP_MODE=prod \
  --env PORT=8080

このインライン方式でも、コントローラー側に/etc/services/svc-inline.jsonファイルを作成します。

このコマンドは、まずRESULT表を出力し、続いてSERVICEの詳細を表示します。

startとstop

指定したサービスを開始・停止します。

構文
servicectl start <service_name>
servicectl stop <service_name>

出力には、操作結果と現在のサービス状態が含まれます。

使用例
/work > servicectl start alpha
/work > servicectl stop alpha

details

サービスが提供するランタイムのdetail値を取得・設定・削除します。 これらの値は静的なサービス設定とは別で、ヘルス状態、カウンター、ラベル、 ユーザー定義の構造化状態などのランタイムメタデータを保持するために使用します。

構文
servicectl details get <service_name> [key] [--format box|json]
servicectl details set <service_name> <key> <value> [--detail-type <string|number|boolean|bool|object|json>]
servicectl details delete <service_name> <key>
detailsオプション
  • --format <box|json> details getの出力形式。既定値box
  • --detail-type <type> details setの値の型。既定値string

対応するdetail値の型は以下のとおりです。

  • string：--detail-typeを省略した場合の既定値
  • number
  • booleanまたはbool
  • objectまたはjson

型の処理規則は以下のとおりです。

  • stringは、入力した文字列をそのまま保存します
  • numberは、入力値をJSONのnumberとして解析します
  • booleanとboolは、入力値をJSONのtrueまたはfalseとして解析します
  • objectとjsonは、入力値をJSONオブジェクトとして解析し、配列やスカラーは許可しません

details setは、1回のRPCリクエストで処理し、upsertとして動作します。 キーが存在する場合は値を上書きし、なければ新規作成します。

--format jsonを使用すると、

  • servicectl details get <service_name>は、detailsオブジェクト全体をJSONで出力します
  • servicectl details get <service_name> <key>は、そのキーだけを含むJSONオブジェクトを出力します
使用例: box出力
/work > servicectl details get alpha
DETAILS (3)
┌─────────┬─────────┬────────────────────┐
│ KEY     │ TYPE    │ VALUE              │
├─────────┼─────────┼────────────────────┤
│ enabled │ boolean │ true               │
│ labels  │ object  │ {"tier":"gold"}    │
│ retries │ number  │ 3                  │
└─────────┴─────────┴────────────────────┘
使用例: JSON出力
/work > servicectl details get alpha labels --format json
{
  "labels": {
    "tier": "gold"
  }
}
使用例: 値の設定
/work > servicectl details set alpha mode warm
/work > servicectl details set alpha retries 3 --detail-type number
/work > servicectl details set alpha enabled true --detail-type bool
/work > servicectl details set alpha labels '{"tier":"gold"}' --detail-type json
使用例: キーの削除
/work > servicectl details delete alpha labels

uninstall

サービス登録を削除します。

構文
servicectl uninstall <service_name>
使用例
/work > servicectl uninstall alpha
RESULT
uninstall alpha yes removed

一般的な作業手順

まず、サービスのJSONファイルを用意します。

{
  "name": "alpha",
  "enable": true,
  "working_dir": "/work",
  "executable": "echo",
  "args": ["hello", "world"]
}

次に、以下の手順で管理できます。

/work > servicectl install alpha.json
/work > servicectl status
/work > servicectl stop alpha
/work > servicectl start alpha
/work > servicectl uninstall alpha

注意

  • servicectlコマンドには、アクセス可能なコントローラーエンドポイントが必要です。
  • statusは、引数がなければ全一覧を、引数があれば単一サービスの詳細を出力します。
  • installでは、設定ファイルのパスとインラインインストールのオプションを併用できません。
  • インラインの--env値は、必ずKEY=VALUE形式にしてください。
  • 相対パスの設定ファイルは、現在の作業ディレクトリを基準に解釈します。
最終更新日
コマンドリファレンスサービスプロキシ