InfiniCloud® HV Suite KVM
Top / サポート情報 / マニュアル / InfiniCloud HV KVMモデル（PROXMOX） / InfiniCloud® HV Suite KVM / Kingfisherの基本操作

Kingfisherの基本操作

本ページでは、InfiniCloud® HV の運用を支援する Kingfisher の概要と、Proxmox VE ホストのメモリ状態を確認する基本操作を説明します。 導入済みのコマンドラインツール kfhvadm を使って操作します。

Kingfisherの概要

Kingfisher は、InfiniCloud が開発する、Proxmox VE ホストの設定と運用を支援するツールです。

コマンドラインツール kfhvadm を使用して、実行したホストのメモリ状態を確認し、設定プロファイルと比較できます。また、適用条件を満たしたホストでは、変更計画を生成・保存し、その計画に従って設定を適用できます。 設定プロファイルは、メモリ設定の期待値を計算するための方針を、名前とバージョンで指定するものです。

基本操作は、次の順に進めます。

  1. バージョンとヘルプを確認する。
  2. ホスト全体、または対象を絞ってメモリ状態を確認する。
  3. 設定ファイル（kfhvadm.yaml） を用意し、設定プロファイルと現在の状態を比較する。
  4. 設定を変更する場合は、適用計画の YAML を生成・保存して内容を確認する。
  5. dry-runで検査し、適用条件を満たしていることを確認したうえで計画を適用する。
  6. 適用結果と適用後の状態を確認する。

現在の機能と制限事項

Kingfisherでは、状態確認・比較・適用計画の生成・適用に関するコマンドが実装されています。

  • メモリ状態の確認や、設定プロファイルとの比較機能を利用できます。
  • memory plan で適用計画を生成し、dry-run で適用前の再検査を行えます。
  • memory apply による設定変更機能も実装されていますが、実機での動作確認と受け入れ試験は未完了です。
  • 適用できる環境は、現在の内蔵対応表に適合するホストに限られます。同じPVEバージョンであっても、適用できるとは限りません。
  • swap 領域の作成・変更、HugeTLBの予約・解除、VNET、setup、doctor、kfhciadm などは未対応です。
  • VMの作成・起動・停止・移行は行いません。

適用対象は、overcommit、swappiness、min_free、global THP、KSM、およびKingfisherが所有する永続設定です。

事前準備

Kingfisherを使用する前に、以下の環境と条件を確認してください。

動作環境

  • 仮想化基盤：Proxmox VE 9.x
  • CPUアーキテクチャ：x86_64
  • 実行環境：Proxmox VEをインストールしたホスト上

Kingfisherは、状態を確認したいProxmox VEホスト上で実行します。リモートの別ホストを指定して実行する機能はありません。また、開発用コンテナなど、ホスト以外の環境で実行しても、Proxmox VEホストの状態確認にはなりません。

本ページの操作例は、kfhvadm コマンドを提供するKingfisher本体が導入済みで、kfhvadm をPATHから実行できることを前提としています。

バージョンとヘルプの確認

Kingfisherのバージョンを確認します。

kfhvadm --version

利用できるコマンドとオプションを確認します。

kfhvadm --help

これらのコマンドは、ホストの状態情報を取得するものではありません。

実行権限

読み取りコマンドは管理者権限がなくても起動できますが、ホストの状態確認に必要な情報を取得できず、通常は終了コード1になります。

必要な情報を取得するため、以降の操作例では sudo を付けて実行します。rootユーザーで実行する場合は、sudo を省略できます。なお、管理者権限で実行しても、環境や取得対象によっては必要な情報を取得できない場合があります。設定の適用および dry-run にはroot権限が必要です。

Kingfisherの基本操作

ホストのメモリ状態を確認する

まず、 ホスト全体のメモリ状態を表形式で確認します。設定ファイルは不要です。

sudo kfhvadm memory status --output table

主に次の情報を表示します。

情報確認できる内容
HugeTLB・THP・KSM・swap予約プール、各機能の状態、有効なスワップ領域と使用量
メモリ容量メモリ総量と利用可能量
NUMAノード構成と各ノードのメモリ情報
関連設定サービス、パッケージ、永続設定ファイルなどの観測結果
commitCommitLimit（メモリ割り当ての会計上の上限）と Committed_AS（計上済みの割り当て量）。実際の RAM 使用量とは別の指標

status コマンドはホストの現在の情報を取得するもので、設定プロファイルとの適合性を判定するものではありません。

終了コード0は、必要な情報を取得できたことを示します。設定が推奨値に適合していることや、安全性を保証するものではありません。

メモリ関連の詳細情報を確認する

確認したい対象を絞って表示することもできます。これらの操作にも設定ファイルは不要です。

HugeTLBの状態を確認する

sudo kfhvadm memory hugepages status --output table

HugeTLBの予約プール、メモリ総量、NUMA情報を表示します。THP（Transparent Huge Pages）の属性を確認する場合は、全体のmemory statusを使います。

KSMの状態を確認する

sudo kfhvadm memory ksm status --output table

KSMの実行状態を示す run 値、ksmtuned サービスの状態、共有ページなどの統計を表示します。

swapの状態を確認する

sudo kfhvadm memory swap status --output table

有効なswap領域、その容量・使用量、swap入出力の診断値を表示します。swapのUUID、LV・パーティション・ディスクの識別子なども確認できます。

領域の識別には、root権限が必要です。

なお、現時点では有効なswap領域がある環境について、適用条件を満たすことを確認するための実機検証が十分ではありません。有効なswap領域がある場合は、適用計画の生成や設定の適用に進めないことがあります。計画を生成するために運用中のホストで、swapを止めないでください。

設定プロファイルと現在の状態を比較する

設定ファイルに指定したプロファイルと、現在のホストの状態を比較します。

check・diff の終了コードは、以下のとおりです。

  • 0：設定プロファイルに適合している
  • 1：必要な情報を取得できない
  • 2：引数や設定ファイルなどが不正
  • 3：設定に差分があるが、適用を妨げる問題はない
  • 4：適用を妨げる問題がある

現在の実装では、Kingfisherに組み込まれた検証情報と対象ホストの環境や起動時の設定定義が一致しない場合、変更に必要な機能が未検証と判定されます。そのため、情報取得の失敗や入力不正などがなければ、終了コード4になる場合があります。

終了コードだけで判断せず、差分や FINDINGS に表示される理由も確認してください。

YAMLファイルの役割

入力設定ファイル、確認結果、適用計画は、それぞれ用途が異なります。

種類用意・出力する方法使い方
入力設定ファイル kfhvadm.yaml運用者（お客様）が用意する--config で読み込む。設定プロファイル、容量、安全閾値などを指定する
確認結果のYAMLKingfisherのコマンド (--output yaml） 実行時に出力するホストの観測値・差分・検査結果を確認する
適用計画のYAMLmemory plan --save-plan PATH で生成・保存するmemory apply コマンド（memory apply --plan PATH） で設定を適用する際に使用する

適用計画のYAMLはKingfisherが生成します。--output yaml の結果全体を保存したファイルは、apply --plan に渡す適用計画にはなりません。また、入力設定ファイルのYAMLを apply に直接渡すこともできません。

比較に使う入力設定

Kingfisherでは、設定プロファイルと現在のホストの状態を比較するために、入力設定ファイル kfhvadm.yaml を使用します。

/etc/kingfisher/kfhvadm.yaml は、使用する設定プロファイルの名前とバージョンのほか、対象ホストの容量・安全閾値・管理主体などの申告を記載する YAML ファイルです。

入力設定ファイルは、お客様（運用者）が用意します。Kingfisherのコマンド実行によって自動生成・更新されるものではありません。

現行の入力形式は apiVersion: infinicloud.jp/v1alpha2、kind: HVHostConfig です。

本手順で使用する kvm-default@2 は、CommitLimit の目標値をホストの MemTotal とするプロファイルです。

対象ホストに必要な容量や安全閾値は、お客様の環境や運用方針に応じて決定してください。設定例に記載された数値は、すべてのホストに適用できる推奨値ではありません。

sudo で読み込む入力設定ファイルは、root所有の通常ファイルとし、group・otherによる書き込みを許可しないでください。また、シンボリックリンクは使用できません。

観測値と検査結果を確認する

設定ファイルを用意したうえで、次のコマンドを実行します。

sudo kfhvadm memory check --config /etc/kingfisher/kfhvadm.yaml --output table

コマンドを実行すると、ホストから取得した観測値、計算された期待値、両者の差分、容量や安全閾値などの検査結果が表示されます。

別の場所に設定ファイルを配置した場合は、--config にそのファイルのパスを指定してください。指定したファイルのみを読み込み、既定の設定ファイルとのマージは行いません。指定したファイルが存在しない場合は、終了コード 2 になります。

差分を中心に確認する

sudo kfhvadm memory diff --config /etc/kingfisher/kfhvadm.yaml --output table

check と同じ計算・検査を行い、表形式では差分を中心に表示します。

表示読み方
CURRENT現在の値
EXPECTED選択したプロファイルと入力から計算した期待値
LAYER比較した層。runtime（稼働中の設定）、persistent（永続設定）、service、package、ownership（所有記録）
NOT COMPARED必要な観測値を取得できず、比較していない項目
not calculated期待値を計算できなかった状態
DIFFERENCES none比較できた項目には差分がなかった状態
 FINDINGS情報の取得不能、未対応・未検証の機能、設定の問題などの指摘事項

DIFFERENCES none と表示されていても、必ず FINDINGS を確認してください。差分がないことと、設定の適用を妨げる問題がないことは別です。

適用計画を保存して設定を適用する

適用前に確認すること

設定の適用は、VMが動いていないKVM専用ホストで行います。VMの停止・退避と、作業中にVMを起動しないための管理は、お客様側で行ってください。KingfisherはVM の停止・退避を行いません。

また、対象ホストに合った入力設定を用意し、差分と指摘事項を確認してください。現在は、検証証拠と同じ環境・起動時の設定定義であることを含め、すべての前提検査に通る必要があります。同じPVEバージョンだけでは適用可能とは判定されません。未検証の機能や設定の競合が理由で止まった場合は、その理由を確認してください。

適用計画のYAMLを生成して保存する

以下は、入力設定と前提検査に問題がないホストでの操作例です。root で計画を生成し、まだ存在しないファイル名に保存します。

sudo kfhvadm memory plan --config /etc/kingfisher/kfhvadm.yaml --save-plan /root/kingfisher-memory-plan.yaml --output table

plan はホストの設定を変更せず、変更内容と順序を計画します。検査を通り、計画の生成・保存に成功すれば終了コード0になります。差分があっても0です。表の PLAN と STEP、差分、FINDINGS を確認してください。

問題があれば計画を保存しません。PLAN not generated の場合は、表示された理由を解消してから新しい計画を生成します。- save-plan を指定しただけでは、ファイルができたとは限りません。

保存した YAML も確認できます。

sudo less /root/kingfisher-memory-plan.yaml

計画は root 所有・0600 で保存されます。既存ファイルは上書きしません。保存先のディレクトリは、あらかじめ存在し、root が所有し、group・other が書き込めない必要があります。/tmp、/etc/kingfisher、/var/lib/kingfisher、/run/lock、sysctl・sysfs の設定場所には保存できません。

dry-runで再検査する

sudo kfhvadm memory apply --plan /root/kingfisher-memory-plan.yaml --dry-run --output table

保存計画と現在のホストを照合し、安全条件などを再検査します。ホストの設定、ロック、実行履歴は変更しません。終了コード0でも、その後の本適用の成功を保証するものではありません。

計画を適用する

変更内容を確認したら、同じ計画を指定して適用します。

sudo kfhvadm memory apply --plan /root/kingfisher-memory-plan.yaml --output table

端末に確認が表示されたら、内容を確認し、続行する場合は yes と入力します。適用時にもホスト・計画の有効期限・安全条件を再検査し、変更後の値を読み戻して結果を確認します。通常確認を省略する --yes でも、安全検査は省略しません。端末以外から実行する場合は、事前に計画を確認したうえで --yes が必要です。

計画は生成から30分未満、同じホスト・同じ起動中でのみ有効です。期限切れ、再起動、前提条件の変化で拒否された場合は、新しい計画を生成・確認してください。

適用結果を確認する

apply の終了コード、PLAN・RUN の行、FINDINGS を確認し、状態と差分を再確認します。

sudo kfhvadm memory status --output table
sudo kfhvadm memory check --config /etc/kingfisher/kfhvadm.yaml --output table

kvm-default@2 の適用成功時は、vm.overcommit_memory=2 と CommitLimit=MemTotal の厳密一致を確認します。終了コード5は、変更を試みた後の失敗・中断・結果不明を示します。表示された run ID と記録を保持し、下記の復旧手順で調査してください。

失敗や中断から復旧する

INCOMPLETE_RUN が出た場合、通常の適用を繰り返すのではなく、記録に示された run ID から復旧計画を作ります。次の <runId> は実際の ID に置き換えます。

sudo kfhvadm memory plan --recover-run <runId> --save-plan /root/kingfisher-recovery-plan.yaml --output table

復旧計画も通常の計画と同じ前提検査を受けます。生成できた場合は内容を確認し、dry-run を経て適用します。

  • recover-run と --config・プロファイル指定は併用できません。記録で説明できない値や取得不能で復旧計画を生成できない場合は、記録を保持して手動調査してください。

出力形式を選ぶ

--output オプションで出力形式を指定できます。

指定できる形式は以下の3種類です。

 値 用途
 table端末で内容を確認する
 jsonスクリプトで処理する、結果を保存する
 yaml YAML 形式で結果を確認・保存する

以下は、出力形式の指定例です。

sudo kfhvadm memory hugepages status --output table
sudo kfhvadm memory ksm status --output table
sudo kfhvadm memory swap status --output table

出力形式を省略した場合、端末への出力は表形式、ファイルやパイプへの出力はJSON形式になります。スクリプトでは形式を明示してください。結果は標準出力に1件、診断ログは標準エラーに出ます。

結果を保存する

次は Bash で結果と標準エラーを別々に保存し、終了コードを確認する例です。保存先はコマンドを実行したディレクトリです。同名ファイルがあれば上書きします。

rc=0
sudo kfhvadm memory status --output json > memory-status.json 2> memory-status.stderr || rc=$?
printf 'exit code: %s\n' "$rc"

JSON/YAML の findings には、問題の識別子 code、説明 message、対処 remediation などが入ります。取得できない観測値は、0で補完せず null と理由で示します。check・diff の applicable は常に false です。適用可能な計画を得るには memory plan を使います。

保存結果にはホストの識別情報が含まれます。問い合わせ時は必要な部分を抜粋し、machine-id・boot-id などの識別子を伏せて共有してください。

終了コードと困ったときの確認方法

終了コード意味確認・対処
0成功。status は必須情報の取得、check・diff は適合、plan は計画の生成、apply は適用成功plan・dry-run は差分があっても0
1必須情報の取得不能、変更試行前のタイムアウトや入出力失敗などFINDINGS、取得不能の理由、標準エラーを確認する
2引数、入力設定、入力形式、保存先などの不正--help、入力設定、指定パスを確認する
3check・diff で差分だけがある差分を確認し、変更する場合は計画を生成する
4適用前提の不合格、未対応・未検証の環境、古い計画、ロック競合、確認の辞退などFINDINGS を確認する。差分だけを示すコードではない
5ホストの変更を試みた後の失敗・中断・結果不明 run ID と記録を保持し、復旧計画または手動調査を行う

現在の実装では、内蔵の検証証拠と対象ホストの環境・起動時の設定定義が一致しない場合、終了コード4となり、計画の生成や適用に進めないことがあります。必要な情報の取得に失敗した場合は終了コード1が優先されます。終了コードだけで判断せず、FINDINGS も確認してください。

権限不足と表示された場合：必要な情報を読み取れる権限で再実行してください。

指定した入力設定がない場合：準備状況と --config のパスを確認してください。適用計画は入力設定の代わりにはなりません。

計画が保存されない場合：PLAN の行と FINDINGS を確認してください。未検証の環境、設定の競合、容量・安全条件などが理由になることがあります。

STALE_PLAN と表示された場合：ホスト・CLI の版・起動状態・期限・固定前提を確認し、新しい計画を生成してください。

INCOMPLETE_RUN と表示された場合：manifest・journal・バックアップを保持し、対象 run の復旧計画を生成してください。

結果が出力されない場合：コマンド名や出力形式の不正では、標準エラーだけに理由が出ることがあります。apply が結果の出力に失敗した場合は、標準エラーの run ID と journal で適用結果を確認してください。