API リファレンス

このページは、統合を作成するときや、手元にある LicOps のレスポンスの意味を知りたいときに参照してください。このセクションのほかのページでは、各リクエストを、それが使われるタスクの中で説明しています。

各 LicOps ホストの API ブラウザー

すべての LicOps デプロイは、実行中のビルドから生成されたインタラクティブなリファレンスを次のアドレスで提供しています。

http://<licops-host>:8100/swagger

使用しているビルドの正確なスキーマは、ここで確認してください。掲載されている項目の大半は Router の運用向けです。統合が呼び出すのは、以下のアドミッションエンドポイントです。

ポート 8100 と 8101 へのアクセスを制限する

ポート 8100 と 8101 は管理用のインターフェイスです。管理用ネットワークとジョブを投入するホストからのアクセスだけを許可し、インターネットには公開しないでください。公開するのは、クライアントが使用するライセンスポートだけにします。システム要件を参照してください。

アドミッションエンドポイント

ベースパス: http://<licops-host>:8100/api/v1/admission-controller。リクエストとレスポンスは JSON で、フィールド名は camelCase、decision などの値は文字列です。エンドポイントを次の表に示します。

メソッド	パス	成功時	その他の応答
POST	/admit	判定を含む 200	無効なボディの場合、または同じセッション ID を異なるベンダー、フィーチャー、シート数で再利用した場合は 400。コールドスタート中は Retry-After 付きの 503。
POST	/dispatch	ライセンスサーバーを含む 200	無効なボディの場合は 400。不明なセッションの場合は 404。ThrottleDeferred と Retry-After 付きの 503、または NoCapacityAtDispatch 付きの 503。
POST	/release	常に 200	無効なボディの場合は 400。
GET	/availability	常に 200	なし

Admit

リクエストのフィールドを次の表に示します。

フィールド	必須	説明
sessionId	はい	自分で生成する ID で、通常は UUID です。1 つのジョブの 3 つのリクエストすべてで使用します。セッションが有効な間は、同じ ID で admit を繰り返すと最初の応答が返されます。拒否された admit は保存されません。
vendor	はい	プールのベンダーデーモン名。大文字と小文字の区別を含めて完全一致です。
feature	はい	プールのフィーチャー名。大文字と小文字の区別を含めて完全一致です。スペースはスペースのまま送信します。
user	いいえ	ジョブを投入したユーザー。記録され、アドミッションルールで使用できます。
host	いいえ	ジョブの投入元。記録され、アドミッションルールでは client host として使用できます。
totalQuantity	いいえ	許可するシート数。1 以上で、既定値は 1 です。すべてのシートが 1 台のサーバーから割り当てられます。
jobDetails	いいえ	シートとともに記録されるジョブのコンテキスト: clusterName、account、queue、jobName、declaredRuntimeSeconds、および Kubernetes では namespace と podName。各フィールドは任意です。判定には影響しません。

レスポンス:

フィールド	説明
decision	Admit または Deny。
sessionId	Admit の場合はセッション ID、Deny の場合は null。
expiresAt	Admit の場合、それまでにジョブが dispatch されないとシートが失効する時刻。
reason	Deny の場合、その理由。拒否理由 を参照してください。

コールドスタート中の 503 には、type、title、status、traceId を含む problem document と、Retry-After ヘッダーが付きます。

拒否理由

拒否理由、発生した状況、対処方法を次の表に示します。

理由	発生した状況	対処方法
NoServerAvailable	このベンダーとフィーチャーを提供する正常なサーバーがありません。	まず GET /api/v1/stats と照らしてスペルを確認します。次に、プールのサーバーが停止していないかを確認します。
NoCapacity	サーバーには到達できますが、要求を満たす空きシートを持つサーバーがありません。	ジョブをキューに入れ、後で再試行します。
ConstraintBlocked	サーバーに空きシートはありますが、すべてのサーバーが予約による上限に達しているか、現在の期間中ブロックされています。	上限の範囲内でシートが空くのを待つか、予約を変更します。スケジュールでシート数を制限する を参照してください。
PolicyDenied	Deny the request が設定されたアドミッションルールに一致しました。	意図された動作です。LicOps Configuration のルールを確認してください。
StaleSnapshot	LicOps が OpenLM Platform から最新の数値を受け取っていないため、自身のカウントを信頼していません。	OpenLM Platform との同期を復旧します。それまでは再試行しても解決しません。トラブルシューティング を参照してください。
ContentionExhausted	現在は返されません。	対処は不要です。古いクライアントとの互換性のためにこの値が残されています。

Dispatch

リクエストのフィールドを次の表に示します。

フィールド	必須	説明
sessionId	はい	admit で送信した ID。
executionNodeIp	はい	ジョブを実行するノードの IP アドレス。チェックアウトのルーティングを使う場合、LicOps はこれを使ってノードのチェックアウトをこのセッションに対応付けます。
jobId	いいえ	スケジューラーのジョブ ID。記録されます。
jobDetails	いいえ	admit と同じです。ここで指定した値は、admit の値をフィールドごとに置き換えます。省略すると admit の値が保持されます。

レスポンス:

フィールド	説明
hostName、port	チェックアウト先のライセンスサーバー。3 サーバー冗長構成のライセンスサーバーの場合は、その 1 台目のマシン。
licenseFile	LM_LICENSE_FILE に使用する値で、port@host の形式です。3 サーバー冗長構成のライセンスサーバーの場合は、3 台すべてのマシンをカンマ区切りで示します。返されたとおりにそのまま使用してください。
fallbackTargets	プール内のその他の正常なサーバー。それぞれに hostName、port、licenseFile があります。

404 のボディは空で、セッションが存在しないか、すでに終了していることを示します。503 のボディはプレーンテキストで、Throttle ルールがチェックアウトのペースを調整している場合は ThrottleDeferred、セッションのサーバーに障害が発生し、プール内のほかのサーバーに空きシートがない場合は NoCapacityAtDispatch です。ThrottleDeferred の場合、シートは保持されたままです。Retry-After の時間だけ待ってから、もう一度 dispatch します。NoCapacityAtDispatch の場合、LicOps はセッションを解放済みで、Retry-After も送信しません。新しいセッション ID でもう一度 admit します。

Release

リクエストに指定するのは sessionId だけです。レスポンスのステータスは常に 200 で、state は次のいずれかです。

状態	意味
Released	このリクエストでシートが返却されました。
AlreadyClosed	セッションはすでに終了しています。対処は不要です。
NotFound	そのようなセッションは存在しません。対処は不要です。

Availability

GET /availability は、LicOps が把握しているすべてのプールと、その背後にあるすべてのサーバー (停止中のサーバーを含む) を、アドミッション自体が使用する数値とともに返します。何も変更しません。

フィールド	説明
lastPlatformSyncTime、lastReconcileTime	LicOps が最後に OpenLM Platform から数値を受け取った時刻と、最後にその数値でカウントを補正した時刻。
coldStart	LicOps が最初の数値を受け取るまでは true。その間、admit は 503 を返します。
staleForAdmission	数値が古すぎて信頼できない場合は true。その間、admit は StaleSnapshot で拒否します。
pools[]	プールごとに 1 エントリ。vendor、feature、アドミッションが使用できるサーバー全体の合計値 total、used、reserved、free、および largestAdmittableRequest (現時点で 1 つのリクエストが取得できる最大シート数) を含みます。
pools[].servers[]	サーバーごとに 1 エントリ。isHealthy、シート数、constraints を含みます。
pools[].servers[].constraints[]	サーバーに対する各予約の上限。その limit、上限の下で保持されているシート数 held、残りの余裕 headroom を含みます。limit が 9223372036854775807 の場合は、上限が適用されていないことを示します。

free は 0 に切り上げられません。負の値は、LicOps がそのサーバーで保有数を超えるシートを許可したことを意味します。通常は、シートを解放しなかったジョブのシートが原因です。

LicOps の運用に使うエンドポイント

LicOps の運用に使うエンドポイントを次の表に示します。

メソッド	パス	機能
GET	/api/v1/status	LicOps が構成済みかどうか、リッスンポート、および configurationManagement に示される OpenLM Platform との同期状況。
GET	/api/v1/stats	すべてのプールとサーバー、および現在のシート数。正確なベンダー名とフィーチャー名の情報源です。
GET	/api/v1/rules/router-admission	LicOps が適用しているアドミッションルール (組み込みのルールを含む)。読み取り専用です。ルールは OpenLM Platform で定義します。
GET	/api/v1/platform/servers	LicOps が OpenLM Platform から受け取ったライセンスサーバー。受け取るまでは 503 を返します。
GET、PUT	/api/v1/admission-controller/platform-credentials	OpenLM Platform 接続を読み取る、または保存します。シークレットはマスクされた状態で返されます。
POST	/api/v1/admission-controller/platform-credentials/check-connection	保存済みの資格情報ではなく、リクエストボディ内の資格情報をテストします。
GET	/readyz	どのリッスンポートがバインドされ、どのポートが必要とされているか。LicOps が構成を取得するまでは 503 を返します。
GET	/health/ready、/health/live、/health/start	OpenLM の標準のヘルスチェック。

既定値

既定の設定を次の表に示します。

設定	既定値	意味
API ポート	8100	上記のすべてのアドレスで使用するポート。
LicOps のリッスンポート	30001	LicOps 経由でルーティングするチェックアウト用。HTTP ではなく FlexLM プロトコルで通信します。
Admit タイムアウト	15 分	この時間内に dispatch されないジョブは、シートを失います。
Dispatch タイムアウト	2 時間	開始したジョブは、release がなくてもこの時間だけシートを保持します。
コールドスタート時の Retry-After	10 秒	コールドスタート時の 503 の後に待つ時間。
OpenLM Platform の数値	約 10 秒ごと	LicOps がカウントを補正する頻度。新しい数値が約 30 秒間届かないと、admit は StaleSnapshot で拒否します。

タイムアウトを変更するには、セッションのタイムアウトを設定する を参照してください。