docker

搭个 agent 团队，还得写一堆胶水代码？ Docker 的 docker-agent：YAML 定义 agent、配工具、多 agent 编排，构建运行分享一条龙。 适合快速拼 agent 团队的人，不用代码就能先跑起来。 先搭几个 agent，分工还是单打独斗？ #Docker #Agent @grok docker/docker-agent

Hyper-V で Podman + docker-compose 環境を作る 1. 概要 自分用に、Hyper-V 上に Rocky Linux の VM を作る手順をまとめます。 この VM は、GitLab コンテナを動かす土台や、VSCode の DevContainer の基盤として使うことを想定しています。職場に近いコンテナ環境（Podman ＋ docker-compose）を手元に用意しておくのが狙いです。 本記事では、仮想スイッチの作成から、VM の作成・OS インストール・NAT 設定・Podman / docker-compose の導入までを扱います（GitLab コンテナの構築自体は別記事に分けます）。 2. Hyper-V で VM を作る なお、自動化等が可能だと思うので、コマンドで実施していますが、GUI でも設定可能な内容です。 UEFI の設定や Hyper-V の有効化など、VM 作成の根本的な部分は省きますので、ご了承ください。 2.1. 構築の準備 職場の環境は、コンテナエンジンにPodmanを使用しており、コンテナの構成管理にdocker-composeを使用し、設定内容が見える（秘伝のタレにならない）ようになっています。それに近い環境の構築を目指したいと思います。 2.1.1. イメージの入手 手元にあるのが、Rocky Linux 10.1なのでこれを使用します。 dl.rockylinux.org 職場のディストリビューション（RHEL9系）とはやや異なりますが、大きな差分にはならないと考えています。 2.1.2. docker-compose の入手 これは手順の中で実施しますが、GitHub から取得する必要があります。 docs.docker.com この手順はLegacyとして扱われているので、あまり良い方法ではありませんが、職場の環境を再現するために実施します。 というより、そもそもRHEL標準リポジトリではDockerは配布されていない（Podmanに置換された）ので、標準リポジトリでdocker-composeを組み合わせるにはこの方法しかなさそう？（Docker 社の外部リポジトリから導入は可能だが Red Hat のサポート外） access.redhat.com ということで、以下を参考に standalone の docker-compose を Podman の Docker 互換ソケット（DOCKER_HOST）に向けて使うように設定します。 fedoramagazine.org 2.2. VM 構築手順 以降のコマンドは 「管理者として実行」した PowerShell で行います。 2.2.1. 仮想スイッチの作成 今回の検証では、外部からの接続は行わないので、内部仮想スイッチを作ります。 $SwitchName = "InternalSwitch" New-VMSwitch ` -Name $SwitchName ` -SwitchType Internal # 以下は出力結果 Name SwitchType NetAdapterInterfaceDescription ---- ---------- ------------------------------ InternalSwitch Internal 仮想スイッチのIPアドレスを192.168.100.1/24設定します。 New-NetIPAddress ` -InterfaceAlias "vEthernet ($SwitchName)" ` -IPAddress 192.168.100.1 ` -PrefixLength 24 # 以下は出力結果 IPAddress : 192.168.100.1 InterfaceIndex : 38 InterfaceAlias : vEthernet (InternalSwitch) AddressFamily : IPv4 Type : Unicast PrefixLength : 24 PrefixOrigin : Manual SuffixOrigin : Manual AddressState : Tentative ValidLifetime : Infinite ([TimeSpan]::MaxValue) PreferredLifetime : Infinite ([TimeSpan]::MaxValue) SkipAsSource : False PolicyStore : ActiveStore IPAddress : 192.168.100.1 InterfaceIndex : 38 InterfaceAlias : vEthernet (InternalSwitch) AddressFamily : IPv4 Type : Unicast PrefixLength : 24 PrefixOrigin : Manual SuffixOrigin : Manual AddressState : Invalid ValidLifetime : Infinite ([TimeSpan]::MaxValue) PreferredLifetime : Infinite ([TimeSpan]::MaxValue) SkipAsSource : False PolicyStore : PersistentStore 作成後、NIC の設定を確認してください。追加したネットワークアダプタ（仮想スイッチ）が表示されれば問題ありません。 ipconfig /all # 以下は出力結果 # 該当部分のみ掲載 イーサネット アダプター vEthernet (InternalSwitch): 接続固有の DNS サフィックス . . . . .: 説明. . . . . . . . . . . . . . . . .: Hyper-V Virtual Ethernet Adapter #4 物理アドレス. . . . . . . . . . . . .: 00-15-5D-20-86-11 DHCP 有効 . . . . . . . . . . . . . .: いいえ 自動構成有効. . . . . . . . . . . . .: はい リンクローカル IPv6 アドレス. . . . .: fe80::1390:7148:87d3:67fc%38(優先) IPv4 アドレス . . . . . . . . . . . .: 192.168.100.1(優先) サブネット マスク . . . . . . . . . .: 255.255.255.0 デフォルト ゲートウェイ . . . . . . .: DHCPv6 IAID . . . . . . . . . . . . .: 637539677 DHCPv6 クライアント DUID. . . . . . .: 00-01-01-00-30-E6-D2-3A-34-5A-60-66-C2-A9 NetBIOS over TCP/IP . . . . . . . . .: 有効 2.2.1.1. 外部スイッチの追加（任意） 今回の検証は内部スイッチ＋NAT だけで完結しますが、「VM を物理 LAN に直結して、ホスト以外の端末からも VM に触りたい」場合は、内部スイッチに加えて外部スイッチも作れます（不要な方は読み飛ばしてください）。 外部スイッチは、VM を物理 NIC 経由で物理 LAN へ直結します（ホストと同一セグメント）。ここでは ホストと NIC を共有する方針 で作ります。こうすると、物理 NIC が 1 枚でもホスト側の通信（インターネット）が維持され、ホスト ↔ VM も外部スイッチ経由でそのまま通ります。 参考（仮想スイッチの作成）：Create a virtual switch for Hyper-V virtual machines learn.microsoft.com まず、バインドする物理 NIC 名を確認します。 Get-NetAdapter 外部スイッチを作成します。-NetAdapterName を指定すると種別は自動的に「外部」になり、-AllowManagementOS を省略すると既定でホストと共有になります。<NIC名> は上で確認した物理 NIC（有線を推奨）に置き換えてください。 New-VMSwitch ` -Name "ExternalSwitch" ` -NetAdapterName "<NIC名>" > 外部スイッチの作成時は、その NIC のネットワーク接続が一時的に中断されます（作成後にホスト側 vEthernet (ExternalSwitch) が IP を取り直します）。 外部スイッチの使い方は、目的によって次の 2 通りに分かれます。なお、VM のアダプター操作（Add-VMNetworkAdapter / Connect-VMNetworkAdapter）は VM を作成した後（[2.2.3. VM の作成](#223-vm-の作成) 以降）に実行してください（$VmName も [2.2.2.1. VMの情報](#2221-vmの情報) で定義します）。 (a) 内部スイッチと両立させる（VM に NIC を 2 枚持たせる） 内部スイッチ側（192.168.100.10）はホスト ↔ VM の管理用として残し、外部スイッチ側でインターネット／LAN に出ます。VM 作成後、2 枚目のアダプターを追加します。 Add-VMNetworkAdapter ` -VMName $VmName ` -SwitchName "ExternalSwitch" VM 側では、外部側の NIC を DHCP（デフォルト経路を持つ側）、内部側の NIC を静的 IP（デフォルトゲートウェイなし）に設定します。 ※デフォルトルートを 2 本持たせると経路が二重化して不安定になります。デフォルトゲートウェイは外部側の 1 本だけにしてください。 (b) 外部スイッチだけにする（内部スイッチをやめる） VM の接続先を外部スイッチへ切り替えます。アダプター名は Get-VMNetworkAdapter -VMName $VmName で確認できます。 Connect-VMNetworkAdapter ` -VMName $VmName ` -Name "ネットワーク アダプター" ` -SwitchName "ExternalSwitch" VM 側の IP は物理 LAN に合わせて DHCP で取り直します（本手順の静的 IP 192.168.100.10 は内部スイッチ専用なので、そのままでは通りません）。 ※(a)(b) いずれも、インターネットは外部スイッチ直結で出られるので、[2.4. NAT 設定](#24-nat-設定) は不要です。 2.2.2. VM 設定用のシェル変数の準備 2.2.2.1. VMの情報 以降で使用するシェル変数を準備しておきます。 $VmName = "Rocky-Podman" $ISO = "C:\ISO\RockyLinux10.1.iso" # iso ファイルがあるパスに書き換えること $DefaultSaveFolder = (Get-VMHost).VirtualHardDiskPath $VhdFullPath = "$DefaultSaveFolder\$VmName.vhdx" 2.2.2.2. メモリ割り当て量 VMに割り当てるメモリサイズもシェル変数として準備しておきます（2MB の倍数にしないとエラーになります）。 なお、メモリのサイズについては、Windows 11 の最低要件である4GBを残すため、$MaxVmMemory は、$TotalHostMemory から4GB引いた値を割り当てています。 また、$MinVmMemoryを小さくしすぎると、メモリひっ迫時に VM が設定値通りの最小 RAM 付近まで搾られる可能性がありますので、最小とはいえ、なるべくシステムが落ちないような値を設定しましょう。 learn.microsoft.com $TotalHostMemory = (Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory $MaxVmMemory = [math]::Floor(($TotalHostMemory - 4GB) / 2MB) * 2MB $MinVmMemory = 4GB # 要件に応じて要調整 やや分かりにくいので、計算例を書いておきます（RAM: 32GB の場合）。 $MaxVmMemory： 32GB - 4GB = 28GB → ÷2MB = 14,336 個（今回は割り切れているので、Floor後も変化なし） Floor → 14,336 個 ×2MB = 28GB 2.2.2.3. CPU コア数 VM に割り当てる CPU のコア数も割り当てます。 最近の Intel CPU は P コア／E コア混在で、どのコアを使うか手動指定できないこともあるので（私が使用しているのは Ryzen 7 5700X ですが）、全論理コアを割り当て、使用率設定でリソースを共有することで、E コアだけで動く（遅くなる）のを避けられるようにしようと思います。 $TotalHostCores = (Get-ComputerInfo).CsNumberOfLogicalProcessors 2.2.2.4. 仮想ハードディスク 仮想ハードディスクのオブジェクトを生成します。なお、動的 VHDX にするので、サイズを大きめに取っても即座に占有はしません。 $VHD = New-VHD ` -Path $VhdFullPath ` -SizeBytes 128GB ` -Dynamic 2.2.3. VM の作成 これまでに準備したシェル変数をもとに、仮想マシンを作成します。 New-VM ` -Name $VmName ` -MemoryStartupBytes 4GB ` -Generation 2 ` -SwitchName $SwitchName ` -VHDPath $VHD.Path 2.2.4. CPU 使用率の割り当て 少数コアを 100% 占有させるのではなく、使用率（優先度） で共有します。最低 50%・最大 80% を割り当てます。 Set-VMProcessor ` -VMName $VmName ` -Count $TotalHostCores ` -Reserve 50 ` -Maximum 80 ※-Reserve/-Maximum は「常に占有」ではなく、スケジューリング（CPU を時間で分け合う仕組み）上の優先度の下限（必要時の最低保証）・上限を指します。 2.2.5. 動的メモリの設定 ホストと VM でメモリを効率的に融通するために、動的メモリを使用します。 Set-VMMemory ` -VMName $VmName ` -DynamicMemoryEnabled $true ` -MinimumBytes $MinVmMemory ` -MaximumBytes $MaxVmMemory ` -Buffer 30 ※-Buffer 30は、VM が必要とする量に対し 30%の空きを確保するよう動的に増やすこと。大きすぎるとホストのメモリが枯渇するので注意。 2.2.6. Secure Boot の有効化 OS イメージの正規性を検証でき、起動前の不正コード実行を防ぐことが可能です。今回の検証ではあまり意味はないおと思いますが、有効化しておきます。 Linux ディストリビューションでは MicrosoftUEFICertificateAuthority テンプレートの選択が必須です。間違うと起動しません。 Set-VMFirmware ` -VMName $VmName ` -EnableSecureBoot On ` -SecureBootTemplate MicrosoftUEFICertificateAuthority 2.2.7. チェックポイント種別の設定 現状では、ゲストエージェント（hyperv-daemons）を導入しないので、ここでは標準チェックポイントを使用します。 Set-VM ` -Name $VmName ` -CheckpointType Standard 2.2.8. ISO のマウントとブート順の設定 DVD-ISO をマウントします。 Add-VMDvdDrive ` -VMName $VmName ` -Path $ISO DVD ドライブを最優先で起動するよう、ブート順を設定します。 Set-VMFirmware ` -VMName $VmName ` -FirstBootDevice (Get-VMDvdDrive -VMName $VmName) 2.2.9. OS 起動前のエクスポート（バックアップ） 初回起動やOSのインストールに失敗した場合のため、起動前の状態（やり直しが効く状態）をエクスポートしておきます。 $ExportPath = "C:\EXAMPLE" # 任意のパスを指定してください Export-VM ` -Name $VmName ` -Path $ExportPath # ファイルが出力されたことを確認する explorer $ExportPath 2.3. OS インストール手順 以下のコマンドで VM を起動します。 vmconnect.exe localhost $VmName Start-VM -Name $VmName 2.3.1. インストーラーでの設定内容 インストーラーで次のような設定を行います。 | 設定項目 | 本手順の値 | 補足 | | ------------- | ------------------------------- | ---------------------- | | 言語 / キーボード | 日本語 or English（任意） | GUI は入らないので好みで可 | | 時刻と日付 | アジア/東京 | — | | ソフトウェアの選択 | 最小限のインストール（Minimal Install） | 軽量化のために GUI を入れない。アドオンも選択しない。 | | インストール先 | 対象ディスクを選択 → 完了（自動構成） | 単一ディスクを使用 | | KDUMP | 無効化（任意） | メモリ節約。チェックを外す | | ネットワークとホスト名 | [手順 2.3.2.](#232-ネットワークとホスト名) | 静的 IP | | root アカウント | [手順 2.3.3.](#233-root-アカウント) | root SSH は禁止 | | ユーザーの作成　| [手順 2.3.4.](#234-ユーザーの作成) | wheel（管理者）付き | 2.3.2. ネットワークとホスト名 まず、画面左下のホスト名に rocky-podman と入力して適用します。 その後、右上の Ethernet（eth0）トグルをオンにし、以降の手順でインタフェースの設定を行います。 1. 設定 → IPv4 Settings タブ： 2. Method：Manual 3. Add で以下を入力： - Address：192.168.100.10 - Netmask：255.255.255.0（または 24） - Gateway：192.168.100.1 （[2.2.1. 仮想スイッチの作成](#221-仮想スイッチの作成) で設定した IP アドレスを使用） - DNS サーバー：8.8.8.8（NAT 経由で到達できるもの） 4. Save → 左上の「完了」ボタンを押す 2.3.3. root アカウント 「root アカウントを有効化」を選び、強いパスワードを設定します（「良好」以上）。 この検証ではあまり関係ありませんが、「総当たり攻撃で root を直接狙われないようする」、ということを心がけようと思うので、root の SSH ログインは無効にします。 よって、「パスワードによる root SSH ログインを許可」のチェックは外しましょう。 2.3.4. ユーザーの作成 以下のように設定します。 1. フルネーム：人間が読むための名称。任意に入力する（ユーザー名と同じでも良い） 2. ユーザー名：ssh や su などで使用。英小文字・空白なし・英字始まりで、任意に入力する 3. 「ユーザーアカウントに管理者権限を付与する（wheel グループに加える）」にチェックを入れる 4. [2.2.3. root アカウント](#223-root-アカウント)と同様に、強いパスワードを設定する 5. 左上の「完了」ボタンを押す 2.3.5. インストール開始と再起動 設定の抜けがないか見直し、右下の「インストールの開始」を押下します。 なお、SMT（同時マルチスレッディング）に関する警告が出ても、本用途では、非本番・限定ネットワークなので無視します。 完了後、「システムの再起動」を押下してください。 また、ISO からの再起動ループを避けるため、再起動後に、以下のコマンドで ISO を外しておきます。 Set-VMDvdDrive -VMName $VmName -Path $null 2.3.6. 初回ログイン 次のような画面が表示されますので、ユーザー名とパスワードを入力し、ログインします。 rocky-podman login: # 設定したユーザー名を入力 Password: # 設定したパスワードを入力 動作確認として次のコマンドを入力します。 cat /etc/rocky-release すると、次の内容が出力されるはずです。 Rocky Linux release 10.1 (Red Quartz) 2.3.7. ホスト（Windows）からの SSH 疎通確認 最小構成でも OpenSSH サーバーは既定で起動し、firewalld も SSH を許可しているはずですが、念のため確認しておきます。 # SSH サーバーが稼働中か systemctl is-active sshd # active なら稼働中 # SSH サーバーが自動起動するか systemctl is-enabled sshd # enabled なら自動起動 # 22番ポートを待ち受けているか ss -tlnp | grep ':22' # 以下は出力結果 # :22 の LISTEN 行が出れば問題なし LISTEN 0 128 0.0.0.0:22 0.0.0.0:* ← IPv4・全インターフェースで :22 を待ち受けている LISTEN 0 128 [::]:22 [::]:* ← IPv6・全インターフェースで :22 を待ち受けている # firewalld が動作しているか sudo firewall-cmd --state # パスワードを尋ねられたら入力 # 稼働中の場合、running が出力される # ファイアウォールで許可（開放）されているサービスの一覧を確認する sudo firewall-cmd --list-services # 出力例：cockpit dhcpv6-client ssh # 上記の出力の場合、一番左に ssh があるため、SSHが使用可能である。 # 自分のIPが 192.168.100.10 になっているか ip -brief addr 上記で問題ないことを確認できたら、ssh を実行しましょう。 ssh <ユーザー名>@192.168.100.10 SSH 接続ができたら Hyper-V のコンソールを閉じます。 Stop-Process -Name vmconnect 2.4. NAT 設定 [2.2.1. 仮想スイッチの作成](#221-仮想スイッチの作成) で内部スイッチとホスト側 IP（192.168.100.1）は作成済みです。しかし、内部スイッチ単体では VM はインターネットに出られません（通信できるのは「ホスト ↔ VM」だけで、物理 NIC には直接つながらない）。 そこで、ホストが VM の通信を外へ中継する（送信元を書き換えて転送する＝SNAT） NAT を作成します。 これで、以下の経路でインターネットにつながるようになります。 VM → ゲートウェイ(192.168.100.1=ホスト) → NAT → 物理NIC → インターネット 参考（NAT ネットワークの考え方）：Set up a NAT network learn.microsoft.com 2.4.1. NAT の作成 以降のコマンドは 「管理者として実行」した PowerShell で行います。 内部ネットワークの範囲（192.168.100.0/24）に対する NAT を作成します。 New-NetNat ` -Name "HyperV-NAT" ` -InternalIPInterfaceAddressPrefix 192.168.100.0/24 作成できたか確認します。 Get-NetNat # 以下は出力結果 # Active が True、プレフィックスが 192.168.100.0/24 であれば OK Name : HyperV-NAT InternalIPInterfaceAddressPrefix : 192.168.100.0/24 Store : Local Active : True 2.4.2. 疎通確認 VM に戻り、「ホスト到達 → インターネット到達（名前解決）」の順に確認します。 まず、ゲートウェイ（ホスト）に届くか。これが通れば NAT の土台（内部スイッチ＋ホスト IP）は正常です。 ping -c 3 192.168.100.1 # ホスト(ゲートウェイ)に届けば、内部スイッチ側は OK 次に、名前解決（DNS）ができるかを確認します。 ping -c 3 rockylinux.org # 応答があれば OK 2.5. 初期設定とPodman導入 2.5.1. システム更新 インターネットに接続できることを確認できたら、システムを更新します。 sudo dnf update -y 2.5.2. Hyper-V 連携デーモン この手順は任意です。 時刻同期・ホストからの正常シャットダウン・IP 情報の通知・（将来の）運用チェックポイントの有効化に効くので、Hyper-V 連携デーモン（hyperv-daemons）を導入します。 sudo dnf install -y hyperv-daemons デーモンの有効化および起動を行います。 sudo systemctl enable --now hypervkvpd hypervvssd hypervfcopyd [2.2.7. チェックポイント種別の設定](#227-チェックポイント種別の設定)では、標準チェックポイントを選択しましたが、運用チェックポイントに切り替えたい場合は、PowerShell で以下のコマンドを実行します。 Set-VM ` -Name $VmName ` -CheckpointType ProductionOnly ゲスト サービス インターフェイスも有効化します。 Get-VMIntegrationService -VMName $VmName # 出力例 VMName Name Enabled PrimaryStatusDescription SecondaryStatusDescription ------ ---- ------- ------------------------ -------------------------- Rocky-Podman ゲスト サービス インターフェイス False OK Rocky-Podman ハートビート True OK Rocky-Podman キー値ペア交換 True OK Rocky-Podman シャットダウン True OK Rocky-Podman 時刻の同期 True OK Rocky-Podman VSS True OK Enable-VMIntegrationService ` -VMName $VmName ` -Name "ゲスト サービス インターフェイス" 2.5.3. 基本ツールと Podman の導入 （VM に戻り、）次のパッケージを導入します。任意に追加しても良いです。 sudo dnf install -y podman git curl tar バージョンを確認します。 podman --version # 表示されれば OK 2.5.4. チェックポイント作成（Podman導入完了） ここまでの状態を保存したいので、念のため、チェックポイントを作成しておきます。PowerShell で以下のコマンドを実行してください。 Checkpoint-VM ` -Name $VmName ` -SnapshotName "Podman インストール完了" 2.5.5. Docker API 互換ソケットの作成 これは「Podman を Docker のふりをさせて、docker-compose から使えるようにする」ための手順です。 fedoramagazine.org ユーザーソケットを有効化します。 systemctl --user enable --now podman.socket # 出力例 Created symlink '/home/ユーザー名/.config/systemd/user/sockets.target.wants/podman.socket' → '/usr/lib/systemd/user/podman.socket'. ユーザーソケットは、docker-compose が命令を送る“受け口”（差込口）となります。 --user は「そのユーザー」専用の systemd で開くことを意味します。Podman 自体は一般ユーザー（＝rootless）のまま動くので、特別な"rootless化"は不要です。ここで行っているのは、docker-compose がつなぐための「Docker 互換ソケット」を、そのユーザー権限で有効化することです。 ソケット作成後、DOCKER_HOST 変数を設定します。 echo 'export DOCKER_HOST=unix://${XDG_RUNTIME_DIR}/podman/podman.sock' >> ~/.bashrc source ~/.bashrc 実行後、状態を確認します。 systemctl --user status podman.socket # 出力例 # Active: active (listening) になっていれば OK podman.socket - Podman API Socket Loaded: loaded (/usr/lib/systemd/user/podman.socket; enabled; preset: disabled) Active: active (listening) since Sun 2026-10-25 19:40:33 JST; 7min ago rootless のユーザーサービスは、既定ではログアウトで止まるので、ログアウト後もコンテナが動くようにします。 loginctl enable-linger $USER 2.5.6. docker-compose の導入 事情は [2.1.2. docker-compose の入手](#212-docker-compose-の入手) にも書きましたが、Docker 公式の standalone インストール手順に従い、GitHub から docker-compose を入手します。 docs.docker.com 以下のコマンドを実行します。 # バージョン確認 COMPOSE_VER=$(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/') && echo $COMPOSE_VER # ダウンロード実行 sudo curl -L "https://github.com/docker/compose/releases/download/${COMPOSE_VER}/docker-compose-linux-x86_64" -o /usr/local/bin/docker-compose # 実行権限の付与 sudo chmod +x /usr/local/bin/docker-compose 動作確認としてバージョンを確認します。 docker-compose --version 先ほど設定したソケットを使って、コンテナエンジン（Podman）に問い合わせ可能かを確認します。 echo $DOCKER_HOST # unix:///run/user/1000/podman/podman.sock docker-compose ls # エラーにならず、空のプロジェクト一覧が出れば OK # NAME STATUS CONFIG FILES # 出力なし 2.5.7. チェックポイント作成（Docker Compose導入完了） ここまでの状態を保存したいので、念のため、チェックポイントを作成しておきます。PowerShell で以下のコマンドを実行してください。 Checkpoint-VM ` -Name $VmName ` -SnapshotName "Docker Compose インストール完了"

Docker MCP Gateway 可以给 AI 工具设白名单：同一个服务，只开放需要的几个工具，不必整包接进去。 MIT 开源，可把服务分组后导出、共享。但按官方说明，独立 CLI 用户要先开启 profiles 功能；Docker Desktop 用户则自动启用。 docker/mcp-gateway

GitHub ActionsとDockerのビルドを1本のトレースにしてGrafana Cloudで見る ! 2026年10月27日に、GitHubホストランナーのUbuntu 24.04で次のバージョンを使って確認した内容です。送信するシグナルはトレースだけです。 Docker Engine 28.0.4 Buildx v0.29.1 BuildKit v0.33.1 OpenTelemetry Collector contrib v0.164.0 GitHubレシーバーのトレース機能は、このバージョンではalphaです。後述する親スパンのID計算もレシーバーの実装に依存します。 はじめに 先日書いたDockerのビルドを遅くしたコミットをGrafana Tempoのトレースで見つけるでは、手元のビルドをトレースにして、遅くなったコミットやDockerfileの手順を調べました。次のステップはCIです。GitHub Actionsの画面で「Dockerのビルドが遅い」とわかっても、そのステップの中で何に時間がかかったかを調べるには、ビルドのログや記録を別に開く必要があります。ワークフロー全体からDockerfileの手順まで、同じトレースの中でたどれるようにしてみました。 TL;DR BuildKitからGrafana CloudのOTLPエンドポイントへトレースを送信できることを確認しました。CIのステップにつなぐには、OpenTelemetry CollectorのGitHubレシーバーがステップに付けるIDをビルドの前に計算し、TRACEPARENTでBuildxへ渡します。CI側のスパンを送るのは、完了した実行の情報をGitHub APIで取得し、Actionsの中で一時的に動かすCollectorです。その結果、ワークフローと2つのジョブが1本のトレースにまとまり、buildジョブのビルドステップの下にBuildKitのスパンがつながりました。 2つの送信経路 今回の構成では、ビルドのトレースとGitHub Actionsのトレースを別々に送ります。両方でトレースIDと親スパンIDを合わせると、Grafana Cloudで1本に表示できます。 ビルド側の送信元は、OpenTelemetryでトレースを送る機能を持つBuildKitです。Dockerfileの各手順のスパンに加えて、クライアントであるBuildxのスパンも、BuildKitへ転送してまとめて送ります。 一方、GitHub Actions側には、BuildKitのようにトレースを送る送信元がありません。ワークフローの実行の記録はWebhookのイベントやREST APIで取得できますが、トレースの形式にはなっていないためです。この記録をスパンに変換するのが、OpenTelemetry CollectorのGitHubレシーバーです。GitHubレシーバーは、GitHubから届くworkflow_runとworkflow_jobのWebhookのイベントを受け取り、ワークフロー、ジョブ、ステップのスパンを作ります。レシーバーはCollectorに組み込んで動かすコンポーネントなので、GitHub Actions側のスパンはCollectorを通し、エクスポーターでGrafana Cloudへ送ります。 今回は、CI側のイベントの取得から送信までをActionsの中で実行する構成を選びました1。ワークフローの完了後に別のワークフローを起動し、そのランナーで一時的にCollectorを動かします。補助スクリプトが完了した実行の情報をGitHub APIで取得し、Webhookと同じ形式のイベントに組み立てて、ランナー内のGitHubレシーバーへ渡す構成です。BuildKitからの送信だけを試す段階では、このCollectorは使いません。 図1: 矢印はデータの移動を表します。左側では計算したTRACEPARENTをBuildxへ渡します。右側は完了後の別ワークフローで、補助スクリプトがGitHub APIの情報をイベント形式へ変換し、OpenTelemetry Collectorへ渡します。Collector内のGitHubレシーバーでCIスパンを生成して送信します。 題材はBusyBox 1.37.0の小さなイメージです。ファイルをコピーしてRUNで別ファイルへ書き出し、ビルドしたイメージを実行して出力も確かめました。実証用のファイル一式を公開しています。 BuildKitからGrafana Cloudへ まず、Actionsの親スパンを付けず、BuildKitからの送信だけを確認しました。Grafana Cloudで取得した接続情報を、リポジトリのActionsシークレットに次の名前で登録します。 シークレット 設定する値 GRAFANA_CLOUD_OTLP_ENDPOINT /otlpまでを含むOTLPのベースURL GRAFANA_CLOUD_OTLP_HEADERS Grafana Cloudの接続画面から取得したAuthorization=...の認証ヘッダー Actionsのステップでは、これらをOTEL_EXPORTER_OTLP_ENDPOINTとOTEL_EXPORTER_OTLP_HEADERSという環境変数に渡しています。scripts/setup-builder.shの内容は次のとおりです。 #!/usr/bin/env bash set -euo pipefail : "${OTEL_EXPORTER_OTLP_ENDPOINT:?Missing OTLP endpoint}" : "${OTEL_EXPORTER_OTLP_HEADERS:?Missing OTLP authentication headers}" docker buildx create --name ci-otel --driver docker-container \ --driver-opt image=moby/buildkit:v0.33.1 \ --driver-opt env.OTEL_TRACES_EXPORTER=otlp \ --driver-opt env.OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf \ --driver-opt "env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=${OTEL_EXPORTER_OTLP_ENDPOINT%/}/v1/traces" \ --driver-opt "env.OTEL_EXPORTER_OTLP_TRACES_HEADERS=${OTEL_EXPORTER_OTLP_HEADERS}" \ --bootstrap >/dev/null docker-containerドライバーではBuildKitが専用のコンテナで動くので、BuildKitのOTLP設定は--driver-opt env.…でそのコンテナの環境変数として渡します。プロトコルはhttp/protobufで、OTLP/HTTPを使います。トレース専用のエンドポイントは、ベースURLの末尾に/v1/tracesを足したURLです。 このbuilderを選んでdocker buildx build --builder ci-otel --load …を実行すると、BuildxとBuildKitの両方のスパンがGrafana Cloudへ届きました。ベースラインの実行から取得したのは、build .をルートにした87スパンのトレースです。イメージのビルドと実行テストも成功しました。 図2: Grafana Cloudで取得したベースラインのトレース。BuildxとBuildKitの87スパンを確認できます2。 Actionsのステップを親にする ここまでのトレースのルートはbuild .です。GitHub Actionsのビルドステップを親にするには、Buildxを実行するステップに環境変数TRACEPARENTを設定します。Buildxは環境変数からトレースコンテキストを読み込む処理でこの値を取り込み、build .を指定された親の子にします。TRACEPARENTに入れるのは、接続先のトレースIDと、親になるステップのスパンIDです。 ただし、ビルドの時点では親になるステップのスパンはまだありません。CI側のスパンは、ワークフローの完了後に作るからです。それでも親のIDを指定できるのは、GitHubレシーバーがトレースIDとスパンIDを乱数ではなく実行IDやジョブIDから決まった規則で計算するためです。ビルドの前に同じ規則で計算すれば、あとで届くステップのスパンと同じIDが得られます。 補助スクリプトscripts/ci-parent.pyは、今回の実行ID、再実行回数、ジョブIDから、レシーバーのID生成の実装と同じ規則でIDを計算します3。計算部分を抜粋すると次のとおりです。 trace_id = hashlib.sha256(f"{run}{attempt}t".encode()).hexdigest()[:32] step_id = hashlib.sha256(f"{job_id}-Build Docker image-s".encode()).hexdigest()[16:32] traceparent = f"00-{trace_id}-{step_id}-01" TRACEPARENTの値は、W3C Trace Contextのtraceparentヘッダーと同じ00-トレースID-親スパンID-01の形式です。スクリプトは、この値をGITHUB_OUTPUTへ書き出します。 ワークフローでは、このスクリプトの出力をビルドステップだけに渡します。build.ymlから該当部分を抜粋すると、次のようになります。 - name: Calculate build step parent id: build_context env: GH_TOKEN: ${{ github.token }} run: python3 scripts/ci-parent.py - name: Build Docker image env: TRACEPARENT: ${{ steps.build_context.outputs.traceparent }} OTEL_RESOURCE_ATTRIBUTES: vcs.ref.head.revision=${{ github.sha }},ci.run.id=${{ github.run_id }},ci.run.attempt=${{ github.run_attempt }},ci.repository=${{ github.repository }},experiment.mode=linked run: docker buildx build --builder ci-otel --load --tag buildkit-otel-spike:ci . ステップのスパンIDはジョブIDとステップ名から決まるので、ステップ名はスクリプトの計算に使ったBuild Docker imageと一致させます。また、ステップ名はジョブ内で一意にしておきます。同じジョブに同名のステップが2つあると、レシーバーが両方に同じスパンIDを付けてしまうからです。 OTEL_RESOURCE_ATTRIBUTESでは、検索に使う実行IDやコミットを付けています。この属性が付くのはBuildxのスパンだけで、BuildKitのスパンには付きません。 CI側のスパンの送信 ビルドステップが終わっても、ワークフロー全体はまだ実行中です。CI側のスパンは、workflow_runのcompletedで起動する送信用のワークフローが作ります。 送信用のワークフローは、完了通知に含まれる実行IDと再実行回数を環境変数で補助スクリプトへ渡します。 OBSERVED_RUN_ID: ${{ github.event.workflow_run.id }} OBSERVED_RUN_ATTEMPT: ${{ github.event.workflow_run.run_attempt }} 再実行回数を指定するのは、取得した時点で最新の再実行ではなく、通知された回のジョブを読むためです。補助スクリプトは、その回のジョブとステップの情報をGitHub APIで取得し、Webhookと同じ形式のイベントに組み立ててランナー内のCollectorへPOSTします。変換の処理はscripts/export-workflow.pyで確認できます。 collector.yamlの内容は次のとおりです4。 receivers: github: webhook: endpoint: 0.0.0.0:19418 path: /events health_path: /health service_name: github-actions scrapers: scraper: github_org: ymotongpoo processors: batch: timeout: 1s exporters: otlp_http/cloud: endpoint: ${env:OTEL_EXPORTER_OTLP_ENDPOINT} headers: Authorization: ${env:GRAFANA_AUTHORIZATION} timeout: 10s sending_queue: enabled: false retry_on_failure: enabled: false service: telemetry: logs: encoding: json pipelines: traces: receivers: [github] processors: [batch] exporters: [otlp_http/cloud] エクスポーターのendpointはベースURLのままです。otlp_httpのエクスポーターが/v1/tracesを付けるので、BuildKitにトレース専用のURLを渡したのとは指定方法が違います。認証ヘッダーには、BuildKitと同じシークレットからAuthorization=の後ろの値を取り出して渡します。 このCollectorは送信のたびに起動して停止する実証用の設定で、送信キューと再試行を無効にしています5。 自分の環境で試すには、2つのシークレットを登録し、ビルド用と送信用のワークフローをデフォルトブランチに置きます。そのうえでBuildKit linked traceを手動で実行し、ビルドとExport completed workflow traceの両方の完了を待ちます。APIの呼び出しに使うのはcontents: readとactions: readの権限を付けたGITHUB_TOKENで、GitHub AppやPATは不要です。 1本につながった結果 ビルド側の実行とCI側のスパンの送信は、どちらも成功しました。ワークフロー全体とビルドの内部が1本のトレースにつながっています。 図3: 同じ実行のワークフロー、2つのジョブ、各ステップが1本のトレースになりました。Build Docker imageの下にbuild .が接続しており、ビルド内部は折りたたんでいます。 サービスごとの内訳は次のとおりでした。 service.name スパン数 記録している処理 github-actions 21 ワークフロー、ジョブ、待ち時間、ステップ buildx 33 ビルドクライアントの処理 buildkitd 54 ビルドデーモンとDockerfileの手順 合計 108 同一トレースIDのスパン ビルド用のbuildと、その完了後に別のランナーで実行するverify-sourceの2ジョブが、同じルートにつながっています。CIの待ち時間やビルド内部の細部を省くと、親子関係は次のようになります。 BuildKit linked trace ├── build │ └── Build Docker image │ └── build . │ └── … │ └── [4/4] RUN cat message.txt > result.txt └── verify-source └── Verify source fixture build .の親IDはBuild Docker imageのスパンIDと一致し、取得した108スパンはすべて同じワークフローのルートへつながっていました6。 GrafanaのExploreでTempoのデータソースを選び、実行した時間帯に絞って、次のTraceQLで検索します。ci.run.idは、OTEL_RESOURCE_ATTRIBUTESでBuildxのスパンに付けた属性です。 { resource.ci.run.id = "40437818776" && name = "build ." } 前回の記事では、ルートのスパンだけを選ぶ条件（span:parentID = ""）でビルドの所要時間を集計しました。今回のビルドはbuild .にActionsの親があるので、この条件では選べません。手元のビルドとCIのビルドをまとめて選ぶ条件は、{ resource.service.name = "buildx" && name = "build ." }です。ベースラインとCIの両方のトレースが、この条件の検索結果に入ることを確認しました。 CI側のスパンは、送信用のワークフローが完了してから届きます。トレースを開くのは、両方のワークフローが完了してからにしてください7。 今回確認した範囲 BuildKitからGrafana Cloudへの送信と、2ジョブのワークフローへのビルド内部の接続までを確認しました。ただし、IDの生成規則はOpenTelemetryの共通の仕様ではなく、GitHubレシーバー v0.164.0の実装です。Collectorのバージョンやレシーバーのfeature gateを変えるときは、取得したトレースでbuild .が親のステップにつながっているかを確かめ直してください。 CI側の時刻はGitHub APIが秒単位で記録した値です。そのため、親子の接続が正しくても、BuildKitのスパンが親の時間範囲からわずかにはみ出すことがあります。今回の実行では、build .の終了が親のBuild Docker imageの終了を約0.84秒超えていました。 今回は信頼できるリポジトリでの手動実行だけで、matrix、reusable workflow、forkからのPR、実際の再実行、実行間でのキャッシュ再利用は検証していません8。 おわりに GitHub Actionsのワークフローとステップから、Dockerfileのどの手順やレジストリへの通信に時間を使ったかまで、1本のトレースでたどれるようになりました。自分のCIへ取り込むときには、まずBuildKitの送信だけを確認し、必要に応じてCIの親スパンを追加する順で試せます。 脚注 GitHubレシーバーは、常時稼働するCollectorでGitHubからのWebhookを受け取る使い方を想定しています。組織のCIを継続して記録するなら、その構成のほうが向いています。常時稼働のCollectorなら、送信キューと再試行を有効にして、Grafana Cloudへの送信に失敗したスパンを再送することもできます。ただし、GitHubからWebhookを受けるために、インターネットから届くエンドポイントを用意して運用する必要があります。今回はその準備をせずに試すため、Actionsの中で完結させました。 ↩︎ 図の上部に赤く表示されているHEAD HTTP HEADのエラーは、Docker Registryのトークン認証で最初に返る401の認証要求です。今回の実行では、トークン取得後の再試行が200となり、ビルドも成功しています。 ↩︎ ジョブの数値IDは、GitHub APIで今回の実行のジョブの一覧を取得し、名前がGITHUB_JOBと一致するジョブから取り出します。ジョブの表示名を変えたりmatrixを使ったりする場合は、別の方法でジョブを特定する必要があります。 ↩︎ v0.164.0のGitHubレシーバーは、トレースだけを使う場合でも、scrapersを1つ以上設定することを求めます。パイプラインはトレースだけなので、github_orgを使ったメトリクスの収集は動きません。 ↩︎ Collectorはbatchプロセッサーを通して送るので、レシーバーがHTTP 200を返しても、Grafana Cloudへの送信が成功したとは限りません。そこで補助スクリプトは、停止後のCollectorがJSON形式で出力したログを読み、levelがエラーを示していれば失敗として扱います。 ↩︎ 検証時のスクリプトと検証記録を公開しています。取得した108スパンは、スパンIDがすべて一意で、ルートが1つ、親が見つからないスパンは0でした。この検査では、送信したすべてのスパンがGrafana Cloudに届いたかまでは判定できません。 ↩︎ Tempoの最初の検索結果では、ルートのサービス名が<root span not yet received>と表示されました。その後にトレースIDで取得すると、CI側を含む108スパンがそろっていました。 ↩︎ 送信用のワークフローは、元の実行のコミットにある補助スクリプトを実行します。外部のPRが起点になる構成へ広げるときは、GitHubが説明するworkflow_runの権限と注意点を確認してください。 ↩︎

Dockerのビルドを遅くしたコミットをGrafana Tempoのトレースで見つける ! 2026年10月20日に確認した内容です。動作確認には次のバージョンを使いました。 Docker Engine 29.0.0、buildx v0.29.1（Ubuntu 26.04.1） BuildKit v0.33.1（builderのイメージをmoby/buildkit:v0.33.1に固定） grafana/otel-lgtm 0.37.0（Grafana 13.2.3、Tempo 3.1.0を含む） mcp-grafana 2.0.2 Claude Code 2.1.303 gcx 0.3.0 記事中のコマンドは、手元で使ったポート番号をotel-lgtmのデフォルトに戻して書いています。 はじめに こんにちは、Grafana Labsでデベロッパーアドボケイトをしているものです。 2026年11月3日にシンガポールで開かれるGrafana & Friends Singapore x Dockerで話すことになりました。Dockerとの共催というせっかくの機会なので、題材には以前から話そうと思っていたDockerのビルドのトレースを選んでいます。Docker自身もビルドのトレースを画面に出せますが、Grafana Tempoに送って溜めておくと、ビルドをまたいだ調査が可能です。この記事は、その手順と、溜めたトレースをAIに調べさせた結果のまとめです。 TL;DR Dockerのビルドを実行するBuildKitは、ビルドごとにOpenTelemetryのトレースを出しています。そのトレースはdocker buildx history traceでJaeger UIに開けるので、ビルドを1回調べるならその画面で十分です。ただし、BuildKitが残す履歴はデフォルトで48時間か50回分までです。同じトレースをGrafana Tempoに送ってコミットのIDを付けておけば、どのコミットからビルドが遅くなったのかをグラフで特定できます。コーディングエージェントやGrafana Assistantにトレースを読ませれば、遅くしたコミットと手順を見つけるところまで任せられます。 BuildKitが出すトレース docker buildの実体は、buildxというCLIのプラグインと、ビルドを実行するデーモンのBuildKitです。BuildKitはOpenTelemetryでトレースを出す機能を持っていて、Dockerfileの手順ひとつひとつがスパンになります。計装を足す必要はありません。 Dockerの公式ドキュメントが示しているのは、環境変数JAEGER_TRACEでJaegerへ送る方法だけです。一方、BuildKitのREADMEには、OTLPで送る方法が載っています。環境変数OTEL_TRACES_EXPORTER=otlpとOTEL_EXPORTER_OTLP_TRACES_ENDPOINTを使う方法で、後でTempoへ送るときにもこちらを使います。 トレースをどこにも送っていなくても、BuildKitはビルドの履歴にトレースを残しています。docker buildx history traceは、その履歴からトレースを取り出し、一時的に立ち上げたJaeger UIで開くコマンドです1。 docker buildx history trace --builder gf-demo --addr 127.0.0.1:16686 docker buildx history traceで開いたJaeger UIの画面。上部はトレースの概要で、下はDockerfileの手順のスパンのあたりを切り出した この画面では、全体の20.27秒のうち19.24秒を[build 4/4] RUN go mod download && go buildの手順が占めていることがわかります。ビルドが遅いと感じたときに、どの手順を疑えばよいかは、この画面だけで判断できます。 Tempoへ送信 同じトレースをGrafana Tempoへ送るには、buildxのbuilderを作るときに環境変数を2つ渡すだけです。送り先にはgrafana/otel-lgtmを使いました。GrafanaとTempoに加えてPrometheusとOpenTelemetry Collectorも1つにまとめたコンテナで、そのOTLPのポートへ送ります。 docker run -d --name lgtm -p 3000:3000 -p 4317:4317 -p 4318:4318 grafana/otel-lgtm:0.37.0 docker buildx create --name gf-demo --driver docker-container \ --driver-opt image=moby/buildkit:v0.33.1 \ --driver-opt network=host \ --driver-opt env.OTEL_TRACES_EXPORTER=otlp \ --driver-opt env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=127.0.0.1 \ --bootstrap docker buildx build --builder gf-demo --load . docker-containerドライバーのbuilderでは、BuildKitはコンテナの中で動きます。network=hostを付けたのは、そのBuildKitからホストのループバックアドレスに公開したOTLPのポートへ届かせるためです2。 トレースには、buildx（サービス名buildx）とBuildKit（サービス名buildkitd）のスパンが1本につながって入ります。ルートのスパンはbuild .です3。クライアント側のbuildxには環境変数を渡していませんが、buildxのスパンもTempoに届きます4。 同じ種類のビルドのトレースをGrafanaのExploreで開いた画面。上部はトレースの概要で、下はDockerfileの手順のスパンのあたりを切り出した ビルドを遅くしてみる ここまでなら、Dockerの画面で十分です。Tempoへ送る価値が出てくるのは、ビルドが1回ではなく、CI/CDのように継続的に多数行われるときです。 BuildKitの設定では、ビルドの履歴はデフォルトでmaxAge = 172800（48時間）、maxEntries = 50です。docker buildx history traceで開けるのは、この履歴に残っているビルドだけで、--compareで2回分を並べて比べる場合も同じ制約がかかります。 使い捨てのCIのrunnerでは、ジョブが終わればbuilderごと履歴も消えます。DockerはGitHub Actions向けに、ビルドの記録をZIPのアーティファクトとして残す機能を持っています。ただ、それをDocker Desktopに取り込んで見るのは、CIの実行1回分ずつです。「どのコミットからビルドが遅くなったのか」を答えるには、何十回分ものビルドを取得して比較しなければなりません。 そこで、コミットを重ねながら何度もビルドし、全部のトレースをTempoに溜めました。題材は、Prometheusのクライアントライブラリに依存する小さなGoのHTTPサーバーです。はじめは、依存のダウンロードとビルドのキャッシュをキャッシュマウントで再利用するDockerfileでビルドしました。 FROM golang:1.26-alpine AS build WORKDIR /src COPY go.mod go.sum ./ RUN --mount=type=cache,target=/go/pkg/mod \ go mod download COPY . . RUN --mount=type=cache,target=/go/pkg/mod \ --mount=type=cache,target=/root/.cache/go-build \ go build -o /out/hello . FROM gcr.io/distroless/static-debian13 COPY --from=build /out/hello /hello ENTRYPOINT ["/hello"] 途中で、Dockerfileを「整理した」コミットを入れて、キャッシュマウントをわざと外しました。あわせてCOPY . .も依存のダウンロードより前に移した状態です。この順序だと、ソースを1行変えるたびに依存のダウンロードと全パッケージのコンパイルがやり直しになります。buildのステージは以下のように変わっています。 FROM golang:1.26-alpine AS build WORKDIR /src COPY . . RUN go mod download && go build -o /out/hello . 前後には、Dockerfileにラベルを足すだけのコミットを1つずつ混ぜました。git logにはDockerfileを変えたコミットが3つ並ぶので、どれでビルドが遅くなったのかはトレースを見ないとわかりません。 各ビルドには、そのときのコミットのIDを付けました。buildxはOTEL_RESOURCE_ATTRIBUTESを読むので、ここにリソース属性vcs.ref.head.revisionとして入れて渡せば済みます。ただし、この属性が付くのはbuildxのスパンだけで、buildkitdのスパンは対象外です。 OTEL_RESOURCE_ATTRIBUTES="vcs.ref.head.revision=$(git rev-parse --short HEAD)" \ docker buildx build --builder gf-demo . ここまでの各ビルドの所要時間を、TraceQLのメトリクスのクエリでグラフにしました。ルートのスパンだけを選んで、30秒ごとの最大値を取っています5。 { resource.service.name = "buildx" && span:parentID = "" } | max_over_time(duration) 各ビルドの所要時間をTraceQLのmax_over_timeでGrafanaに描いた画面。点の時刻は30秒の区間の終わりを表す トレースで見ると、キャッシュマウントを外す前のビルドは1.9〜2.5秒で終わり、外した後は20.3〜21.7秒に延びて戻りません6。跳ねた直後のトレースを開けば、vcs.ref.head.revisionからコミットがわかります。このデモでは「整理した」コミットでした。遅くなる前後のトレースを並べると、どの手順が延びたのかもわかります。 遅くなる前のビルドのトレースをGrafanaのExploreで開いた画面。依存のダウンロードはキャッシュから読まれ、go buildは約0.9秒で終わっている 遅くなる前は、依存のダウンロードの手順がload cache:で始まるスパンになり、キャッシュから読まれています。遅くなった後は、手順がRUN go mod download && go buildの1つにまとまり、その手順だけで19.36秒かかっています。 手順のスパン名には、RUNのコマンドがそのまま入ります。Dockerfileを変えるとスパン名も変わるので、変更の前後を1本の系列で比べるなら、ルートのスパンの所要時間を使ってください。 エージェントに修正させる Tempoに溜めたトレースは、人だけでなくプログラムからも問い合わせられます。mcp-grafanaは、GrafanaをMCPのサーバーとして公開するツールです。Tempo向けには次のようなツールを持っています。 search_tempo_traces：TraceQLでトレースを検索する query_tempo_metrics：TraceQLのメトリクスを計算する diff_tempo_traces：2本のトレースを比べる これをコーディングエージェントにつなぎ、ビルドが遅くなった原因を調べさせました。mcp-grafanaの起動方法とMCPのクライアントへの登録方法は、mcp-grafanaの公式ドキュメントを参照してください。書き込み系のツールは--disable-writeで外せるので、調査に使うだけなら外しておくと安心です。 今回はClaude Codeを使いましたが、MCPのサーバーを使えるほかのコーディングエージェント（Codexなど）でも同じようにできるでしょう。Gitの履歴の参照やdocker buildx buildの実行など、必要なツールは適宜許可してください。頼んだ内容は次のとおりです。 コンテナのビルドが最近遅くなりました。ビルドのトレースはTempo（Grafanaのデータソース UID "tempo"）に送っています。各ビルドにはサービス buildx の "build ." という名前のスパンがあり、そのスパンのリソース属性 vcs.ref.head.revision にビルドしたコミットが入っています。Tempoのトレースを使って、どのコミットでなぜビルドが遅くなったのかを調べ、このディレクトリのDockerfileを直してください。直したら docker buildx build --builder gf-demo --output type=cacheonly . で再ビルドし、新しいビルドが速くなったことをTempoで確かめてください。新しいトレースが検索できるようになるまで1〜2分かかることがあります。 エージェントは、まずGitの履歴を読み、search_tempo_tracesでコミットごとの所要時間を並べました。そこから導いた結論は、所要時間が約2秒から約21秒に跳ねたのは「整理した」コミットだというものです。遅くなる前と後のトレースをdiff_tempo_tracesで比べ、RUN go mod download && go buildの手順に約19.9秒かかるようになったことと、以前は依存のダウンロードがキャッシュから読まれていたことも確かめました。 修正では、go.modとgo.sumを先にコピーする順序とキャッシュマウントを元に戻し、後から足されたラベルは残しました。再ビルドのあとは新しいトレースが検索できるようになるのを待ち、所要時間が2.31秒に戻ったことをTempoで確かめています。全体で約3分かかり、そのうち約1分半は新しいトレースを待つ時間でした。 オブザーバビリティのSaaSに送る利点 ここまでは、手元のotel-lgtmにトレースを送ってきました。otel-lgtmは、イメージの説明にあるとおり開発、デモ、テストのための環境で、コンテナを消せばトレースも消えます。ビルドをまたいで問いを立てるには、トレースを長く残せて、CIのrunnerからも送れる場所が必要です。Grafana CloudのようなオブザーバビリティのSaaSに送ると、その場所を自分で運用せずに済みます。たとえばGrafana Cloudでも、BuildKitで保持する量よりも圧倒的に多くのトレースを保持できます7。 Grafana Cloudへ送るときも、builderに渡す環境変数を変えるだけです。Grafana CloudのOTLPのゲートウェイにはOTLP/HTTPで送るので、BuildKitのデフォルトのgRPCからhttp/protobufに切り替えます。エンドポイントと認証のヘッダーは、Grafana CloudのポータルのOpenTelemetryのタイルで生成した値をそのまま使いました。 docker buildx create --name gf-cloud --driver docker-container \ --driver-opt image=moby/buildkit:v0.33.1 \ --driver-opt env.OTEL_TRACES_EXPORTER=otlp \ --driver-opt env.OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf \ --driver-opt "env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=${OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces" \ --driver-opt "env.OTEL_EXPORTER_OTLP_TRACES_HEADERS=${OTEL_EXPORTER_OTLP_HEADERS}" \ --bootstrap トレース専用の変数（名前にTRACESが入るもの）だけを渡しているのは、BuildKitがOTEL_EXPORTER_OTLP_ENDPOINTを見るとメトリクスの送信も始めるためです8。このbuilderで手元と同じ20回のビルドを流すと、21本（動作確認の1回を含む）のトレースが全部Grafana CloudのTempoに届きました9。トークンはbuilderのコンテナの環境変数とbuildxの設定ファイルに残るので、使い終わったらdocker buildx rm gf-cloudでbuilderを消してください。 Grafana Assistantに調査させる SaaSの側には、溜めたトレースを調べる機能も最初から用意されています。その例が、Grafana Cloudに組み込まれたAIアシスタントのGrafana Assistantです。ドキュメントによると、AssistantはTempoを含むデータソースに問い合わせ、TraceQLのクエリを書いて実行できます。トレースのIDを渡せば1本のトレースをウォーターフォールで表示でき、実験的な機能として、あるトレースと比べる候補のトレースを探すこともできます。 前の節でエージェントに調べさせたときは、mcp-grafanaを起動してエージェントに登録する準備が必要でした。Assistantは最初からスタックのデータソースにつながっているので、この準備は要らないのが利点です。ビルドが遅くなったことに気づいた人が、Grafanaの画面からそのまま「ビルドの所要時間はいつから延びたか」と聞けば済みます。原因の調査まではAssistantに任せ、Dockerfileを直して再ビルドするところはリポジトリを編集できるコーディングエージェントに任せる、という分担です。 実際に、Grafana Cloudへ送った20回分のビルドについてAssistantに聞きました。AssistantはGrafanaの画面のほか、Grafanaのコマンドラインツールのgcxからも呼べるので、今回はgcxを使いました。伝えたのは、コーディングエージェントに渡したのと同じ前提だけです。 gcx assistant prompt 'コンテナのビルドが最近遅くなりました。ビルドのトレースはTempo（データソース grafanacloud-shophub-traces）に送っています。各ビルドにはサービス buildx の "build ." という名前のスパンがあり、そのスパンのリソース属性 vcs.ref.head.revision にビルドしたコミットが入っています。過去1時間のトレースから、ビルドの所要時間がいつから延びたのか、どのコミットからなのか、ビルドのどの手順が遅くなったのかを調べてください。' Assistantはデータソースへの問い合わせを17回行い、132秒で答えを返しました。答えの冒頭は次のとおりです。 結論: ビルド時間は、およそ 07:09 UTC に約2秒から約20秒へ延びました。最初に遅くなったコミットは 9eac8b9 です。遅くなった手順は Dockerfile の RUN go mod download && go build -o /out/hello . です。 9eac8b9は「整理した」コミットで、答えは正しいものでした。手順についても、速いビルドの6ステップと遅いビルドの4ステップを比べた結果、遅いほうではRUN go mod download && go buildの1つの手順が約19.4秒、全体の約95%を占めるという答えです。依存の取得のキャッシュが効かなくなったことを原因として推測しつつ、「このデータにはコミットの親子順がありません」と書き、時間の順で最初に遅くなったコミットだという限定も付けていました。動作確認のために送った30.2秒のビルドも、コミットの属性がないことに気づいて、ほかのビルドとは別に扱っていました。 Assistantは、自前で運用しているGrafanaからGrafana CloudのAssistantにつないで使うこともできます10。 おわりに Dockerは、ビルドのトレースを出す仕組みも、それを確認する画面も持っています。ビルドを1回調べるならDockerの画面で十分で、Tempoに送る意味が出てくるのはビルドをまたいだ問いを立てるときだと確認しました。 この記事では、長くなるので、ビルドのトレースをGrafanaに送り、溜めたトレースをAIに調べさせるところまでにしました。次は、これを踏まえてCIの設定も含めて書きたいと考えています。CIのジョブがTRACEPARENTを渡せば、ビルドのスパンをジョブのスパンの下に入れて、パイプライン全体の中でビルドを見られるはずです。 ビルドが遅くなったと感じたことがあるなら、まず手元のbuilderに環境変数を2つ足して、トレースを溜めるところから始めてみてください。コンテナビルドでもオブザーバビリティを高めていきましょう。 脚注 標準出力が端末でないときは、Jaeger UIを起動せずに、トレースをJaegerの形式のJSONとして標準出力に書き出しました。 ↩︎ 確認したのはLinuxのDocker Engineだけです。Docker Desktopではnetwork=hostの意味が変わるので、この設定のままでは届かない可能性があります。 ↩︎ buildxは、環境変数TRACEPARENTがあると、それを親のトレースコンテキストとして扱います。この変数が設定されたシェルからビルドすると、ビルドがその親のトレースに入り、build .がルートになりません。ビルドを1回ずつ別のトレースにしたいなら、TRACEPARENTを外してから実行してください。buildx v0.29.1は、cmd/buildx/tracing.goでBuildKit v0.25.0のutil/tracing/envを読み込んでいます。このパッケージがTRACEPARENTとTRACESTATEを読みます。buildxのもっと新しいバージョンでは、同じ役割のパッケージがutil/tracing/childprocessに変わっています。 ↩︎ buildx v0.29.1は、BuildKitに接続するときにclient.WithTracerDelegateを指定しています（driver/manager.go）。buildxは自分のスパンをBuildKitに渡し、BuildKitがまとめて送ります。BuildKitのREADMEにも、buildctlはスパンをbuildkitdに転送するので、exporterはデーモン側だけに設定すればよいとあります。また、docker-containerドライバーではbuildctl dial-stdioというトレースがビルドとは別に毎回届くので、検索するときはresource.service.name = "buildx"で絞ると見やすくなります。 ↩︎ quantile_over_time(duration, .5)で中央値を取ると、約20秒のビルドが、区間を60秒にすると24.3秒、30秒にすると34.4秒になります。quantile_over_timeは所要時間を2のべき乗の幅のバケットに入れて近似するので、値がバケットの境目に寄ります。max_over_timeは、区間に入ったトレースの所要時間の最大値をそのまま返します。 ↩︎ グラフの範囲から外した最初のビルドは、キャッシュが空だったので38.1秒かかりました。 ↩︎ Grafana Cloudの料金のページによると、Tracesの保持期間はFreeプランで14日、Proプランで30日です。BuildKitの履歴の48時間か50回分より長く、手元の開発機のビルドとCIのビルドを同じTempoに入れて、同じクエリで比べられます。 ↩︎ BuildKit v0.33.1のutil/tracing/detect/otlp.goは、OTLPのクライアントをオプションなしで作っています。OpenTelemetryのGoのexporterは、送り先、プロトコル、ヘッダーを環境変数から読みます。 ↩︎ Grafana CloudのTempoでビルドのトレースを検索するときは、name = "build ."で絞ると確実に見つかります。 ↩︎ Grafana Assistantの紹介のページによると、自前で運用しているGrafanaから使う場合も、チャット、ダッシュボードの作成、クエリ、ナビゲーションは使えます。ただし、複数のデータソースを調べてレポートにまとめるInvestigationsと、Grafana CloudのMCPへの接続は、Grafana Cloudに限られた機能です。 ↩︎

LBM流体解析ツールVirtualFluidsの活用【01:Docker導入方法と動作確認】 この文書では、WSL2のDocker上でLBM（格子ボルツマン法）流体解析ツールVirtualFluidsを活用する方法を紹介します。 VirtualFluidsは、ドイツのブラウンシュヴァイク工科大学（iRMB）で開発されている、格子ボルツマン法（LBM）をベースにしたオープンソースの流体解析（CFD）ソフトウェアコードです。従来のナビ・ストークス方程式を直接解く手法とは異なり、微視的な粒子集団の「衝突」と「移動」に基づくメソスケールのアプローチを採用しています。 最大の技術的特徴として、計算の大部分が局所的なグリッド間で完結するLBMの特性を活かしたGPUやマルチコア環境における超並列・HPC（ハイパフォーマンスコンピューティング）への高度な最適化が挙げられ、分散型の前処理・後処理機能と組み合わせることで100億を超える自由度（DOFs）を持つ大規模かつ高解像度なシミュレーションを実行可能です。 さらに、複雑なCAD形状や入り組んだ境界に対してもデカルトグリッドベースで高精度な境界条件処理を行えるほか、乱流や多相流などの複雑な物理現象を組み込んだシミュレーションにも幅広く対応しており、最先端の研究開発やエンジニアリングにおいて高効率で高精度な数値解析を実現する強力な解析ツールとなっています。 VirtualFluids公式サイト：irmb.gitlab-pages.rz.tu-bs.de VirtualFluids公式GitHubリポジトリ なお、VirtualFluidsに関する技術的な詳細を記述した論文が、以下で公開されています。 「VirtualFluids – open source parallel LBM solver」 sciencedirect.com VirtualFluidsの重要機能の解説 VirtualFluids は、ドイツのブラウンシュヴァイク工科大学（TU Braunschweig）などで開発されている、格子ボルツマン法（LBM）を用いたオープンソースの流体解析ソフトウェアです。GPUやCPUによる並列計算に対応し、複雑な流れや大規模な乱流解析を効率的に実行することを目的としています。以下に、主要な機能を技術的な内容と用途を含めて整理します。 - 格子ボルツマン法（Lattice Boltzmann Method：LBM）： VirtualFluidsは、流体を多数の仮想粒子の運動として表現する格子ボルツマン法を採用しています。各格子点における粒子の分布関数を時間発展させることで、流体の速度や圧力などを計算します。従来の有限体積法などとは異なり、分布関数の衝突（Collision）と伝播（Streaming）を繰り返すことで流れを解析します。LBMは局所的な計算を中心とするため、GPUの並列処理と相性がよく、大規模な3次元流体解析に適しています。 - Cumulant衝突モデル： VirtualFluidsは、従来のBGKモデルに加えて、Cumulant（キュムラント）に基づく衝突モデルを利用できます。Cumulantモデルは、分布関数をキュムラント空間に変換して衝突計算を行う手法であり、各次数のキュムラントを適切に緩和させます。通常のBGKモデルでは、すべての非保存モーメントを基本的に同じ緩和時間で扱いますが、Cumulantモデルでは異なる成分の緩和を制御できます。これにより、数値安定性の向上や高Reynolds数流れへの適用が期待できます。 - GPU計算（CUDA）： NVIDIA CUDAを利用して、GPU上でLBMの衝突・伝播処理を並列実行できます。LBMでは各格子点で比較的独立した計算を行うため、GPUの多数の演算コアを活用しやすい特徴があります。CPUと比較して、大規模な格子を使用する流体解析の計算時間を短縮できる可能性があります。特に、複雑な3次元流れや乱流解析など、膨大な格子点を扱う問題で有効です。 - マルチGPU・MPI並列計算： VirtualFluidsは、複数GPUや複数計算ノードを利用する大規模並列計算に対応しています。計算領域を複数の領域に分割し、それぞれのGPUやCPUに担当させることで、計算負荷を分散します。領域境界では、隣接する計算領域間で分布関数などの情報を交換します。MPI（Message Passing Interface）を利用することで、複数の計算ノードを接続した並列解析環境を構築できます。単一GPUのメモリ容量を超えるような大規模解析にも応用できます。 - マルチスケール格子・格子細分化（Grid Refinement）： VirtualFluidsは、計算領域のすべてを同じ格子幅で分割するのではなく、必要に応じて異なる解像度の格子を配置する機能を備えています。例えば、物体周辺や境界層、渦が発生する領域には細かい格子を配置し、流れが比較的単純な領域には粗い格子を使用します。これにより、全領域を細かい格子で計算する場合と比較して、計算格子数やメモリ使用量を削減しながら、重要な領域の解析精度を確保することを目指します。異なる解像度の格子間では、物理量や分布関数の補間・交換処理が必要になります。 - 乱流解析（Turbulence Modeling）： VirtualFluidsでは、乱流を扱うための計算機能が用意されています。乱流は大小さまざまな渦が時間的・空間的に変化する現象であり、十分な解析精度を確保するには細かな空間解像度と時間解像度が必要です。乱流モデルを利用する場合には、未解像の小さな渦の影響をモデル化して、計算負荷を抑えながら乱流の特徴を再現します。特にLES（Large Eddy Simulation）などのアプローチは、建築物周辺の風環境、自動車周辺の流れ、複雑な流路の流動解析などへの応用が考えられます。 - 境界条件（Boundary Conditions）： VirtualFluidsは、固体壁や流入口、流出口などの境界条件を設定して流体解析を行います。例えば、No-slip条件では壁面で流体速度を壁面速度と一致させ、Velocity条件では流入口などに指定した速度を与えます。Pressure条件では圧力に関する境界条件を設定し、Outflow条件では流体が計算領域から自然に流出するように処理します。これらの境界条件を適切に設定することで、実際の流路や物体周辺の流れを再現できます。 - 移流拡散・熱輸送解析（Advection-Diffusion）： 流体の速度場だけでなく、温度や濃度などのスカラー量が流れによって移動・拡散する現象を扱う機能があります。例えば、空気の流れに伴う温度分布の変化や、流路内の物質濃度の輸送などを解析できます。流体の移動による移流と、温度差・濃度差による拡散を組み合わせて計算することで、流れと熱・物質輸送を関連付けた解析に利用できます。 - 多成分流体解析（Multicomponent Flow）： 複数の流体成分が存在する系を扱うための解析機能です。例えば、異なる流体の混合や、複数の成分が共存する流れなどへの応用が考えられます。単一成分の流体解析とは異なり、各成分の濃度や相互作用を考慮する必要があります。混合現象や成分輸送を扱う研究に利用できる機能です。 - 複雑形状・物体周辺の流れ解析： VirtualFluidsは、複雑な形状を持つ物体や流路を対象とした流体解析に対応しています。計算格子と物体表面の位置関係に基づいて境界処理を行い、物体表面での流速条件を表現します。自動車周辺の空気抵抗、建築物周辺の風の流れ、機械内部の流路など、単純な直方体領域では表現できない形状を対象とする解析に応用できます。 - 解析結果の出力と可視化： 解析結果をVTKなどの可視化形式で出力し、速度、圧力、渦構造などの空間分布を確認できます。また、時間ステップごとの結果を保存することで、流れの時間変化や渦の発生・消滅を観察できます。出力したデータはParaViewなどの可視化ソフトウェアで読み込み、断面表示、流線、等値面、ベクトル表示などを利用して解析結果を評価できます。 - Python連携（pyfluids）： VirtualFluidsは、Pythonバインディングを通じてC++で実装された解析機能をPythonから利用できます。これにより、解析条件の設定、計算処理の呼び出し、解析データの後処理などをPythonで扱うことができます。NumPyやMatplotlibなどのPythonライブラリと組み合わせることで、解析結果の統計処理、グラフ化、パラメータスタディなどを実施できます。また、機械学習による流体解析の高速化や、解析結果を利用したデータ駆動型モデルの構築にも応用できます。 VirtualFluidsの技術的な位置付け | 技術分野 | 主な機能 | 期待される効果 | | ------ | --------------- | ----------- | | LBM | 分布関数による流体解析 | 局所的な並列計算 | | 衝突モデル | BGK、Cumulantなど | 数値安定性の向上 | | GPU計算 | CUDA | 計算の高速化 | | 並列計算 | MPI、マルチGPU | 大規模解析 | | 格子制御 | Grid Refinement | 計算効率と解像度の両立 | | 乱流解析 | LESなど | 非定常乱流の再現 | | 物理現象 | 移流拡散・多成分流れ | 熱・物質輸送への応用 | | Python | pyfluids | 解析自動化・AI連携 | | 可視化 | VTK、ParaView | 解析結果の評価 | 総括すると、VirtualFluidsの大きな特徴は、Cumulant LBMによる数値安定性、GPU・MPIによる大規模並列計算、マルチスケール格子による計算効率の向上を組み合わせられることです。特に、建築物周辺の風環境解析や自動車周辺の空力解析など、複雑な3次元形状と非定常乱流を扱う研究に注目できるソフトウェアです。 ※各機能の実装状況や利用可能なモデルは、VirtualFluidsのバージョンやビルド設定によって異なります。実際の研究で使用する場合は、公式ソースコードと各モデルの実装を確認する必要があります。 VirtualFluidsを活用する計算機環境 VirtualFluidsを利用するためには、以下の「Documentation / Getting Started」を見ると「We recommend using VirtualFluids with Docker：VirtualFluidsはDockerを用いた活用を推奨」とあります。 irmb.gitlab-pages.rz.tu-bs.de そこで、以下の「Getting Started with Docker」の手順を確認します。 irmb.gitlab-pages.rz.tu-bs.de 対応プラットフォームと開発環境 VirtualFluidsは、主に WindowsとLinux の2つのプラットフォームに対応しています。本記事では、Windows11, WSL2, Docker, Visual Studio Code（VS Code）、ターミナル、UbuntuのDockerイメージを組み合わせた開発環境を使用します。この構成を採用する理由は、WindowsとLinuxの両方で共通の開発環境を構築できるためです。また、Dockerを利用することで、開発に必要なソフトウェアを個別にインストールする手間を大幅に削減できます。 使用するUbuntuのDockerイメージには、以下の開発ツールがあらかじめ含まれています。 　コンパイラ　CMake（ビルド管理ツール）　MPI（分散メモリ並列計算） 　OpenMP（共有メモリ並列計算）　Clang-Format（C++ソースコードの整形ツール） このほか、開発に必要な各種ツールも用意されています。 重要な注意点： Docker環境でVirtualFluidsのGPU計算機能を利用する場合は、Windows 11以上が必要です。これは、Windows上のDockerからGPUを利用するための環境要件に関係しています。 要するに、 VirtualFluidsでは、VS CodeとUbuntuベースのDockerを組み合わせることで、OSによる環境の違いを抑え、必要な開発ツールをまとめて利用できる環境を構築できます。またGPUを利用するWindows環境では、Windows 11が必須条件となります。 Windows+DockerでGPUを使う方法 Windows 11でDockerのGPU利用にWSL2が必要な理由 結論からいうと、Windows版Docker Desktopは、Linuxコンテナを動かすためにLinuxカーネルを必要とするためです。Windows 11では、そのLinuxカーネルを提供する役割をWSL2が担っています。特にVirtualFluids、XLB、NVIDIA WarpのようなCUDAを利用する科学技術計算では、この仕組みが重要になります。 【WindowsとLinuxの違い】 まず、Dockerコンテナの仕組みを理解すると分かりやすくなります。Dockerコンテナは、独立した小さなOSのように見えますが、実際にはホスト側のカーネル機能を利用します。例えば、VirtualFluidsのDockerイメージがUbuntuベースの場合、コンテナ内ではLinuxのカーネル機能が必要です。 WSL2を使わないWindows環境：　 Windows 11：Windowsカーネル → Linuxコンテナとはカーネルが異なる → Linuxコンテナ：Linuxカーネルが必要 WSL2を利用するWindows環境： Windows 11：Windowsカーネル → WSL2：Linuxカーネルを提供する軽量VM環境 → Docker Linuxコンテナ：Ubuntu、CUDA、VirtualFluidsなど つまり、WSL2はWindows上でLinux環境（GPUを活用する）を提供する基盤です。 【GPUを利用する場合の仕組み】 GPUの場合は、さらに一段階あります。Windows 11では、NVIDIAのGPUドライバがGPUを管理します。WSL2は、そのGPU機能をLinux側に公開します。そのため、LinuxコンテナからもGPUを利用できます。 ■ NVIDIA GPU：RTX A4500など ⇅ Windows NVIDIA Driver：GPUを管理するドライバ ⇅ WSL2 GPU連携：/dev/dxg、CUDA連携ライブラリ ⇅ Docker Linux Container：NVIDIA Container RuntimeによるGPU公開 ⇅ CUDAアプリケーション：VirtualFluids / XLB / NVIDIA Warp GPU計算の命令は、最終的にWindows側のNVIDIAドライバを通じて実際のGPUに送られます。ここで重要なのは、WSL2の中にWindows用とは別のNVIDIAディスプレイドライバをインストールする必要はないということです。基本的にはWindows側の対応ドライバを使用します。 【なぜWindowsのDockerだけではGPUを使えないのか？】 ここは少し注意が必要です。Docker Desktopには複数の実行方式があります。 | Dockerの実行方式 | Linuxコンテナ | NVIDIA CUDA GPU | | ------------------ | ------------- | ------------------------------------ | | WSL2バックエンド | ○ | ○ | | Hyper-Vバックエンド | ○ | Docker DesktopのLinuxコンテナGPUパススルーは非対応 | | Windowsコンテナ | ×（Linux用ではない） | Linux CUDAコンテナとは別方式 | Docker公式も以下の資料では、Windows上で --gpus を使ってLinuxコンテナにGPUを渡す機能は、WSL2バックエンドで利用可能と説明しています。したがって、VirtualFluidsのようなLinuxベースのCUDAアプリケーションでは、WSL2バックエンドを選ぶのが適切です。 「GPU support in Docker Desktop for Windows」 docs.docker.com 【WSL2を使うメリット】 研究・教育で利用する場合、次のメリットがあります。一方、WSL2にはCUDAの一部機能に制約があります。例えばUnified Memoryの完全な機能や、一部のGPUデバッグ・プロファイリング機能には制限があります。 | 項目 | メリット | | ------- | ----------------------- | | Linux環境 | Ubuntuのコマンドやライブラリを利用できる | | GPU | NVIDIA CUDAを利用できる | | Docker | Linuxコンテナをそのまま実行できる | | Python | Linux版Python環境を利用できる | | C++ | GCC、CMakeなどを利用できる | | 再現性 | Dockerイメージで環境を共有できる | 【今回のVirtualFluidsに適した構成】 これまでのXLBやWarpの利用環境と比較すると、次の構成が扱いやすいと思います。なお、WSL2はDocker Desktop専用ではありません。WSL2のUbuntuにDocker Engineを直接インストールして使う方法もあります。 | ソフトウェア | 役割 | | ----------------- | -------------- | | Windows 11 | ホストOS | | NVIDIA Driver | GPU管理 | | WSL2 Ubuntu 24.04 | Linux環境 | | Docker Desktop | コンテナ管理 | | CUDA | GPU計算 | | VirtualFluids | 流体解析 | | pyfluids | Pythonインターフェース | | ParaView | 解析結果の可視化 | 本検証でのおすすめは、「Windows 11 + WSL2/Ubuntu 24.04 + Docker Desktop + GPU対応VirtualFluids」 です。 これならWindows側でParaViewやVS Codeを使いながら、Linux側でC++・CUDA・Pythonの解析環境を管理できます。 改めて今回構築する環境は以下の通りです。 - OS：Windows 11 - GPU：GeForce RTX 3070 Ti - コンテナ：UbuntuベースのVirtualFluids公式Docker環境 - 開発環境：Docker Desktop + WSL2 + Ubuntu - 計算：NVIDIA GPUを利用するCUDA版VirtualFluids - Python：後半でPythonバインディングの利用を確認 RTX 3070 TiはAmpere世代で、CUDAのCompute Capabilityは 8.6 です。GPU向けにソースからビルドする場合、この値をビルド設定に指定するのが基本です。 参考になる公式資料： - Docker：WindowsでのGPUサポート - Microsoft：WSL2でNVIDIA CUDAを有効にする - NVIDIA：CUDA on WSL User Guide - Docker：WSL2バックエンドの説明 動作環境Ubuntu-24.04-VFluidsの準備 ここでは、「WSL2上のUbuntu24.04LTS」を用いることにして、VirtualFluids用のDocker環境を作ることにします。初めて取り組む方は、以下の手順でWSL2上にUbuntu24.04を、導入してください。 qiita.com WSL2上に複数のUbuntu24.04を利用する場合には、基盤となるUbuntuを導入して、これをexportしてから、目的の環境としてimportします。具体的な以下の手順で行います。環境名としては「Ubuntu-24.04-VFluids」とします。 qiita.com PowerShell 7.6.8 PS C:\Users\ryos> wsl --import Ubuntu-24.04-VFluids .\WSL2VM\Ubuntu-24.04-VFluids .\Ubuntu-24.04-Base.tar [======================== 41.6% ] ↓ この操作を正しく終了しました。 PS C:\Users\ryos> wsl -l -v NAME STATE VERSION * Ubuntu-24.04 Stopped 2 Ubuntu-24.04-VFluids Stopped 2 この導入で、作成したUbuntu-24.04-VFluidsを起動したとき、プロンプトが＃でroot環境の時には、先のQiitaに示した手順で、一般ユーザー（ここではryos）にしておきます。 Ubuntu環境を起動して、最新「Ubuntu 24.04.5 LTS」に更新しておきます。 PS C:\Users\ryos> wsl -d Ubuntu-24.04-VFluids dalab@dalab2312nb01:/mnt/c/Users/ryos$ cd dalab@dalab2312nb01:~$ sudo apt update [sudo] password for dalab: ： dalab@dalab2312nb01:~$ sudo apt upgrade ： dalab@dalab2312nb01:~$ lsb_release -a No LSB modules are available. Distributor ID: Ubuntu Description: Ubuntu 24.04.5 LTS Release: 24.04 Codename: noble NVIDIA GPUドライバの確認、Windowsに導入したNVIDIA Driverが、PowerShellとUbunutで認識されているか、確認します PS C:\Users\ryos> nvidia-smi.exe Sat Oct 24 20:43:20 2026 +-----------------------------------------------------------------------------------------+ | NVIDIA-SMI 595.97 Driver Version: 595.97 CUDA Version: 13.2 | +-----------------------------------------+------------------------+----------------------+ ： dalab@dalab2312nb01:~$ nvidia-smi Sat Oct 24 20:43:44 2026 +-----------------------------------------------------------------------------------------+ | NVIDIA-SMI 595.58.02 Driver Version: 595.97 CUDA Version: 13.2 | +-----------------------------------------+------------------------+----------------------+ | GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC | ： Docker Desktop for Windowsの導入 ここでは、WSLのUbuntuからDockerを利用しますが、ここでは「Docker Desktop for Windows」を、Windowsに導入します。WindowsのWebブラウザで以下の公式サイトに接続します docker.com 左上の青色リンク「Download Docker Desktop」の「Download for Windows - AMD64」に進みます。 ダウンロードフォルダに、ファイル「Docker Desktop Installer.exe(612MB)」が保存されます。 このインストーラーをダブルクリックして、以下の設定でインストールします。 ・Configuration：Per-user installation を選択します。WSL2 backendを用いる場合はこちらが必要です。[OK]で進む。 ・Docker Desktop 4.963：ダウンロードとインストールが進む。完了したら、[Close]で終わる。 Windowsの「Docker Desktop」をスタートメニューなどから起動します。 ・「Docker Subscription Service Agreement」をよく読んで、[Accept]で進む。 ・「Welcome to Docker」でユーザー登録をします。「Work・Personal」で選択できますし、右上[Skip]も可能です。 ・上部の歯車の「Settings」に進みます。右側メニューの「General」に進み、「Choose how to run Docker containers」で、「WSL 2」を確認します。 ・左側メニューの「Resources」の「WSL Integration」タブに進み、「Enable integration with additional distros」において、Dockerを利用するWSLの「Ubuntu-24.04-VFluids」を選択し、[Apply Restart Engine]で進む。 ・「docker desktop」のツールは、起動した状態で以下の作業を行います。 利用するWSLの「Ubuntu-24.04-VFluids」において、dockerコマンドの利用を確認します。 dalab@dalab2312nb01:~$ docker --version Docker version 29.9.2, build a82e528 dalab@dalab2312nb01:~$ docker info Client: Version: 29.9.2 Context: default Debug Mode: false ： 両方とも正常に実行できれば、Dockerの基本環境は準備できています。WindowsではDocker DesktopのWSL2バックエンドを利用するのが、公式ガイドに沿った構成です。 DockerからGPUが使えるか確認 VirtualFluidsのインストールに進む前の確認手順として、汎用CUDAコンテナでGPUを確認します。Ubuntuのターミナルで実行してください。 dalab@dalab2312nb01:~$ sudo docker run --rm --gpus all \ nvidia/cuda:12.8.1-base-ubuntu24.04 \ nvidia-smi [sudo] password for dalab: Unable to find image 'nvidia/cuda:12.8.1-base-ubuntu24.04' locally 12.8.1-base-ubuntu24.04: Pulling from nvidia/cuda 73389fbd088f: Pull complete a102f36d092c: Pull complete 05ec76e31584: Pull complete 398182656c47: Pull complete 5a7813e071bf: Pull complete Digest: sha256:133c78a0575303be34164d0b90137a042172bdf60696af01a3c424ab402d86e2 Status: Downloaded newer image for nvidia/cuda:12.8.1-base-ubuntu24.04 Sat Oct 24 18:59:45 2026 +-----------------------------------------------------------------------------------------+ | NVIDIA-SMI 595.58.02 Driver Version: 595.97 CUDA Version: 13.2 | +-----------------------------------------+------------------------+----------------------+ | GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. | | | | MIG M. | |=========================================+========================+======================| | 0 NVIDIA GeForce RTX 3070 ... On | 00000000:01:00.0 Off | N/A | | N/A 51C P0 24W / 85W | 0MiB / 8192MiB | 0% Default | | | | N/A | +-----------------------------------------+------------------------+----------------------+ +-----------------------------------------------------------------------------------------+ | Processes: | | GPU GI CI PID Type Process name GPU Memory | | ID ID Usage | |=========================================================================================| | No running processes found | +-----------------------------------------------------------------------------------------+ この確認用コンテナは、VirtualFluids本体とは別のものです。初回はイメージのダウンロードが発生します。成功すると、コンテナ内でGPU名やドライバ情報が表示されます。これでDockerからGPUが見えていることを確認できます。 もし失敗した場合は、そこで止めてください。VirtualFluidsのビルドより先にGPU連携を直す必要があります。 VirtualFluidsのソースコードを取得する まず、WSL2の「Ubuntu-24.04-VFluids」を起動して、ターミナルを開きます。ソースコードはWindows側の C:\ ではなく、WSL2のLinuxファイルシステム内に置くことをお勧めします。 Dockerとのファイル共有やビルド時の性能面で有利です。公式チュートリアルも、Gitでソースコードを取得してDockerコンテナ内で開発する手順を案内しています。 Dockerコンテナを使用してVirtualFluidsの環境を構築しますが、改めて目標となる構成は、次のとおりです。 ・Windows 11：NVIDIA Driver / Docker Desktop ・WSL2 Ubuntu 24.04：Git / Docker CLI ・Dockerコンテナ：Ubuntu / CUDA / CMake / MPI ・VirtualFluids：GPU計算：RTX 3070 Ti（Compute Capability 8.6） 以下では、公式リポジトリのDocker開発環境を利用する方法を優先します。独自にCUDA環境を組み立てるよりも、VirtualFluidsが想定するコンパイラやMPIなどの依存関係を揃えやすいためです。 作業ディレクトリ「~/VFluidsWork」を作成し、gitコマンドで公式リポジトリ「git.rz.tu-bs.de WSL2 Ubuntuで作業ディレクトリを作る dalab@dalab2312nb01:~$ cd ~ dalab@dalab2312nb01:~$ ls dalab@dalab2312nb01:~$ mkdir ~/VFluidsWork dalab@dalab2312nb01:~$ cd ~/VFluidsWork/ VirtualFluidsのソースコードをダウンロードする 以下のコマンドでリポジトリから入手するのですが、なぜか入手終了までに相当に時間がかかります。 git clone https://git.rz.tu-bs.de/irmb/virtualfluids.git もしGitLab側のリポジトリに接続できない場合や時間がかかって終了しない場合は、公開されているGitHubミラーを使う方法もあります。 公式のDockerチュートリアルも、このGitLabリポジトリからの取得を案内しています。入手が完了したら、ソースコードの場所へ移動して内容を確認します。 dalab@dalab2312nb01:~/VFluidsWork$ git clone https://github.com/irmb/virtualfluids.git Cloning into 'virtualfluids'... remote: Enumerating objects: 92832, done. remote: Counting objects: 100% (13409/13409), done. remote: Compressing objects: 100% (6054/6054), done. remote: Total 92832 (delta 8198), reused 12013 (delta 7175), pack-reused 79423 (from 1) Receiving objects: 100% (92832/92832), 71.50 MiB | 1.48 MiB/s, done. Resolving deltas: 100% (66591/66591), done. dalab@dalab2312nb01:~/VFluidsWork$ ls virtualfluids dalab@dalab2312nb01:~/VFluidsWork$ cd virtualfluids/ dalab@dalab2312nb01:~/VFluidsWork/virtualfluids$ ls 3rdParty CMakePresets.json.license THIRD_PARTY_NOTICES.md sonar-project.properties AUTHORS.md COPYING.txt apps src CHANGELOG.md Containers cpu.cmake tests CITATION.cff Contributing.md docs utilities CMake LICENSES gpu.cmake CMakeLists.txt Python pyproject.toml CMakePresets.json README.md pythonbindings 開発元のDockerイメージについて ここで開発元のDockerイメージを利用する手順が、以下の公式ウエブに記述されています。 irmb.gitlab-pages.rz.tu-bs.de しかし、よく読むと次の通りです。「Currently, it is not possible to access the Git server with an SSH key outside the TU Braunschweig network.」つまり、「TU Braunschweigのネットワーク外では、SSH鍵を使ったGitサーバーへのアクセスはできない」という意味です。リポジトリからソースコードは入手できたので、Dockerイメージだけは利用不可になっているようです。 詳しく調べると、ソースコードの取得は、先ほどの git clone で外部ネットワークから成功しています。一方、Dockerイメージを配布しているレジストリのポート4567には接続できていません。したがって、現時点では認証情報やDockerのGPU設定を変更する必要はありません。公式Dockerイメージを取得できないネットワーク環境として、別の方法で構築するのが合理的です。 公開されていませんが、公式Docker環境の構成を調べます。つまり、すぐに別のCUDA環境をゼロから作るよりも、公式Docker環境の構成を調べ、それを再現するDockerfileを作る方法が可能です。 まずは リポジトリから入手したソースコードのなかで、「.devcontainer/devcontainer.json」 の内容を確認してみます。 dalab@dalab2312nb01:~/VFluidsWork/virtualfluids$ ls -la .devcontainer total 12 drwxr-xr-x 2 dalab dalab 4096 Oct 25 05:14 . drwxr-xr-x 16 dalab dalab 4096 Oct 25 05:14 .. -rw-r--r-- 1 dalab dalab 1988 Oct 25 05:14 devcontainer.json dalab@dalab2312nb01:~/VFluidsWork/virtualfluids$ cat .devcontainer/devcontainer.json // SPDX-License-Identifier: CC-BY-4.0 // SPDX-FileCopyrightText: Copyright © VirtualFluids Project contributors, see AUTHORS.md in root folder { "name": "virtual-fluids-environment", ： 実は、VirtualFluidsのリポジトリには、公式Dockerイメージを取得できない場合に利用できるDockerfile「devcontainer.json」が用意されています。特に、今回の devcontainer.json には次の記述があります。 //"image": "git.rz.tu-bs.de:4567/irmb/virtualfluids/ubuntu24_04:1.0", // only accessible from within the tu-bs network "build": { "dockerfile": "../Containers/Ubuntu24_04.Dockerfile", "target": "base" } これは重要な情報です。 - image：TU Braunschweigのネットワーク内でのみ利用できる公式イメージ：現時点ではtu-bsの外部から利用不可 - build：リポジトリ内のDockerfileから自分でイメージを構築する設定 - target: base：Dockerfile内の base ステージを利用する指定 つまり、今回の環境ではGitLab Registryからイメージをダウンロードする必要はありません。公式Dockerfileから直接構築できます。 DcokerfileからVirtualFluidsのDockerイメージを作成する WSL2 Ubuntuのターミナルで、プロジェクトのルートディレクトリ「~/VFluidsWork/virtualfluids」に移動して、次のコマンドで、公式Dockerfileからイメージを構築します。コンテナを作成するために必要な情報のディレクトリ「Containers」の中身を確認します。 dalab@dalab2403sv01:~$ cd ~/VFluidsWork/virtualfluids/ dalab@dalab2403sv01:~/VFluidsWork/virtualfluids$ ls 3rdParty CMakePresets.json.license THIRD_PARTY_NOTICES.md sonar-project.properties AUTHORS.md COPYING.txt apps src CHANGELOG.md Containers cpu.cmake tests CITATION.cff Contributing.md docs utilities CMake LICENSES gpu.cmake CMakeLists.txt Python pyproject.toml CMakePresets.json README.md pythonbindings dalab@dalab2403sv01:~/VFluidsWork/virtualfluids$ cd Containers/ dalab@dalab2403sv01:~/VFluidsWork/virtualfluids/Containers$ ls Ubuntu20_04.Dockerfile Ubuntu22_04.Dockerfile Ubuntu22_04_wiFI.Dockerfile Ubuntu24_04.Dockerfile 今回は、Ubuntu24.04の環境を利用しているので、定義ファイル「Ubuntu24_04.Dockerfile」を了します。実は変更が必要となるので、このファイルを「Ubuntu24_04.Dockerfile.org」にコピーして、元ファイルを修正します。 dala@dalab2403sv01:~/VFluidsWork/virtualfluids/Containers$ cp Ubuntu24_04.Dockerfile Ubuntu24_04.Dockerfile.org dala@dalab2403sv01:~/VFluidsWork/virtualfluids/Containers$ ls Ubuntu20_04.Dockerfile Ubuntu22_04_wiFI.Dockerfile Ubuntu24_04.Dockerfile.org Ubuntu22_04.Dockerfile Ubuntu24_04.Dockerfile 変更点は以下の２つです。viエディタなどで定義ファイル「Ubuntu24_04.Dockerfile」を開いて、該当部分を修正します。 ① apt-get install に doxygen を追加 64行目： flex bison　→　flex bison doxygen ② Doxygenのソースコードをコンパイルする部分を削除 次の2行を削除するか、#でコメントにしてください。 76行目：　RUN wget doxygen.nl && tar -xvf doxygen-1.9.8.src.tar.gz \ 77行目：　 && cd doxygen-1.9.8 && mkdir build && cd build && cmake -G "Unix Makefiles" .. && make -j8 && make install この状態で、修正したDockerfile「Ubuntu24_04.Dockerfile」から、VirtualFluidsのDockerイメージを構築します。プロジェクトのルートディレクトリ「~/VFluidsWork/virtualfluids」に移動して、以下の手順で行います。 dalab@dalab2312nb01:~/VFluidsWork/virtualfluids$ sudo docker build \ --target base \ --build-arg TZ=Asia/Tokyo \ -f Containers/Ubuntu24_04.Dockerfile \ -t virtualfluids:ubuntu24.04 \ . [sudo] password for dalab: [+] Building 542.7s (9/9) FINISHED docker:default => [internal] load build definition from Ubuntu24_04.Dockerfile 0.0s ： 次の手順で、イメージができたか確認します。「virtualfluids:ubuntu24.04」としてできています。 dala@dalab2403sv01:~/VFluidsWork/virtualfluids$ sudo docker images IMAGE ID DISK USAGE CONTENT SIZE EXTRA nvidia/cuda:12.8.1-base-ubuntu24.04 133c78a05753 411MB 101MB virtualfluids:ubuntu24.04 176cfa16f09e 21.1GB 6.98GB VirtualFluidsのDockerイメージを実行する ここまで成功したら、次はGPUを有効にして、以下の手順でコンテナを起動します。このWSLのUbuntuで、dockerコマンドを利用する場合には、Windowsの「docker desktop」を起動した状態にします。 dala@dalab2403sv01:~/VFluidsWork/virtualfluids$ sudo docker run --rm -it \ --gpus all \ --name virtualfluids-gpu \ -e TZ=Asia/Tokyo \ -e HWLOC_COMPONENTS=-gl \ -v "$PWD":/workspace/virtualfluids \ -w /workspace/virtualfluids \ virtualfluids:ubuntu24.04 \ bash ========== == CUDA == ========== CUDA Version 12.9.1 Container image Copyright (c) 2016-2023, NVIDIA CORPORATION & AFFILIATES. All rights reserved. This container image and its contents are governed by the NVIDIA Deep Learning Container License. By pulling and using the container, you accept the terms and conditions of this license: https://developer.nvidia.com/ngc/nvidia-deep-learning-container-license A copy of this license is made available in this container at /NGC-DL-CONTAINER-LICENSE for your convenience. ubuntu@f359122df793:/workspace/virtualfluids$ pwd /workspace/virtualfluids ubuntu@f359122df793:/workspace/virtualfluids$ ls 3rdParty CMakePresets.json.license THIRD_PARTY_NOTICES.md sonar-project.properties AUTHORS.md COPYING.txt apps src CHANGELOG.md Containers cpu.cmake tests CITATION.cff Contributing.md docs utilities CMake LICENSES gpu.cmake CMakeLists.txt Python pyproject.toml CMakePresets.json README.md pythonbindings コンテナ内でGPUと開発環境を確認する コンテナに入ったら、プロンプト「ubuntu@f359122df793」に変わります。以降はコンテナ内で実行します。 【GPU確認】：利用しているGPUが表示されることを確認します。 ubuntu@f359122df793:/workspace/virtualfluids$ nvidia-smi Sun Oct 25 15:06:25 2026 +-----------------------------------------------------------------------------------------+ | NVIDIA-SMI 595.58.02 Driver Version: 595.97 CUDA Version: 13.2 | +-----------------------------------------+------------------------+----------------------+ ： | 0 NVIDIA RTX A4500 On | 00000000:01:00.0 On | Off | ： 【CUDAコンパイラ確認】：nvccの導入を確認します。 ubuntu@f359122df793:/workspace/virtualfluids$ nvcc --version nvcc: NVIDIA (R) Cuda compiler driver Copyright (c) 2005-2025 NVIDIA Corporation Built on Tue_May_27_02:21:03_PDT_2025 Cuda compilation tools, release 12.9, V12.9.86 Build cuda_12.9.r12.9/compiler.36037853_0 【CMake・MPI・C++コンパイラ確認】：ビルドに必要なツールを確認します。 VirtualFluids公式Dockerイメージには、コンパイラ、CMake、MPI、OpenMPなどが含まれると説明されています。 ubuntu@f359122df793:/workspace/virtualfluids$ cmake --version cmake version 3.26.3 CMake suite maintained and supported by Kitware (kitware.com/cmake). ubuntu@f359122df793:/workspace/virtualfluids$ mpic++ --version g++ (Ubuntu 14.2.0-4ubuntu2~24.04.1) 14.2.0 Copyright (C) 2024 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. ubuntu@f359122df793:/workspace/virtualfluids$ g++ --version g++ (Ubuntu 14.2.0-4ubuntu2~24.04.1) 14.2.0 Copyright (C) 2024 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 利用するGPU向けにVirtualFluidsのGPU版をビルドする ここではNVIDIA GPUに対応したビルドが必要です。重要な情報として、NVIDIAの「RTX 3070 Ti・RTX A4500」のCompute Capabilityは 8.6 です。他のGPUの場合も調べてから、作業を進めます。 次は、Dockerコンテナ内で VirtualFluids本体をCUDA対応でコンパイルし、GPU解析を実行する段階です。まず、コンテナ内でVirtualFluidsのソースコードがあるディレクトリに移動します。 最初に、CMakeのプリセットを確認します。 ubuntu@045094eb5860:/workspace/virtualfluids$ cd /workspace/virtualfluids/ ubuntu@045094eb5860:/workspace/virtualfluids$ cmake --list-presets Available configure presets: "make_all" - all make configuration "make_numerical_tests_gpu" - gpu numerical tests make configuration "make_gpu" - make gpu configuration "make_gpu_debug" - make gpu debug configuration "make_cpu" - make cpu configuration "make_cpu_apple" - make cpu configuration (apple clang + homebrew libomp) "make_cpu_debug" - make cpu debug configuration 公式のBuild and Run資料には、GPU専用プリセットとして make_gpu が掲載されています。RTX 3070 TiでGPU解析を行う目的なので、まずは make_all ではなく、GPU専用の make_gpu を使う方針で進めましょう。 まず、CMakeプリセットの設定を確認します。 ubuntu@045094eb5860:/workspace/virtualfluids$ cat CMakePresets.json ： "name": "default", "binaryDir": "build", これより、binaryDir：ビルドファイルの保存先が「build」でした。 まず、GPU用のVirtualFluidsをビルドするためのcmakeの準備します。CUDAのアーキテクチャ指定には、CMake標準の変数名 CMAKE_CUDA_ARCHITECTURES（複数形）を使用します。コンテナ内の /workspace/virtualfluids で実行してください。 ubuntu@045094eb5860:/workspace/virtualfluids$ cmake --preset=make_gpu \ -DCMAKE_CUDA_ARCHITECTURES=86 Preset CMake variables: CMAKE_BUILD_TYPE="Release" VF_ENABLE_ALL_APPS="ON" VF_ENABLE_DOUBLE_ACCURACY="OFF" VF_ENABLE_GPU="ON" ： -- Configuring done (12.0s) -- Generating done (0.1s) -- Build files have been written to: /workspace/virtualfluids/build CMakeの構成が成功したら、実際にコンパイルします。 ubuntu@045094eb5860:/workspace/virtualfluids$ cmake --build --preset=make_gpu -j 8 [ 0%] Building CXX object _deps/spdlog-build/CMakeFiles/spdlog.dir/src/spdlog.cpp.o [ 0%] Building CXX object _deps/spdlog-build/CMakeFiles/spdlog.dir/src/stdout_sinks.cpp.o [ 0%] Building CXX object _deps/spdlog-build/CMakeFiles/spdlog.dir/src/color_sinks.cpp.o ： [100%] Linking CUDA device code CMakeFiles/ResearchCrossingNeighbourhoodGpu.dir/cmake_device_link.o [100%] Linking CXX executable ../../../bin/ResearchCrossingNeighbourhoodGpu [100%] Built target ResearchCrossingNeighbourhoodGpu [100%] Linking CUDA device code CMakeFiles/ActuatorLineDisk.dir/cmake_device_link.o [100%] Linking CXX executable ../../../bin/ActuatorLineDisk [100%] Built target ActuatorLineDisk ここで、-j 8 は8並列でコンパイルする指定です。メモリ不足が発生する場合は -j 4 に変更してください。 以上のように、エラーなくVirtualFluidsのGPU版ビルドが完了したら、実行ファイルを確認します。４つの実行形式が、ディレクトリ「build/bin」に作られています。 ubuntu@045094eb5860:/workspace/virtualfluids$ find build -type f -executable | grep -E 'LidDrivenCavityGPU|DrivenCavity|SphereInChannel|TaylorGreenVortex' build/bin/SphereInChannel build/bin/TaylorGreenVortex build/bin/DrivenCavityMultiGPU build/bin/DrivenCavity ビルドした実行形式でGPU計算を実行する 例題 DrivenCavity ビルド後、実行ファイルを確認します。公式のBuild and Run資料にあるDrivenCavityの実行例は次のとおりです。 irmb.gitlab-pages.rz.tu-bs.de ubuntu@045094eb5860:/workspace/virtualfluids$ pwd /workspace/virtualfluids ubuntu@045094eb5860:/workspace/virtualfluids$ ./build/bin/DrivenCavity \ ./apps/gpu/DrivenCavity/drivencavity_1level.cfg [2026-10-25 20:35:29.052] [trace] Using command line argument for config path: ./apps/gpu/DrivenCavity/drivencavity_1level.cfg [2026-10-25 20:35:29.053] [info] Start initializing level 0 ： [2026-10-25 20:35:34.409] [info] ... finish Running simulation... [2026-10-25 20:35:34.409] [info] Total runtime: 1190 ms [2026-10-25 20:35:34.409] [info] NUPS: 2416676407 (2416.7e6 NUPS) この例では、計算結果は通常 output 以下に保存されます。VTK形式の結果はParaViewでファイル「LidDrivenCavity_bin_ID_0.pvd」で可視化できます。 ubuntu@045094eb5860:/workspace/virtualfluids$ ls 3rdParty CMakePresets.json.license THIRD_PARTY_NOTICES.md output AUTHORS.md COPYING.txt apps pyproject.toml CHANGELOG.md Containers build pythonbindings CITATION.cff Contributing.md cpu.cmake sonar-project.properties CMake LICENSES docs src CMakeLists.txt Python gpu.cmake tests CMakePresets.json README.md logs utilities ubuntu@045094eb5860:/workspace/virtualfluids$ cd output/ ubuntu@045094eb5860:/workspace/virtualfluids/output$ ls DrivenCavity_uniform ubuntu@045094eb5860:/workspace/virtualfluids/output$ cd DrivenCavity_uniform/ ubuntu@045094eb5860:/workspace/virtualfluids/output/DrivenCavity_uniform$ ls LidDrivenCavity.yaml LidDrivenCavity_bin_ID_0_t_9000.vtk.pvtu LidDrivenCavity_bin_ID_0.pvd LidDrivenCavity_bin_lev_0_ID_0_Part_1_t_0.vtk.bin.vtu LidDrivenCavity_bin_ID_0_t_0.vtk.pvtu LidDrivenCavity_bin_lev_0_ID_0_Part_1_t_1000.vtk.bin.vtu LidDrivenCavity_bin_ID_0_t_1000.vtk.pvtu LidDrivenCavity_bin_lev_0_ID_0_Part_1_t_10000.vtk.bin.vtu ： 現在の結果は、最後の段階の速度vx1が以下のようになって、いつも見るCavityの結果に近い形になります。 !image.png 例題 SphereInChannel 次の例題として、SphereInChannelを以下のように実行してみます。 ubuntu@045094eb5860:/workspace/virtualfluids$ pwd /workspace/virtualfluids ubuntu@e84ed3fe8cc6:/workspace/virtualfluids$ ./build/bin/SphereInChannel ./apps/gpu/SphereInChannel/sp here_1level.cfg [2026-10-30 03:35:43.035] [trace] Using command line argument for config path: ./apps/gpu/SphereInChannel/sphere_1level.cfg Reading stl from ./apps/gpu/SphereInChannel/sphere02.stl. [2026-10-30 03:35:43.035] [info] Start reading ascii STL file: ./apps/gpu/SphereInChannel/sphere02.stl [2026-10-30 03:35:43.036] [info] Reading STL-Group Visualization Toolkit generated SLA File as patch 0 ： [2026-10-30 03:35:45.488] [info] GPU Info: [2026-10-30 03:35:45.488] [info] -------------- [2026-10-30 03:35:45.488] [info] name: NVIDIA GeForce RTX 3070 Ti Laptop GPU, compute capability: 8.6 [2026-10-30 03:35:49.670] [info] PID --- Average performance --- Processing time (ms) Nups in Mio Bandwidth in GB/sec [2026-10-30 03:35:49.670] [info] 0 --- Average performance --- 4181.5/ 4181.5 1213.0 135.9 [2026-10-30 03:35:49.670] [info] Write files t = 10000 ... [2026-10-30 03:35:49.788] [info] ... done [2026-10-30 03:35:49.788] [info] 0 --- Average performance --- 0.0/ 4181.5 1213.0 135.9 [2026-10-30 03:35:49.788] [info] ... finish Running simulation... [2026-10-30 03:35:49.788] [info] Total runtime: 4182 ms [2026-10-30 03:35:49.788] [info] NUPS: 1212975990 (1213.0e6 NUPS) この例も、計算結果は output 以下に保存されます。VTK形式の結果はParaViewでファイル「SphereInChannel_bin_ID_0.pvd」で可視化できます。可視化できます。 ubuntu@e84ed3fe8cc6:/workspace/virtualfluids$ cd output/SphereInChannel_1Level/ ubuntu@e84ed3fe8cc6:/workspace/virtualfluids/output/SphereInChannel_1Level$ ls SphereInChannel.yaml SphereInChannel_bin_ID_0.pvd SphereInChannel_bin_ID_0_t_0.vtk.pvtu SphereInChannel_bin_ID_0_t_10000.vtk.pvtu SphereInChannel_bin_lev_0_ID_0_Part_1_t_0.vtk.bin.vtu SphereInChannel_bin_lev_0_ID_0_Part_1_t_10000.vtk.bin.vtu planeProbe_bin_ID_0_t_10000.vtk.pvtu planeProbe_bin_lev_0_ID_0_Part_1_t_10000.vtk.bin.vtu pointProbe_bin_ID_0_t_10000.vtk.pvtu pointProbe_bin_lev_0_ID_0_Part_1_t_10000.vtk.bin.vtu 現在の結果は、最後の段階の速度vx1が以下のようになって、球周りの速度分布が確認できます。 !image.png コンテナを終了・再起動する方法 計算やビルドが終わったら、コンテナ内で次のコマンドを実行します。 exit 今回は --rm を付けて起動しているため、コンテナ自体は終了時に削除されます。ただし、ソースコードとビルド結果はWSL2側に残ります。

Docker Compose : des modèles prêts à l'emploi sur GitHub Tu montes des conteneurs Docker à chaque projet en partant de zéro ? Awesome Compose, c'est une collection officielle de Docker avec 60+ exemples prêts à l'emploi. Clone, configure, lance en une seule commande. **Résumé :** - Awesome Compose : dépôt officiel créé par Docker en 2020, licence CC0 (réutilisable librement) ; - 3 catégories : 21 applications multi-services (Go + PostgreSQL, React + Rust…), 12 services seuls (Angular, Django, FastAPI…), 6 configurations basiques (Nextcloud, Prometheus, Gitea) ; - Commande unique : `docker compose up -d` pour lancer, `docker compose down` pour tout arrêter ; - Exemples concrets : Minecraft, Pi-hole, Plex, Portainer, WireGuard, ELK stack, Prometheus + Grafana ; - Guides pas à pas : dossier officiel pour apprendre étape par étape ; - Bonus : WebAssembly + Docker (WasmEdge avec MySQL, Kafka) pour les curieux. ⚠ **AVERTISSEMENTS** - À développement local uniquement, pas pour la production. Le README le précise : « These samples must not be deployed in production environments. » - Pas de sécurité intégrée, pas de sauvegarde automatique, pas de haute disponibilité ni de monitoring avancé. - Services attendent parfois des variables d'environnement ou des ports libres : lis toujours le README du dossier avant de lancer. - Réutilisable librement (CC0) mais vérifie les licences de chaque technologie utilisée. Chapitres : 0:00 Intro 0:23 60 templates Docker 0:50 C'est quoi ? 1:15 Pourquoi ce dépôt ? 1:40 Comment t'en servir 2:05 Les 3 catégories 2:29 Services seuls + basiques 2:52 Des applis connues 3:17 Docker + WASM 3:41 Cas concrets 4:06 Guides pas à pas 4:29 Limites et précautions 4:51 Pièges à éviter 5:13 À toi de jouer Sources : Sources officielles (consultées le 2026-10-21) : - docker/awesome-compose - github.com/docker/awesome-compose/tree/master/ela… - github.com/docker/awesome-compose/tree/master/ngi… - github.com/docker/awesome-compose/tree/master/rea… - github.com/docker/awesome-compose/tree/master/was… - github.com/docker/awesome-compose/tree/master/pro… - github.com/docker/awesome-compose/tree/master/min… - github.com/docker/awesome-compose/tree/master/pih… - github.com/docker/awesome-compose/tree/master/off… #Docker #Compose #githubtutorial

devcontainer のビルドが「--allow=fs.read」で止まるときの回避策（features を使っていなくても起きる） Docker Desktop を更新したあと、いつもどおり VS Code で WSL 環境の devcontainer を開いたら、ビルドがはじまった直後に失敗しました。Dockerfile も compose.yml も変えていません。ログを見ると、使っていないはずの features のファイル名が出ています。 additional privileges requested: pass "--allow=fs.read=/tmp/devcontainercli-<user>/container-features/0.89.0-1792734723773/Dockerfile-with-features" to grant requested privileges AI に聞くと「features を Dockerfile に移しましょう」と返ってきましたが、そもそも devcontainer.json に features は書いていません。調べると、Docker 側のセキュリティ修正と Dev Containers の作りがぶつかって起きていたようです。 この記事では、原因と回避策をまとめます。上記の additional privileges requested の行がログに出ていれば、同じ原因の可能性があります。 結論 ホストに環境変数を 1 つ設定し、devcontainer をリビルドします。 export BUILDX_BAKE_ENTITLEMENTS_FS=0 features を使っていなくても、devcontainer.json で Docker Compose を使い、サービスを Dockerfile からビルドしていれば起きます。 この環境変数は、作業ディレクトリの外のファイルを読み書きするときの確認を無効にします。Docker Compose の修正版が出たら削除してください。 検証環境 項目 内容 ホスト WSL の Ubuntu Docker Docker Desktop 4.96.3（Engine 29.9.2） Docker Buildx 0.38.1 Docker Compose 5.6.1 VS Code 1.126.0（Dev Containers CLI 0.469.0） devcontainer の構成 Docker Compose、build: で Dockerfile からビルド、features なし エラーの読み方 ログは長いですが、見るのは次の 3 か所だけです。 Start: Run: docker compose --project-name app -f /home/<user>/apps/app/.devcontainer/compose.yml -f /tmp/devcontainercli-<user>/docker-compose/docker-compose.devcontainer.build-1792734723775.yml build => [internal] load local bake definitions => => reading from stdin 679B additional privileges requested: pass "--allow=fs.read=/tmp/devcontainercli-<user>/container-features/0.89.0-1792734723773/Dockerfile-with-features" to grant requested privileges Dev Containers は、プロジェクトの compose.yml に加えて、/tmp に作った 2 つ目の Compose ファイルを -f で重ねて docker compose build を実行しています。 load local bake definitions は、docker compose build が中で Docker Buildx の bake を使ってビルドしていることを示しています。 bake が /tmp の Dockerfile-with-features を読む許可を求めて、止まっています。 この後に続く at Dp (...devContainersSpecCLI.js...) のようなスタックトレースは、Dev Containers の CLI が「docker compose build が失敗した」と報告しているだけです。原因は書かれていないので、読み飛ばしてかまいません。 AI の見立ては外れた 原因にたどり着く前に、AI の見立てが外れました。ログだけを見れば、もっともらしい見立てでした。 AI が挙げた原因は「features を使っているから」です。エラーに出ているファイル名が Dockerfile-with-features なので、そう読むのは自然です。ただ、devcontainer.json に features は書いていないので、この見立ては外れでした。 そこで、別の AI に、Dev Containers の CLI のソースを確かめてもらいました。features がないときに足される処理を読むと、入っていたのはイメージにラベルを付ける 1 行でした。何が足されているかは、次の節で説明します。 なぜ起きるか bake とは bake（docker buildx bake）は、Docker Buildx のビルド機能の 1 つです。ビルドの設定をコマンドの引数で並べる代わりに、ファイルに書いておき、複数のイメージをまとめて（並行して）ビルドできます（Docker のドキュメント「Bake」）。設定ファイルは HCL か JSON で書くのが基本で、Compose ファイルをそのまま読むこともできます（Building with Bake from a Compose file）。 target "app" { context = "." dockerfile = "Dockerfile" tags = ["myapp:latest"] } この記事で bake が関係するのは、docker compose build が中で bake を使っているからです。Compose は、BuildKit が有効で Buildx のプラグインが入っていれば、compose.yml のビルドの設定を bake 用の JSON に変換します。その JSON を docker buildx bake --file - --progress rawjson に標準入力で渡して、ビルドします（docker/compose の build_bake.go）。エラーのログにあった load local bake definitions と reading from stdin 679B は、この JSON を受け取った bake の出力です。 つまり、docker compose build を実行しているつもりでも、実際にビルドの可否を判断しているのは bake です。bake の確認に引っかかれば、Compose のビルドも止まります。Compose が渡している設定は、docker compose build --print で表示できます（docker compose build のリファレンス）。 Buildx が、作業ディレクトリの外のファイルを読むときに許可を求めるようになった bake には「エンタイトルメント」という仕組みがあります。ビルドが作業ディレクトリの外のファイルを読み書きするときは、--allow fs.read=<パス> で許可するか、確認のプロンプトで許可しないと進みません（docker buildx bake のリファレンスの --allow）。他人のリポジトリにある bake の定義を実行したときに、手元のファイルを勝手に読まれないようにするためのものです。 ところが、Buildx v0.21.0 から v0.37.1 までは、--progress=rawjson で実行するとこの確認が飛ばされていました。これは脆弱性として報告され（GHSA-gwr2-q96m-6682）、2026 年 9 月 30 日の Buildx v0.37.2 で修正されました。 Docker Compose は、bake を必ず --progress rawjson で呼び出します。今まで確認が飛ばされていたので問題になりませんでしたが、v0.37.2 以降は確認が効くようになりました。しかも Compose は、ビルドコンテキストには読み取りの許可を付けていましたが、Dockerfile には付けていませんでした（docker/compose#14285）。そのため、Dockerfile がビルドコンテキストの外にあると、Compose のビルドが止まるようになりました。 Docker Desktop を更新しただけで、設定を何も変えていないのに起きたのはこのためです。 Dev Containers は、features がなくても /tmp に Dockerfile を作る Dev Containers は、Compose のサービスを Dockerfile からビルドするとき、元の Dockerfile をそのまま使いません。元の Dockerfile の前後に数行を足したものを、/tmp/devcontainercli-<user>/container-features/<バージョン>-<数字>/Dockerfile-with-features に書き出します。そして 2 つ目の Compose ファイルで、dockerfile: をこのファイルに差し替えてビルドします（devcontainers/cli の dockerCompose.ts）。 features を使っていれば、足される数行に features のインストール処理が入ります。features を使っていなくても、次の処理は足されます（devcontainers/cli の containerFeatures.ts）。 FROM $_DEV_CONTAINERS_BASE_IMAGE AS dev_containers_target_stage LABEL devcontainer.metadata="..." devcontainer.json の設定を、イメージのラベルとして焼き込んでいます。ファイル名に features と付いているのは、features 用の仕組みを使い回しているからです。features を使っているかどうかとは関係ありません。 まとめると、次の 2 つが重なって、ビルドが止まっています。 devcontainer を使わなくても再現できる 原因がこの 2 つの組み合わせなら、Dev Containers を使わなくても、Dockerfile をビルドコンテキストの外に置くだけで同じエラーになるはずです。docker/compose#14285 の再現手順で試しました。Compose の修正はまだリリースされていないので、今の Compose でも再現します。 mkdir -p /tmp/outside && echo 'FROM alpine' > /tmp/outside/Dockerfile mkdir -p /tmp/repro && cd /tmp/repro cat > compose.yaml <<'YAML' services: app: build: context: . dockerfile: /tmp/outside/Dockerfile YAML 環境変数なしでビルドすると、devcontainer のときと同じ行で止まります。 $ env -u BUILDX_BAKE_ENTITLEMENTS_FS docker compose build [+] Building 0.0s (1/1) FINISHED => [internal] load local bake definitions 0.0s => => reading from stdin 458B 0.0s additional privileges requested: pass "--allow=fs.read=../outside/Dockerfile" to grant requested privileges BUILDX_BAKE_ENTITLEMENTS_FS=0 を付けると通ります。 $ BUILDX_BAKE_ENTITLEMENTS_FS=0 docker compose build [+] Building 0.2s (7/7) FINISHED => [internal] load local bake definitions 0.0s => => reading from stdin 458B 0.0s => [internal] load build definition from Dockerfile 0.0s （中略） ✔ Image repro-app Built 試し終わったら rm -rf /tmp/outside /tmp/repro で削除してください。 回避策 エラーメッセージは --allow=fs.read=... を付けるよう求めていますが、docker compose build は Dev Containers が組み立てて実行するので、利用者が引数を足すことはできません。代わりに、bake のファイルシステムの確認を無効にする環境変数 BUILDX_BAKE_ENTITLEMENTS_FS を 0 にします。 この環境変数は、Dev Containers が docker compose を実行するプロセスに届いている必要があります。 BUILDX_BAKE_ENTITLEMENTS_FS とは BUILDX_BAKE_ENTITLEMENTS_FS は、bake のエンタイトルメントのうち、ファイルシステムに関するもの（fs・fs.read・fs.write）を確認するかどうかを切り替える Buildx の環境変数です。この環境変数を読むのは Buildx です。Compose は bake を子プロセスとして起動するので、Compose を実行するプロセスに設定しておけば Buildx まで届きます。 値ごとの動きは次のとおりです（buildx の bake/entitlements.go）。 値 動き 設定しない 確認する（既定） 0・false など ファイルシステムの確認をしない 1・true など 確認する no・off など、上記以外 許可が必要なビルドのときに failed to parse BUILDX_BAKE_ENTITLEMENTS_FS value のエラーで止まる 値は Go の strconv.ParseBool で読まれるので、使えるのは、確認しない 0・f・F・false・FALSE・False と、確認する 1・t・true などだけです。no や off は使えません。 この環境変数は、Docker のドキュメントのビルド用の環境変数の一覧には載っていません。Buildx のソースと、そこから出るメッセージ（To disable filesystem entitlements checks, you can set BUILDX_BAKE_ENTITLEMENTS_FS=0）に出てくるだけです。 シェルの設定ファイルに書く VS Code（Dev Containers）が docker compose を実行するマシン（WSL なら Ubuntu）の ~/.bashrc に追記します。 export BUILDX_BAKE_ENTITLEMENTS_FS=0 追記したら、コマンドパレットから「Dev Containers: Rebuild Container」を実行します。私の環境（WSL に接続した VS Code）では、VS Code を再起動しなくても、リビルドをもう一度実行するだけでエラーが消えました。 BUILDX_BAKE_ENTITLEMENTS_FS=0 にしたときの影響 無効になるのはファイルシステムの確認だけ 0 にして無効になるのは、bake を実行したディレクトリ（作業ディレクトリ）の外のファイルを読み書きするときの確認です。network.host や security.insecure など、ほかのエンタイトルメントの確認は残ります。 無効になる確認には、読み取り（fs.read）だけでなく書き込み（fs.write）も含まれます。 読み取り：ビルドコンテキスト、Dockerfile、secrets に file: で指定したファイル、SSH の鍵、ローカルのキャッシュなど 書き込み：ビルドの結果をローカルのディレクトリに書き出す出力先や、キャッシュの書き出し先など これらが作業ディレクトリの外を指していても、エラーにも確認のプロンプトにもならず、そのまま進みます。 有効範囲は、環境変数が届くすべてのビルド ~/.bashrc に書くと、そのシェルから起動したプロセスのビルドすべてに効きます。Dev Containers の /tmp の Dockerfile だけを許可するのではありません。ターミナルで実行する docker compose build や docker buildx bake も、同じように確認なしで進みます。 たとえば、他人のリポジトリの docker-bake.hcl にホームディレクトリの ~/.ssh をビルドコンテキストにする設定が書かれていたり、compose.yml に ~/.aws/credentials を secret として読む設定が書かれていたりしても、気付かないままビルドできてしまいます。Compose のビルドについては、Buildx v0.37.2 より前と同じように、ファイルシステムの確認が飛ばされる状態に戻ります。 環境変数をいつ削除するか 根本の修正は、Compose が Dockerfile のパスにも読み取りの許可を付けるようにする docker/compose#14325 です。2026 年 10 月 12 日にマージされました。ただ、執筆時点の最新版 v5.6.1（10 月 21 日）には入っていません。VS Code 側の microsoft/vscode-remote-release#11896 も、執筆時点では open のままです。修正を含む Compose がリリースされたら、環境変数を削除してもう一度「Rebuild Container」を実行し、エラーが出ないことを確かめてください。 まとめ エラーの原因は、Buildx v0.37.2 で bake のファイル読み取りの確認が効くようになったことと、Dev Containers が /tmp に Dockerfile を作ってビルドすることの組み合わせです。 features を使っていなくても、Compose で Dockerfile からビルドしていれば起きます。 回避策として BUILDX_BAKE_ENTITLEMENTS_FS=0 を設定し、devcontainer をリビルドします。 この 1 行は、環境変数が届くすべてのビルドで、作業ディレクトリの外のファイルを読み書きするときの確認を無効にします。Compose の修正版が出たら削除してください。 参考 GHSA-gwr2-q96m-6682: Bake filesystem entitlement consent is skipped under --progress=rawjson（docker/buildx） Buildx v0.37.2 のリリース（docker/buildx） docker/buildx の bake/entitlements.go Build fails with fs.read entitlement error when dockerfile is outside the build context（docker/compose#14285） fix(bake): grant permissions for configured build inputs（docker/compose#14325） Docker Compose v5.6.1 のリリース（docker/compose） docker/compose の pkg/compose/build_bake.go Buildx v0.37.2 breaks compose builds（microsoft/vscode-remote-release#11896） devcontainers/cli の src/spec-node/containerFeatures.ts devcontainers/cli の src/spec-node/dockerCompose.ts Bake（Docker） Building with Bake from a Compose file（Docker） docker buildx bake（Docker） docker compose build（Docker） Build variables（Docker） strconv.ParseBool（Go）

给 AI 助手接好几个 MCP 工具，配置越来越乱？🐳 Docker MCP Gateway 把 MCP 服务统一接到一个入口，方便管理工具连接。🔌 docker/mcp-gateway #MCP #浇朋友 #蓝朋友 #互关 #fo

Anyone know when Docker sbx will officially support the Antigravity CLI? I've found that Docker's sbx sandbox is currently the safest way to run AI agents locally on my laptop. For the past few weeks, this setup with Claude has worked flawlessly: sbx run claude ~/claude-workspace ~/secrets-for-Claude:ro Now, I want to harness the power of Gemini (via Antigravity), so I tried running the equivalent command: sbx run gemini ~/gemini-workspace ~/secrets-for-Gemini:ro Unfortunately, this fails because the legacy Gemini CLI has been replaced by the Antigravity CLI (as tracked in sbx-releases#197). Does anyone have any insight into when the Docker/sbx team plans to add official built-in support for the Antigravity CLI?