はじめに

Cyber Security Innovation Group、FutureVulsチームの棚井です。

2026年7月27日に「AWS Certified DevOps Engineer - Professional (DOP-C02)」を受験し、833点/1000点（合格ラインは750点）で一発合格しました。

先日、「AWS Certified Solutions Architect - Professional 合格体験記」を公開しました。その記事の締めで、次はDevOps Engineer - Professionalを目指すと書いており、SAP-C02に合格した勢いのまま受験しました。

試験の概要

DOP-C02は、DevOpsエンジニアロールを担う人を対象に、AWSでの分散システムのプロビジョニングや運用、管理の技術的な専門知識を検証する試験です。受験対象者には「AWS環境でのプロビジョン、運用、管理に関する2年以上の経験」に加えて、ソフトウェア開発ライフサイクルとプログラミングまたはスクリプティングの経験が求められています。

試験の基本情報

出題形式や合格ラインはSAP-C02と同じです。

コンテンツ分野と出題比率

最大配点は第1分野「SDLCのオートメーション」の22%で、第2分野「設定管理とIaC」と合わせると39%になります。CI/CDパイプラインとIaCが試験の中心です。

面白いのは、試験ガイドに「受験対象者として範囲外の職務」が明記されていることです。高度なネットワークに関する知識、データベースの設計やクエリ、パフォーマンスの最適化、フルスタックアプリケーションのコード開発は範囲外とされています。全領域を広く問うSAP-C02に対して、DOP-C02は運用の自動化に的を絞った試験です。

学習方法

今回はSkill BuilderとUdemyの2本立てです。これまでの試験勉強で続けてきた「わからないところをPerplexityに質問する」流れは、今回はほとんど使いませんでした。後述するUdemyの解説が詳しく、疑問がその場で解消されたからです。

1. Skill Builderで出題の傾向をつかむ

まずAWS Skill Builderで、分野別のDomain Practiceを1から6まで解きました。問題の傾向を知るためです。そのあとに、無料で受けられるOfficial Practice Question Set（20問）を解きました。

公式模試（Official Pretest）はやっていません。解説が自分にとっては不足しており、理解するまで自力で補う労力が大きすぎたからです。CI/CDまわりのサービス群は業務でちょうど使っておらず、解説を読んでも「なぜその選択肢が最適なのか」を判断するだけの事前知識がありませんでした。

2. Udemyの演習問題で「知らない」を潰す

『【全出題範囲網羅+詳細解説】AWS DOP-C02日本語実践問題225問(DevOps Engineer Pro)』（syo @Cloud 講師）を使いました。

同じ講師の講座を使うのは、これで5回連続です。演習問題1〜3（75問・75問・76問）と出題順固定版を合わせて計452問が収録されており、ほぼすべての問題に図解が付いています。

正直に書くと、解き始めの正答率は50%程度で、とても焦りました。SAP-C02に合格した直後なので知識の貯金で解けるつもりでいたのですが、CI/CDパイプラインの構成やコンテナ運用など、「知らない」問題が次々に出てきたからです。

そこからは、正誤にかかわらず解説を読み込み、知らないサービスや機能を「どんなユースケースで使うのか」とセットで頭に入れていきました。この講座は正解と不正解の両方の選択肢に解説が付き、公式ドキュメントへのリンクも張られているので、「知らない」をその場で潰す使い方に向いています。

試験勉強で得た学び

ここからは、演習問題で「知らない」となって覚え直した内容です。

PowerUserAccessとよく使うAWS管理ポリシー

AWS管理ポリシーのPowerUserAccessは、権限設計を考えるうえで押さえておきたいポリシーです。このポリシーはNotActionを使って「iam:*、organizations:*、account:*以外のすべて」を許可する構造になっています。

開発チームに幅広い権限を渡しつつ、ユーザーやロールの管理（＝権限の自己拡張につながる操作）は渡さない、という用途のポリシーです。ただし例外があり、iam:CreateServiceLinkedRoleやorganizations:DescribeOrganizationなど、サービスの利用に必要な読み取り系とサービスリンクロール系のアクションは許可されています。渡さないのはアイデンティティと組織の管理だけだと理解しておくと、選択肢の切り分けがしやすくなります。

PowerUserAccess以外にも、名前から権限の範囲を即答できるようにしておきたいAWS管理ポリシーがあります。よく登場するものを整理します。

混同しやすいのは、ReadOnlyAccessとViewOnlyAccessの違いです。どちらも「読み取り専用」に見えますが、データの中身まで読めるのはReadOnlyAccessだけです。閲覧させたいのがリソースの一覧なのか、格納されたデータそのものなのかで選択肢が分かれます。なお、SecurityAuditとViewOnlyAccessをインシデント初動調査に使う話は、「AWS Certified Security - Specialty」の試験勉強でも登場しました。

CodeArtifactで依存パッケージを一元管理する

第1分野「SDLCのオートメーション」で登場するのが、AWS CodeArtifactです。npmやPyPI、Mavenなどに対応したマネージドのアーティファクトリポジトリで、ドメインの下にリポジトリを作り、チームごとに使い分けます。

特徴は、アップストリームと外部接続の仕組みです。目当てのパッケージがなければ社内の共有リポジトリをたどり、その先の外部接続からnpmjsやPyPIといった公開リポジトリをオンデマンドで参照します。取得したバージョンはCodeArtifact側に保存されるので、2回目以降は社内で完結します。

flowchart LR
    BUILD["開発者 / ビルド環境"] -->|"npm install など"| TEAM["CodeArtifact
チーム用リポジトリ"]
    TEAM -->|"なければ
アップストリームをたどる"| SHARED["CodeArtifact
共有リポジトリ"]
    SHARED -->|"外部接続で
オンデマンド取得"| PUB["公開リポジトリ
npmjs / PyPI / Maven Central"]
    PUB -.->|"取得したバージョンを保持"| SHARED

セキュリティ面の利点は2つです。

• ビルド環境の通信先をCodeArtifactに一本化でき、IAMの認可トークンで誰がどのリポジトリから取得できるかを制御できる
• 取得済みのバージョンが保持されるので、公開リポジトリ側で削除や障害が起きても手元のビルドは止まらない

依存関係かく乱攻撃（dependency confusion）への対策にもなります。社内パッケージと同じ名前を公開リポジトリに登録して取り込ませる攻撃ですが、パッケージオリジンコントロールで「直接公開のみを許可し、外部接続からの取得はブロックする」と統制すれば、内部パッケージが外の同名パッケージにすり替わる経路を塞げます。

CloudFormationのサービスロールとiam:PassRole

第2分野「設定管理とIaC」では、CloudFormationそのものの機能に加えて、権限まわりの設計が問われます。

CloudFormationはデフォルトでは操作した人の権限でリソースを作りますが、サービスロールを指定すると、そのロールの権限でスタックを操作するようになります。開発者にはスタック操作の権限とiam:PassRoleだけを与え、リソース作成の強い権限はサービスロールに寄せます。この形にすると、開発者本人に強い権限を直接持たせずに、スタックの作成や更新、削除を回せます。

flowchart LR
    DEV["開発者
（スタック操作の権限
＋ iam:PassRole のみ）"] -->|"サービスロールを指定して
スタックを操作"| CFN["CloudFormation
＋ サービスロール"]
    CFN -->|"ロールの権限で
リソースを作成・更新・削除"| RES["AWSリソース"]

鍵になるのがiam:PassRoleです。これは「このロールをサービスに渡してよいか」を制御する権限で、これがないとサービスロールを指定した（関連付け・変更する）スタック操作ができません。注意したいのは、一度サービスロールを関連付けたスタックでは、以後のすべての操作でそのロールが使われる（作成後に取り外せない）点です。スタックへの操作権限を持つユーザーは、PassRoleを持っていなくてもそのロールの権限を利用できるため、サービスロール自体も最小権限にしておく必要があります。逆に、PassRoleを広く許可してしまうと、強力なロールを任意のサービスに渡せてしまいます。CloudFormationに限らず、権限昇格の話で何度も出てくる考え方でした。

Trusted AdvisorのService Limitsチェック

クォータ管理の自動化で中心になるのが、Trusted AdvisorのService Limitsチェックです。アラートの条件が具体的に決まっていて、使用率がクォータの80%に達すると黄色、100%に達すると赤になります。

このチェック結果はAWS Support APIから取得・更新できるので、「クォータ超過でデプロイが失敗する前に検知する」といった自動化に組み込めます。ただし、Service LimitsチェックそのものはBasicプランでもコンソールから確認できる一方、APIの利用自体にはBusinessサポート以上のプランが必要です。Trusted Advisorの全チェックを使う場合も、同じくBusinessサポート以上が前提になります。

通知まで自動化するなら、EventBridgeとの組み合わせです。チェックのステータスがWARNやERRORに変わったことをイベントとして拾い、SNSで運用チームに通知したり、Lambdaで後続の対応につなげたりします。

flowchart LR
    TA["Trusted Advisor
Service Limits チェック
使用率80%でWARN"] -->|"ステータス変化を
イベントとして発行"| EB["EventBridge
ルールは us-east-1 に作成"]
    EB -->|"WARN / ERROR に
マッチしたら"| SNS["SNS"] --> OPS["運用チームへ通知"]
    EB --> LMD["Lambda"] --> ACT["クォータ緩和申請などの
後続対応"]

ここで見落としやすいのがリージョンです。Trusted Advisorはグローバルサービスなので、イベントはすべて米国東部（バージニア北部）リージョンのEventBridgeに出力されます。ルールをus-east-1に作らないと、東京リージョンでいくら待ってもイベントは届きません。閾値とサポートプランの前提に加えて、このリージョン制約まで押さえておく必要があります。

試験結果の振り返り

最終スコアは833点（合格ライン750点）で、83点上回っての一発合格でした。これまで受けたAWS認定でいちばん高いスコアです。

分野別の評価は次のとおりです。

第5分野「インシデントとイベントへの対応」だけは「改善が必要」となりました。

試験を通しての実感は、「難しい」ではなく「知らない」が多い、に尽きます。SAP-C02は要件を読んで積み上げた知識から最適解を選ぶ試験で、考えれば答えに近づけました。いっぽうDOP-C02は、考える以前に「知らない」とどうにもならない問題が多くありました。SAP-C02と重なったのはIaCやモニタリングの考え方までで、CI/CDやコンテナ運用まわりの細部の知識は別物でした。

もうひとつ、この試験は二段構えで理解していないと解けません。まずシステム構成をイメージできる前提知識があり、そのうえで「AWSが提供するDevOps関連のサービス群を活用するなら、どのツールのどの機能を使うべきか」を答えさせられます。構成がイメージできないと問題文が頭に入らず、ツールの理解が浅いと選択肢が絞れません。

時間配分には余裕があり、見直しを入れても30分余りました。180分を使い切ったSAP-C02とは対照的です。矛盾するようですが、これは同じことの裏返しです。知らなければ考えても解けない代わりに、知っていれば即答できる問題が多数を占めます。

おわりに

ドメインが変わると「知らない」が一気に増える感覚は、「AWS Certified Generative AI Developer - Professional」のときにも味わいました。裏を返せば、資格の勉強は、普段の業務では使わないサービスをまとめて学べる機会でもあります。今回もCodeArtifactのように、業務では触れていなかったサービスを、使いどころごと知ることができました。

設計の選択肢が増えたことも収穫でした。「自前で実装しなくても、ネイティブ機能としてすでに用意されている」と知っていれば、その機能を前提にした構成を最初から検討できます。問題演習の中で「もっと簡単な正解」を何度も突きつけられたので、まずマネージドな機能を探して、なければ作る、という考え方が身につきました。

ProfessionalとSpecialtyの上位資格は、これで揃いました。ただ、AssociateとFoundationalのレベルにはまだ合格していません。次はそちらを進めて、全冠達成まで頑張ります。

はじめに

こんにちは。Cyber Security Innovation Group所属、FutureVulsチームの棚井龍之介です。

2026年8月10日(月)開催の Japan Datadog User Group Meetup#20@札幌 に登壇しました。テーマは「Bits AI & Datadog MCP Server」で、さっぽろ大通ビアガーデンの時期に合わせた現地参加限定の回です。会場はクラスメソッド札幌オフィスでした。

前回の登壇で「活用事例はまた今度」という個人的な宿題を残していたので、今回はその回収です。フューチャーからの過去の登壇ブログもあわせてご覧ください。

• Japan Datadog User Group Meetup#8@札幌に登壇しました(棚井)
• Japan Datadog User Group Meetup#14@福岡に登壇しました(FutureVulsチーム 市川さん)

発表内容

私の発表タイトルは「AI時代の”ひとりSRE”のすすめ～Datadog MCP Serverで運用もチーム連携もコンプラ対応も～」です。Datadog MCP Serverを軸として、運用・チーム連携・コンプライアンス対応をひとりで進められるようになった経緯を話しました。

発表の冒頭で、ひとつ謎かけをしました。

うちでいちばん Datadog を使っているメンバーは、Datadog の UI を、ほとんど操作していません。

「ひとり」の意味の変化

私は脆弱性管理SaaSの FutureVuls でSREとCSIRTを担当しています。これまで、ひとりSREは属人化やバス係数1のようなネガティブな文脈で語られてきました。この前提が、AIエージェントの実用化で変わったと私は考えています。AIはトークンの許す限り24時間365日動かせるため、個人で捌ける量が桁違いになり、守備範囲は自分の手が届く範囲から文脈を渡せる範囲へ広がりました。

転機と決断

Datadog導入の当初の目的は、率直に言えば調査工数の削減でした。ところが2026年3月、あるサプライチェーン攻撃について「うちは、影響を受けているか?」という調査を当日中に終わらせる経験をしました。ただ、当日の対応を振り返ると課題がありました。調査に必要な情報がどこにあるかは分かっていても、調査とデータの集約は人手に依存し、実際に調べられるメンバーも限られていました。これはもはやSPOF(単一障害点)なので、改善したいと考え始めました。

たまたま翌月、世界最大級の脆弱性サミットであるVulnCon 2026(米国)に「The CVE Blind Spot」というタイトルで登壇していました(詳細は FutureVulsブログのレポート にあります)。その会場で刺さったのが、次の一言です。

トリアージは、検知ではなく、文脈集約の問題だ

この一言をきっかけに、「データの集約はDatadogへ、活用のインターフェースはMCP Serverへ」という方針を決めました。帰国後に進めたことは2つあります。ひとつは環境整備です。分散していたデータをDatadogに集約し、タグや命名をAIエージェントが読める形に整理して、DatadogやGitHub、ZendeskなどのMCP Server接続を整えました。もうひとつはセキュリティ強化で、インシデント対応の型化や外部認証の取得準備を進めました。ひとりで両方を回せたのは、調査や作業をClaude CodeなどのAIエージェントに任せられたからです。

チームに定着した使い方

ほんの二、三ヶ月でDatadog MCP Serverをベースとした運用が定着しました。問い合わせ対応、開発前の壁打ち、PoCとCSの支援、環境キャッチアップ、パフォーマンス改善などです。発表では、このうち3つを紹介しました。

問い合わせ対応が新規参画者の教材になった

Zendeskの問い合わせチケットを起点に、Claude Codeへ調査を依頼するようになりました。Claude CodeはDatadogやGitHubなどのMCP Serverへ並列に照会し、結果を集めて回答のドラフトと根拠まで作ります。参画直後のメンバーが問い合わせ対応で仕様を学ぶという運用スタイルもできました。MCP連携のフル活用により、問い合わせの総数が増えても少人数で回っています。

作る前に、システム環境に聞く

開発の着手前に、AIエージェントへ現状を調べさせて設計の壁打ちができるようになりました。To-Be(ありたい姿)はリクエストやBacklogに日々集まってきます。一方のAs-Is(いまの姿)は、メトリクスやログが集約済みのDatadogにAIエージェント経由でいつでも聞けます。このTo-BeとAs-Isの差分が、そのまま設計レビューの材料にもなります。上級エンジニアでなければ意識しないメトリクスまで調べてくれますし、変更前後の状態も全てログに残ります。

エンジニア以外のメンバーもDatadogを使い始めた

RUM(Real User Monitoring)と自然言語の組み合わせで、契約単位やユーザ単位の機能利用状況を、非エンジニアのメンバーが自分で調べられるようになりました。PoC支援やCS活動の判断材料になり、セールスやCSのチームにも利用が広がり始めています。ダッシュボードに抵抗があったメンバーも、自然言語で欲しい情報へ届くようになりました。

コンプライアンス対応(ISO 27001/27017)

ここまでは、環境整備の上で生まれた使い方の話でした。並行して進めていたセキュリティ強化でも成果があり、FutureVulsは2026年6月にISO/IEC 27001と27017を取得しました(詳細は FutureVulsのセキュリティへの取り組み をご覧ください)。DatadogのCloud SecurityにあるCompliance機能を、現在地を測る計器として、ギャップ分析の起点や改善サイクルの参考指標に使いました。調べる道具が、証明を支える道具にもなりました。

種明かし

冒頭の謎かけに戻ります。

うちでいちばん Datadog を使っているメンバーは、Datadog の UI を、ほとんど操作していません。

答えは、Datadogへの入口がUIからMCPに変わっていたからです。MCP対応が決め手となり、UI経験ゼロのメンバーを含むチーム全員がDatadogのデータを使うようになりました。一方で、新しい課題もあります。MCP経由の利用が中心になると、UIに触れる機会が減り、機能の全体像を知らないまま使う場面も出てきます。ここは今後、私からメンバーへのUIレクチャーで補っていく必要があります。

発表の最後に、ひとりSREを「全員が意識しなくても使える状態を作る人」と定義し直しました。まず、私がタグや命名、MCP接続をAIエージェントが読める形に整えます。すると、聞き方を共有するだけで、エンジニア以外のメンバーにも使い方が広がっていきます。さらに、私が想定していなかった使い方がチームに生まれて、次の整備のヒントとして還ってきます。この「整える、広がる、還ってくる」という循環は、意思決定の速いひとりだからこそ一気に回せます。

発表は、この3行で締めました。

データをDatadogに集約し、MCPで誰でも使えるようにする。
それにより、守備範囲はSREからセキュリティ、外部認証まで広がる。
そして、Datadogを活用するメンバーが増えていく。

当日の様子

テーマの通り、Claudeの利用状況の監視、Bits Agent Builderの活用事例、DASH 2026のre:Capなど、Bits AIとMCP Serverの事例が並ぶ濃い回でした。セッション一覧は connpassのイベントページ にあります。当日の雰囲気は、Xで #JDDUG を検索すると参加者の投稿から伝わります。

今回いちばんの収穫は、Datadogアンバサダーのようにフル活用しているユーザの意見を直接聞けたことです。Datadogでは次々と新しいサービスが追加されますが、自分のシステム環境ですぐに試せるとは限りません。だからこそ、すでに使い込んでいるユーザから使用感や勘所を聞き、気になった部分をその場で質問できる機会は貴重です。ユーザ同士だからこそ話せる、ネットには載せられないディープな情報が飛び交うのも、ユーザ会ならではの面白さです。

Datadog認定プログラムのすすめ

種明かしで書いた通り、MCP経由の利用が広がるほど、UIや機能の全体像に触れる機会は減っていきます。ここで役立つのが Datadogの認定プログラム です。現在は次の5つがあります。

• Datadog Fundamentals:プラットフォーム利用の基礎。Agentの設定やトラブルシューティング、データの可視化など
• Log Management Fundamentals:ログの収集からパース、検索、分析まで
• APM and Distributed Tracing Fundamentals:アプリケーションの計装と分散トレーシング
• Datadog Cloud SIEM for AWS Fundamentals:AWS環境の脅威検知とインシデントレスポンス
• Datadog Database Monitoring Fundamentals:DBモニタリングの構成とパフォーマンス分析

ユーザ会の参加者には、この5資格を当たり前のようにコンプリートしている方が複数いて、刺激を受けました。試験のシラバスがDatadogの機能一覧を兼ねているので、MCP経由で使い始めたメンバーがUIを学ぶ順序の参考になります。うちのチームでも、それぞれの担当領域に近いFundamentalsから勧めるつもりです。

おわりに

「活用事例はまた今度」という個人的な宿題を1年半越しに回収できました。運営の皆様、会場を提供いただいたクラスメソッド様、参加者の皆様、ありがとうございました。

次の宿題は、Bits AIも含めたその後の話でしょうか。今後とも、JDDUGコミュニティの皆様方、よろしくお願いします。

はじめに

TIG（Technology Innovation Group）の真野です。

Mermaid.js で図を書こうと Mermaid Live Editor を開いたはいいものの、思いの外色々なボタンがあって機能を使いこなせない！と感じている人も多いのではないでしょうか。

そんな人に役立つかもしれない知識を、Tipsという形で9つまとめました。

Mermaid.js とは？

Mermaid.js はテキスト DSL から SVG で図を描画する JavaScript ライブラリです。2014年公開時点ではフローチャートとシーケンス図の2種類しかありませんでした。今ではフローチャート、シーケンス図、ER 図など、v11 時点で30種類近いダイアグラムに対応しています（ちなみに名前は『リトル・マーメイド』から取ったそうです）。

2022年2月に GitHub が Markdown の Mermaid ネイティブサポート を発表してから一気に広まった印象があり、現在は GitHub・GitLab・Notion などが標準対応しています。クライアントサイド JS 単独で動く身軽さと相まって、Diagrams as Code の中心的存在です。

同じく「図をテキストで書く」系としては PlantUML が先行しています。PlantUML は Java ベースで開発されていて、配置図・タイミング図・ユースケース図など UML 記号の網羅性が高いのが特徴です。ただしレンダリングにサーバサイド環境を要する分、GitHub や社内 Wiki にそのまま貼って読ませる気軽さは Mermaid の方がある、という棲み分けかなと思います。フューチャーでも過去に PlantUML 用のカラーテーマ（toy / vibrant / mars）を自作して公式テーマに採用された 経緯があり、社内では Mermaid.js も PlantUML もよく使われています。

Mermaid Live Editor とは？

Mermaid Live Editor は、Mermaid コードを書くとリアルタイムでプレビューしてくれる公式ブラウザ IDE です。ログイン不要で、開けばすぐ使えます。

画面構成は以下のとおり。

• 左ペイン：エディタ（Code / Config / History の3タブ）
• 右ペイン：プレビュー（Diagram / Actions タブ）
• 図のコードは URL に埋め込まれるため、URL を共有すれば同じ図が他人の環境で開ける

裏側は VS Code と同じ Monaco Editor ベースで、Config タブは独立した Monaco インスタンスです。これが後述するショートカット系Tipsに効いてきます。

エディタを効率化する

1. VS Code のショートカットがそのまま使える

Live Editor のエディタは VS Code と同じ Monaco Editor ベースなので、VS Code の感覚で使えるショートカットがそのまま効きます。個人的にヘビロテしているのは次の3つです。

ガントチャートで全タスクの期間を後ろ倒しにしたい時や、シーケンス図で参加者名を一括リネームしたい時にマルチカーソルが効きます。クラス図の属性名リファクタでは、正規表現置換（例：private string (\w+)Name → private string $1_name）が刺さります。「マウスに手を伸ばさない編集」が図面の編集にもそのまま効くのは、地味ですが効果が大きいです。

2. Config タブでスタイルを本体コードから隔離する

Live Editor の左ペイン Config タブに JSON を書くと、theme / themeVariables といったスタイル設定を、コード本体の frontmatter とは分離してプレビューに反映できます。

{
  "theme": "forest",
  "themeVariables": {
    "primaryColor": "#ffefd5"
  }
}

コード本体はこのままの素の状態で動きます。

flowchart LR
  A[開始] --> B[処理] --> C[終了]

frontmatter に config: を書くのと見た目の結果は同じです。

• コード本体と一緒に持ち回りたい → frontmatter に書く。移植性が高まる
• Live Editor 内だけで良い → Config タブに書く。コード本体をスリムに見せることができる

ちなみに、config を変更してもURLは反映されるので、単にMermaid Live Editorで閉じてやり取りする場合はどちらを使っても大差ないです。こだわりがなければ、私は移植性が高いfrontmatter記述が良いと思いますが、どうでしょうか？

3. 時計アイコンで履歴パネルを開きスナップショット保存

画面上部の GitHub アイコンの隣にある白黒の🕓️アイコンをクリックすると、履歴パネルが開きます。Save Current State を押すと現在の編集状態がスナップショットとして残り、あとで一覧から選んで戻せます。

大きな編集をするときは、Save Current State でスナップショットを残すか、Live Editor を別タブで開いてそちらで試すのがお勧めです。元タブの URL（#pako:...）にその時点のコードが保持されているので、別タブの試行が失敗しても元タブに戻ればすぐやり直せます。Save Current State の保存先はブラウザの localStorage なので、別PC・別ブラウザには引き継がれない点に注意してください。

同じ履歴パネルに Save diagram ボタンもありますが、こちらは Mermaid Chart のクラウドに保存するもので、Mermaid Chart アカウントへのログインが必要です。長期保管したいバージョンや環境を跨いで残したいバージョンは、ログインの上 Save diagram を使うか、GitHub 等の外部リポジトリで別途管理する運用になります。

見た目を整える

4. ダークモードでの見え方を気軽に確認する

Live Editor のプレビューエリア右下（白塗りの☀マーク / 🌜️マーク）には、背景をライト/ダークに切り替えるアイコンがあります。

Tip 2 のように themeVariables で独自スタイルを当てた時は、両モードで確認するクセをつけておくのが安全です。ライトモードでは視認性が良くなったが、ダークモードでは文字が読みにくいといったことも多いためです。特に技術ブログなど、外部公開系はどちらでも読めるようにしておくと、読者に優しいです。

5. スクラッチモードを Live Editor の外でも使う

Live Editor のプレビューエリアの下部に、図を手書き風に描画してくれる Sketch モードの切替ボタン（✏️のようなボタン）があります。手書き風の方が頭に入りやすい気がするので、よく使いたくなります。

ただし Live Editor 上で Sketch を有効にしただけでは、コードを他ツールに貼り付けても手書き風は再現されません。Sketch はプレビュー側の描画オプションとして効いているだけで、コード本体には何も書き込まれないためです。

GitHub / Qiita / 自社サイトなどで同じ見た目を再現したい場合は、frontmatter の config.look に handDrawn を明示します。

---
config:
  look: handDrawn
---
flowchart LR
  A[開始] --> B[処理] --> C[終了]

---
config:
  look: handDrawn
---
flowchart LR
  A[開始] --> B[処理] --> C[終了]

look: handDrawn は Mermaid v11 でサポートされた設定で、Rough.js ベースの揺れた線で図が描画されます。Live Editor の Sketch ボタンをオンにした時と同じ見た目が、コードブロックを貼り付けた先でも再現されるようになります。

共有・公開のTips

6. 実は読み取り専用ビューを作れる

Live Editor の共有URLには、実は2種類あります。

• https://mermaid.live/edit#pako:...：エディタUI付きで開く（デフォルト）
• https://mermaid.live/view#pako:...：プレビューだけの読み取り専用ビュー

#pako:... 部分のハッシュは同一なので、URL のパスを edit / view で書き換えるだけで切り替わります。edit はエディタUI付きで編集可能、view は読み取り専用でレンダリング済みの図だけが表示されます。

Share ボタンから取得できるのは edit 系 URL のみで、view URL は UI 上には出てきません。コピーした URL のパス部分を手動で view に書き換える必要があります。

7. URL ハッシュの正体は pako + URL-safe base64

共有URLの #pako:... の正体を追っておきます。Live Editor のserde.ts を読むと、以下の処理が行われています。

1. 図のコードと設定を JSON 化
2. pako で deflate 圧縮（level 9）
3. URL-safe base64 化（+ → -、/ → _）
4. 先頭に pako: プレフィックスを付ける

これが分かると、Live Editor の UI を使わずに共有URLをプログラム生成できます。Python なら標準ライブラリだけで書けます。

import base64
import json
import zlib

state = {
    "code": "flowchart LR\n  A[開始] --> B[処理] --> C[終了]",
    "mermaid": '{"theme": "default"}',
    "autoSync": True,
    "updateDiagram": True,
}
compressed = zlib.compress(json.dumps(state).encode(), 9)
encoded = base64.urlsafe_b64encode(compressed).decode().rstrip("=")
print(f"https://mermaid.live/view#pako:{encoded}")

社内ツールで CSV → 図 → Live Editor URL という一括変換パイプラインを組もうと思えば組めそうです。pakoってなんだろう思ってましたが、ライブラリ名だったとは。

Sample Diagrams を覗く

8. Sample Diagrams にある ZenUML とは？

Live Editor 上部の Sample Diagrams ドロップダウンを開くと、フローチャートやシーケンス図などに並んで ZenUML という見慣れない選択肢が入っています。個人的に以前から気になっていたので、この機会に中身を覗いてみました。

ZenUML は Mermaid v10 から統合されたシーケンス図専用の別 DSL で、標準の sequenceDiagram と並ぶ選択肢として Live Editor に同梱されています（公式ドキュメントの ZenUML ページ）。コードの1行目を zenuml にするだけで切り替わります。

標準 sequenceDiagram：

sequenceDiagram
  Client->>API: POST /order
  API->>DB: INSERT order
  DB-->>API: ok
  alt stock > 0
    API->>Queue: publish
    API-->>Client: 201 Created
  else
    API-->>Client: 409 Conflict
  end

ZenUML：

zenuml
  title 注文フロー
  Client->API.createOrder() {
    API->DB.insert()
    if (stock > 0) {
      API->Queue.publish()
      return 201
    } else {
      return 409
    }
  }

標準のシーケンス図が素直に上から下へ流れる記法なのに対し、ZenUML は Java / C# の関数呼び出しに近い中括弧ベースで、条件分岐・並列処理のネストが中に折り畳まれる形になります。alt ... else ... end で縦に伸びていく標準記法より、深いネストの構造が把握しやすい気がします。while / par / try-catch、@Async / @Starter などのアノテーションもあって、非同期フローの表現力でも ZenUML が優位です。

ただし現時点では大きな落とし穴があります。（※2026年5月時点）手元で試した限り、GitHub Markdown も Qiita も ZenUML コードブロックを描画できませんでした（各プラットフォームが内蔵する Mermaid レンダラーが ZenUML 統合のバージョンにまだ追いついていないのが原因のようです）。Mermaid 最大の旨味である「コードブロックをそのまま貼って読ませる」気軽さが失われるので、現時点では ZenUML の採用は見送り、標準の sequenceDiagram を使うのが無難、というのが実際に試してみての結論です。

セキュアに使う

9. Actions タブの Export 系ボタンは外部サービスに図コードを送信している

Actions タブには Copy Image / PNG / SVG / PDF / Copy Markdown といった便利なボタンが並んでいます。Mermaid にネイティブ対応していない社内 Wiki やメール本文に図を貼りたい時に刺さる機能ですが、実際には Live Editor 本体ではなく外部サービスの mermaid.ink や Kroki にコードを送信してサーバサイドでレンダリングしています。

flowchart LR
  User(("👤
ユーザー"))
  subgraph browser["ブラウザ内（編集・プレビューはここで完結）"]
    Editor[Live Editor]
  end
  subgraph external["外部サーバ"]
    Ink[mermaid.ink / Kroki]
  end
  User -->|①編集・プレビュー| Editor
  User -->|②Export ボタン押下| Editor
  Editor -->|③図コードを送信| Ink
  Ink -->|④画像 or 画像URL| Editor
  Editor -->|⑤ダウンロード / クリップボード| User

プレビューしているだけならブラウザ内で完結していますが、Export ボタンを押した瞬間にコードが外に出る、という構造です。Copy Markdown はクリップボードに以下のような形を返してくれます。画像 URL をクリックすると Live Editor の編集画面に戻れる気の利いた作りで、Mermaid 非対応の Wiki・メールに貼るぶんには便利です。

[![](https://mermaid.ink/img/pako:eNp...)](https://mermaid.live/edit#pako:eNp...)

便利な反面、社外秘の情報を扱うなど固くしたい場合は、これらのボタンを押さないといったチーム方針も考えられます。逆に技術ブログなど最初から公開前提の図であれば、mermaid.ink の URL にクエリパラメータを足して画像フォーマットや解像度の調整もできます。パラメータの詳細は mermaid.ink の README を参照してください。

完全に閉じた環境で図を画像化したい場合は、CLI の mmdc（mermaid-cli）をローカルで回すのが現実的です。

おまけで、Mermaid Chart アカウント（無料）でログインすると、シンタックスエラー時にプレビューエリアに Fix with AI ボタンが表示され、LLM に修正案を返してもらえる機能も使えます。GeminiやClaudeなどに直してもらう人が多いと思いますので、利用したいモチベーションは低いかと思いますが、これも Mermaid Chart の LLM 基盤にコードを送信する仕組みです。そのため、Export 系と同じく社外秘の図では使わない方針が固いでしょう。

おわりに

毎日のように開いている Live Editor ですが、改めて整理してみると意外と触れていない機能がまだまだある、というのが書き終えての率直な感想です。

特に外部データ送信については、よく考えればその通りなのですが、きちんと考えたことはなかったので調べる過程で勉強になりました。

Node.jsのイメージがおかしい

Node.js + PostgreSQLのベース設定をもとに環境を作ると、いきなり起動時に失敗します。Node.js 22であれば問題ないのですが、現在アクティブなサポートバージョンの24だとエラーになります。コンテナイメージのタグの命名規則が変わったようです。

ついでにdebianも最新のtrixieに変えましょう。

- FROM mcr.microsoft.com/devcontainers/javascript-node:1-24-bookworm
+ FROM mcr.microsoft.com/devcontainers/javascript-node:dev-24-trixie

同一のWSLで複数のPostgreSQLを使うDev Containersを利用するとエラー

これ、わかりにくかったのですが、DBに依存しているアプリケーション開発環境の方が起動できない（参加したいネットワーク service.dbがない）という感じのエラーなのですが、よくよく見てみると、DBがエラーで再起動を続けています。

以前はPostgreSQL 17を使っていたのですが、今回18にしてみたら(docker-compose.ymlのタグを書き換えた)らエラーが発生しました。どうも17と18はデータの配置のルールが変わり、なおかつデータの置き場（ボリュームのマウントポイント）も/var/lib/postgresql/dataから、/var/lib/postgresqlに変わったようです。

- version: 3.8
  service:
  :
    db:
-     image: postgres:17
+     image: postgres:18
      restart: unless-stopped
      volumes:
-      - postgres-data:/var/lib/postgresql/data
+      - postgres-data:/var/lib/postgresql
      environment:
        POSTGRES_PASSWORD: postgres
        POSTGRES_USER: postgres
        POSTGRES_DB: postgres

サービス名も重複しない名前にしておく

アプリ名がぶつかるのもよくないということを聞きましたので、そうなるとサービス名とかも変えておく方が良いですね。

  services:
-   app:
+   myproj-app:
      build:
        context: .
        dockerfile: Dockerfile
-     network_mode: service:db
+     network_mode: service:myproj-db

-   db:
+   myproj-db:
      image: postgres:18
      restart: unless-stopped

プロキシ

プロキシ突破はコツがわからないと苦労しがちです。一般的なDockerのプロキシ設定であれば、以下の当ブログの記事で書かれたGUIの設定の内容で十分でしょう。

• ProxyとDockerと新人社員と時々わたし

しかし、特にDockerをDev Containersで使う場合は、通常のイメージ作成で使う

• イメージ取得
• ビルド時

に加えて、

• 通常ユーザーの実行時(npm installやgo get)
• sudoの実行時(apt-get)

と4パターンの通信を扱う必要があり、それぞれ別に設定が必要だったりするためにさらにややこしいです。以前、当ブログで紹介した記事ではあっさり紹介しましたが、今回、まっさらな環境からDev Containersを作るスクリプトを書いてみて、いろいろ試行錯誤したのでその知見も紹介します。

Dev Containersは、.devcontainer/devcontainer.jsonが設定の大本です。ここで開発環境のDockerfile、もしくは既成のイメージを選択します。PostgreSQLなどのDBも併用する場合はcompose.yamlを間に挟むこともあります。プロキシを通過する場合はさまざまなこれらの設定ファイルに記述していく必要があります。その相関関係を記したのが以下の図です。

以下の3つのレイヤーの設定について紹介していきます。

• ホスト環境(イメージ取得、ビルド時のapt-getなどの通信)
• devcontainer.json(実行環境の通信)
• Dockerfile(sudoの通信)

ホスト環境(イメージ取得、ビルド時のapt-getなどの通信)

まず、Dockerが動くホスト環境でDockerのプロキシ設定および、環境変数を指定します。条件によって組み合わせが複雑なので要注意です。

個々の設定が終わったあとの確認方法としては、これらを設定すれば、ホスト環境の中でdocker pullやcurlコマンドで外につなぎにいけるはずなので、Dev Containersの起動前に試してみましょう。また、Dockerfileの中の外部通信(apt-getなど)もいけるはず。

(1): Dockerデスクトップのプロキシ設定

Dockerデスクトップの場合はGUIで設定ができます。これを設定することで、イメージ取得やビルド内の通信の両方でプロキシが取った状態で通信ができます。

(2): Linuxのイメージ取得用の設定

Dockerコマンド自体はデーモンへのリクエストだけを行い、実際のビルドやイメージ取得はデーモンが行います。そのデーモンに対しては専用の設定ファイルがあります。

[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080/"
Environment="HTTPS_PROXY=http://proxy.example.com:8080/"
Environment="NO_PROXY=localhost,127.0.0.1,docker-registry.somecorporation.com"

修正したらデーモンを再起動します。

sudo system docker restart

(3): WSL2+Linuxのイメージ取得の設定

WSL2の中でLinux版のDockerを使っている場合、現行のWSL2であればは自動でWindowsのプロキシを設定する機能(autoProxy)があります。Windows側設定が適切であればイメージ取得は通るようになります。裏のネットワークインターフェース側で解決してくれるようです。デフォルトでtrueになっていますが、明示的に書きたい場合は次のように設定します。

[wsl2]
dnsTunneling=true
autoProxy=true

(4): LinuxのDockerの設定

ビルド時にプロキシ情報の環境変数を渡す方法には、–build-argでコマンドで渡す方法と設定ファイルで渡す方法があります。VSCodeのDev Containersのビルドの中の触れない場所で呼ばれてオプションが追加できないため、ファイルで渡す方法しかないでしょう。

{
 "proxies": {
   "default": {
     "httpProxy": "http://proxy.example.com:8080",
     "httpsProxy": "http://proxy.example.com:8080",
     "noProxy": "*.test.com,localhost,127.0.0.1"
   }
 }
}

Dockerfile内で直接書いてしまう方法もありますが、ポータビリティも下がりますし、認証情報が入る可能性があるため、お勧めしません。

(5): 環境変数の設定(WSL2の場合)

デスクトップ版はWSL2を使います。また、WSL2+Linux版の組み合わせでもWSL2になります。Dev Containerに渡すにはWSL2の中のLinuxの環境変数にプロキシ設定がある状態にしておく必要があります。

設定方法としては、2つあり、まずはWindowsの環境変数にhttp_proxy, https_proxy, no_proxyなどを設定するとともに、次の環境変数も一緒に設定する方法です。

WSLENV="http_proxy/u:https_proxy/u:no_proxy/u"

これらで指定した環境変数がWSL2の中にも取り込まれます。それ以外としては次のLinux単独の環境変数設定方法も使えます。

(6): 環境変数の設定(Linuxの場合)

WSL2ではないLinuxの場合は、いつも通り、ユーザーの.profileとか.bashrcといったところに環境変数でプロキシ設定を書きます。

export http_proxy="http://proxy.example.com:8080"
export https_proxy="http://proxy.example.com:8080"
export no_proxy="localhost,127.0.0.1,host.docker.internal"

devcontainer.json(実行環境の通信)

devcontainer.jsonの中でホスト側の環境変数を実行時に展開してくれる機能があるのでこれを利用します。docker run -e 環境変数=値で渡すのと同じですが、元の変数も参照として書けるため、設定ファイルをプロジェクトで共有する場合にもハードコード不要で安全です。

{
	"remoteEnv": {
		"HTTPS_PROXY": "${localEnv:https_proxy}",
		"https_proxy": "${localEnv:https_proxy}",
		"HTTP_PROXY": "${localEnv:http_proxy}",
		"http_proxy": "${localEnv:http_proxy}",
        "NO_PROXY": "${localEnv:no_proxy}",
        "no_proxy": "${localEnv:no_proxy}"
	}
  }

これで、https_proxy環境変数などを参照するnpmやgo getなどは正しく動きます。

なお、証明書のエラーが出る場合は証明書の検証をやめるオプションを定義して回避もできますが、可能であれば証明書を入れる方がましです。Dockerfileに以下の行を追加しましょう。

COPY my-company-ca.crt /usr/local/share/ca-certificates/my-company-ca.crt

Dockerfile(sudoの通信)

これまでのところでほぼ問題ありませんが、開発環境の中でapt-getで追加のツールなどを入れようとするとエラーになります。devcontainer.jsonは、作業ユーザーの環境変数には設定してくれますが、sudo apt-getとすると、一時的に環境変数が設定されていない別ユーザーに代わってしまい、設定が見えなくなってしまうからです。

sudoしても必要な環境変数を引き継ぐような設定をDockerfileに足してあげることで、自由にapt-getできるようになります。

RUN echo 'Defaults env_keep += "http_proxy https_proxy HTTP_PROXY HTTPS_PROXY no_proxy NO_PROXY"' >> /etc/sudoers

macOSの場合

macOSの場合はWSL2のレイヤーを意識する必要性がないのでシンプルです。Linux VMは確かにありますが、Windowsと違ってパフォーマンスのためにWSL2の中のファイルシステムに環境を作ってWSL2の中からVSCodeを起動するということがないからです。

Docker Desktop版を使うなら、そちらのプロキシ設定とmacOSの一般の環境変数にhttp_proxyなどを設定すればおしまいです。Linux VMの中にわざわざ作るのであれば同じように設定は必要になると思いますが。

まとめ

Dev Containersは便利ですが、若さにあふれているというか、安定性よりも新しいものを、という気概を感じます。そこそこ小さい苦労があったので、メモ代わりに書いてみました。もし、ほかにもこんな問題もあったぞとかがあれば、Xなどでお知らせいただければと思います。

はじめに

Technology Innovation Groupの八木です。

フューチャー社内の有志メンバーでログ設計ガイドラインを作成し公開しました！

ログは、システムの稼働状況を可視化し、トラブルが発生した際に迅速に原因特定するための生命線になります。しかし、その重要性の一方で、プロジェクトごとに設計がバラバラになりがちだったり、とりあえず標準出力しているだけになっていたりと、十分に活用しきれていないケースも多く見受けられます。

本記事では、今回公開したログ設計ガイドラインの背景や、現場で役立つ設計のポイントを抜粋してご紹介します。

ガイドライン作成のモチベーション

これまで、ログ設計は個々のエンジニアの経験則や、プロジェクトごとの慣習に委ねられることが多くありました。しかし、システムが複雑化し、マイクロサービスやクラウドネイティブな構成が当たり前になった現代において、ログの役割は「単なるデバッグ用のテキスト」から「オブザーバビリティ（可観測性）の基盤」へと進化しています。

ログ設計が不十分だと、以下のような課題が発生し得ます。

1. 原因追求ができない: 必要な情報（トレースIDやユーザーIDなど）が不足しており、エラーの原因を追えない
2. 横断的な集計ができない: フォーマットがバラバラで、CloudWatch Logs や Datadog などのツールで検索・集計がしにくい
3. コストと性能: 無意味なログが大量に出力され、ストレージ費用を圧迫したり、アプリケーションの性能を劣化させる

ガイドラインのポイント紹介

ログ設計ガイドラインでは、アプリケーションログを対象に命名規則から出力項目、セキュリティ、コストまで幅広くカバーしています。その中から主なトピックをいくつかピックアップします。

1. ログキー命名規則

特定のプラットフォーム（AWS/GCP）やSaaS（Datadog/New Relic）に依存しすぎない移植性の高いログにするため、標準仕様といえるOpenTelemetry (OTel) Semantic ConventionsやElastic Common Schema (ECS)をベースにした命名規則を推奨しています。

• 標準化のメリット: timestamp や @timestamp といった些細な表記揺れを排除し、ログ解析ツールで利用しやすくする
• 共通スキーマ: timestamp, severity.text, message, trace_id といった、どのログにも含めるべき必須項目を定義する

2. コンテキスト情報の付与

エラーが発生した際、「何が起きたか（メッセージ）」だけでは原因特定に至らないことが多々あります。「どのユーザーが」「どのリクエストで」起こしたのかというコンテキスト情報を付与することで、調査の解像度を高めます。

• トレースID：マイクロサービスなどの分散システムにおいて、サービス間をまたぐ一連の処理を紐付けるためのIDです。これを全ログに含めることで、点在するログを追跡可能にします
• HTTP/DBコンテキスト：リクエストメソッドやパス、ステータスコード、DBクエリの実行時間といった情報を「拡張スキーマ」として定義します。これにより、「特定のAPIだけレスポンスが遅い」「特定のクエリでエラーが頻発している」といった多角的な分析が可能になります

3. 出力ルールとメッセージの書き方

意外と疎かにされがちなログメッセージ自体の書き方について紹介しています。

• 事実とデータの分離: メッセージ内に可変値を入れる（例. User login failed: {userId}） ではなく、メッセージ自体は User login failed と固定し、user.id を構造化データの別フィールドとして分離します。これにより、ログの集計が楽になります
• メッセージコードの導入: エラーログを運用者が参照する「運用手順書（障害対応マニュアル）」と紐づけるために、一意のメッセージコード（例：E001）を付与するパターンを紹介しています
• 「通知フラグ」の考え方: 全てのエラーを即座に通報するのではなく、ログに「通知の是非」のフラグを持たせる設計についても言及しています

4. セキュリティと機密情報

ログに含めてはいけない情報（個人情報、パスワード、認証トークン等）の管理と、誤って出力しないためのマスキングの考え方についてもガイドを設けています。

ガイドライン活動後の感想

私自身、これまでログ設計についてあまり時間をかける機会がありませんでした。しかし、今回のガイドライン活動を通して、今まで慣習として従っていたキー名や構造にもOTel Semantic Conventionsといった標準が存在することや、効率的に開発/運用するための考え方を知ることができました。

加えて、活動内でシニアな方々と議論することで、なぜそのような設計なのかというWhyの部分も学ぶことができたことも大きな収穫でした。

今後は自らのプロジェクトでこれを実践し、開発/運用者が幸せになれるシステム作りに貢献したいと思います。

おわりに

ログは「出力して終わり」ではなく、「トラブル時にいかに迅速に原因を特定できるか」という運用のための資産になります。

今回公開したガイドラインが、皆さんのプロジェクトにおける保守・運用しやすいシステム作りの一助となれば幸いです。

また、ガイドラインを読んでのフィードバックやGitHubでのIssue/PRもお待ちしております！

ログ設計ガイドライン:

• https://future-architect.github.io/arch-guidelines/documents/forLog/log_guidelines.html

先日開催された Datadog User Group Meetup #14@福岡 にて、「リクエストとDB のパフォーマンスを Datadog で監視する」というテーマで登壇してきました。

実は今回の登壇は、開催の1週間前に急遽決定したものでした。先日 札幌の Datadog ユーザ会 で登壇したチームメンバーの棚井さんから「福岡も盛り上がりそうなので、ぜひ行ってきてください」と勧めを受けたことがきっかけです。 (棚井さんの登壇ブログは こちら)

ちょうど私自身、ここ半年ほどパフォーマンス問題の解決に向けて試行錯誤を続けており、その中で得られた Datadog の知見を一度整理して共有したいと考えていたタイミングでもありました。準備期間は短かったですが、熱量の高いうちにアウトプットしようと思い、参加することにしました。

本記事では、当日の発表内容の抜粋と、実際にユーザ会に参加して感じたことを紹介します。

発表内容

当日のスライドはこちらです。

私の登壇内容について、一部のみとなりますが、抜粋してご紹介します。

今回は、FutureVuls というサービスにおいて、ユーザ数増加に伴い顕在化してきたパフォーマンス問題に対し、Datadog を用いてどのようにアプローチしたかをお話ししました。

監視導入前の課題

当初は、パフォーマンスの問題 (特定の画面が遅い、裏でロック待ちが発生している 等) が発生していても、ユーザからの問い合わせがあるまで気づけない状態でした。

そこで、パフォーマンス監視の第一歩として「リクエストのレイテンシ（ユーザ体験）」と「DBのスロークエリ（システム全体への影響）」の2点を重点的に監視することにしました。

リクエストの監視 : アラート疲れと「日次集計」への転換

リクエストレイテンシの監視では、当初「30秒を超えたら即アラート」という設定にしていました。しかし、これでは通知が鳴り止まず、いわゆる「アラート疲れ」を起こしてしまいました。

そこで、「レイテンシの問題は、傾向を掴んで優先度をつけられるようにすることが重要であり、リアルタイム性は必要ない」と割り切り、カスタムメトリクスを用いた日次集計へと運用を切り替えました。

これにより、各リクエストのパフォーマンス悪化がどの程度ユーザに影響を与えているかを大まかに把握できるようになり、開発チーム内で定量的な議論ができるようになりました。

DB のスロークエリの監視

一方で、DBのスロークエリ（ロック待ちなど）に関しては、以下の 2 点を達成するため、Database Monitoring (DBM) モニターを用いてリアルタイムにアラートを飛ばす構成にしました。

1. pg_stat_activity (リアルタイムで走っているクエリの情報を取得できるビュー) を用いた原因特定およびボトルネック解消のため、問題発生にリアルタイムで気づきたい
2. 「異常に時間がかかっているスロークエリ」が検出された時にアラートが上がってほしい

結果として、問題発生時にリアルタイムで気づけるようになり、どんな問題が発生しているかを調査しやすくなりました。

まとめ

最終的に、監視対象の性質に合わせて監視方法を使い分けることが、重要であるという結論に至りました。

詳細な設定方法や、カスタムメトリクスの具体的なクエリについては、ぜひスライド本編をご覧ください。

Datadog ユーザ会に参加してみてよかった点

Datadog ユーザ会に参加してよかったと感じる点を、インプット面とアウトプット面に分けて記載します。

インプットの観点

Datadog は機能数が膨大なため、概要はなんとなく把握しているけれど普段の業務には活かせていない機能や、そもそもあまり知らない機能が眠っていたりします。実際の現場で Datadog を使いこなしているユーザの発表を聞くことで、今まであまり知らなかった機能について知ることができたり、普段使っている機能についても「そんな使い方もあるのか！」といった発見があったりして、とても良かったです。

また、現場で参加すると、発表の中で深掘りしたい点が出てきた際、発表者に気軽に質問できるのも良いなと思いました。現場で使用している人の意見は腹落ち感が段違いで、「Datadog をより活用していこう」というモチベーションアップにもつながりました。

アウトプットの観点

「他の人に教える」というアウトプットの機会を作ることで、自分が断片的に持っていた知識を体系化できたり、あやふやだった知識をしっかり理解し定着させることに繋がったりと、結果的に自分に返ってくる、ということをあらためて実感しました。

おわりに

今回は開催1週間前という駆け込みでの参加でしたが、結果として非常に有意義な時間を過ごすことができました。

他の参加者の方々と意見交換することで、自分たちの取り組みを客観的に見直す良い機会になりました。また、熱量の高いコミュニティに触れることで、エンジニアとしてのモチベーションも大きく向上しました。今回得られた知見や刺激を、今後のFutureVulsの開発や運用に活かしていきたいと思います。また、共有できそうな事例が溜まったら、積極的に外部へ発信していこうと思います！

最後に、温かく迎えてくださった運営や参加者の皆様に感謝いたします。

9/2に開催された「Grafana Meetup Japan #6｜どうする？Grafanaする！」にLTで登壇してきたので、参加レポートも含めて記事にします。当日のYouTubeもアーカイブ公開されているのでそちらと合わせて読んでいただけると幸いです。

自身のLT: Grafana Alloyのconfig運用

今回、私が登壇したネタになります。資料は以下です。

Grafana Alloyの利用経緯

私が今所属しているチームでは、従来EC2で動かしていたアプリケーションをECS on Fargateで稼働するようにリアーキを実施しました。また、合わせて利用していた監視やジョブについても再選定の対象とし、コンテナとの相性、今後の展開性も含めてGrafanaを利用しました。

その時、コンテナから様々なメトリクスデータを収集する時に利用するツールとしてGrafanaと合わせてAlloyを選定しました。

Alloyの導入の時に考えたこと

AlloyはHCL(HashiCorp Configuration Language)に近い記法で書くことができ、個人的には馴染みが良かったのですが、実際の環境や運用を考えてみると…

• アプリケーション
  • Java
  • Go
  • ミドルウェア
• 稼働環境
  • EC2(VM)
  • ECS on Fargate(コンテナ)
• 環境面
  • 本番
  • ステージング
  • 開発

と様々な要因で統合は厳しいと判断しました。

しかし、なるべく省力化を図るために、以下の2つを検討し、実践しました。

環境変数で吸収

Alloyにはsys.envという形で環境変数の値を取得できるライブラリがあります。

• https://grafana.com/docs/alloy/latest/reference/stdlib/sys/

このライブラリを以下の形で使うと、環境変数の値が取得でき、例示している (LOKI_PUSH_URLに向けて)ような収集したデータのプッシュ先を変えることができます。

loki.write "loki_destination" {
  endpoint {
    url = sys.env("LOKI_PUSH_URL")
  }
}

起動時にファイルを取得する方法

環境変数で環境面に対応できましたが、もう1つ、Alloyが収集する対象のアプリ、ミドルに対しての適用です。

様々なログのパス、メトリクスのパスなどはどうしても環境変数で吸収することは難しいので、ファイルごとに分離し、Alloyコンテナが起動する時にファイルを取得する形式としました。

この2つの方法を織り込むことで、複数の環境面、複数の収集対象に適用できました。

いただいた質問

当日、質問を募集するslidoにていただいた質問について、当日で回答できなかったので、こちらで回答します。

Q. Alloyを運用していて、パフォーマンスの問題はありましたか？Otelのcollectorだと、必要なパッケージだけ入れてビルドする、という運用ですが、Alloyはデフォルトで全部盛りと聞いていて、ナレッジあればお願いいたします
A. 全部盛りであると理解しています。私のチームでも実際にAlloyからMimir、Lokiへ転送しているため、このほかGrafanaのスタックに対しても使えます。

Q. Alloyは1つのコンテナでメトリクスとログ全て送信していますか？それとも用途によってコンテナを分けていますか？
A. 今回は1つのコンテナで全てメトリクスもログも収集、送信しています。

Q. Remotecfgを使っていないという認識で合っていますか？もし使わなかった理由などあればご享受頂けば幸いです。
A. remotecfgは知らなかったです。ドキュメントを見てみたのですが、その過程としてremote.s3というコンポーネントがあるらしく、これを使うと以下のように書けそうです（未検証のため確認が必要です）。

remote.s3 "external_config" {
  path = "s3://bucket-name/alloy/config.alloy"
}

他にもアクセスキーなどについても設定できそうでした。今回のユースケースであればFargateにタスクロールがついているので、そちらで賄えるのではないかと考えています。

そのほかのセッション、LT

Grafanaスタックをフル活用したオブザーバビリティ基盤の紹介

今回のメインセッションであるGO株式会社のQuentinさんによるセッションでした。

GOでは100を超えるマイクロサービスをAWS、およびGoogle Cloud上のKubernetes基盤で稼働させており、これを「Kenos」と呼称しているそうです。

この大きなクラスターを稼働させる上でオブザーバビリティがより重要になってきていましたが、SaaS監視ツールの料金高騰や問い合わせ対応時にツールが分散している煩雑さから、Grafanaのスタックを徐々に自前で導入しています。

規模感は日々ログがTBオーダー、メトリクスやトレースでもGBオーダーと、私も自前で構築をしているものの桁が違いすぎて非常に驚いたこともありますし、さらにその規模を安定して運用されているところが興味深かったです。個人的に改めて納得したポイントではありますが、同じツールでも自前で運用するか、SaaSで展開するかは扱っているデータサイズにも依存していると思いました。ただ、Grafana Cloudもあるので、ある程度運用負荷が高いなどがあれば切り替えることができるのもGrafanaの良さだと感じました。

また、Grafanaの自前運用での振り返りとして話されていたのは、初期の設定の躓きであったり、運用の安定性などについて自身でも気をつけたいところでした。例えば、Grafanaでの障害切り分けをする際に、Grafana自体が過負荷になりサービスダウンしてしまうといったことがあったようで、ここはGrafana自体のチューニングであったり、Loki, Mimirまで含めて設定を洗っておこうと思います。

そのほかの話については以下のブログにも公開されており、見返してみると私もだいぶお世話になったブログでした。

• LGTM！オブザーバビリティ基盤第1話
• Grafana Lokiでログを検索 | オブザーバビリティ基盤第2話
• Grafana LokiのLogQLを理解する

Grafanaをリバプロ配下で動かすときにやること ~ Grafana Liveってなんだ ~

Grafanaがサクサク、ヌルヌル動く秘密の部分を解説してくれるセッションでした。Grafanaにはストリーミングの機能があり、ここではWebSocketを使っていますが、これをNginxなどのリバースプロキシ経由でどう使うか、使えるようにするか解説されました。
私自身は過去、複数の環境を束ねているNginx越しでGrafanaを触ろうとして方式を変えた記憶があったので、改めてトライしてみようと思いました。

Grafana MCPサーバーによるAIエージェント経由でのGrafanaダッシュボード動的生成

Grafana MCPサーバを実際に使って利用できるダッシュボードを作成するセッションでした。今回はClaudeに対して自然言語で入力、対話を続けていき、最後は…

OSS版でも対応している限りMCPサーバは使えるようですので、また試したいものが増えてしまいました。

イベント中の小話

今回はGrafana Labsの方もいらっしゃったのですが、なんとついに立ち上がった日本法人の入社初日だったらしく、日本のGrafanaのコミュニティが大きく変わりそうな予感がしました。そんなタイミングであることはもちろん知らなかったのですが、LTをここでできたのは個人的には良かったなと思いました。

まとめ

今回はLTという形で登壇をしつつイベントに参加しましたが、課題を持って、感じてイベントに参加するとイベント後の懇親会も含めてより有意義になることを改めて感じたので、ちゃんと話題としても持っていこうと思いました。

また、今回は実際にto C向けサービスを運用している立場の声を聞くことができたので、よりどう活かそうか、取り込もうかと考えられたことも大きかったので、自身で取り組んでいる構成も見直そうと思います。

今後の日本におけるGrafanaのコミュニティがより盛り上がるように微力ながら頑張っていけたらと思います。

参考

• Grafana Alloyを使って、EKSクラスタ外部のサーバからメトリクス取得を試してみた

初めまして、コアテクノロジーグループに所属している二宮と申します。

私たちのチームでは普段Grafanaを利用していますが、Grafana Alloyはまだ使ったことがありませんでした。当初は、promtailの後継ツールとしての利用のみを考えていただけでしたが、ドキュメントを読み進める内にAlloyを使えばテレメトリデータの活用方法がさらに広がるのでは…？ と感じました。

そこで今回は、Alloyの豊富な機能の一部を利用してEKSクラスタ外部のサーバ監視に挑戦してみました。本記事では、その設定手順や使ってみて分かったポイントを、初めてAlloyに触れた目線でご紹介します。

1. Grafana Alloyとは

Grafana Alloyは、Grafana Labsが開発するOSSのテレメトリ収集エージェントです。

メトリクス・ログ・トレース・プロファイルをこれ1つで統合的に扱うことができます。Grafana Agentの正式な後継製品であり、Promtailが担っていたログ収集機能もAlloyに統合されています。OpenTelemetryをベースに作られているため、柔軟で強力なデータパイプラインを構築できるのが特徴です。

2. 構成説明

• EKSクラスタ: メトリクスの管理先となるPrometheusと、可視化ツールであるGrafanaをすでに構築済みです

• EC2インスタンス: 監視対象であるEKSクラスタ外部のサーバです。このサーバ上にGrafana Alloyをコンテナとして構築します

  • EC2インスタンスの準備: Alloyをコンテナとして動かすため、監視対象のEC2インスタンスにはDockerおよびDocker Composeを事前にインストールしています。

• 通信経路の確保: 本記事では詳細を割愛しますが、AlloyからPrometheusへデータを送信できるよう、事前にセキュリティグループを設定します。

• 本記事作成時の環境: 今回の検証で使用した、主なソフトウェアの構成は以下の通りです

  ツール	バージョン
  Grafana	12.0.0
  Grafana Alloy	1.8.3
  Prometheus	3.4.1

3. 今回の検証で利用するAlloyコンポーネントの概要

本記事の中では以下のコンポーネントを利用しています。

実際の利用方法と記載内容は後述します。

• prometheus.export.unix
  メトリクスを生成します。
  このコンポーネントを利用することで、別途node_exporterをインストールしなくても、CPU、メモリ、ディスクスペース、ディスクI/O、ネットワークなどUNIXシステムのメトリクスを公開できます。
• prometheus.scrape
  exporterが公開したメトリクスを定期的に収集(スクレイプ)します。
  指定されたtargetsのHTTPエンドポイントにアクセスしてデータを取得します。
  収集したメトリクスは、forward_toで指定された次のコンポーネントに渡されます。
• prometheus.relabel
  Prometheus形式のメトリクスが持つラベルを、動的なルールに基づいて書き換え・追加・削除します。
  正規表現を使ったラベルの生成や、不要なメタデータラベルの削除など、メトリクスの整形・加工を担います。
• prometheus.remote_write
  収集・加工したメトリクスを、最終的な保存先であるPrometheus互換のバックエンドに送信します。
  Prometheus Remote Writeプロトコルを使って、設定されたendpointのURLにデータをまとめて送信します。
  今回、送信先はPrometheusにしていますが、Grafana MimirやGrafana Cloudなども指定可能です。
  送信先のエンドポイントURLはIngressやNodePortまたはTargetGroupBinding等で設定したものを指定します。

4. 設定方法

4-1. コンポーネント同士の連携方法

Grafana Alloyではconfig.alloyという設定ファイルで、機能単位である「コンポーネント」を繋ぎ合わせ、テレメトリデータの取得ができます。

設定ファイルは、Grafana agentの設定言語であるriver言語をベースに記述され、宣言的に記述できるという特徴があります。

この連携には、データを次のコンポーネントに押し出すPush方式と、他のコンポーネントからデータを引き出すPull方式があります。

Push方式は、Alloy内部にてコンポーネント間でデータを渡す仕組みで、forward_to引数で出力先を指定し、データを受け取る側のコンポーネントはreceiverという入力口を持っています。Pull方式も、Alloy内部でコンポーネントが連携するための仕組みで、targets引数で入力元を指定します。データを提供する側のコンポーネントはtargetsという監視対象リストを公開しています。

他のコンポーネントを参照する際は、<コンポーネント種別>.<コンポーネント名>.<公開名>の形式で記述します。

• コンポーネント種別 : prometheus.scrapeやprometheus.exporter.unixなど
• コンポーネント名 : “internal_node_metrics”や”set_instance_name”など、自分で付けた名前
• 公開名 : receiverやtargetsなど、各コンポーネントが公開している名前

4-2. config.alloy

config.alloyの設定です。

// Node Exporter相当の機能をAlloy内部で提供
prometheus.exporter.unix "default" {
  // コンテナ内でホストOSの各パスがどこにマウントされているかを指定(compose.ymlのvolumes設定と合わせる)
  // procfs: CPU使用率、メモリ情報、実行中プロセスの一覧などの情報
  procfs_path = "/host/proc"
  // sysfs: 接続されているデバイスやドライバに関する情報
  sysfs_path  = "/host/sys"
  // rootfs_path: ホストOSのルートファイルシステム(/)のマウントパスを指定,ディスク使用量などのファイルシステム関連のメトリクスを正しく収集できるようにする
  rootfs_path = "/rootfs"
}

// prometheus.exporter.unixが公開するメトリクスをスクレイプする設定を記載
prometheus.scrape "internal_node_metrics" {
  targets    = prometheus.exporter.unix.default.targets          // 内部エクスポーターターゲットを指定
  forward_to = [prometheus.relabel.set_instance_name.receiver]   // スクレイプしたメトリクスの転送先の指定
  scrape_interval = "15s"                                        // メトリクス収集頻度を15sに変更(デフォルトは60s)
}

// 収集したメトリクスのラベルを整形
// コンポーネントを"set_instance_name"という名前で定義
prometheus.relabel "set_instance_name" {
  // relabelコンポーネントからの転送先を、remote_writeに設定
  forward_to = [prometheus.remote_write.stg_prometheus.receiver]

  // 書き換えルールを定義
  rule {
    // 書き換えの元となるラベルとして "instance" を指定
    source_labels = ["instance"]
    // 上書きしたいラベルとして "instance" を指定
    target_label  = "instance"
    // 上書きする値として、環境変数からホスト名を直接取得
    replacement   = env("HOSTOS_HOSTNAME")
  }
}

// Prometheusにメトリクスを送信
// Prometheusへの送信設定を定義
prometheus.remote_write "stg_prometheus" {
  // メトリクスの送信先となるPrometheusサーバのremote_writeエンドポイントURLを指定
  endpoint {
    url = "http://<prometheus-endpoint>/api/v1/write"
  }

  // WAL(Write-Ahead Log)の設定
  // 送信先のサーバがダウンしている場合などに、メトリクスを一時的にディスクに保存してデータ損失を防ぐための仕組みです。
  wal {
    // 正常に送信が完了した古いデータを、WALから削除する頻度を1時間に設定。
    truncate_frequency = "1h"
  }

  // このAlloyインスタンスから送られる全てのメトリクスに共通のラベルを付与
   external_labels = {
     cluster = "external",
   }
}

この設定によって構築される、メトリクスデータのパイプラインを図にすると以下のようになります。

4-3. その他のファイル、ディレクトリ構成

作成したconfig.alloyを読み込み、Alloyコンテナを起動するため、compose.ymlは以下のように記載しています。

services:
  grafana-alloy:
    image: grafana/alloy:v1.8.3     # 今回の検証で利用したバージョンです
    container_name: grafana-alloy
    hostname: grafana-alloy
    restart: always
    user: root
    pid: host  # Node Exporter機能がホストのプロセス情報を正確に収集するため
    environment:
      - TZ=Asia/Tokyo
      - HOSTOS_HOSTNAME=${HOSTNAME}
    volumes:
      - /opt/volumes/grafana_alloy/grafana_alloy:/grafana_alloy/:ro
      # Alloy の WAL (Write-Ahead Log) データ用永続ボリューム
      - /data/app/grafana_alloy/wal:/var/lib/alloy/data
      - /etc/localtime:/etc/localtime:ro
      # prometheus.scrapeのためにホストの重要なパスをマウント
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/rootfs:ro
      #diskstatsコレクターが参照するため
      - /run/udev/data:/run/udev/data:ro
    ports:
      - "12340:12340"
    command:
      # 'run' サブコマンドで設定ファイルを指定してAlloyを実行
      - "run"
      - "/grafana_alloy/etc/config.alloy"
      # --storage.path で WAL などのデータディレクトリを指定 (volumes でマウントしたパスと合わせる)
      - "--storage.path=/var/lib/alloy/data"
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "3"

networks:
  default:
    external:
      name: stg_network

• /data配下のディレクトリ構成
  AlloyのWAL(Write-Ahead Log)機能によるデータ永続化のため、compose.ymlでホストOSのディレクトリマウントを行っています。
  送信先のPrometheusがダウンしていても、Alloyは未送信のメトリクスをこのWALに一時的に保存します。
  コンテナを再起動してもデータが消えないようにホストOSに保存し、メトリクスの損失を防ぎます。
  マウント先のディレクトリまで作成後、ディレクトリ配下に作成されるファイルやディレクトリは、Alloyが自動で作成・削除します。

/data/app/grafana_alloy/
└── wal                                        # WALデータが格納されます
    ├── prometheus.remote_write.stg_prometheus
    │   └── wal
    │       ├── 00000325
    │       └── checkpoint.00000324

• Prometheus側の設定
  Grafana Alloyからデータを受け取るには、送信先であるPrometheus側でremote-writeリクエストを有効にする必要があります。
  今回、Prometheusはkube-prometheus-stackのHelm Chartを利用しているので、values.yamlを編集してこの設定を有効にしています。

  • values.yamlの設定方法
    values.yamlで--web.enable-remote-write-receiverという起動オプションを追記する必要があります。

    containers: - name: prometheus args: # 下の行を追記 - "--web.enable-remote-write-receiver"

    この設定を追記し反映させることで、PrometheusがAlloyからのデータを受け付けられるようになりました。

5. Grafana上からダッシュボードを用いたメトリクス可視化

ダッシュボードにはGrafana Labsから提供されているNode Exporter Full を利用します。

上記URLからJSONをダウンロードして、Grafana上のDashdoardsを選択し、Import dashboardでJSONをアップロードしダッシュボードを作成します。

5-1. Variables(変数)の設定

GrafanaのVariablesを設定し、監視対象のサーバをドロップダウンで選択できるようにします。

1. ダッシュボード右上のeditをクリックし、Settingsを選択します。
2. Variablesタブに移動してnodeを選択します
3. Label filtersに設定されているラベルを削除して、Label filtersにcluster = externalを設定
4. 画面下のRun Queryを押して対象のサーバが表示されたら、Save dashboardから保存します。

5-2. 主なダッシュボードパネル

「Node Exporter Full」ダッシュボードには多くの情報が表示されますが、一部パネルについてご紹介します。

• CPU Basic: CPUの基本的な使用率をuser,system,iowaitなどのモード別に表示し、サーバの負荷状況を確認できます
• Memory Basic: システム全体のメモリ使用量、空き容量、バッファやキャッシュとして利用されている量が表示され、メモリ不足の兆候を把握できます
• ディスク Space Used Basic: ディスクごとの使用率(％)を確認できます
• Network Traffic Basic

ネットワークインターフェースごとの送受信トラフィック(MB/s)を表示し、通信量の急増や異常を検知できます。

インポートしたダッシュボードは自由にカスタマイズが可能なので、必要に応じてパネルの追加や削除ができます。

5-3. 複数サーバの監視

4. 設定方法に記載した設定のサーバを複数台構築した場合、instanceを切り替えることで監視対象サーバを切り替えることができます。

5-4. 監視設定

今回はメトリクスの可視化までを行いましたが、収集したメトリクスを元に閾値を設定し、アラート設定も可能です。

アラートの通知先として、Slackやメール等、様々なツールを指定できるため、システムの異常を迅速に検知する体制を構築できます。

6. まとめ

Grafana Alloyの機能の一部である、メトリクスの収集・送信設定を行い、複数サーバの監視にも対応できるダッシュボードを作成しました。

コンポーネントの記載方法は少し独特ですが、慣れたらパズルのように組み合わせて直感的に設定できそうと感じました。Alloyはメトリクス以外にもログ、トレース、プロファイルも収集できます。

今後はこれらの機能も試し、Grafanaを利用したデータ利活用をさらに広げていきたいです。

最近仕事でLLMサーバーを構築することになりました。

雰囲気をお伝えすると、HuggingFaceの transformers をFastAPIのようなフレームワークでラップしたものです。

from fastapi import FastAPI, Request
from transformers import pipeline

app = FastAPI()

generator = pipeline("text-generation", model="Qwen/Qwen2-0.5B-Instruct")

@app.post("/generate")
async def generate(request: Request):
    data = await request.json()
    prompt = data.get("prompt", "")
    result = generator(prompt, max_new_tokens=50)
    return {"output": result[0]["generated_text"]}

curl -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "生命、宇宙、そして万物についての究極の疑問の答え"}'


# 42という答えを期待していたのですが、軽量モデルだからか無理でした
{"output": "生命、宇宙、そして万物についての究極の疑問の答えを探求します。あなたは「あなたの世界」をどのように描いていますか？何がその世界に存在するのか、そしてそれがどのような形で存在しているのか？そし"}

これらをECSでホストするべく Python のベースイメージでコンテナ化したのですが、LLM関連のパッケージをインストールしたコンテナイメージは非常に大きくなります。

例えば、 huggingface/transformers-pytorch-gpu は約10GBです。

# nerdctl  images
REPOSITORY                              TAG       IMAGE ID        CREATED           PLATFORM       SIZE       BLOB SIZE
huggingface/transformers-pytorch-gpu    latest    f0a0db1c2168    23 minutes ago    linux/amd64    18.66GB    9.746GB

中身を調べてみるとcudaやpytorchなどが重量級です。

4.8G    /usr/local/cuda-12.6
2.7G    /usr/local/lib/python3.10/dist-packages/nvidia
1.6G    /usr/local/lib/python3.10/dist-packages/torch

さらに私の場合、モデルの重みをイメージに同梱していたためサイズが肥大化していました。コンテナイメージサイズの削減を頑張るべきかもしれません。例えば思い付きですが、モデルの重みはイメージに含めずにボリュームとして切り出してマウントするなどが考えられます。

しかし、今回はECSなどでコンテナの起動を高速化することを目標に、イメージを遅延して読み込むLazy-pullingな技術に目を向け、LLMコンテナに対し効果があるのかどうかを検証します。

CNCF連載 ということで取り上げるのはGraduatedなプロダクトであるcontainerdです。

containerdとSnapshotter

docker runしたときの処理の流れをざっくりおさらいすると、

1. イメージを取得して展開
2. ファイルシステムをホストと分離
3. いろいろ名前空間を分離しつつプロセスを起動する

…です。この上半分くらいを担当するのがcontainerdに代表されるCRIランタイムというものです。DockerやKubernetesの影にいます。

containerdの機能はpluggableです。例えば 下半分くらいを担当するOCIランライムはOCIランタイム仕様に則っていれば切替可能です。

今回着目するイメージの展開やファイルシステムを管理するコンポーネントはSnapshotterと呼ばれ、これも差し替え可能になっています。

デフォルトはoverlayfsですが、lazy pull対応のsnapshotter(Remote Snapshotterといいます)に差し替えることでその機能を利用する形です。

Snapshotterはデーモンとして起動させunix domain socketごしにcontainerdと通信します。

Lazy Pullingとは

通常のコンテナ起動では、イメージ全体をダウンロードしてから展開・プロセス起動という流れですが、コンテナ起動時に全てのファイルが必要なわけじゃないよね、という観察があります。

この手のツールのREADMEでよく参照されているHarter et al.によると、コンテナ起動時間の76％がイメージダウンロードに費やされている一方、実際にコンテナが開始するのに必要なデータは平均で6.4％だそうです。

なので、Remote Snapshotterは初回起動時は必要なファイルだけをpullしてプロセスを開始してしまいます。レジストリはFUSEを介してマウントしておき都度取得する、という仕組みです。

ところでコンテナイメージのレイヤーのフォーマットであるtar.gzにおいては、全てのファイルを展開せずに特定のファイルのみにアクセスし取得する、ということができません。イメージのレイヤー内のすべてのファイルがtarにアーカイブgzipで圧縮されており団子状態なためです（Seekableではないという言い方をします）。

ということでRemote Snapshotterを使うにはコンテナイメージをSeekableなイメージに変換する必要があったり、どのファイルがどのレイヤーのどのオフセットに含まれているのかのインデックスをメタデータとして持たせたりする必要があります。

今回検証するのは以下の2つです。

stargz-snapshotter

• eStargzというイメージフォーマットでlazily-pullableを実現します

soci-snapshotter

• AWSが提供していてECS・Fargateで使えます
• AWSのブログはこちら

実験してみた

LLMで文を生成するスクリプトをコンテナ化し、レジストリにpushしておき、以下の3パターンのsnapshotterでdocker runの時間を計測しました。

• overlayfs: 通常のsnapshotter
• stargz-snapshotter
• soci-snapshotter

検証環境構築

今回の検証環境はこんな感じです。

docker runするホスト

• EC2
• m5.large
• Ubuntu
• 東京リージョン

コンテナレジストリ

• ECR
• 東京リージョン

今回LLMを実行しますが、GPUは使わないことにしました。

containerdとそのクライアントのnerdctl(docker CLIのようなもの)などをインストールします。このあたりはcontainerdのgetting startedの手順通りです。
https://github.com/containerd/containerd/blob/main/docs/getting-started.md

snapshotter設定をstargz-snapshotterを例にざっくり記載すると、まずsnapshotterをインストールしてデーモンとして起動します。

tar -C /usr/local/bin -xvf stargz-snapshotter-${version}-linux-${arch}.tar.gz containerd-stargz-grpc ctr-remote
wget -O /etc/systemd/system/stargz-snapshotter.service https://raw.githubusercontent.com/containerd/stargz-snapshotter/main/script/config/etc/systemd/system/stargz-snapshotter.service
systemctl enable --now stargz-snapshotter

conatinerdのconfigを設定してデーモンを再起動します。

version = 2

# Enable stargz snapshotter for CRI
[plugins."io.containerd.grpc.v1.cri".containerd]
  snapshotter = "stargz"
  disable_snapshot_annotations = false

# Plug stargz snapshotter into containerd
[proxy_plugins]
  [proxy_plugins.stargz]
    type = "snapshot"
    address = "/run/containerd-stargz-grpc/containerd-stargz-grpc.sock"

systemctl restart containerd

soci-snapshotterも大体同様です。

実験用のコード

LLMのモデルをロードし、文を生成させるだけのスクリプトを用意します。

from transformers import pipeline

pipe = pipeline(task="text-generation", model="Qwen/Qwen2-0.5B-Instruct")
out = pipe("生命、宇宙、そして万物についての究極の疑問の答え", max_new_tokens=20)[0]['generated_text']
print(out)

コンテナのエントリポイント用のスクリプトを用意します。イメージをpullする速度とPython実行の速度を分けて計測したい意図でshellscriptでラップすることにしました。

#!/bin/bash
set -e

echo "=== [START] $(date --iso-8601=seconds) ==="
START=$(date +%s)

time python run.py

END=$(date +%s)
echo "=== [END] $(date --iso-8601=seconds) ==="
echo "Duration: $((END - START)) seconds"

以上をコンテナ化します。ここでLLMのモデルをあらかじめpullしてイメージに同梱しておきます。アンチパターンな気もしますが…。

FROM python:3.11-slim

RUN apt update && apt install -y git && \
    pip install --no-cache-dir torch transformers

# キャッシュとしてモデルを事前にpullして含める
RUN python -c "from transformers import pipeline; \
    pipeline(task='text-generation', model='Qwen/Qwen2-0.5B-Instruct')"

WORKDIR /app
COPY run.py .
COPY entrypoint.sh .
RUN chmod +x entrypoint.sh

CMD ["./entrypoint.sh"]

ちなみにイメージサイズは5GBくらいでした。

nerdctl  images
REPOSITORY                                           TAG               IMAGE ID        CREATED        PLATFORM       SIZE       BLOB SIZE
foobar.dkr.ecr.ap-northeast-1.amazonaws.com/foobar    overlayfs    728928885b94    9 hours ago    linux/amd64    7.929GB    4.755GB

それぞれのsnapshotterに対応させるためイメージフォーマットの変換や、インデックスの作成します。

# stargz フォーマットに変換
nerdctl image convert --estargz --oci foobar.dkr.ecr.ap-northeast-1.amazonaws.com/foobar  :latest foobar.dkr.ecr.ap-northeast-1.amazonaws.com/foobar:estargz
nerdctl push foobar.dkr.ecr.ap-northeast-1.amazonaws.com/foobar:estargz

計測項目

以下を計測します。

1. イメージpull + containerd初期化時間（time nerdctl run）
2. コンテナ内でLLMが起動して実行終了するまでの時間（entrypoint.shで計測）

各snapshotterでの実行コマンドは以下の通りです。

# overlayfs（通常）
time nerdctl --snapshotter=overlayfs run --rm \
  foobar.dkr.ecr.ap-northeast-1.amazonaws.com/foobar:overlayfs

# stargz
time nerdctl --snapshotter=stargz run --rm \
  foobar.dkr.ecr.ap-northeast-1.amazonaws.com/foobar:stargz

# soci
time nerdctl --snapshotter=soci run --rm \
  foobar.dkr.ecr.ap-northeast-1.amazonaws.com/foobar:soci

結果

結果はこんな感じでした。

sociは速くなってますが、stargzはむしろ遅くなってますね！

結局イメージサイズに対し支配的なcudaやpytorch系のライブラリへのアクセスが必要なので、総実行時間としてはガンっと速くなったりはせずむしろ遅くなるケースもあるということなんでしょうか。チューニングの余地はありそうです。

検証は若干いい加減なので追試が待たれます。

ちなみに echo hello みたいなコマンドを実行させるケースだと stargz、sociは一瞬で終了しました。試してないですがWebサーバーの起動などだと、遅延読み込みの嬉しさが感じられるのかもしれません。

# stargz
time nerdctl --snapshotter=stargz run --rm \
  foobar.dkr.ecr.ap-northeast-1.amazonaws.com/foobar:stargz echo hello

おわりに

LLMサーバーをホストするにあたって、コンテナ起動を高速化するLazy-pulling技術について検証しました。sociはAWSで導入しやすいし効果もありそうなのでいいなと思いました。

本ブログのネタの構成には以下のKubeCon + CloudNativeCon Japan 2025セッションを参考にしました（現地参加しておらず見ていないのですが）。

• KubeCon + CloudNativeCon Japan 2025: Zero-Extraction Cold Starts: How FUSE-St…

KubeConセッションと同じ内容のブログ記事も公開されています。

• 25x Faster Cold Starts for LLMs on Kubernetes

はじめに

１か月前、情報安全確保支援士を受験してきまして、問題の選択肢にあった “SonarQube” という初耳ワードがどんなOSSなのか気になりました。タイミングよくこの『CI/CD pipeline』企画を目にしたので、これは私に書けと言っている！と思い、このブログ記事の題材にすることに決め、ミニマム版を実装構築してみました(/・ω・)/

ちなみに今回（令和7年春）の問題には、弊社セキュリティプロダクトの Future Vuls の得意分野である脆弱性管理の大問がそっくり出ていて、「これを機に Future Vuls の導入を検討してみては？」と回答に書いても丸もらえるのか試したかったです（さすがに試していない）。

SonarQubeとは？

SonarQubeとは、SonarSourceが開発したオープンソースプラットフォームで、29のプログラミング言語（2025年5月現在）において、コードの静的解析による自動レビューと継続的なコード品質検査をし、バグやコードスメルを観測できます。具体的には、重複コード、コーディング規約、単体テスト、コードカバレッジ、コードの複雑さ、コメント、バグ、セキュリティ推奨事項に関するレポートを提供してくれるソフトウェアです。

• OSS originalはこちら → https://github.com/SonarSource/sonarqube

※無料で使う場合、制限として解析できるのは公開リポジトリのみに限られます。プライベートリポジトリは解析できません。

SonarQube Cloud

• SonarQube Cloud Online Code Review as a Service Tool | Sonar

今回は、SonarQubeのクラウド版である SonarQube Cloud を使用します。GitHubアカウントがあれば、GitHub ActionsのCI/CDパイプラインにSonarQube（またはそのクラウド版であるSonarCloud）を導入する準備は整っています。どちらを利用したいかによって手順が少し異なりますが、一般的にSonarCloudの方がGitHubとの連携が簡単で、サーバー管理の手間もないため、特に初めての方や公開リポジトリでの利用におすすめです。

公式サイトの Docs が充実しているため、こちらを一次情報として読みこんでいきます。

• Getting started with GitHub | SonarQube Cloud Documentation

基本構想

基本的に、解析対象コードとテストコードは以下の理由から 同一言語 で書いた方がよいです。

• カバレッジ取得が容易で、静的解析と一元管理できる
• エコシステムが統一されていて、ツール連携しやすい
• 上記に付随して解析精度が向上する

今回はPythonで進めていきます。

最低限必要なファイル群

必須のファイル

1. 解析対象Pythonソースコード（.py）
2. CI/CDワークフローファイル

上記がないと始まりません。（２）はSonarCloudスキャンを実行するための自動化スクリプトです。使用するCI/CDサービスによってファイル名や場所、形式が異なります。

• GitHub Actionsの場合の例： .github/workflows/XXX.yml

このファイルには、リポジトリのチェックアウト、Python環境のセットアップ、依存関係のインストール（オプション）、テストとカバレッジレポートの生成（推奨）、そしてSonarCloudスキャナの実行といったステップを記述します。

強く推奨されるファイル（解析の品質と有用性を大幅に向上させるため）

• テストコードファイル (test_*.py など)
  ユニットテストやインテグレーションテストのコードのこと。コードの品質を保証し、カバレッジを測定できる。 （例） tests/test_main.py tests/test_utils.py
• カバレッジレポートファイル (CI/CDパイプラインで生成)
  テストがコードのどの程度をカバーしているかを示すレポート。SonarCloudはこの情報を表示する。通常、CI/CDのテスト実行ステップで生成され、SonarCloudスキャナに渡される。ex. coverage.xml (pytest-cov や coverage.py で生成)
  ※このファイルはリポジトリに直接コミットするものではなく、CI/CDプロセス中に生成され、 .gitignore に追加されるのが一般的です。しかし、CI/CDワークフローで「生成してSonarCloudに渡す」という設定が不可欠。
• .gitignore ファイル
  Gitが追跡すべきでないファイルやディレクトリ（例: __pycache__ .venv *.pyc coverage.xml など）を指定する。これにより、不要なファイルがSonarCloudによって解析されるのを防ぎ、解析のノイズを減らす。

オプションだが有用なファイル

• 依存関係定義ファイル
  プロジェクトが依存しているライブラリとそのバージョンをリスト化したファイル。(例) requirements.txt pyproject.toml (PoetryやPDMを使用している場合)
  SonarCloudがプロジェクトの構成をより深く理解するのに役立ち、将来的には依存関係の脆弱性チェック機能（もしあれば）との連携にも繋がる可能性がある。
• sonar-project.properties ファイル (オプション)
  リポジトリのルートディレクトリにこのファイルを置くことで、SonarCloudのプロジェクト設定（プロジェクトキー、ソースディレクトリ、エンコーディング、除外設定など）をCI/CDワークフローファイルとは別に管理可能。設定項目が多い場合や、複数のCI/CD環境で同じ設定を使いたい場合に便利である。これがなくても、CI/CDワークフローファイル内のSonarScannerの引数で設定を指定できるが、ファイルとして記載しておくのが無難である。（※今回も配置済み）

全体ファイル構成

今回は下記のように作成しました。ミニマム構成でシンプルですね！

PJ_ROUTE/
├── .github/
│   └── workflow/
│       ├── ci_pipeline.yml      # CI (テスト、カバレッジ、SonarCloud解析) ワークフロー
│       └── cd_pipeline.yml      # CD ワークフロー
│
├── pixel_art_app.py             # あなたの提供したメインのPythonスクリプト
|―― screenshot.py                # 今回テスト実行にあたり作成したダミーファイル
│
├── tests/                       # テストコードを格納するディレクトリ
│   ├── __init__.py              # testsディレクトリをパッケージとして認識させる
│   └── test_pixel_art_app.py    # pixel_art_app.py のテストコード
│
├── requirements.txt             # 必要なPythonパッケージリスト
├── sonar-project.properties     # SonarCloud 解析用の設定ファイル
├── .gitignore                   # Gitで追跡しないファイルやディレクトリを指定
├── pytest.ini                   # (オプション) pytest の設定ファイル
└── README.md                    # プロジェクトの説明ファイル

使用するソフトウェアアカウントの登録

Github account のサインイン

新規開設方法については割愛します。

SonarCloud account のサインイン

１．SonarCloudのアカウント作成とプロジェクト設定

SonarCloud のウェブサイトにアクセスし、[Log in] or [Sign up] > [GitHub] を選択してGitHubアカウントで連携・登録する。

２．解析対象リポジトリの選択

SonarCloudのダッシュボードで [Analyze new project] (または[+]メニュー > [Analyze new project]) をクリックし、GitHub Organizationを選択後、解析したいリポジトリを選択して [Set Up] をクリック。通常は「With GitHub Actions」が推奨されるので、それを選択する。

この段階で、SonarCloud側にプロジェクトが作成されるため、以下の情報をメモしておきます。（※いつでも確認できるので見逃しても問題ない）

３．SonarCloudトークンの生成とGitHub Secretsへの登録

SonarCloudの画面右上の自分のアイコン > [My Account] > [Security] に移動。[Generate Tokens] セクションで、トークン名（例: GITHUB_ACTIONS_TOKEN）を入力し、[Generate] をクリックする。生成されたトークンが表示されるので、必ずコピーして安全な場所に一時保管してください。
※この画面を閉じると二度と表示されません!!

４．TOKENの登録

GitHubリポジトリに移動。[Settings] > [Secrets and variables] > [Actions] を選択する。[New repository secret] ボタンをクリックし、Name に 今回使用した名称 “SONAR_TOKEN” を入力する。Secret または Value に、先ほどSonarCloudで生成・コピーしたトークンを貼り付け、[Add secret] ボタンをクリックする。

構築手順

それでは、具体的に設定ファイルの作成および設定に移ります！

GitHub Actions CI pipeline & SonarCloud による解析

先にこちらを構築します。

１．github/workflows ディレクトリの作成

CI/CDを設定したいGitHubリポジトリのルート（一番上の階層）に、 .github という名前のディレクトリを作成します。さらにその中に workflows という名前のディレクトリを作成します。最終的なパスは .github/workflows/ となります。GitHub Actionsはこのディレクトリ内のYAMLファイルを自動的に認識します。

２．ワークフローファイルの作成

yamlの書き方など参考にすべく、初心者は GitHub Actions のテンプレートを使用するのが分かりやすいです。下記、 [Actions] > [Simple workflow] > [Configure] から作成できます。

静的解析をするためのワークフローファイルを別で分けて、CI用, Sonarcloud用, CD用 と3つ作成しても問題ありませんが、解析もテストと共に検査した方がよいという考えのもと、CIと同一ファイルにSonarcloudのワークフローファイルを記載することが一般的なようです。

name: CI - Python Build, Test, SonarCloud Analysis

on:
  push:
    branches:
      - main
      - 'feature/**'
      # Other branch patterns you want to run CI for
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  build_test_analyze:
    name: Build, Test, Analyze
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          # SonarCloud needs full history for accurate analysis, however, specified shallow clone this time.

      # --------------------------------------------------------------------
      # Python Environment Setup
      # --------------------------------------------------------------------
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
          # preferable the same version with sonar.python.version parameter in sonar-project.properties file.

      - name: Install Python dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
          pip install pytest pytest-cov

      # (Install Python dependencies ステップの後、Run tests ステップの前に追加)
      #- name: Show workspace structure and PYTHONPATH
      #  run: |
      #    echo "Current working directory: $(pwd)"
      #    echo "-------------------------------------"
      #    echo "Listing files in workspace (${{ github.workspace }}):"
      #    ls -R ${{ github.workspace }}
      #    echo "-------------------------------------"
      #    echo "PYTHONPATH environment variable is: $PYTHONPATH"
      #    echo "-------------------------------------"
      ###

      - name: Run tests and generate coverage report
        run: pytest --cov=. --cov-report=xml:coverage.xml
        env:
          PYTHONPATH: ${{ github.workspace }}
          # added PJ_ROUTE path to PYTHONPATH

      # --------------------------------------------------------------------
      # SonarCloud Analysis
      # --------------------------------------------------------------------
      - name: SonarCloud Scan
        uses: SonarSource/sonarcloud-github-action@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # Required for Pull Request decoration
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          # SonarCloud token set in GitHub Secrets

      # --------------------------------------------------------------------
      # Upload Artifacts (Optional, for inspection)
      # --------------------------------------------------------------------
      - name: Upload XML coverage report (for SonarCloud and inspection)
        uses: actions/upload-artifact@v4
        with:
          name: coverage-xml
          path: coverage.xml

      - name: Upload HTML coverage report (for local inspection)
        uses: actions/upload-artifact@v4
        with:
          name: coverage-html
          path: htmlcov/

３．sonar-project.properties ファイルの作成

SonarCloud (または SonarQube) が対象プロジェクトをどのようにスキャン（解析）すべきかを指示するための設定ファイルです。SonarScanner（コードをスキャンして SonarCloud に結果を送るツール）が実行される際に、このファイルを読み込み、プロジェクトの基本的な情報や解析のパラメータを取得します。

# --- SonarCloud 必須設定 ---　※SonarCloud側で確認可能
sonar.projectKey=ask-lycoris_.github-workflows-
sonar.organization=ask-lycoris

# --- 基本設定 ---
sonar.projectName=Pixel Art Project
# ソースコードのディレクトリ (カレントディレクトリを指す)
sonar.sources=.
sonar.host.url=https://sonarcloud.io

# --- 言語設定 (自動検出されることが多いが、明示も可能) ---
# sonar.language=js # 例: JavaScript
# sonar.java.source=11 # 例: Javaのソースバージョン

# --- エンコーディング ---
sonar.sourceEncoding=UTF-8

# --- Python固有設定 ---
# sonar.language=py # 言語を明示的に指定することも可能 (通常は自動検出)
# CIで使用するPythonバージョンと合わせる。複数指定も可能。
sonar.python.version=3.8,3.9,3.10,3.11
sonar.tests=tests

# --- テストカバレッジレポートのパス (CIで生成したレポートを指定) ---
# Pythonの場合、一般的に coverage.py (または pytest-cov) で生成されたXMLレポートを指定します。
sonar.python.coverage.reportPaths=coverage.xml

# --- 除外設定 (必要に応じて) ---
 sonar.exclusions=venv/**, .venv/**, __pycache__/**, tests/**
# テスト自体はカバレッジ対象から除外する
 sonar.coverage.exclusions=tests/**

# --- Javascriptの場合：テストカバレッジレポートのパス (CIで生成したレポートを指定) ---
# sonar.javascript.lcov.reportPaths=coverage/lcov.info # JavaScript/TypeScriptの場合
# sonar.java.coveragePlugin=jacoco
# sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml # Java/JaCoCoの場合

# --- その他のプロジェクト固有設定 ---
# sonar.verbose=true # 詳細ログ (デバッグ用)

記載する上での注意点

完成したワークフローがパースの影響で誤認識され回らなかった時がありました。

特に sonar.tests=tests # ... のようにプロパティ値の直後に # でコメントを続けている場合、# がパスの一部として解釈されたり、あるいはその前のスペースと合わせて問題を引き起こすことがあるようです。最も安全なのは、プロパティ定義の行には値のみを記述し、コメントは独立した行に記述することです。

４．解析対象レポジトリの準備

今回は、外部通信のないスタンドアロンのソースコード（Python）を解析対象とします。SonarCloud は、テストカバレッジの結果やビルド情報を利用してより詳細に解析します。

• ビルドスクリプト： プロジェクトをビルドするためのスクリプト ( package.json の scripts Makefile pom.xml など) がリポジトリに含まれていることを確認します。
• テストスクリプト： ユニットテストやインテグレーションテストを実行し、カバレッジレポートを生成するスクリプトを準備します。言語毎にカバレッジレポートを作成するためのライブラリが存在するため、それが出力されるように設定します。

５．ブランチ保護ルールの設定 (推奨)

コードの品質を確保し、main ブランチにマージする前に CI チェックがパスするように設定します。[GitHub リポジトリ] > [Settings] > [Branches] に移動し、[Require status checks to pass before merging]を有効化し、main ブランチに対するブランチ保護ルールを追加します。今回は下記のようにしました。

CI パイプラインから 該当ジョブ を選択し、Require pull request reviews before merging (マージ前にプルリクエストレビューを必須にする) も有効にします。

６．ワークフローファイルのコミット＆プッシュと結果確認

作成・編集したワークフローファイル (.github/workflows/ci.yml など) をリポジトリにコミットし、GitHubにプッシュします。

ワークフローファイルがリポジトリにプッシュされると、GitHubはそれを自動的に検出し、on: で指定したトリガー条件（例: main ブランチへのプッシュ）が発生した際にワークフローを実行します。リポジトリのメインページにある [Actions] タブをクリックすると、実行されたワークフローのリストと、それぞれの成功/失敗ステータス、実行ログなどを確認できます。通るまで何度もトラブルシューティングを行います。

↓↓↓

７．SonarQube Cloud ルールセットの設定について

上記工程までで、Github ActionsとSonarQube Cloudの連携は完了ですが、SonarQube側でコード解析を全く行っていない状態（=SASTとしての機能を果たしていない）のため、別途ルールセットの設定が必要です。

QualityProfile と QualityGate の違い

• Quality Profile：ルールブックそのもの
  静的コードを解析する際に、「どのような観点でコードを検査し、どんな問題を検出対象とするか」という具体的なルールセットを定義（=ルールブック）します。プロジェクトや組織のコーディング標準、品質基準に基づいて、コードの潜在的な問題点を網羅的に洗い出すための「検査項目リスト」を作成する際に使用する機能です。通常、プログラミング言語ごとに設定します。
• Quality Gate：ルールブック結果の品質管理
  クオリティプロファイルに基づいて行われたコード解析の結果が、「プロジェクトとしてリリース（またはマージ）して良い品質基準を満たしているか」を判定するための条件セットです。プロジェクトが定める品質基準をクリアしているかどうかを自動的に判断し、基準を満たさない場合、ビルドを成功/失敗させてコードが本番環境にデプロイされたり、メインブランチにマージされたりするのを防ぐ際に使用する機能です。通常、プロジェクトごと、または組織全体で共通のゲートを設定できます。

Quality Profileの設定

ルールセット の設定は、主にWeb UIから行います。SonarQube Cloudのプラットフォーム上で直接 Quality Profile を作成・編集し、プロジェクトに適用します。新しいルールを有効化したり、既存のルールの重要度を変更したりできます。下図のように、右上部から [Account page] > [ADMIN] > [Quality Profiles] へ移動します。

※下図のようにプロジェクト毎 Quality Profiles ページも存在するので、そちらではないため注意してください。無料枠内ではプロジェクト毎の設定はできません。

１．Quality Profile の選択または作成

各プログラミング言語ごとに定義されているQuality Profileの一覧が表示されており、デフォルトで「Sonar way」という推奨ルールセットが用意および設定されています。

「Sonar way」のような組み込みプロファイルは直接編集できません。編集するためには、コピーを作成する必要があります。（無料枠ではこれはできなさそう…）

新しいプロファイルを作成する

Quality Profilesページの右上にある「Create」ボタンをクリックし、下記を入力していきます。Parentに指定すると、指定したQualityGateの内容を引き継いでProfileを作成してくれます。

設定したプロファイルをactivateする

今回は、セキュリティ面での解析をしてみたいので➀で設定したルールの中で security に関わる項目を有効化してみました！→ 設定自体はできそうですが、無料枠内だとデプロイまで行きつかないので結局ここでの設定は反映できなかったです。

Quality Profileをプロジェクトに割り当てる

Quality Profileをカスタマイズしたら、それを解析対象のプロジェクトに割り当てる必要があります。

• [方法1] Quality Profileのページから
  カスタマイズしたQuality Profileの詳細ページで、右上にある「Actions」（または歯車アイコンなど）メニューから「Set as Default」（その言語のデフォルトにする場合）または「Change Projects」のようなオプションを選択します。
  「Change Projects」を選択した場合、このプロファイルを適用したいプロジェクトを検索して選択し、割り当てます。
• [方法2] プロジェクトの設定ページから
  SonarCloudで対象のプロジェクトページに移動します。
  「Administration」 > 「Quality Profiles」を選択します。
  プロジェクトで使用されている各言語に対して、どのQuality Profileを使用するかのドロップダウンリストが表示されます。Pythonの項目で、先ほど作成またはカスタマイズしたQuality Profileを選択します。（無料枠では選択できず）

２．Quality Gate の設定

無料枠内では default: Sonarway 以外のプロジェクトに対する 適用はできない ようですが、QualityGateの作成自体はできる ようなので興味のある方は是非手を動かしてみるとよいかもしれません。

GitHub Actions CD パイプライン構築手順

CI（ビルドとテスト）が成功したら、自動的にアプリケーションをサーバーやクラウドサービスにデプロイするCDパイプラインも構築できます。CIジョブの後続としてデプロイ用のCDジョブを追加します。

１．デプロイに際し必要な認証情報の設定

デプロイ先（ex. GitHub Pages, AWS S3/EC2/ECS, Azure App Service, Google Cloud Run, Heroku）に応じた GitHub Actions (例: actions/deploy-pages aws-actions/configure-aws-credentials azure/webapps-deploy) や、デプロイ用のコマンド (scp rsync docker push など) をワークフローに追加します。

デプロイに必要なAPIキーやパスワードなどの認証情報は、セキュリティ上の理由からワークフローファイルに直接書き込まず、リポジトリの [Settings] > [Secrets and variables] > [Actions] で Secrets として安全に登録し、ワークフロー内から ${{ secrets.YOUR_SECRET_NAME }} のように参照します。（一般的なやり方）

２．ワークフローファイルの作成

name: CD - Deploy Application

on:
  push:
    branches:
      - main
    # Trigger deployment on push to main branch
    # Alternatively, you might trigger on tag creation:
    # tags:
    #   - 'v*.*.*'

jobs:
  deploy:
    name: Deploy to Production
    runs-on: ubuntu-latest
    # Ensure CI has passed before deploying.
    environment: production
    # Optional: Define a GitHub environment for protection rules and secrets

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      # --------------------------------------------------------------------
      # Setup Your Deployment Environment & Deploy
      # Replace this section with steps specific to your deployment target
      # (e.g., AWS, Azure, Google Cloud, Heroku, Docker Hub, etc.)
      # --------------------------------------------------------------------
      # Example: Deploying a static site to AWS S3
      # - name: Configure AWS credentials
      #   uses: aws-actions/configure-aws-credentials@v4
      #   with:
      #     aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
      #     aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      #     aws-region: us-east-1
      #
      # - name: Build Project (if not done in CI or if artifacts are not passed)
      #   run: npm run build # Example build command
      #
      # - name: Deploy to S3
      #   run: aws s3 sync ./dist s3://your-s3-bucket-name --delete # Example S3 sync command
      # --------------------------------------------------------------------

      - name: Placeholder for Actual Deployment
        run: echo "Deploying application..." # Replace with your actual deployment commands

３．ワークフローのコミット＆プッシュと結果確認

作成・編集したワークフローファイル (cd_pipeline.yml) をリポジトリにコミット＆プッシュします。GitHubリポジトリの [Actions] タブを開き、ワークフローが実行されていることを確認し、ワークフローがエラーなく完了したことを確認してください。

次に、SonarCloudのプロジェクトページにアクセスしてください。コードの品質、バグ、脆弱性などの解析結果が表示されていれば連携完了です！！Pull Requestを作成した場合、しばらくすると以下のように SonarCloudの解析結果 がPull Requestのチェック欄やコメントとして表示されるようになります。

↓↓↓

今回は、無料枠内でできることを行ったため、SonarQube Cloudの静的解析を適用するまでには至らず結果としては “0” 表記となりましたが、連携して回してカバレッジ取得までは実装できました👏

Sonar Qubeの各評価項目

SonarCloudでは、主に以下のような項目でコードの品質を評価します。分析結果の解読に役立ててください。

• Quality Gate (品質ゲート)
  意味: プロジェクトが定めた品質基準をクリアしているかどうかを示す。「Passed」（合格）なら基準を満たしており、「Failed」（不合格）なら問題あり。
• Bugs (バグ)
  意味: プログラムが正しく動かない可能性のある箇所、つまり「虫（バグ）」が存在する箇所の割合。
• Vulnerabilities (脆弱性 - ぜいじゃくせい)
  意味: セキュリティ上の弱点。悪意のある人（ハッカーなど）に攻撃される可能性がある箇所
• Security Hotspots (セキュリティホットスポット)
  意味: セキュリティ上、特に注意深く確認する必要がある箇所。必ずしも脆弱性とは限らないが、専門家によるチェックが推奨される部分の割合？
• Code Smells (コードの臭い / 技術的負債)
  意味: 直接的なバグではないけれど、読みにくかったり、将来的に問題を引き起こしやすかったりする「良くない書き方」のコードの割合？。「技術的負債」とも呼ばれ、放置すると修正にかかる時間（xx日、xx時間などで表示）が増大する。
• Coverage (カバレッジ)
  意味: プログラムのテストが、コード全体のどれくらいの範囲をカバーできているかを示す割合（パーセンテージ）
• Duplications (重複)
  意味: 同じようなコードが複数箇所にコピー＆ペーストされている割合（パーセンテージ）や行数

おわりに

コンサルとして日々業務にあたっていると様々な事情により、テスト自動化やpipelineの構築などまだまだ自動化できていない企業が多いのかなと思います。しかし、ソフトウェアのセキュリティ対策は後付けでは対応しきれない部分も多く、DevSecOpsが昨今開発の主流となりつつあります。是非これを機に “CI/CD pipelineの構築” と “SonarQubeの組み込み” をマスターし、社内でも一目置かれる人材になってみてはいかがでしょうか！？

参考

• 「入門】GitHub Actionsとは？概要やメリット、使用例まとめ - カゴヤのサーバー研究室
• 【入門】GitHubの使い方｜設定や基本操作など - カゴヤのサーバー研究室
• getting-started | SonarQube Cloud Documentation

HyperDXはいわゆるオブザーバービリティに属すプロダクトです。この領域のプロダクトはかなりのデータ量を扱う必要があったり、可用性のために、ストレージとビューアが分かれていたり、大量のツールと連携させる必要があったりします。

ELKスタックだと、ElasticsearchとLokiとKibana。GrafanaはLokiとPrometheusを連携させたり。OpenTelemetryのときによくデモされたJaegerはDBとビューを持ってトレースの機能を備えていてオールインワンです。

本番環境はSaaSにまるっと運用をお任せというのが良いとは思いますが、ローカルの作ったり壊したりする環境用良さそうなツールを探してみて見つけたのがHyperDXでした。

• ログ、メトリックス、トレースに対応
• ストレージもUIも持っている
• OpenTelemetry対応

HyperDX自身はプロダクション環境でも使えるレベルのプロダクトのようです。管理画面のユーザー管理も厳しいパスワード条件の要求などもしてきます。今回はローカル開発で気軽に使いたい、という目的だったので、管理ユーザーもないローカル版を入れます。ユーザー管理付きのオールインワン版とか、クラウドのClickHouseストレージを使うバージョンとかもあります。

以下のDockerコマンドで起動します。

$ docker run -p 4318:4318 -p 4317:4317 -p 8080:8080
    -v ./mongodb:/data/db
    docker.hyperdx.io/hyperdx/hyperdx-local

(略)

Send OpenTelemetry data via:
  http/protobuf: OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
  gRPC: OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Exporting data to ClickHouse:
  Endpoint: tcp://ch-server:9000?dial_timeout=10s
  Database: default

Waiting for ClickHouse to be ready...
ClickHouse is ready!

Visit the HyperDX UI at http://localhost:8080

ウェブのインターフェースが8080ポート、gRPCの情報受付が4317ポートです。

なお、このイメージは永続化可能なパスが3つあります。ローカルで気軽に使いたいという用途なのでログ自身は消えても良いので管理画面のデータだけ永続化するようにしています。

• /data/db (HyperDXの管理画面で設定する情報を保持するMongoDBのデータ)
• /var/lib/clickhouse (バックエンドのDBのClickHouseのデータ)
• /var/log/clickhouse-server (バックエンドのDBのClickHouseのログ)

Pythonアプリケーションを作る

OpenTelemetryで情報を出力するPythonアプリケーションを作ります。FastAPIで作ります。

mkdir pysample
uv init
uv add fastapi --extra standard

OpenTelemetryのトレースのspanを追加するために、traceパッケージを利用します。いまどきのOpenTelemetryはゼロコードコンフィグということで、接続先の情報はプログラムに書いたりしないという方法が追加されたようです。言語によって手法は違うようですが、モンキーパッチやeBPFなんかを利用するようです。なので接続情報はこのコードにはありません。

uv add opentelemetry-api opentelemetry-sdk

import logging

from fastapi import FastAPI

from opentelemetry import trace

app = FastAPI()

from time import perf_counter, sleep

# ここがエンドポイント本体！
@app.get("/")
async def read_root():
    sleep(0.1)
    # トレースを手動で設定
    with trace.get_tracer_provider().get_tracer("sleep").start_as_current_span(__name__) as span:
        sleep(0.2)
        logging.info("read_root")
        logging.warning("I am hungry")
    sleep(0.1)
    return {"message": "Hello, world!"}

今回はuvを使っていますが、uvの場合はちょっと問題があって回避の手順が別のページにあります。その手順の通りに行います。uv pip installはuv addとは異なりpyproject.tomlにパッケージは追加しません。opentelemetry-bootstrapというコマンドが有名どころのPythonライブラリを検知して、それに対応した計装ライブラリをピックアップします。なかなか力技。

uv pip install opentelemetry-distro opentelemetry-exporter-otlp
uv run opentelemetry-bootstrap -a requirements | uv pip install --requirement -

これはuv pip installで入れているのでuv pip compile pyproject.tomlには出てきません。uv pip freeze > requirements.txtでrequirements.txtを作る必要があります。

以下のコマンドで起動して、 http://localhost:8000/ で起動してログを送ります。設定は環境変数とopentelemetry-instrumentコマンドラッパーの--service_nameといった引数で渡す方法が選べますが、真設定は環境変数にしといた方がDockerとかにするときに便利かと思って環境変数にしています。

デフォルトのOTLPのプロトコルはgrpcですが、この場合はhttpsになってしまい証明書エラーが出てしまいます。今回はローカルなので証明書はいらないhttp/protobufもしくはhttp/jsonにします。

export OTEL_SERVICE_NAME=hyperdx-demo
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 # 省略可能
export OTEL_PYTHON_LOG_CORRELATION=true
export OTEL_PYTHON_LOG_LEVEL=info
export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true

$ uv run opentelemetry-instrument fastapi run --port 8000

結構はまったのですが、fastapi devの開発モードだとログとかは出てこないですね。ちょっと不便。

UIの設定

ローカルモードだとユーザー設定などはありませんので、いきなりコネクション選択が表示されます。オールインワンのイメージだとパスワード設定などがあります。このコネクションは緑のCreateを押せばOKです。

引き続きデータソース入力が表示されます。最初は二進も三進もわからなかったのですが、こちらの情報を見れば少しは歯が立ちます。

以下の2つのソースを設定しました。名前、ソースタイプ、テーブル以外はデフォルトのままです。

• Name: Logs
  • Data Source Type: Logs
  • Table: otel_logs
• Name: Traces
  • Data Source Type: Trace
  • Table: otel_traces

ログを見てみる

左上のメニューでSearchを選び、データソースを選択すると出力したログ一覧が見られます。クリックすると時間や出力したサービスなど詳細な情報が見られます。いちいちデータソース選択とか面倒と思われるかもしれませんが、プロダクションで超大規模サービスを想定してでしょうね。同じ種類のデータでも日ごとにパーティションを切って別テーブルに、とかそういうのを想定しているのかと思います。

トレースは、それぞれのログをクリックしたあとに、トレースのタグを選択します。右側でトレースのデータソースを選択すると、いつものトレースが見られます。ログのデータソース設定のオプショナル中くれている設定に関連するトレースデータソースを設定できるので、そこを設定しておくとクリックは不要になります。動作は軽快です。

まとめ

ローカルでログやトレースが見られるHyperDXを試してみました。メトリクスも本当は見られたりするのですがダッシュボード設定が難しくまた今度にしようかと。あと、ウェブの操作画面を記録するセッション機能とやらもあるのですが、機能とかが多くてちょっとこちらも時間を設けてゆっくり調べてみようと思います。

OpenTelemetryでデータ投入できるので、本番環境のクラウドサービスのログ基盤とかにもスムーズに遷移できる気がします。

設定がyamlかなにかで軽く共有できれば開発用Dockerとかで気軽に立ち上げてみんなで見るとかやりたいところですが、ちょっとそこはローカル専用にするにはちょっと不便。

こんにちは。TIGの伊藤です。この記事はCNCF連載2025の2日目の記事です。

今回はこのCNCF連載とタイミングを同じくして開催しているKubeCon + CloudNativeCon Japanに参加してきたので、1日目に私が回ったセッションや会場の雰囲気についてお伝えできればと思います。

KubeConとは

Cloud Native Computing Foundation(CNCF)が開催しているカンファレンスであり、これまで、ヨーロッパ、北アメリカをはじめとして世界各国で開催されてきました。私がクラウドネイティブ系のコミュニティに関わり始めたのが2019年ごろで、その時から行ってみたいカンファレンスでした。
そして、今年ついに日本で開催されると聞き、今回参加できました。
（参考：日本初開催！KubeCon + CloudNativeCon Japan 2025、6月16日-17日に東京で開催）

KeyNote

CNCFのChrisから、直近のクラウドネイティブのコミュニティや今回の開催地となった日本のCNCFへのコントリビューションの度合いなどについてのセッションでした。

まず、今回のKubeConにおいては、1500人分のチケットが全て売り切れとなり、今回のカンファレンスへの関心度がわかります。

また、それだけではなく、来年のKubeCon + CloudNativeCon Japan 2026も開催が決定し、会場も非常に盛り上がっていました。

私としても今回連れてきたかった同僚たちを誘って、来年は会社としてもっといろんな情報が集められればいいなと思い、来年の楽しみが1つ増えました。

その他、日本の企業におけるCNCFプロジェクトのケーススタディについても紹介されており、日本のコミュニティ自体にも注目が集まっているようでした。私としては、プロジェクトでもがっつり利用しているKeyCloakが日本のコントリビュートが活発であることから、出せる情報は登壇などできたらいいなと思います。

他のセッション

その他のセッションについては海外の参加者がほとんど、というわけでもなく、だいたいどの時間帯も1つは日本の方のセッションをやっていました。

ただ、セッション自体は全て英語で進んでいくので、本当にぎりぎり聞けたものや、一緒に聞いていた知り合いなどと話してちょっとずつ理解していくという感じでした。帰り際に、翻訳ツールも用意されているということを聞き、2日目はしっかり活用しようと思います（完全に準備不足でした）

タイムテーブル自体、個人的な最近の興味関心も含まれていますが、生成AI系やOpen TelemetryをはじめとしたObservabilityが多いように感じました。

また、今回私がみたセッションを1つ紹介します。

Should Our Project Join the CNCF? - Lenka Bočincová, Red Hat

このセッションでは、仮想的にKubeFishというプロジェクトがCNCFにジョインする場合、どのようなことが想定されるか、議論の対象になるかを解説していました。

例えば、企業で開発していて、プロジェクトを公開し、CNCFにジョインすることを決定した場合、権限もCNCFに移譲します。すると、企業としての意思決定よりもCNCF・コミュニティとしての意思決定が重要視されるようになり、改めてこの観点についてはOSSという公平性を重んじていることがわかりました。

一方、CNCFのプロジェクトとしてジョインする場合、成熟度として以下の3種類あります。

• Graduated
• Incubating
• Sandbox

このレベルはプロジェクトの健全性、および成熟度で判断され、コントリビューションだけではなく、プロジェクトがさまざまな環境で利用されていることも判断の対象になるようです。

また、仮にジョインできた場合、CNCFからも支援を受けることができるが、サンドボックスは他と比べるとはるかに少ないこともあり、ジョインする場合にはどの成熟度でいくかもジョインする側の観点としてはありそうです。各成熟度ごとにチェックリストがあり、事前にすべてクリアしていることが望ましいようです。

https://github.com/cncf/toc/blob/main/process/README.md#how-to-apply-to-move-levels

例えば、OSSのライセンスについても言及されていますが、これは利用しているライブラリについても追求されるため、何かしらのFoundationにジョインを目指すのであれば、開発時にある程度のチェックポイントを設けるのが良いのかなと思っていました。昨今、OSSのライセンスについてはさまざまな問題になったりしていることもあり、より注意が必要だと感じました。

会場の様子とカンファレンスの雰囲気

参加者の比率を見ているところ、かなり日本の方が多かったです。そのため、飛び交う言葉自体も日本語が多く、そこは安心して参加できました。

スポンサーブースについても、本国の社員の方が直接説明してくれたり、英語で聞くことが難しい場合にも日本の方が説明してくれるようになっており、そこまで尻込みせずに話を聞くことができました。私はそれでもビビりながら話しかけていて、1日目で回れなかったところもあるので、2日目も回ろうと思います。

まとめ

普段仕事としていろんな技術に触れていることも好きですが、改めて勉強会、カンファレンスに足を運ぶとモチベーションになると感じたので、この新しく得たモチベーションを元にプロジェクトの仕組みなどに取り入れていこうと思いました。

また、今回日本開催の海外カンファレンスに参加してきましたが、セッションだったりは基本的にずっと英語なので、改めてリスニング、スピーキングはしっかりできるようにしようと思います。

来年も日本開催が決まったので、そこで英語力、技術力をアップさせていけたらいいなと思います。

CNCF とは

Cloud Native Computing Foundation の略で、コンテナオーケストレーションとして知られている Kubernetes を中心とした OSS を管理している Linux Foundation 傘下の非営利団体です。2015 年に Google などが中心となり、コンテナオーケストレーションツールである Kubernetes のバージョン 1.0 リリースと同時に設立されました。

2025 年で Kubernetes リリースから 10 年経過し、クラウドネイティブ技術の普及も随分進んだ気がします。コンテナ、CI/CD、オーケストレーション（ここは ECS や CloudRun なども）、ログやメトリクス収集などのオブザーバビリティなどは導入してもニュースにもならなず、それぞれの組織やプロダクトに自然に導入されているように思えます。

コミュニティ活動の支援も活発で年に数回ほど、KubeCon と呼ばれるカンファレンスを世界各地で実施しています。

直近ではKubeCon + CloudNativeCon Japan 2025が東京で 6/16 ～ 6/17 に開催されます。実はこれが日本での初開催となります。おめでたいですね！

CNCF が提唱するクラウドネイティブとは

CNCF が提唱するクラウドネイティブ技術とは、CNCF のリポジトリで以下のように定義されています。

クラウドネイティブ技術は、パブリッククラウド、プライベートクラウド、ハイブリッドクラウドなどの近代的で動的な環境において、拡張性あるなアプリケーションを開発・実行するための能力を組織にもたらします。この手法の代表例として、コンテナ・サービスメッシュ・マイクロサービス・イミュータブルインフラストラクチャ・宣言型 API があります。
これらの技術により、回復性・運用性・可観測性のある疎結合システムが実現します。これらを堅牢な自動化と組み合わせることで、エンジニアは影響の大きな変更を頻繁かつ予測どおりに行うことができ、最小限の労力で作業できます。

一言でいうと、クラウドの利点を最大限に引き出した、アプリケーションの設計・開発・運用することかなと思います。

プロジェクトについて

CNCF では多くの OSS をホスティングしてします。プロジェクトは成熟度レベル別に 3 つ分類しています。キャズムのイノベーター、アーリーアダプター、アーリーマジョリティに似ているなと思われる方もいらっしゃるかと思いますが、公式サイトにも、それに相当したコンセプトであると記載されています。

• Graduated（卒業）
  • 「成熟した」プロジェクトとして認められたものについては Graduated になります
  • Kubernetes、Prometheus、Envoy、containerd など
  • 2025 年には、CubeFSやin-totoがこのレベルに昇格
• Incubating
  • Sandbox から利用数などが増加すると Incubating になります
  • オープンソースの Kubernetes セキュリティプラットフォームである、Kubescape が 2025 年 2 月に昇格
• Sandbox
  • CNCF のプロジェクトとしては「early stage」として位置付けられています
  • 2025 年には、物理サーバ上に PaaS を構築するCozystack、複数の k8s クラスタ管理する KubeFleet などが追加されました

他にも、Archive というステータスがあり、2025 年 6 月 13 日時点で 16 プロジェクトが存在していました。

• https://www.cncf.io/archived-projects/

プロジェクト数の推移は公式サイトのメトリクスページから確認できます。

Graduated が 31、Incubating が 36、Sandbox が 143 という内訳のようです。

チャートを見ると分かる通り、右肩上がりでまだまだ勢いがある領域だと感じられます。

CNCF Annual Report 2024

2025 年 5 月 19 日にCNCF Annual Report 2024 という、年次報告書が公開されました。せっかくなので NotebookLM に読み込ませ、面白かった内容をサマリで紹介します。

• CERN が、CNCF プロダクトである、Prometheus、Argo、FluentD、CoreDNS、Harbor などを導入し、数千のノード（！）かつ、500 以上のクラスターを管理している（！）とのこと、トップエンドユーザー賞を受賞
• 北米の、KubeCon + CloudNativeCon North America 2024 では、プラットフォームエンジニアリング、大規模なクラウドネイティブ AI、セキュリティが主要な焦点だった
• 中国の、KubeCon + CloudNativeCon + Open Source Summit + AI_dev China 2024 では、クラウドネイティブ AI (CNAI) が主要テーマとなり、大規模言語モデル (LLM) や機械学習ツールがクラウドネイティブインフラで稼働している事例があった
• Kubernetes とクラウドネイティブのスキルを証明する新しい認定資格として、Kubernetes and Cloud Native Security Associate (KCSA)、Certified GitOps Associate (CGOA) など、合計 6 つが導入されました
• OpenTelemetry は貢献者ベースを拡大し続けており、最近プロファイリングを新しいシグナルタイプとして追加し、golang コンパイル時計測機能の追加に取り組んでいる

CNCF 連載とは

2020 年、2023 年にも開催した、技術ブログのリレー企画です。フューチャーでは月に 1 回程度のペースで、何かしらの技術テーマを元にブログリレー（ブログ連載）を行っています。6 月は先に紹介した KubeCon + CloudNativeCon が日本で初開催されるということで、それを記念に開催するとなりました。少しでも盛り上がりに繋がればと思っています。

メンバーは基本的には社内で参加を募り、有志で集まってもらいました。どのプロダクトを選ぶかは完全に各々の自由です。「どれを選ぶべきか分からないんだけど..」という声も最初はよく聞かれました。アイコンを並べるだけでなかなかの情報量です。

そのたび、Graduated か Incubating のページか、Sandbox のページ から、プロダクトのアイコンを見て「ジャケ買い」しましょうと伝えています。CNCF のアイコンは、少しでも目立って覚えてもらおうという気持ちからか、デザインが良いです。各自の感性にビビッときた気鋭のプロダクトが選ばれるでしょう。

スケジュール

さいごに

私自身は、クラウドマネージドサービスを優先的に技術選定することが多く、CNCF プロジェクトの OSS を直接的に利用することが少ないですが、いざ調べてみると魅力的なプロダクトが数え切れないほど多数あり、調べていくとあっという間に時間が溶けました。

このブログ連載が、CNCF のプロジェクトのエキサイティングな世界に触れるきっかけとなれば幸いです。

• Containerization の紹介 - WWDC25 - ビデオ - Apple Developer

毎年 WWDC の時期になると仮想化のアップデートの話が来るのをずっと首を長くしてまっていた日々だったので、待望のアップデートです。macOS は以前から、Linux 仮想化の機能が OS の API レベルでサポートしており、カーネルイメージを指定して起動できたりしました。これで、WSL2 に負けない環境はすぐにでも出るんじゃないかと思いはや数年。それがとうとうきました。なお、今回は macOS 26 beta 1 と、0.1.0 のcontainerをもとにしていますので、時間がたてば状況が変わる可能性がある点にご注意ください。

WWDCで一番楽しみにしていたVirtualization Frameworkのセッション。EC2のmacインスタンスを実装しているような人には嬉しそうなネットワークブロックデバイス。I/Oパフォーマンスアップはどれぐらいのものだろうか？https://t.co/f3UF03wUxa

— 渋川よしき (@shibu_jp) June 7, 2023

WWDCで一番期待しているのは、AIでも新型Macの発表でもなくて、macOS Subsystem for Linuxです。メモリバルーニングで固定メモリ割り当てなくてもいいLinuxサブシステムが実現できるAPIはすでにある。そうすれば少ないメモリでも効率よくコンテナ起動したりできる。

— 渋川よしき (@shibu_jp) May 10, 2024

container

今回、Apple は 2 つの OSS を公開しました。前者がコマンドラインツールで後者はバックエンドのサービス？のようです。前者の Release にあるインストーラでインストールすれば後者からは特にダウンロードする必要はありません。OSS で修正したい人向けにソースが公開されています。

• github.com/apple/container
• github.com/apple/containerization

インストールしたら以下のコマンドを実行すると必要なものを追加でダウンロードしてきます。

container system start

Docker とほぼ互換の container コマンドで起動すれば素早く立ち上がります。起動早いですね。

container run --rm -it --name debian debian:bookworm

コンテナを Linux 以外で動かす歴史

コンテナは Linux の軽量なリソース分離の仕組みを活用して、VM よりもコンパクトな独立した OS 環境を作って起動する、というのが元の始まりです。ただし、Linux 以外だと Linux カーネルの仕組みは使えないため、仮想 OS で Linux を入れてから動かす必要がありました。

当初は 4GB だと 8GB だの固定のメモリ領域を持った仮想 PC の Linux を起動し、その中で Docker を動かしていました。どんな小さなアプリケーションを起動するのにも固定のリソースのリソースが必要でした。

Windows は WSL2 という、Linux 仮想環境を 5 年前にリリースしました。Windows の持つ Hyper-V という仮想化の仕組みの上で Linux を動かします。Linux と Windows はメモリを共有しており、デフォルト設定では、Linux からは Windows の持つ物理メモリの 50%のメモリもしくは 8GB の少ない容量が見えます。アプリケーションがメモリを必要として Linux カーネルにリクエストしてきたら、Windows からメモリをもらってきてアプリケーションに渡します。

• WSL2: 開発環境構築＆ツール開発ガイド

ただし、Linux は本来は自分だけが管理する世界でパフォーマンスに全力を出すという世界の中で生きています。ディスクアクセスをすると、2回目のロードのためにすべてバッファとしてメモリがある限りはキャッシュします。そんな感じで一度 Linux カーネルが持ったメモリはあまり Windows に帰ってこないという問題がありました。当初は Windows の 80%が見えていましたが減らされて現在に至ります。

その後アップデートで多少の改善はありました。

• zenn: dozo 氏 WSL のアップデートでメモリ開放？

Apple は確か 2022 年に Virtualization Framework をリリースしました。これも WSL2 同様メモリを macOS と融通し合うメモリバルーニングに対応しているし、将来に期待、と思っていましたが、残念ながらこれを活用するコンテナエンジンはこれまで出てきませんでした。ただ、パフォーマンスは良くなったので体験は良くなりました。mac でよく問題として言われていたホストとのストレージの共有はそもそも必要性は減っていますが、速度もアップしました。

今回の仕組みは軽量なカーネルと独自の initd のみの軽量な VM をコンテナごとに動かすという方法を Apple は発表しました。

こちらの説明を見ると、Windows 同様 OS にメモリを返すところはまだ部分的なサポートとありますが、コンテナ=VM の場合の macOS では影響範囲としては単独のコンテナになります。WSL とは違ってコンテナさえ再起動しちゃえば OK のように見えます。Go のように言語ランタイムの TCMalloc で OS とのメモリのやり取りを減らしてメモリを使い回すとか、sync.Pool でアプリ内部でメモリ再利用を積極的に行うようにすればさらに問題は軽減されるかと思われます。

Linux カーネルはここの説明によると、virtio だけカーネルに組み込み（モジュールではなく）にしておけば良いうという感じのようですね。Microsoft はいろいろカスタムしていた気がしますが。

WSL2 との違い

現状の僕の理解で WSL2 との違いはこうじゃないかというのを書いてみました。

今どきの Windows は Hyper-V の上で動いている OS の 1 つという構成です。Windows 10 のときは WSL2 や Hyper-V の仮想化をした時だけこのような構成になっていましたが、Windows 11 からはセキュリティ対策も兼ねてこの構成が標準になったと理解しています。Docker は WSL2 の中で動きます。Linux カーネルがあってその中にコンテナのランタイムがあり、その中でコンテナが動いています。

macOS はそのようなハイパーバイザの上で動く感じではなく、おそらく通常の darwin カーネルの中で Virtualization Framework がいます。絵には書いてないですが、その下にさらに低レベルな Hypervisor Framework があります。今回の発表では、コンテナごとに VM があがり、その中でコンテナが実行されるということだったので、この図のような感じかと思います。Docker のランタイムにあたるプログラムは Linux カーネルの外側にあるというのが違いかな、と思います。

皆さんのパソコンではプログラムはたくさんの共有ライブラリを使っています。100 個のプログラムが共通の dll なり.so なりを使ていたとして、100 個分のメモリは使わず、ディスクから読み込んだプログラムイメージは物理メモリ上は 1 つだけ配置されて、仮想メモリの形で見た目のアドレスだけ複製されているような形になります。macOS のほうの Linux カーネルも同じような感じでメモリ共有されるのかどうかはわからないのですが、もし共有されるとしたら面白いな、と思っています。

compose や Dev Containers はまだ動かない

現状は単独の Docker 相当の機能のみの提供となっています。compose もありません。

コンテナというと開発環境をすべてコンテナのなかで動かす Dev Containers が実用になるかどうかが気になるところかと思います。podman とかも起動コマンドが違うので、Dev Containers 側でコマンドは変更できるようになっています。一応これを設定してみても・・・

実行時にはエラーになります。

また、Docker Desktop のようなコンテナのインスペクタとか管理画面はありません。Docker はという Unix ドメインソケットを/var/run/docker.sockというパスにつくり、そこに対してリクエストを送ることで、リモートで制御できます。container は XPC というプロセス間通信を使っており、/var/run/docker.sockはないので、dozzleやPortainerといった既存の管理画面は動きません。

あとは、まだ GPU や NPU を使う方法とかも情報はないですね。

とはいえ、このあたりは些細な差というか、まだ正式リリースまでは先だと思うので更新が楽しみです。

※画像はGemini Pro 2.5で作成しました。

CI/CD連載 3本目です。

はじめに

TIG 真野です。

GitHub Actionsをローカル環境で実行できるnektos/actをMakefileやTaskfileなどのタスクランナーの代わりとして使えるのか、試してみた記事です。

nektos/act とは

act は GitHub Actionsのワークフローをローカル上で実行できる、Go言語で実装されたツールです。Dockerを利用してGitHub Actionsの実行環境をエミュレートしてくれ、GitHubのリポジトリにプッシュすることなくワークフローのテストやデバッグを行うことができます。actの名前の由来は、actionsからもらっているんだろうなと思っています。

act のREADMEには以下のようにactを使うべき理由が書かれています。

Run your GitHub Actions locally! Why would you want to do this? Two reasons:

• Fast Feedback - Rather than having to commit/push every time you want to test out the changes you are making to your .github/workflows/ files (or for any changes to embedded GitHub actions), you can use act to run the actions locally. The environment variables and filesystem are all configured to match what GitHub provides.
• Local Task Runner - I love make. However, I also hate repeating myself. With act, you can use the GitHub Actions defined in your .github/workflows/ to replace your Makefile!

日本語訳:
GitHub Actions をローカルで実行しましょう！これを行うべき理由は2つあります：

• フィードバックを早くする - .github/workflows/ ファイルに加えている変更（または埋め込まれた GitHub Actions への変更）をテストしたいと思うたびにコミット/プッシュをする代わりに、act を使えばアクションをローカルで実行できます。環境変数やファイルシステムは、GitHub が提供するものと一致するようにすべて設定されます
• タスクランナーとして動かす - 私は make が大好きです。しかし、同じことを繰り返すのも嫌いです。act を使えば、.github/workflows/ で定義された GitHub Actions をあなたの Makefile の代わりに利用できるのです！

2つ目の理由として書かれていた、タスクランナーとして使うという点が意外でした。MakefileかTaskfileあたりで十分良い気もしますが、GitHub Actionsとローカル実行でも利用するコマンド定義を共有できれば確かに便利そうです。

この点で評価している記事が、自分の観測範囲で見つけることができなかったため、CI/CD連載の1ネタとして試します。

actの使われどころ

Gitea という、GitHubのセルフホスト可能なGo言語製のプロダクトがあります。類似のツールにGogsも存在しますが、Giteaは元々Gogsからフォークされたものです。理由は公式の発表ブログがあります。

そのGiteaのGitea Actionsは、act （のソフトフォークで、ライブラリ呼び出しなどをできなくしている）で動いているとのことです。Giteaからさらに派生した Forgejoでも Forgejo Runnerで利用されています。

複数のプロダクトからCI/CDランナーとして採用されていることから、完成度も高まっているのではないでしょうか。なお、2025年6月時点ではバージョン v0.2.78 でした。そもそもがGitHub Actionsの互換を謳っているため、安定性は高いと言えるのではないでしょうか。

アーキテクチャ

act のアーキテクチャは少し特殊です。Makefileの代わりにと説明があったので、最初はステップの中で uses: actions/checkout@v4 のような別途コンテナ起動が必要な場合のみ、Docker呼び出しし、その他はホスト上で直接コマンドを実行するのかと思っていました。

実際は、GitHub Actionsと同じくRunner(ランナー)のコンテナイメージをローカルに取得し、そのランナー上でジョブを処理します。ステップの中でDocker呼び出しが必要な場合のみ、ランナーとは別にコンテナイメージを起動させます。データのやり取りはボリューム共有機能を経由して行われます。Docker呼び出しが不要な場合は、ランナーで直接実行します（そのために必要な、Node.jsなどの最低限のセットアップはされています）。

上記の構造のため、ちょっとしたスクリプト実行も、上図でいうジョブコンテナの呼び出しが必要です。

事前準備

act を利用する上でDockerのインストールは前提条件です。もし、未構築の場合はMac・Windowsの場合はDocker Desktop（Linuxの場合はDocker Engine）をインストールします。

• Docker Desktop: The #1 Containerization Tool for Developers | Docker

actのインストール

公式ドキュメントにインストールについて独立したページがあり、様々なパッケージマネージャーに対応しています。

• Installation - act - User Guide | Manual | Docs | Documentation

私はGo環境が構築済みだったため、 go install で対応します。

$ go install github.com/nektos/act@v0.2.78
$ act --version
act version 0.2.78

helpを見ると、オプションが豊富なことも分かります。

$ act --help
Run GitHub actions locally by specifying the event name (e.g. `push`) or an action name directly.

Usage:
  act [event name to run] [flags]

If no event name passed, will default to "on: push"
If actions handles only one event it will be used as default instead of "on: push"

Flags:
      --action-cache-path string                          Defines the path where the actions get cached and host workspaces created. (default "/home/mano/.cache/act")
      --action-offline-mode                               If action contents exists, it will not be fetch and pull again. If turn on this, will turn off force pull
  -a, --actor string                                      user that triggered the event (default "nektos/act")
      --artifact-server-addr string                       Defines the address to which the artifact server binds. (default "172.29.0.214")
      --artifact-server-path string                       Defines the path where the artifact server stores uploads and retrieves downloads from. If not specified the artifact server will not start.
      --artifact-server-port string                       Defines the port where the artifact server listens. (default "34567")
  -b, --bind                                              bind working directory to container, rather than copy
      --bug-report                                        Display system information for bug report
      --cache-server-addr string                          Defines the address to which the cache server binds. (default "172.29.0.214")
      --cache-server-external-url string                  Defines the external URL for if the cache server is behind a proxy. e.g.: https://act-cache-server.example.com. Be careful that there is no trailing slash.
      --cache-server-path string                          Defines the path where the cache server stores caches. (default "/home/mano/.cache/actcache")
      --cache-server-port uint16                          Defines the port where the artifact server listens. 0 means a randomly available port.
      --concurrent-jobs int                               Maximum number of concurrent jobs to run. Default is the number of CPUs available.
      --container-architecture string                     Architecture which should be used to run containers, e.g.: linux/amd64. If not specified, will use host default architecture. Requires Docker server API Version 1.41+. Ignored on earlier Docker server platforms.
      --container-cap-add stringArray                     kernel capabilities to add to the workflow containers (e.g. --container-cap-add SYS_PTRACE)
      --container-cap-drop stringArray                    kernel capabilities to remove from the workflow containers (e.g. --container-cap-drop SYS_PTRACE)
      --container-daemon-socket string                    URI to Docker Engine socket (e.g.: unix://~/.docker/run/docker.sock or - to disable bind mounting the socket)
      --container-options string                          Custom docker container options for the job container without an options property in the job definition
      --defaultbranch string                              the name of the main branch
      --detect-event                                      Use first event type from workflow as event that triggered the workflow
  -C, --directory string                                  working directory (default ".")
  -n, --dryrun                                            disable container creation, validates only workflow correctness
      --env stringArray                                   env to make available to actions with optional value (e.g. --env myenv=foo or --env myenv)
      --env-file string                                   environment file to read and use as env in the containers (default ".env")
  -e, --eventpath string                                  path to event JSON file
      --github-instance string                            GitHub instance to use. Only use this when using GitHub Enterprise Server. (default "github.com")
  -g, --graph                                             draw workflows
  -h, --help                                              help for act
      --input stringArray                                 action input to make available to actions (e.g. --input myinput=foo)
      --input-file string                                 input file to read and use as action input (default ".input")
      --insecure-secrets                                  NOT RECOMMENDED! Doesn't hide secrets while printing logs.
  -j, --job string                                        run a specific job ID
      --json                                              Output logs in json format
  -l, --list                                              list workflows
      --list-options                                      Print a json structure of compatible options
      --local-repository stringArray                      Replaces the specified repository and ref with a local folder (e.g. https://github.com/test/test@v0=/home/act/test or test/test@v0=/home/act/test, the latter matches any hosts or protocols)
      --log-prefix-job-id                                 Output the job id within non-json logs instead of the entire name
      --man-page                                          Print a generated manual page to stdout
      --matrix stringArray                                specify which matrix configuration to include (e.g. --matrix java:13
      --network string                                    Sets a docker network name. Defaults to host. (default "host")
      --no-cache-server                                   Disable cache server
      --no-recurse                                        Flag to disable running workflows from subdirectories of specified path in '--workflows'/'-W' flag
      --no-skip-checkout                                  Use actions/checkout instead of copying local files into container
  -P, --platform stringArray                              custom image to use per platform (e.g. -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04)
      --privileged                                        use privileged mode
  -p, --pull                                              pull docker image(s) even if already present (default true)
  -q, --quiet                                             disable logging of output from steps
      --rebuild                                           rebuild local action docker image(s) even if already present (default true)
      --remote-name string                                git remote name that will be used to retrieve url of git repo (default "origin")
      --replace-ghe-action-token-with-github-com string   If you are using replace-ghe-action-with-github-com  and you want to use private actions on GitHub, you have to set personal access token
      --replace-ghe-action-with-github-com stringArray    If you are using GitHub Enterprise Server and allow specified actions from GitHub (github.com), you can set actions on this. (e.g. --replace-ghe-action-with-github-com =github/super-linter)
  -r, --reuse                                             don't remove container(s) on successfully completed workflow(s) to maintain state between runs
      --rm                                                automatically remove container(s)/volume(s) after a workflow(s) failure
  -s, --secret stringArray                                secret to make available to actions with optional value (e.g. -s mysecret=foo or -s mysecret)
      --secret-file string                                file with list of secrets to read from (e.g. --secret-file .secrets) (default ".secrets")
      --use-gitignore                                     Controls whether paths specified in .gitignore should be copied into container (default true)
      --use-new-action-cache                              Enable using the new Action Cache for storing Actions locally
      --userns string                                     user namespace to use
      --var stringArray                                   variable to make available to actions with optional value (e.g. --var myvar=foo or --var myvar)
      --var-file string                                   file with list of vars to read from (e.g. --var-file .vars) (default ".vars")
  -v, --verbose                                           verbose output
      --version                                           version for act
  -w, --watch                                             watch the contents of the local repo and run when files change
  -W, --workflows string                                  path to workflow file(s) (default "./.github/workflows/")

サンプルスクリプト

プロジェクトルートに移動し、GitHub Actionsのワークフローファイルを配置する .github/workflows ディレクトリを作成します。

mkdir -p .github/workflows
cd .github/workflows

今回は、ローカルタスクランナーとしての act を試すため、CI用のワークフローとは別に、ローカル実行専用のワークフローファイル local-tasks.yaml （名前は任意）を作成してみましょう。作成後は git commit をしておくと良いです。act側でgitのリビジョン情報などを取得しようとするため、未コミットの場合はWARNログなどでコンソールが埋まってしまうためです。

name: Local Development Tasks

on: [workflow_dispatch] # 手動実行できるようにするため

jobs:
  greet: # hello act するジョブ
    runs-on: ubuntu-latest
    steps:
      - name: Say Hello
        run: echo "🐈️こんにちﾆｬﾝ"

act -j greet で実行します。

初回はMicro/Medium/Largeのうち、どのランナーで動かすか？ と聞かれますが、Medium で良いでしょう。

$ time act -j greet
INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock'
[Local Development Tasks/greet] ⭐ Run Set up job
[Local Development Tasks/greet] 🚀  Start image=catthehacker/ubuntu:act-latest
[Local Development Tasks/greet]   🐳  docker pull image=catthehacker/ubuntu:act-latest platform= username= forcePull=true
[Local Development Tasks/greet] using DockerAuthConfig authentication for docker pull
[Local Development Tasks/greet]   🐳  docker create image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/greet]   🐳  docker run image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/greet]   🐳  docker exec cmd=[node --no-warnings -e console.log(process.execPath)] user= workdir=
[Local Development Tasks/greet]   ✅  Success - Set up job
[Local Development Tasks/greet] ⭐ Run Main Say Hello
[Local Development Tasks/greet]   🐳  docker exec cmd=[bash -e /var/run/act/workflow/0] user= workdir=
| 🐈️こんにちﾆｬﾝ
[Local Development Tasks/greet]   ✅  Success - Main Say Hello [115.57099ms]
[Local Development Tasks/greet] ⭐ Run Complete job
[Local Development Tasks/greet] Cleaning up container for job greet
[Local Development Tasks/greet]   ✅  Success - Complete job
[Local Development Tasks/greet] 🏁  Job succeeded

real    0m3.386s
user    0m0.071s
sys     0m0.046s

echo だけで3秒…。タスクランナーとしてこの時点で利用する可能性が厳しいのでは？ とすでに感じますが、続けます。

続いて、リポジトリ上で ls -la をします。ローカル実行とは言え、実体はDockerコンテナ上で動作するため actions/checkout@v4 をする必要があります。先程の local-tasks.yaml の最後に以下を追加します。

+  list-files: # ファイル一覧を表示するジョブ
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code # コードをチェックアウトしないとプロジェクトファイルにアクセスできない
+        uses: actions/checkout@v4
+      - name: List current directory
+        run: ls -la

act -j list-files で実行します。

$ time act -j list-files
INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock'
[Local Development Tasks/list-files] ⭐ Run Set up job
[Local Development Tasks/list-files] 🚀  Start image=catthehacker/ubuntu:act-latest
[Local Development Tasks/list-files]   🐳  docker pull image=catthehacker/ubuntu:act-latest platform= username= forcePull=true
[Local Development Tasks/list-files] using DockerAuthConfig authentication for docker pull
[Local Development Tasks/list-files]   🐳  docker create image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/list-files]   🐳  docker run image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/list-files]   🐳  docker exec cmd=[node --no-warnings -e console.log(process.execPath)] user= workdir=
[Local Development Tasks/list-files]   ✅  Success - Set up job
[Local Development Tasks/list-files] ⭐ Run Main Checkout code
[Local Development Tasks/list-files]   🐳  docker cp src=/home/mano/actsample/. dst=/home/mano/actsample
[Local Development Tasks/list-files]   ✅  Success - Main Checkout code [50.644993ms]
[Local Development Tasks/list-files] ⭐ Run Main List current directory
[Local Development Tasks/list-files]   🐳  docker exec cmd=[bash -e /var/run/act/workflow/1] user= workdir=
| total 16
| drwxr-xr-x 4 root root 4096 Jun  7 00:33 .
| drwxr-xr-x 3 root root 4096 Jun  7 00:33 ..
| drwxr-xr-x 7 root root 4096 Jun  7 00:33 .git
| drwxr-xr-x 3 root root 4096 Jun  7 00:33 .github
[Local Development Tasks/list-files]   ✅  Success - Main List current directory [125.864705ms]
[Local Development Tasks/list-files] ⭐ Run Complete job
[Local Development Tasks/list-files] Cleaning up container for job list-files
[Local Development Tasks/list-files]   ✅  Success - Complete job
[Local Development Tasks/list-files] 🏁  Job succeeded

real    0m3.875s
user    0m0.099s
sys     0m0.055s

カレントディレクトリのファイル一覧が表示されました。微妙に実行時間は長くなりました。

ローカルでの実行にあたり、GitHubのシークレット (secrets.GITHUB_TOKEN など) が必要なワークフローの場合、act では –secret MY_SECRET=value や .secrets ファイルを使用してこれらを提供できます。タスクランナーとして使う場合、必ずしもシークレットが多用されるわけではありませんが、覚えておくと良いでしょう。

他のランナーで動かすとどうなるのか

Runners - act - User Guide でmicro, largeで利用しているイメージが記載されています。-P オプションで指定できるようです。

おそらく、最軽量のmicroで動かします。

$ time act -P ubuntu-latest=node:16-buster-slim -j greet
INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock'
[Local Development Tasks/greet] ⭐ Run Set up job
[Local Development Tasks/greet] 🚀  Start image=node:16-buster-slim
[Local Development Tasks/greet]   🐳  docker pull image=node:16-buster-slim platform= username= forcePull=true
[Local Development Tasks/greet] using DockerAuthConfig authentication for docker pull
[Local Development Tasks/greet]   🐳  docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/greet]   🐳  docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/greet]   🐳  docker exec cmd=[node --no-warnings -e console.log(process.execPath)] user= workdir=
[Local Development Tasks/greet]   ✅  Success - Set up job
[Local Development Tasks/greet] ⭐ Run Main Say Hello
[Local Development Tasks/greet]   🐳  docker exec cmd=[bash -e /var/run/act/workflow/0] user= workdir=
| 🐈️こんにちﾆｬﾝ
[Local Development Tasks/greet]   ✅  Success - Main Say Hello [101.2046ms]
[Local Development Tasks/greet] ⭐ Run Complete job
[Local Development Tasks/greet] Cleaning up container for job greet
[Local Development Tasks/greet]   ✅  Success - Complete job
[Local Development Tasks/greet] 🏁  Job succeeded

real    0m2.719s
user    0m0.033s
sys     0m0.053s

少しだけ早くなりましたが、劇的に高速化とはならないようです。

続いて、large を動かしたかったのですが、イメージが上手く取得できなかったので試していません。ご存じの方がいましたら、Xなどで教えて下さい。

オフライン実行

act にはオフラインモードが存在します。ローカルにジョブコンテナやアクションのイメージがキャッシュされていれば、オフラインでも動作可能。原理的に高速化もされます。

$ time act --action-offline-mode -j greet
INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock'
[Local Development Tasks/greet] ⭐ Run Set up job
[Local Development Tasks/greet] 🚀  Start image=catthehacker/ubuntu:act-latest
[Local Development Tasks/greet]   🐳  docker pull image=catthehacker/ubuntu:act-latest platform= username= forcePull=false
[Local Development Tasks/greet]   🐳  docker create image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/greet]   🐳  docker run image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/greet]   🐳  docker exec cmd=[node --no-warnings -e console.log(process.execPath)] user= workdir=
[Local Development Tasks/greet]   ✅  Success - Set up job
[Local Development Tasks/greet] ⭐ Run Main Say Hello
[Local Development Tasks/greet]   🐳  docker exec cmd=[bash -e /var/run/act/workflow/0] user= workdir=
| 🐈️こんにちﾆｬﾝ
[Local Development Tasks/greet]   ✅  Success - Main Say Hello [119.563033ms]
[Local Development Tasks/greet] ⭐ Run Complete job
[Local Development Tasks/greet] Cleaning up container for job greet
[Local Development Tasks/greet]   ✅  Success - Complete job
[Local Development Tasks/greet] 🏁  Job succeeded

real    0m1.073s
user    0m0.074s
sys     0m0.013s

2-3倍、性能が改善しました。体感上もこれなら待てます。続いて、checkout@v4 を含んだlist-filesを動かします。

e$ time act --action-offline-mode -j list-files
INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock'
[Local Development Tasks/list-files] ⭐ Run Set up job
[Local Development Tasks/list-files] 🚀  Start image=catthehacker/ubuntu:act-latest
[Local Development Tasks/list-files]   🐳  docker pull image=catthehacker/ubuntu:act-latest platform= username= forcePull=false
[Local Development Tasks/list-files]   🐳  docker create image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/list-files]   🐳  docker run image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/list-files]   🐳  docker exec cmd=[node --no-warnings -e console.log(process.execPath)] user= workdir=
[Local Development Tasks/list-files]   ✅  Success - Set up job
[Local Development Tasks/list-files] ⭐ Run Main Checkout code
[Local Development Tasks/list-files]   🐳  docker cp src=/home/mano/actsample/. dst=/home/mano/actsample
[Local Development Tasks/list-files]   ✅  Success - Main Checkout code [34.498731ms]
[Local Development Tasks/list-files] ⭐ Run Main List current directory
[Local Development Tasks/list-files]   🐳  docker exec cmd=[bash -e /var/run/act/workflow/1] user= workdir=
| total 16
| drwxr-xr-x 4 root root 4096 Jun  7 01:29 .
| drwxr-xr-x 3 root root 4096 Jun  7 01:29 ..
| drwxr-xr-x 7 root root 4096 Jun  7 01:29 .git
| drwxr-xr-x 3 root root 4096 Jun  7 01:29 .github
[Local Development Tasks/list-files]   ✅  Success - Main List current directory [122.866479ms]
[Local Development Tasks/list-files] ⭐ Run Complete job
[Local Development Tasks/list-files] Cleaning up container for job list-files
[Local Development Tasks/list-files]   ✅  Success - Complete job
[Local Development Tasks/list-files] 🏁  Job succeeded

real    0m1.164s
user    0m0.059s
sys     0m0.044s

こちらも2-3倍高速化しています。これならまだなんとかなるかもしれません。

それなりに歴史を重ねたリポジトリで動かしてみる

試したリポジトリサイズは以下です。size-pack がリモートサーバーにpushされた時のサイズとのことで、1.3GiB程度です。

$ git gc
$ git count-objects -vH
count: 0
size: 0 bytes
in-pack: 188260
packs: 1
size-pack: 1.13 GiB
prune-packable: 0
garbage: 0
size-garbage: 0 bytes

これで試してみます。 先程の act --action-offline-mode -j list-files を試してみます。

$ time act --action-offline-mode -j list-files
INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock'
[Local Development Tasks/list-files] ⭐ Run Set up job
[Local Development Tasks/list-files] 🚀  Start image=catthehacker/ubuntu:act-latest
[Local Development Tasks/list-files]   🐳  docker pull image=catthehacker/ubuntu:act-latest platform= username= forcePull=false
[Local Development Tasks/list-files]   🐳  docker create image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/list-files]   🐳  docker run image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/list-files]   🐳  docker exec cmd=[node --no-warnings -e console.log(process.execPath)] user= workdir=
[Local Development Tasks/list-files]   ✅  Success - Set up job
[Local Development Tasks/list-files] ⭐ Run Main Checkout code
[Local Development Tasks/list-files]   🐳  docker cp src=/home/mano/myRepo/. dst=/home/mano/myRepo
[Local Development Tasks/list-files]   ✅  Success - Main Checkout code [5.007896049s]
[Local Development Tasks/list-files] ⭐ Run Main List current directory
[Local Development Tasks/list-files]   🐳  docker exec cmd=[bash -e /var/run/act/workflow/1] user= workdir=
| total 236
（中略）
| drwxr-xr-x 18 root root   4096 Jun  9 01:04 tool
[Local Development Tasks/list-files]   ✅  Success - Main List current directory [126.408501ms]
[Local Development Tasks/list-files] ⭐ Run Complete job
[Local Development Tasks/list-files] Cleaning up container for job list-files
[Local Development Tasks/list-files]   ✅  Success - Complete job
[Local Development Tasks/list-files] 🏁  Job succeeded

real    0m6.452s
user    0m0.530s
sys     0m2.852s

チェックアウトだけで5秒程度が追加となり、全体で6.5秒程度。リポジトリサイズが増えると厳しい感じがしますね。

プロキシ、カスタム証明書の読み込みが難しい？

例えば、Goの環境を構築したい場合、以下のように actions/setup-go などを呼び出します。しかし、ローカル環境によってはエラーになります。

+  lint:
+    name: Lint Go Files
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.22'
+      - name: Run vet
+        run: go vet ./...

エラーの例です。 failed to verify certificate: x509: certificate signed by unknown authority とカスタム証明書を利用している環境において、あるあるなエラーが出ています。

[Local Development Tasks/Format Go Files] Unable to clone https://github.com/actions/setup-go refs/heads/v5: Get "https://github.com/actions/setup-go/info/refs?service=git-upload-pack": tls: failed to verify certificate: x509: certificate signed by unknown authority

カスタムイメージをビルドしたり、ルート証明書を読み込ませたり、SSL VERIFYを無効化などいろいろ試しましたが、残念ながら私の実力では未解決でした。もちろんこの課題が発生すること自体が組織のネットワークポリシー次第であり万人がハマるわけではありません。しかし、ランナーのコンテナが起動する分、環境セットアップが難しくなることは間違いなく、構造上、難易度が高くなるなという印象です。

ちなみに、 setup-go@v5 を利用せず、個別に定義を書けば成功できました（もはや、GitHub Actionsのお作法からは外れていますが）。

  lint:
    name: Lint Go Files
    runs-on: ubuntu-latest

    defaults:
      run:
        working-directory: /workdir

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Set up Go
-        uses: actions/setup-go@v5
-        with:
-          go-version: '1.22'
+        run: |
+          curl -sSL -k -o go.tar.gz https://go.dev/dl/go1.22.4.linux-amd64.tar.gz
+          sudo tar -C /usr/local -xzf go.tar.gz
+          echo "/usr/local/go/bin" | sudo tee -a $GITHUB_PATH
      - name: Run vet
        run: cd backend && go vet ./...

なお、上記は curl の部分で -k をつけて簡易的に実装しています。プロダクションで用いる場合はカスタム証明書を読み込ませた方がよいでしょう。

actでリンター（go vet） を実行して成功した結果です。

$ time act -j lint
INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock'
[Local Development Tasks/Lint Go Files] ⭐ Run Set up job
[Local Development Tasks/Lint Go Files] 🚀  Start image=catthehacker/ubuntu:act-latest
[Local Development Tasks/Lint Go Files]   🐳  docker pull image=catthehacker/ubuntu:act-latest platform= username= forcePull=true
[Local Development Tasks/Lint Go Files] using DockerAuthConfig authentication for docker pull
[Local Development Tasks/Lint Go Files]   🐳  docker create image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/Lint Go Files]   🐳  docker run image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/Lint Go Files]   🐳  docker exec cmd=[node --no-warnings -e console.log(process.execPath)] user= workdir=
[Local Development Tasks/Lint Go Files]   ✅  Success - Set up job
[Local Development Tasks/Lint Go Files] ⭐ Run Main Checkout code
[Local Development Tasks/Lint Go Files]   🐳  docker cp src=/home/mano/MyRepo/. dst=/home/mano/MyRepo
[Local Development Tasks/Lint Go Files]   ✅  Success - Main Checkout code [14.494783288s]
[Local Development Tasks/Lint Go Files] ⭐ Run Main Install Go
[Local Development Tasks/Lint Go Files]   🐳  docker exec cmd=[bash -e /var/run/act/workflow/1] user= workdir=
| /usr/local/go/bin
[Local Development Tasks/Lint Go Files]   ✅  Success - Main Install Go [16.761998127s]
[Local Development Tasks/Lint Go Files]   ⚙  ::add-path:: /usr/local/go/bin
[Local Development Tasks/Lint Go Files] ⭐ Run Main Run vet
[Local Development Tasks/Lint Go Files]   🐳  docker exec cmd=[bash -e /var/run/act/workflow/2] user= workdir=
| go: downloading github.com/aws/aws-lambda-go v1.41.0
| go: downloading github.com/rs/zerolog v1.29.0
| go: downloading github.com/go-playground/validator/v10 v10.16.0
（中略）
[Local Development Tasks/Lint Go Files]   ✅  Success - Main Run vet [59.368599077s]
[Local Development Tasks/Lint Go Files] ⭐ Run Complete job
[Local Development Tasks/Lint Go Files] Cleaning up container for job Lint Go Files
[Local Development Tasks/Lint Go Files]   ✅  Success - Complete job
[Local Development Tasks/Lint Go Files] 🏁  Job succeeded

real    1m40.689s
user    0m0.769s
sys     0m3.229s

厳しいのは、実行時間が1分40秒かかったというところでしょう。これは go vet を実行するためにコンパイルが必要なので、 go mod download 相当の処理が動くためです。go mod 側のキャッシュをボリュームマウントすれば高速化できると思いますが、逆に言うとそういったチューニングが必要だということです。

ちなみにもし、go vet が失敗（違反コードが存在）した場合は exit 1 でジョブが以下のように失敗します。

| # github.com/.../...
| app/my_model.go:30:2: struct field myfields has json tag but is not exported
[Local Development Tasks/Lint Go Files]   ❌  Failure - Main Run go vet [1m2.783279728s]
[Local Development Tasks/Lint Go Files] exitcode '1': failure
[Local Development Tasks/Lint Go Files] ⭐ Run Complete job
[Local Development Tasks/Lint Go Files]   ✅  Success - Complete job
[Local Development Tasks/Lint Go Files] 🏁  Job failed
Error: Job 'Lint Go Files' failed

成功/失敗の表示は、タスクランナーとして、特段大きな違和感は無いと思います。

フォーマットする場合

フォーマットやコード生成などの場合は、ホスト側のコードに反映させる必要があります。この場合、checkout 経由ですと、フォーマット結果を反映できず困ってしまいます。そのため、ボリュームマウントで対応します。ボリュームマウントするので、 checkout のステップは無くすことができます。

defaults.run.working-directory に適当なマウント先のフォルダを定義します。

+  fmt:
+    name: Format Go Files
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: /workdir # マウント先を適当に定義
+    steps:
+      - name: Install Go
+        run: |
+          curl -sSL -k -o go.tar.gz https://go.dev/dl/go1.22.4.linux-amd64.tar.gz
+          sudo tar -C /usr/local -xzf go.tar.gz
+          echo "/usr/local/go/bin" | sudo tee -a $GITHUB_PATH
+     - name: Run gofmt
+        run: gofmt -l -w .

実行時は --container-options でボリュームマウント定義を渡します。このオプションはドキュメントで探せなかったのですが、 https://github.com/nektos/act/issues/1548 のIssueから見つけました。

act コマンドを実行します。 --container-options "-v $(pwd):/workdir" の /workdir の値は、さきほどの local-tasks.yaml で指定した値と一致させます。

$ time act -j fmt --container-options "-v $(pwd):/workdir"
INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock'
[Local Development Tasks/Format Go Files] ⭐ Run Set up job
[Local Development Tasks/Format Go Files] 🚀  Start image=catthehacker/ubuntu:act-latest
[Local Development Tasks/Format Go Files]   🐳  docker pull image=catthehacker/ubuntu:act-latest platform= username= forcePull=true
[Local Development Tasks/Format Go Files] using DockerAuthConfig authentication for docker pull
[Local Development Tasks/Format Go Files]   🐳  docker create image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/Format Go Files]   🐳  docker run image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Local Development Tasks/Format Go Files]   🐳  docker exec cmd=[node --no-warnings -e console.log(process.execPath)] user= workdir=
[Local Development Tasks/Format Go Files]   ✅  Success - Set up job
[Local Development Tasks/Format Go Files] ⭐ Run Main Install Go
[Local Development Tasks/Format Go Files]   🐳  docker exec cmd=[bash -e /var/run/act/workflow/0] user= workdir=/workdir
| /usr/local/go/bin
[Local Development Tasks/Format Go Files]   ✅  Success - Main Install Go [17.32964836s]
[Local Development Tasks/Format Go Files]   ⚙  ::add-path:: /usr/local/go/bin
[Local Development Tasks/Format Go Files] ⭐ Run Main Run gofmt
[Local Development Tasks/Format Go Files]   🐳  docker exec cmd=[bash -e /var/run/act/workflow/1] user= workdir=/workdir
| backend/my_model.go
[Local Development Tasks/Format Go Files]   ✅  Success - Main Run gofmt [711.356576ms]
[Local Development Tasks/Format Go Files] ⭐ Run Complete job
[Local Development Tasks/Format Go Files] Cleaning up container for job Format Go Files
[Local Development Tasks/Format Go Files]   ✅  Success - Complete job
[Local Development Tasks/Format Go Files] 🏁  Job succeeded

real    0m20.747s
user    0m0.069s
sys     0m0.111s

checkout が無くなった分、高速化したのと、単純に gofmt を呼ぶだけ（コンパイルなどは不要）であるため、20秒で終わりました。--pull=false や --action-offline-mode をつければ、数秒早くできる可能性があります。ちなみに、ホスト上で直接 gofmt を呼び出す場合は1～2秒で終わります。

ボリュームマウントですが、ローカルでの実行速度を最優先に考えるのであれば、actions/checkout@v4 を呼び出さなくて済むため必須かもしれないと思いました。もちろん、代償として GitHub Actions とのコード共有・再利用性は下がります。

Makefileとの棲み分けは？

リンターやフォーマッタなど、具体的なコマンドはMakefile（Taskfile）に記載し、ローカル開発時にはそれらのタスクコマンドを単純呼び出しできるようにしておく方がデバッグもやりやすいかなと思います。CI/CD定義からはそれらのコマンドを呼び出すだけ、という構成にすると、定義が重複せず保守性を保てるでしょう。

このような棲み分けの概念を壊せないかと、CI/CD定義を直接ローカルで動かせる act を、タスクランナーとして使ってみようという試みでしたが、現時点ではプロキシ・カスタム証明書の問題が解決したとしても、実行時間のオーバーヘッドが大きく微妙です。そもそも、定義の共有自体が私の技術力では微妙な結果に終わってしまいました。そのため、この記事の結論としては、よくローカル開発で実行するコマンドは、 act 経由ではなく引き続きMakefileやTaskfileを利用する方が無難でしょう。

ボリュームマウントの定義などは煩雑なので、何ならMakefileにactの呼び出しコマンドを書いてしまいたいくらいです。

まとめ

act をタスクランナーとして試しました。

現時点で得た課題感は以下です。

• actでは全てのタスクが、コンテナ上で動くため、起動のオーバーヘッドが1～3数秒かかる
• 1GiB超えのリポジトリの場合は、チェックアウトのみでさらに5秒程度かかる
• 依存ライブラリの解決など毎回実行するには重い処理は、キャッシュが有効だが、そうするとホストとのボリュームマウントなど面倒なチューニングが必要となり、管理コストが上がる
• フォーマットやコード生成など、ホスト側のファイルを書き換えたい場合は actions/checkout@v4 を行わず、直接リポジトリごとボリュームマウントする必要があり、管理コストが上がる
• プロキシ・カスタム証明書などを前提とする組織ネットワークでは、 actions/setup-go などのコマンドがうまく動作しない可能性。そのため、プロキシ問題をトラブルシュート＆解決できる人材・時間が必要

上記、チューニングや環境構築に成功したとしても、GitHub Actions側の workflows 定義の共有は難しく、結局、別のファイルとして管理することになりそうということでした。

act 側のナレッジをチームで積んでいけば、性能その他の課題は潰せそうですが、タスクランナーとして利用するのは、それなりの意思決定が必要になりそうな印象です。GitHub Actionsにある程度習熟した人であればもう少し別の見方になるかもしれません。積極的に導入しているよーという方やチームがいらっしゃいましたら、Xなどで教えてください。

はじめに

コードレビューを自動で可視化するためのツールといえば reviewdog が有名です。

最近（2025年03月）reviewdog のソースリポジトリが侵害され、reviewdog を実行しているリポジトリにおいて シークレット情報がワークフロー上に漏洩するセキュリティインシデントが発生 したことは記憶に新しいでしょう。

筆者も reviewdog にはお世話になっている開発者の一人ですが、本件を受けて「そもそも GitHub の標準機能だけで同じようなことができないか」という考えを持ち、あらためて GitHub 標準の Annotation 機能について調べてみた記事になります。

なお、reviewdog 自体の有用性を否定するものでは一切ありません。

レビューの可視化とは

まず誤解のないよう本記事における「レビューの可視化」とは具体的に何を指すのかを説明しておきます。

レビューの可視化とは、Linter や Formatter などソースコードの解析結果をもとに、結果をわかりやすく表示してくれるしくみのことを指しています。実際にソースコードのエラーや警告を検出する部分の話ではなく、その結果を解析してよい感じに開発者へフィードバックしてくれる部分の話となります。

reviewdog とは

reviewdog は Linter や Formatter などの出力結果を GitHub などのコードホスティングサービス上にコメントなどで投稿してくれるツールです。

その思想や誕生の背景については、開発者のブログを貼る形で本記事では割愛したいと思います。

http://haya14busa.com/reviewdog/

GitHub Annotation とは

GitHub Annotation（アノテーション）とは、GitHub Actions のワークフロー実行中に出力されるエラーや警告などを、対象のファイルや行に紐付けて GitHub の UI 上に表示する標準のしくみです。公式ドキュメントでは、GitHub Actions のワークフローコマンドの中で説明されています。

https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions

具体的には ::error, ::warning, ::notice といったコマンドをファイルパスや行数とともに出力することで、アノテーションを作成できます。

::error file={name},line={line},endLine={endLine},title={title}::{message}

実際にアノテーションを作成するサンプルを見てみましょう。
次のようなワークフローファイルを作成して GitHub Actions を実行してみます。echo "::error ..." や echo "::warning..." と記載している部分がコマンド部分になります。

name: Emit Annotation Directly

on:
  pull_request:
  workflow_dispatch:

jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Emit Error and Warning Annotations
        run: |
          echo "::error file=.github/workflows/annotation.yaml,line=16,col=5::Example Error: This is a sample error message for demonstration purposes."
          echo "::warning file=.github/workflows/annotation.yaml,line=17,col=5::Example Warning: This is a sample warning message for demonstration purposes."

このワークフローを実行して GitHub Actions の実行結果サマリをみると 次のように アノテーションが出力されます。

また、このワークフローが PR（Pull Request）をトリガとして実行されている場合は、 次のように PR の「Files changed」タブから該当する箇所にインラインでアノテーションが表示されていることが確認できます。

このように、GitHub Annotation を活用することで該当ファイル・該当行にピンポイントでメッセージを表示できます。
サンプルではファイルや行数をベタ書きしましたが、 Linter や Formatter などの解析ツールと組み合わせることで、これらのツールの実行結果をアノテーションとしてユーザにフィードバックできます。

GitHub Annotation の実践的な活用方法

GitHub Annotation の概要について理解できたところで、実践的な使い方について説明していきます。

Problem Matcher の利用

Problem Matcher とは、GitHub Actions におけるログ出力からエラーや警告の情報を自動的に抽出し、アノテーションとして表示するためのしくみです。

先ほどの例では直接 echo "::error ..." と記述していましたが、これをより汎用的に使いやすくした機能だと理解してもらえれば OK です。

Problem Matcher はパターン（正規表現）を JSON 形式で定義することで、任意のツールの出力形式にマッチさせます。
公式ドキュメントにも記載されている ESLint の出力結果に対応させる例をみてみましょう。

test.js
  1:0   error  Missing "use strict" statement                 strict
  5:10  error  'addOne' is defined but never used             no-unused-vars
✖ 2 problems (2 errors, 0 warnings)

設定ファイル

この ESLint の出力結果に対応する Problem Matcher の設定ファイルは次のとおりです。

{
  "problemMatcher": [
    {
      "owner": "eslint-stylish",
      "pattern": [
        {
          // Matches the 1st line in the output
          "regexp": "^([^\\s].*)$",
          "file": 1
        },
        {
          // Matches the 2nd and 3rd line in the output
          "regexp": "^\\s+(\\d+):(\\d+)\\s+(error|warning|info)\\s+(.*)\\s\\s+(.*)$",
          // File is carried through from above, so we define the rest of the groups
          "line": 1,
          "column": 2,
          "severity": 3,
          "message": 4,
          "code": 5,
          "loop": true
        }
      ]
    }
  ]
}

ESLint の出力のように、最初にファイル名が 1 行だけ表示され、その後に複数のエラーや警告が続く「マルチライン形式」の出力に対応するため、Problem Matcher では複数の pattern を組み合わせて定義できます。

最初のパターンでは、ファイル名の行を検出します。正規表現（"regexp": "^([^\\s].*)$"）により、先頭が空白で始まらない行をファイル名として抽出し、ファイル名として指定（"file": 1）しています。ここでの 1 は、正規表現内の括弧 () によって囲まれた 1 番目のキャプチャグループを指しています。

最初のパターンはファイル名の出力に対応する部分となります。正規表現（"regexp": "^([^\\s].*)$"）でマッチした部分をファイル名（"file": 1）として設定しています。"file": 1 の 1 は正規表現のキャプチャグループの番号を表しています。
続く 2 つ目のパターンでは、各エラー・警告行の情報（行番号、列番号、深刻度、メッセージ、ルール名など）をそれぞれのキャプチャグループから取り出し、アノテーションとして表示するための各要素にマッピングしています。各要素は次のとおりです。

最後の "loop": true は、同じファイルに対して複数行のエラー・警告が連続して出力される場合に、1 回目に取得したファイル名を保持したまま、後続の行に繰り返しこのパターンを適用するための設定です。

登録と削除

Problem Matcher は、GitHub Actions のワークフロー内で ::add-matcher:: および ::remove-matcher:: コマンドを使用することで動的に登録・削除できます。

たとえば、先ほどの eslint-matcher.json ファイルを .github/matchers/ ディレクトリに保存した場合、次のように登録できます。

- name: Add ESLint Problem Matcher
  run: echo "::add-matcher::.github/matchers/eslint-matcher.json"

このようにすると、以降のステップで ESLint の出力に応じたアノテーションが自動的に表示されます。
不要になった場合は、次のように削除します。

- name: Remove ESLint Problem Matcher
  run: echo "::remove-matcher::eslint-stylish"

ここで指定する eslint-stylish は、Problem Matcher の設定ファイル内で定義した owner に対応しています。

ただし、実際のところ ESLint を GitHub Actions 上で実行する場合、通常この登録処理を明示的に記述することはありません。
なぜなら、ESLint を実行する前には一般的に actions/setup-node を使って Node.js のセットアップを行いますが、このステップの中で ESLint 用の Problem Matcher が自動的に登録されるためです。

ほかにも setup-python や setup-go そして setup-dotnet などでも言語に応じて標準的な Problem Matcher が登録されるようになっています。

GitHub Annotation にネイティブに対応しているツールの利用

Python 用の Linter である Ruff など GitHub Annotation に対応した出力をサポートしているツールもあります。
Ruff では --output-format に github を指定することで、次のような出力を得ることができます。

ruff check test.py --output-format github
::error title=Ruff (F401),file=test.py,line=1,col=8,endLine=1,endColumn=10::test.py:1:8: F401 `os` imported but unused

GitHub Annotation の制約

GitHub Actions はワークフロー実行時のアノテーション数を次のように制限しています。
https://github.com/orgs/community/discussions/26680

• 1 ステップ（ワークフロー定義の run や uses の単位）あたりエラー 10 件、警告 10 件、通知 10 件
• 1 ジョブ（ワークフロー定義のステップを 1 つ以上含む jobs の単位）あたり 50 件
• 1 実行（ワークフローの実行）あたり 50 件

大量にエラーや警告が出力される場合は、一度にすべてを表示できないため、注意が必要です。
ただし通常 Linter などはローカルでも動作させてエラーを確認できるため、このあたりは割り切れるケースが多いのではないでしょうか。

reviewdog との比較

ここまで GitHub 標準の Annotation 機能を紹介してきましたが、先に紹介した reviewdog と比較したときのメリット・デメリットを整理しておきます。

Annotation 機能を利用するメリットは次のとおりです。

• サードバーティのアクションに依存しない
  GitHub が公式に提供しているしくみであり、追加のツールや依存パッケージを導入する必要がありません。
• パーミッションの付与が不要でセキュア
  reviewdog を使用する場合は GitHub API を操作するため、GITHUB_TOKEN を使います。一方、Annotation 機能はログ出力ベースで動作するため、追加の認証情報を必要とせずセキュリティ的に安心です。
• GitHub API の Rate Limit を気にしなくてよい
  reviewdog は PR コメントを投稿する際に GitHub API を呼び出すため、大量のコメントや高頻度の実行で Rate Limit に引っかかる恐れがあります。Annotation はログ出力ベースで動作するため、Rate Limit の考慮は不要です。
• 標準機能であるため将来的な安定性が高い
  GitHub が提供するしくのため、GitHub Actions のアップデートや仕様変更にも継続的に対応される可能性が高く、メンテナンスコストや不具合のリスクが比較的小さいと考えられます。

Annotation 機能にはない、reviewdog ならではのメリットは次のとおりです。

• コメントの対象を差分ファイルに限定できる
  reviewdog では、差分のある行に限定してコメントを残すことができるため、古いコードや無関係な部分に過剰にコメントが付与されることを防げます。これにより、修正しなければならない対象が明確になります。
• 多くのツールに標準で対応している
  reviewdog は Checkstyle 形式 や SARIF 形式 など さまざまな形式に標準で対応 しており、自分でフォーマットを定義しなくてもさまざまなツールに対応するできます。
• PR コメントとして明示的に残せる
  reviewdog は PR 上に直接コメントを残すことができます。これにより通知などでレビューイが気付きやすく、PR 上でディスカッションするトリガにもなります。
  そのほか、GitHub の Annotation や GitHub PR Checks などの出力にも対応しており、さまざまな出力先を選べるのが特徴です。
• GitHub 以外のプラットフォームに対応できる
  GitLab や Bitbucket など、複数の SCM プラットフォームで利用可能な点も reviewdog の強みです。マルチリポジトリ・マルチサービス環境を前提とした CI にも対応できます。

どちらを使うべきか

機能的には当然 GitHub Annotation より reviewdog の方が高機能です。

当たり前のことを言ってしまえば、reviewdog の機能が必要であれば reviewdog を使うべきですし、GitHub Annotation で事足りるなら標準機能のみで実現する形が望ましいでしょう。

根本的にはフラットに比較すべきものではないような気がします。

おそらく多くの場合ポイントになるのは、差分出力ではないでしょうか。

ここについては Linter や Formatter が導入されていない既存のコードに対して後から CI を導入する場合は、大量のエラーや警告が発生し、それがノイズになることが多くあります。逆に、新規開発において始めから PR 駆動できっちりと CI を回すケースにおいては、全件出力でも問題にならないでしょう。

おわりに

案外 GitHub Annotation でもやれるんじゃないか、という記事でした。

CI/CD連載 1本目の記事です。

Dokployというのを知ったので動かしてみました。よくあるクラウドサービスのPaaSマネージドサービスようなインフラをオンプレ環境やVPSなどに簡単に構築できるものです。自宅サーバーは欲しいなと思いつつ（昔たててqmailで自宅メールサーバー運用したりしたことはあったが）、K8sはあんまり興味ないな、と思っていて何かしらいいのがないかなと思っていたところ、結構自分の理想に近かったので試してみました。

• ソースコードをアップロードしてコンテナでサービス起動
• 各種OSSのサービスを簡単起動
• これらすべてウェブベースの管理画面があり、AWSとかGoogle Cloudの管理画面のようにシステムの設定や閲覧ができる
• ログ、メトリックスのビューア完備(Dozzleとかを自前で立てる必要はない)

今回試していない機能ですが、以下の機能もあります。

• 通知
• Docker Swarmベースの複数のサーバーノード管理
• 管理画面のユーザー管理
• バックアップ機能付きのデータベースサポート
• GitHubやGitLabと連携した自動デプロイ
• スケジュール機能
• SSH鍵管理とか

このサービスはDockerとTraefikのリバースプロキシサーバが主要要素で、コンテナでアプリケーションを起動できます。アプリケーションをビルドしてDocker上で起動したり、Docker上で動いているデータベースのデータをバックアップしたりする便利機能群を提供しています。

なお、Dokployそのものはローカルマシンに入れずに、SaaSで動いているDokployに外部からマシン管理機構だけを任せる運用というサービスも提供されています。月当たり$3.5/台+$1ぐらい。また、さまざまなホスティング環境もサポートしています。

インストールしてみる

DokployはLinuxのみをサポートしています。macOSでは直接は動かないのでLinuxの仮想PCを入れてその上で動かします。

macOSは仮想化機能がOS内蔵なのにWSLみたいな直接使えるインターフェースがないので、UTMを入れてその上でDebianを動かします。WWDCのたびにVirtualization Frameworkの新情報を待ち望んでいるのですが・・・今年は新情報来たらいいな。

UTMはApp Storeでも入れられますし、公式サイトからダウンロードしてもいいですし、Homebrew使って brew install --cask utm でもお好きな方法を選びます。

Linuxインストール

DokployがサポートしているOSはDebian, Ubuntu, Centosです。今回はUbuntuを選びました。手元のmacはM3なので下記のページの「小さなCDまたはUSBメモリ」のARM64のイメージをダウンロードします。Debian Downloadで出てくるサイトだとAMD64版しかないので要注意。

UTMのウインドウで＋ボタンを押して「仮想化」を選びます。OS選択ではLinuxを選び、Apple仮想化と、ISOイメージで先ほどダウンロードした.isoファイルを選択して、あとはすべてデフォルトでインストールしていきました。特にパッケージなども追加はしていません。SSHサーバのみが入った感じですかね。

起動してIDとパスワードを入れて起動できたら、sudoとcurlコマンドだけインストールしておきます。

$ su -
(rootのパスワードを入れる)
$ apt-get install sudo curl
$ adduser debian sudo

内部で起動したサービスにつながるかテスト。ネットワークはデフォルトのホストネットワークを使っています。まずはゲストの中でIPアドレスを確認します。192.168.64.7というIPv4アドレスを持っているようです。

$ ip a
1: lo: ...
    :
2: enp0s1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_code1...
    link/ether 92:60:fc:72:aa:9c brd ff:ff:ff:ff:ff:ff
    inet 192.168.64.7/24 brd 192.168.64.255 scope global dynamic enp0s1
    :

引き続き、ゲストの中からPythonのウェブサーバーを起動してみます。

$ python3 -m http.server
Serving HTTP on :: port 8000 (http://[::]:8000/) ...

ホストのマシンからこのゲスト上で動いているサービスにアクセスしてみてHTMLが帰ってきたら無事にサーバーがでっきていることの確認ができます。

% curl http://192.168.64.7:8000
<!DOCTYPE HTML>
<html lang="en">
:

これでLinuxのインストールは完了。

Dokployのインストール

Dokployはシェルでインストールします。さまざまなビルドツールとかをダウンロードするので、そこそこの量のダウンロードが走ります。間違ってもテザリングでやらないように・・・勇気と無謀は違います。この手のシェルでインストールはちょっと怖い気持ちはあるのですが、まあ何もないLinux仮想環境なのでえいやで実行します。最後のシェル実行だけroot権限が必要なのでsudoをつけます。

$ curl -sSL https://dokploy.com/install.sh | sudo sh

最後に管理画面のURLが表示されますが、IP部分は先ほどip aコマンドで出てきたものを使います。

アプリケーションのデプロイ

アプリケーションをデプロイしていきます。

設定ファイルなしの自動ビルド(Railpack)

まずはGoのアプリケーションを作ってみます。ふつうのウェブアプリケーションです。

module goapp

go 1.24

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"os/signal"
	"syscall"
	"time"
)

func hello(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "hello world")
}

func main() {
	http.HandleFunc("/hello", hello) // /hello以下でリクエストを受ける
	srv := &http.Server{
		Addr: ":8080",
	}
	go func() {
		log.Printf("start listening at %s\n", srv.Addr)
		if err := srv.ListenAndServe(); err != http.ErrServerClosed {
			log.Fatalf("ListenAndServe(): %v", err)
		}
	}()
	ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer cancel()
	<-ctx.Done()
	ctx2, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()
	if err := srv.Shutdown(ctx2); err != nil {
		log.Fatalf("Fail to shutdown: %v", err)
	}
}

すべてのアプリケーション、データベースなどは「サービス」という名前のインスタンスで、各サービスは必ず「プロジェクト」に属すという構成になっています。プロジェクト共有で環境変数を設定したり、サービスごとに環境変数の設定もできます。まずはプロジェクトを作ります。名前を入れるだけですね。go appにしました。

プロジェクトの中にはサービスをおきます。サービスは（自作）アプリケーション、データベース、Compose、テンプレート（後述）、AIで相談して作る、というのがあります。今回はアプリケーションを作ります。こちらもほぼ名前だけです。サーバーはDokployを複数サーバー管理に使っている場合に選びます。今回は1台だけなので選ぶ必要はありません。

アプリケーションのGeneralタブでアプリケーションをデプロイします。ビルドタイプはDockerやBuildpackなどいろいろありますがデフォルトのRailpackにしました。Gitとかと接続もできますが、今回はローカルで作ったzipのソースをドラッグしてデプロイします。Railpackの場合、Goアプリケーションはトップにmain.goがあればこれをアプリとみなしてビルドするようです。Deployボタンをおせば初回は50秒、2回目は9秒ほどでビルドが終わりました。

外からアクセスできるようにするためにはドメインを作成します。DMZで動いているマシンならtraefik.meのサブドメインの無料のドメイン発行機能もあり、ボタン一発（サイコロアイコン）で外からもアクセスさせることもできます。

Deokployが動いているサーバーの80番ポートでサービスは公開されるので、そのアドレスで起動すればOKですね。

複数アプリケーション起動したくなると思うので、その場合はドメインのパスを / から /helloとすればそれ以外のパスは他のアプリから使えます。ただし、アプリケーションが受け取るパスはこのプレフィックス部分も含むため、プレフィックス部分は環境変数とかで変えられる機能をアプリ側につけると良さそうです。パスのプレフィックスをトリムする機能はなさげですので。

なおブラウザの管理画面からデプロイ（ビルド）時のログが見られたり、アプリケーションのログも見られるし、メトリックスも見られるし、シェルがあるならコンテナの中に入ることもできるし、コマンドを起動もできるし、ローカル開発と遜色なく利用できます。

複数のアプリケーションを起動の準備

PaaSなので複数のアプリケーションを稼働させられます。ただ、各アプリケーションはみんな自分のパスの空間を持っています。例えば、/healthでヘルスチェック用のエンドポイントを提供というのはみんなやっているので、80番ポートにフラットにマウントされてしまうと複数のアプリケーションが稼働できません。そこで、バーチャルホストの設定をして複数起動できるようにします。

先ほどのGoアプリと、このPythonアプリ、どちらも /helloというエンドポイントを持っています。192.168のアドレスにマッピングすると使い分けられません。DokployにはTraefikというプロキシが内蔵されています。このプロキシがリクエストを受けるときに、HTTPリクエストに含まれるhostヘッダーフィールドを見て後続のサービスを判断してリクエストを投げ分けます。

そのためにはサービスごとにドメインを発行する必要があります。hostsファイルでも良かったのですがワイルドカード対応のためにdnsmasqをローカルに入れて使います。macOSの手順を書いています。他のOSの方は生成AIにでも投げて自分の環境に合わせて変更してください。

# dnsmasqをインストール
$ brew install dnsmasq

設定ファイルは以下の通りです。Linuxだと/etc/dnsmasq.confですかね。ローカル用にprivateというトップレベルドメインを作ってしまいましょう。次の行を足します。どんなサブドメイン向けのリクエストもこのIPアドレスが返ります。

address=/.private/192.168.64.7

privateドメインだけはこのDNSサーバーを見にいくようにします。/etc/resolver/フォルダを作りprivateというファイルを作成して以下の内容を書きます。

nameserver 127.0.0.1

最後にDNSサーバーとOSキャッシュをクリアします。

$ sudo brew services restart dnsmasq
$ sudo killall -HUP mDNSResponder

試しにping test.privateとかいろいろ叩いてみて、192.168.64.7を向いているか確認します。確認できたらアプリをインストールします。

Docker形式のアプリのビルド

以下の記事で書いたPythonアプリケーションをデプロイしてみます。

• FastAPI on Dockerがかなりシンプルになった(2025年版)

プロジェクトは先ほどの使い回しでも新規で作っても大丈夫です。その後サービスを作ります。今度のアプリケーションはDockerファイル入りなので、ビルドタイプにDockerfileを選び、ファイル名のDockerfileも入れます。あとはまたzipにしてドロップしてデプロイボタンを押せばビルド完了です。

ドメイン設定ではpyapp.privateというドメインを追加します。

先ほどのGoのアプリケーションの方のドメイン設定にはgoapp.privateというドメインを追加しておきます。ドメインは複数設定できるので前のものは消さなくても大丈夫です。

新しいドメインでアクセスすると複数のサービスが同時に利用できました。

テンプレートカタログからアプリケーションのデプロイ

自作のアプリケーション以外にも人気のアプリケーションを簡単にデプロイできるテンプレートがあります。

試しにminioを選択しました。サーバー選択だけですぐにアプリが登録できました。デプロイ（コンテナのダウンロード）はされていない状態です。ドメインはtraefikの自動生成になっていているのでminio.privateに書き換えて、デプロイボタンをおしたところ、あっという間に起動しました。パスワードなどは環境変数のところに書いてありました。楽勝ですね。

Dokployでできないこと

ドメインの管理はdnsmasqでやりました。AWSとかだとRoute 53みたいなサービスでドメインも一緒にコントロールできますが、ネットワーク周りはオンプレだったり外からアクセスできるサービスだったり、有料のドメインだったりが絡むので扱いきれないのはまあ仕方がないですね。

Dokployそのものの制限というよりも下で動いているDocker/Traefikの制約でできないのがオートスケールです。スケールそのものはDocker Composeの機能にあるのですが、明示的にコマンドを打つ必要があります。AWSやGoogle CloudのロードバランサーはサービスのメモリやCPUの計測値や接続数をみてスケーリングを行えます。モニタリングは大変でも、接続数が70超えたらインスタンス増やす、みたいなのが簡単にできる（ついでにしばらくアクセスがなかったらインスタンスがなくなる）とかがあれば、少なめリソースの自宅サーバーでたくさんサービスを起動しておいて・・・・みたいなのができるんですけどね。

まとめ

「アプリケーション」「データベース」の2つに特化したローカルPaaSのDokployで遊んでみた記録でした。今回はデータベース周りの機能はまだ触らず、またcomposeで複数のアプリの組み合わせを起動みたいなことはしていませんが、基本的なアプリケーションのデプロイを色々試したり、

クラウドのコンソールでちょいちょいアプリケーションを動かして遊んでいた人は、それがそのままオンプレやローカルで動くと考えると興味を持つ人は多いんじゃないでしょうか。「技術は螺旋で行ったり来たりする」と言われますが、コンテナや12 factors appといったクラウドで発展したものがオンプレでも便利に使えるようになるという流れは自然な発展な気がします。

もちろん、フルサービスなGoogle CloudやAWSと比べるとネットワーク周りの設定がなかったり機能が少ない点はありますが、モニタリングやログビューアとかも備えており、ローカルで動かしてテストするのと遜色なく利用できます。今回紹介したもの以外にも色々同様のものもあり、今後さらに発展していていってくれるんじゃないかと思っています。

• Coolify
• CapOver
• Kubero
• Dokku

DNSサーバーを建てるときに、最初.localでやろうとしてハマって「macOSのmDNSが別の用途で使うからダメ」というアドバイスを@takabowと@takuan_oshoにもらってなんとか書き切りました。ありがとうございます。

• 参考
  • Buildpacksのビルダーをスクラッチから作ってみる

※図は Gemini 2.5 Proで生成しました。

はじめに

入梅のみぎり、いかがお過ごしでしょうか。

フューチャーは月に1回、何かしらの技術テーマを元にブログリレー（ブログ連載）を行っています。6月はCI/CDについて取り上げます。本来は5月予定でしたが、春の入門祭りが総勢26名参加され、スケジュールがスライドしたため1ヶ月ズレての開催です。

CI/CDについて

インテグレーション (Continuous Integration) と継続的デリバリー/デプロイメント (Continuous Delivery/Deployment) の略で、開発手続きを自動化し、より早く確実にリリースするための開発手法です。

• CI (継続的インテグレーション): コード変更をリモートリポジトリにプッシュ・マージされたことを起点に、ビルドやテストを自動的に実行し、不具合を検知し手戻りを防ぐ
• CD (継続的デリバリー/デプロイメント): CI後、自動的にデプロイメント環境にリリースする方法。手動の作業を減らし、誤操作を防ぐことができる

CI/CDの略歴を説明すると以下かなと思います。

1. 1990年代後半 ～ 2000年代初頭
   • XP（エクストリーム・プログラミング）やテスト駆動開発(TDD) で有名なKent Beckさんや、マーチン・ファウラーさんなど、CIを書籍やブログなどで具体的な開発手法として紹介・提唱して広める
2. 2000年代初頭
   • Hudson (後のJenkins) などのツールが登場し、オンプレミスでのCIが活発に行われる
3. 2010年代前半
   • Travis CIやCircleCIといったクラウドベースのCI/CDサービスが登場し、急速に普及（特にスタートアップ系）
4. 2010年代後半
   • GitHub Actions（2018年提供開始）やGitLab CI/CDが登場。Gitホスティングサービスがネイティブに提供するCI/CD機能が主要な選択肢に
5. CI/CDを中心として概念の広がり
   • CI/CD普及に従い、自動テストとの相性の良さからTDD（テスト駆動開発）を取り入れたり・TerraformなどのIaC（Infrastructure as Code）もCI/CDへの組み込み・GitOps（Gitを唯一の情報源として、コミットをトリガーにインフラ・アプリへの自動デプロイを行う手法）・SRE・Four Keysを元にして定量的な開発生産性の計測など様々な広がりがあります。CI/CDはその基盤として位置づけられています

フューチャーにおけるCI/CD

私の知る限り、HudsonからCIは私が入社した2009年時点ではすでに当たり前のように行われていました。その後、Jenkinsにツールは変わりつつ、CircleCIやGitHub Actionsなどにツールも加わり、時代に合わせて進化しています。

社内標準ツールとしては、自社チームがホスティングしているGitLabがあるため、GitLab CI/CDの利用率も高いのが特徴でしょうか。以下のような記事もあります。

• GitLabのレビューにPR-Agentを組み込んでみた
• GitLab CIを新人研修に導入した話

連載スケジュール

7名、以下のスケジュールです。

澁川さんは担当分の記事を執筆するための調査で判明した事項を、別途FastAPI on Dockerがかなりシンプルになった(2025年版)の記事にまとめてもくれました。こちらも面白い記事だと思いますので、Pythonを扱う方はぜひご一読ください。

さいごに

初めてCI/CDをテーマに技術ブログ連載を始めます。

現代のソフトウェア開発の基盤・前提となる内容ですので、比較的広いテーマかなと思います。私個人としても他のメンバーがどのようなCI/CDナレッジを公開するか楽しみです。

引き続きよろしくお願いします。

書き方の部分は別として Python におけるコンテナイメージ選択の考え方とかは 2020 年に書いたときとは変わっていませんので、適宜そちらを参照してください。

• 仕事で Python コンテナをデプロイする人向けの Dockerfile (1): オールマイティ編
• 仕事で Python コンテナをデプロイする人向けの Dockerfile (2): distroless 編

(1)の方からのアップデートとしては Debian のバージョンですね。stretch(9), buster(10)はすでに EOL です。その次に出た bullseye(11)は 2026 年 8 月で EOL です。今からなら bookworm(12)がおすすめです。

(2)の方のアップデートもほぼ同じで、Debian の新バージョンを使ったイメージが追加されています。それにともって Python のバージョンも新しくなっています。

• gcr.io/distroless/python3-debian11: Python 3.9.2
• gcr.io/distroless/python3-debian12: Python 3.11.2

Dockerfile の書き方自体のアップデートとしては以下に書いた内容がベースとなります。本エントリーでもちょくちょく Docker の説明はありますが、詳細はこちらも併読してもらえると良いかと思います。

• 2024 年版の Dockerfile の考え方＆書き方

本エントリーでは Dockerfile を使った debian-slim, Chainguard, Distroless ベースのイメージ作成だけを取り上げます。コンテナ用のイメージについては次のページにまとめがあります。

• builders.flesh: コンテナサイズ最小化のためのベースイメージ再考

FastAPI のアプリケーションを作る

まずはコンテナイメージに焼き込むアプリケーションを作ります。以前の FastAPI 記事では Poetry を使った環境構築を紹介しましたが、ここ数年で Rye、uv と出てきて、今では uv が覇権を取りそうですので、uv で作ってみます。ただ、ツールは変わっても基本的なメンタルモデルはあんまり変わらないですね。早くなんでもいいから標準に入ってほしい。

環境構築からパッケージのインストールまで一気に終わります。

$ mkdir pyapp
$ cd pyapp
$ uv init
$ uv add fastapi --extra standard

とりあえずファイルを作ります。

from fastapi import FastAPI

app = FastAPI()

@app.get("/hello")
async def read_root():
    return {"Hello": "World"}

次のコマンドを実行するとポート番号 8000 で開発モードで起動します。開発モードだとファイル変更を検知して自動再起動します。

uv run fastapi dev

起動するスクリプトとかも自動探索してくれますし、gunicorn で uvicorn ワーカーを使って起動（5 年前にブログに書いたやつ）とか、uvicorn コマンドで起動（FastAPI の本家の日本語訳はまだこれだった）とかではなく、fastapiコマンド一発で裏で uvicorn を使って非同期 IO を活用したモードで立ち上がります。Next.js とかそういうのと近い感触。

本番モードは dev の代わりに run を使います。自動探索ではなく明示的に初期スクリプトを指定したり、ポート番号を与えるのも良いでしょう。こちらの方が明示的になるし検索でひっかかるようになるので長期運用されるものに対してはこうする方が個人的には好きです。

uv run fastapi run main.py --port 8000

ブラウザでアクセスしてみて大丈夫だったら次に進みます。

Docker 化

効率の良い Docker イメージ化にはマルチステージビルドが必要で、キャッシュのマウントやら何やら、というのは一度以上見かけたことがある方は多いでしょう。しかし、Docker の機能追加のおかげで、言語によってはマルチステージビルドは不要になりました。

基本な Python ベースのイメージの作成

docker initコマンドが追加され、よくコンテナと一緒に使われる言語であれば、Dockerfile が自動生成できます。Python もその対象の言語の 1 つですので、特別な要件がなければ書き方に頭を悩ませる必要はありません。以下のDockerfileはこのコマンでほぼ一発で出力したものです。debian-slim ベースなのでサイズはそこそこ小さく、速度や性能は問題ないです。ウィザードの最後のコマンドとポートだけちょっと直したぐらい。

# syntax=docker/dockerfile:1
ARG PYTHON_VERSION=3.13.3
FROM python:${PYTHON_VERSION}-slim AS base
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
WORKDIR /app
ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser
RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=bind,source=requirements.txt,target=requirements.txt \
    python -m pip install -r requirements.txt
USER appuser
COPY main.py main.py
EXPOSE 80
CMD ["fastapi", "run", "main.py", "--port", "80"]

これの実行前には requirements.txt の生成が必要です。uv は良いのですがライブラリ更新のたびに自動で出力してくれるオプションとかあったらなぁ、と画竜点睛感はありますが。

uv pip compile pyproject.toml > requirements.txt

この Dockerfile はマルチステージビルドではありません。新しい bind/cache マウントが入る前は次のような手順でやっていました。 requirements.txt やロックファイル、インストール用のツールはデプロイ用イメージにはいらないのでマルチステージビルドビルドで分離していたわけです。

1. requirements.txt やロックファイルを COPY する
2. インストール用のツールを入れる
3. インストールする(キャッシュが残る)
4. 別のデプロイ用イメージに必要なファイルをコピーする

しかし、この Dockerfile ではこれらが不要となっています。

• python -m pip install: uv を使えば開発用ツールは requirements.txt に入らないので標準ライブラリの範疇で十分
• --mount=type=cache,target=/root/.cache/pip: キャッシュはそもそもイメージに入らない
• --mount=type=bind,source=requirements.txt,target=requirements.txt: インストールだけに必要なファイルだがこれもビルド時にだけ存在し、イメージに入らない

最初から余計なものが入らない工夫をしているため、マルチステージビルド自体が不要です。Go とか Rust とか TypeScript の静的コンパイル言語だったりだとまだまだ必要ですが、そのまま実行するスクリプト言語だとかなりシンプルです。レイヤーキャッシュ芸とか&&でつながりまくったRUNは過去のものに。

RUN のマウント周りの引数、よくわからん、自分で書ける気がしない、と思われるかもしれませんが、心配する必要はありません。pip なり、apt なり、npm なり、ビルドでたくさん中間ファイルを撒き散らすコマンドごとに正解のオプションは調べれば出てきます。定型句です。

Chainguard

以前も紹介した Distroless は Google のプロダクトですが、それをメインのビジネスとしているのがChainguardです。無料だと latest のみが選べ、有償サービスに入るとバージョン固定ができる、という感じのようです。Chainguard ベースのイメージも Distroless 同様にシェルがないのでセキュリティに穴があってもそもそも稼働中のコンテナの中で悪さができない（ログインできない）から強い（アタックサーフェースが狭い）、というのが理屈です。なお、Python の標準ライブラリも、攻撃の足掛かりにされるようなビルドしたりインストールするためのものは省かれています。そのためpython -m pipでインストールを行った標準的なやり方はでず、必然的にマルチステージビルドが必要になります。

Distroless は debug にするとシェル入りになる以外の選択肢がなく、イメージ作成には Debian ベースの標準の Python イメージを使いましたが、Chainguard はシェルなしの latest と、開発ツールやシェル、pip モジュールなどの開発用の標準ライブラリも揃っている latest-dev の 2 つがあり、どちらも Chainguard で揃えられます。なお、Chainguard の OS は Debian ではなく、Wolfiというもので、これも Chainguard がメンテナンスしています。apk コマンドがあるので Alipne 系な雰囲気ですが、musl ではなく readelf で見てみると libc を使ってそうなところも Python 的には良いですね。

Chainguard の° ドキュメントを見ると、venv を持ってきてそれを使っています。以前のエントリーでは Distroless はシェルがないので venv を使う方式は避けて無理やり site-packages に入れる方針でやりましたがバージョン番号固定の Dockerfile になってしまうのでこちらの方が良いですね。

# syntax=docker/dockerfile:1

# ビルド用イメージ
FROM cgr.dev/chainguard/python:latest-dev AS builder
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
WORKDIR /opt/app
RUN python -m venv /opt/app/venv
RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=bind,source=requirements.txt,target=requirements.txt \
    /opt/app/venv/bin/pip install -r requirements.txt

# 実行用イメージ
FROM cgr.dev/chainguard/python:latest AS runner
WORKDIR /opt/app
ENV PYTHONUNBUFFERED=1
ENV PATH="/venv/bin:$PATH"
COPY --from=builder /opt/app/venv /venv
COPY main.py /opt/app/main.py
EXPOSE 80
ENTRYPOINT ["python", "/venv/bin/fastapi", "run", "main.py", "--port", "80"]

Chainguard のドキュメントだと古い COPY と RUN を組み合わせた書き方になっていますが、マルチステージビルドであったとしても、cache/bind マウントを活用する方がキャッシュ効率を上げつつ、キャッシュのために余計なパズルを組み立てる必要はないというメリットは得られます。

Distroless

前回書いた Distroless のイメージ作成方法は site-packages を丸ごと持ってくるちょっと無理やりな方法で実現していました。Chainguard のやり方がスマートだったので、それと同様の venv を使った方式でやってみます。

なお、前回書き忘れましたが、:debug付きイメージはエントリポイントとしてシェル(busybox)を起動できます。Distroless の Python イメージは、本来シェルが指定される ENTRYPOINT に Python インタプリタが指定されているのでシェルを起動する場合はイメージ名の後ろにコマンドを書いてもダメで、--entrypoint引数でシェルを渡す必要があります。

docker run --rm -it --entrypoint=sh gcr.io/distroless/python3-debian12:debug

# syntax=docker/dockerfile:1

ARG PYTHON_VERSION=3.11.2
ARG DISTROLESS=python3-debian12

# ビルド用イメージ
FROM python:${PYTHON_VERSION}-slim AS builder
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
WORKDIR /app
RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=bind,source=requirements.txt,target=requirements.txt \
    python -m pip install -r requirements.txt
# debianとdistrolessでPythonのフォルダが違うのでvenvの中のシンボリックリンクを修正
RUN rm /opt/app/venv/bin/python
RUN ln -s /usr/bin/python /opt/app/venv/bin/python

# 実行用イメージ
FROM gcr.io/distroless/${DISTROLESS}:debug AS runner
WORKDIR /opt/app
ENV PYTHONUNBUFFERED=1
ENV PATH="/venv/bin:$PATH"
COPY --from=builder /opt/app/venv /venv
COPY main.py /opt/app/main.py
EXPOSE 80
ENTRYPOINT ["python", "/venv/bin/fastapi", "run", "main.py", "--port", "80"]

Chainguard と違ってビルド用イメージと実行用イメージが違う関係で Python のパスが違っており、それにより venv フォルダ(中で Python インタプリタへのシンボリックリンクを持っている)をそのまま持ってきてもうまくいきませんのでちょっとリンクを貼り直す行が必要です。おかげで venv に詳しくなりました。

• えんでぃの技術ブログ: venv が動作する仕組みを調べてみた

まとめ

Docker の更新そのものは追っかけてましたが、それにより Python のイメージの作成がどう変わったのかというのは把握できていなかったので「なぜそうなっているのか」「今の時代どうすべきか」を調べながら書いてみました。また、FastAPI 自身もアップデートがあり、実行方法が簡単になっていた（簡単になりすぎて不安になった）ので、それも盛り込んでみました。

春の入門祭り2025の22本目の記事です。

はじめに

はじめまして、公共サービス事業部の星と申します。2023年10月に新卒入社、翌年1月から約1年間、前所属の事業部でシステムの保守運用業務を担当しました。

この記事は、私の業務経験をもとにしており、まだ保守運用の経験がない方や始めたばかりの方向けです。

システムの保守運用とは

一般的に「保守」と「運用」は別物で、それぞれ具体的に何をするのか簡潔に説明すると以下でしょうか。

• 保守：機能の改修を含む活動
• 運用：安定稼働させるための活動（定型、非定型）

より具体的には、私の場合ですと監視やデータパッチ等の定常作業を実施しつつ、エラーが発生した時の原因調査および復旧や、想定外の挙動を発見した時の改修なども実施していました。

私は特定の顧客向けのシステムを担当していたので、上記に加えて顧客の要望に応じた機能追加やデータ調査等も行っていました。

キャッチアップにおける工夫

私のように保守運用フェーズの途中から配属された場合、当然ですが配属当初からシステムは完成しており既に稼働していることになります。今まで触れたことや聞いたことすらない技術が数多く使われていました。さらに、技術面に加えて顧客の業務背景なども勉強する必要があります。

学ばないといけないことが多いですが、なるべく早くキャッチアップするために意識していたこと、実践していたことを書きたいと思います。

一般の知識か内部の知識か

今学ぼうとしていることは「インターネットで検索したら多数の記事がヒットする」ような広く知れ渡っているものなのか、それとも「プロジェクト内のドキュメントにしか記載がない」ような内部の人しか知らないものなのか。この違いを常に意識していました。

前者であれば、時間をかけてでも納得いくまで調べることが多くありました。様々な記事を読んだり、ひたすらAIに質問したりしていました。特にAIへの質問は、どんなに初歩的な内容でも気軽にできるのでおすすめです。AIからの回答が正しそうか調査し、新たに生まれた疑問をまたAIに聞いてみる、というサイクルが効果的でした。

一方で後者の場合は、自分で調べるだけでは限界がありますし、AIに聞くわけにもいきません。ある程度調べても解決しないものは躊躇せず先輩方に質問していました。そのためにも、やはり素早くプロジェクトに溶け込んで周囲と良い関係を構築するのは重要なことです。以下の記事で紹介されている工夫が興味深かったです。

• チームを異動で環境が変わった後の立ち上がりについて

保守運用業務に限る話ではないですが、両者の違いを意識すると効率的なキャッチアップができるのではないかと思います。

データを見る

保守運用担当者に対してどこまでデータベースにアクセスする権限が与えられているかはプロジェクトにもよると思いますが、許されている範囲で実際のデータを積極的に見ると良いと思います。

データを見ている中で「このテーブルのこのカラムにはそういう意味があるのか」「このカラムにはこういったイレギュラーなデータが入ることもあるのか」というような発見が多くあり、顧客業務の理解にも繋がっていました。

障害発生時の対応

私が配属された時点ではシステム全体が安定稼働していましたが、それでも稀にメインシステムがエラーで落ちてしまうことがありました。

顧客業務に大きな影響があることは理解していたので、発見次第すぐに周囲に伝えることを徹底していました。先輩方の動きを見て対応を少しずつ学んでいきましたが、自分では原因の特定が困難だったと感じる場面もあり、やはり障害を発見した際はまず共有することが大事だと感じました。

システム障害対応の心構えと対応 にもあるように、障害発生時は初動が重要だということを身をもって実感しました。

注意すべき点

特に特定の顧客向けに作られたシステムの場合、顧客業務の事情がソースコードに反映されていることがあるという点は気を付けるべきだと感じました。

例えば、ある機能の改修を担当することになり該当するソースコードを読んでいると、以下のような疑問を抱く場面があるかもしれません。

• なぜこのような “不自然な” 処理順序になっているのか？
• この処理はもっと簡潔に記述できるのでは？

そうした場合に改善の余地ありとすぐに断定するのは危険です。不自然あるいは冗長に見える実装がされているのは、顧客の業務上発生しうるイレギュラーなケースに耐えるためかもしれません。もちろん実際に改善できる場合もあると思いますが、まずは周囲に確認することが大切です。

おわりに

私の業務経験をもとに、保守運用について共有したいと感じたポイントを書きました。

技術的な話はできませんでしたが、少しでも保守運用業務のイメージがわいたり、参考になる部分があれば幸いです。

はじめに

こんにちは。TIG（Technology Innovation Group）の長谷川です。2025年11月にWeb系企業からの転職でキャリア入社し、現在は主にフロントエンド開発を担当しています。

新しいプロジェクトで支給されたのはPCはWindows。大学入学以降、約10年間MacBookを使い続けてきた私にとっては、高校生以来となるWindowsとの再会です。

私物のマシンはMacBookのUS配列である一方で、支給PCはWindowsのJIS配列。

この差がなかなかにつらく、正直、チャットすら満足にできない状態でした（入社して一番苦戦したポイントかもしれません…w）。

そこで、Windowsを徹底的にMacBookに近づけ、快適な作業環境を構築することにしました。そのプロセスを詳しく紹介します。

「Mac派だけど諸事情でWindowsに触れることになった」方はもちろん 「元々Windowsユーザだけど便利な設定を知りたい」という方にも役立つ内容となっていますので、ぜひ最後までご覧ください。

前提

MacユーザーがWindows環境で快適に作業するためのアプローチは、以下の3つに大別できます。

• A. Windowsに慣れる
• B. 双方で統一的に使える環境を整える
• C. WindowsをMacに寄せる

今回は Cの「WindowsをMacに寄せる」方針 で進めています。

なお、使用するOSはWindows 11です。

目指す使用感

普段のMacBook使用スタイルは非常にシンプルで、「内蔵のキーボードとトラックパッドのみを使う」派です。BetterTouchTool（以下BTT）でジェスチャーを割り当て、さまざまな操作を実現しています。

MacBookの使い方から離れないために、Windowsをカスタマイズをしていく上でのポリシーを以下とします。

• マウスは使用しない
• キーボードは持ち運ばない

最初は外付けキーボード自体を使わないつもりでしたが、現在はリモートワークの際には分割キーボードを利用しています。

トラックパッド

最初に取り組むのは、トラックパッドのつらさへの対処です。

トラックパッドにおける課題はクリックの重さ。これはWindowsでもデバイスによると思いますが、支給PCのデバイスはクリック時に必要な力が少し大きく若干ストレスでした。

自宅にMagic Trackpadがあったため、Windowsでも利用できるか調査したところ、問題なく使えそう。導入方法については以下の記事を参考にさせていただきました。とくに複雑な設定は不要で簡単に利用できます。

cf. Windows 11 で Apple Magic Trackpad を快適に使う方法

これでまずはトラックパッドがMacに近づきました🎉

Windowsの設定をMac風に

Magic Trackpadの導入により、カーソルの操作性が向上しました。

キーボードを改善する前に、各種設定を調整してMacに近い使用感を目指します。

以下に主な設定を記載しています。

• Bluetoothとデバイス > タッチパッド
  • カーソル速度: 10
    • カーソルは速さが正義💨
  • タップ
    • タッチパッドの感度: 低い感度
    • 1本の指でタップしてシングルクリックする: ON
    • 2本の指でタップして右クリックする: ON
    • 2回タップしてドラッグすると複数選択: OFF（誤動作することが多かったので）
    • 右クリックするにはタッチパッドの右下を押します: OFF
  • スクロールとズーム
    • 2本の指をドラッグしてスクロールする: ON
    • スクロール方向: ダウンモーションで上にスクロール
    • ピンチ操作によるズーム: ON
  • ジェスチャ
    • 3本指ジェスチャ
      • タップ: マウスの中央ボタン（リンクを開くときに新規タブで開いたり便利です）
      • 上方向にスワイブ: デスクトップの表示
      • 下方向にスワイブ: カスタムショートカット（Ctrl + W）（タブを閉じる）
      • 左方向にスワイブ: カスタムショートカット（Ctrl + Page Up）（前のタブに移動）
      • 右方向にスワイブ: カスタムショートカット（Ctrl + Page Down）（次のタブに移動）
    • 4本指ジェスチャ
      • タップ: 通知センター
      • 上方向にスワイブ: タスクビュー
      • 下方向にスワイブ: カスタムショートカット（Ctrl + Shift + T）（閉じたタブを復元）
      • 左方向にスワイブ: デスクトップを切り替える
      • 右方向にスワイブ: デスクトップを切り替える
    • MacではBTTを使って色々とジェスチャーを登録しています
    • BTTほど柔軟ではありませんが、Windows公式の機能でそれなりに柔軟に対応できるのは嬉しい
• システム＞クリップボード
  • クリップボードの履歴 をONに
  • MacだとBTTでクリップボード管理しています
• システム > マルチタスク
  • ウィンドウのスナップ: ON
    • ウィンドウをスナップしたときに、次にスナップする対象を提案する: OFF
    • ウィンドウの最大化ボタンにカーソルを合わせたときにスナップレイアウトを表示する: ON
    • ウィンドウを画面の上部にドラッグしたときにスナップレイアウトを表示する: OFF
    • タスクビューのタスクバーアプリ上にマウスカーソルを移動したとき、そしてAlt+Tabを押したときに、スナップしたウィンドウを表示する: ON
    • ウィンドウをドラッグしたときに、画面の端までドラッグしなくてもウィンドウをスナップできるようにする: ON
  • スナップまたはAlt+Tabを押したときにアプリのタブを表示する: （最新の3つのタブ）
  • デスクトップ
    • タスクバーに開いているすべてのウィンドウを表示: すべてのデスクトップで
    • Alt+Tabを押したときに、開いているすべてのウィンドウを表示: 使用中のデスクトップでのみ
    • 💡Windowsの仮想デスクトップ使いづらいと感じていましたが、この設定をすることでMacと似た感じで使えるようになりました
  • タイトルバーウィンドウのシェイク: OFF
• アカウント > サインインオプション > 追加の設定
  • 再起動可能なアプリを自動的に保存し、再度サインインした時に再起動する: ON（再起動前に開いていたアプリを再起動してくれる）
    • Macほどすべてが復元されるわけではなさそう
• 個人用設定 > タスクバー
  • 検索: 検索ボックス
  • ウィジェット: OFF
• 個人用設定 > テーマ >デスクトップ アイコンの設定
  • ゴミ箱をデスクトップから非表示に
  • 何もないデスクトップは至高
• Google IME
  • ことえりのショートカットを選択
    • ことえりのライブ変換のような機能はなさそうでした・・・
  • 後述するAutoHotKeyを使わない場合の英数/かなの切り替えはGoogle日本語入力の機能で対応できそう
    • cf. Google日本語入力で無変換キーでIMEをオン/オフする - 日記とか、工作記録とか

キーボードの調整

US配列（Mac）とJIS配列（Windows）の差によるキーボードの課題は以下の3つ。

• 記号等の配置の違い
• 修飾キーの意味や使い方、配置の違い
• ショートカットキーの組み合わせの違い

最初はJIS配列のWindowsキーボードに慣れようとしたものの、Macの操作感からのギャップが大きく断念しました。
また、仮に慣れたとしても、今度はMacが使いづらくなってしまう。

そこでMac風の操作に近づける方向でキーボードを調整することとしました。

（Macの場合は大抵 command + ⚪︎ ですが、Windowsは操作によってWindows Alt Ctrl を使い分ける印象がありますね。思想の違いがありそう。）

Change Key の活用

キーボード配列はそれぞれ以下のようになっています。

• MacBookのUS配列
  • fn・control・option・command・スペースバー・command・option
• WindowsのJIS配列
  • ctrl・fn・win・alt・無変換・スペースバー・変換・カタカナ・Copilot

このように並びが全然違っており、左手側を見ると、似た機能を持つことが多いcommand(Mac)とctrl(Windows)の位置が反対にあります。とくに使うことが多いコピペの配置が全く違うのでこれはかなり困りました。

そこで今回はChange Keyというソフトで配列を以下のように変更します。

• 無変換 → Ctrl左
• 変換 → Ctrl右
• カタカナ・ひらがな → Alt右

これでMacと似た感覚でコピペできるようになりました🎉

📝参考記事：

• Mac 慣れした私に Windows が支給されたので、まず設定したこと | フューチャー技術ブログ
• 【Change Key】キーボードの割り当てを変更するソフトの使い方 | ナポリタン寿司のPC日記

ULE4JIS でUS配列風に

JIS配列を完全にUS配列で上書きするとたまに不都合があるため、ULE4JIS を導入し、必要に応じてON/OFFを切り替える方式を採用しました。スタートアップに登録して運用しています。

なお、Google Docsのショートカットに一部不具合がある等、少しバグがある(?)点には注意が必要です。
（箇条書きのショートカットは本来Ctrl + Shift + 8 だが Ctrl + Shift + 9 になってしまう）

今だとこちらを利用させてもらってもいいかも。

• USkey2JP - Musashino Software

📝参考記事：

• ノートパソコンはJIS配列で外付けキーボードをUS配列に（Windows）
• Windows11のスタートアップを設定する方法 - mouse LABO

AutoHotKey による魔改造

Change KeyとULE4JISのおかげで普通にタイピングできるようにはなりました。

しかし、Macで染み付いたショートカットはWindowsで利用できません。

そこで、AutoHotKeyを使ってMacの操作感を再現しました。

具体例：

• ctrl(無変換/変換)単押しによるIME切替（左単押しで英数、右単押しでかな）
• Mac風のウィンドウ操作やショートカット
• 各種アプリ（Chrome・Excel・Slack）でのカスタム対応

コメント付きのコードを以下に添付するのでご参照ください。

main.ahk をスタートアップに登録しておくと快適です。

main.ahk

#Requires AutoHotkey v2.0

#Include ./lib/IMEv2.ahk
#Include ./utils.ahk
#Include ./applications.ahk
#Include ./configs.ahk

#SingleInstance Force

; main.ahk を再起動
^!.:: {
    MsgBox("Rerun main.ahk")
    Reload()
}

;=============================================
; キーボードの Remap
;---------------------------------------------
; Alt 単押しでカーソルのフォーカスが外れるのを防ぐ
~LAlt:: Send "{Blind}{vk07}"
~RAlt:: Send "{Blind}{vk07}"

; Copilot ボタンを無効化
#+F23:: Send "{Blind}{vk07}"

; Win + Alt + Ctrl + BackSpace で Delete
#!^BackSpace::Delete
;=============================================
; macOS 風キーバインド
; cf. <https://jimon.info/macos-like-windows#単語単位カーソル移動を再現>
; --------------------------------------------
; cmd+矢印 の挙動を再現
^Left::Home ; Mac の「cmd + ←」風
^Right::End ; Mac の「cmd + →」風
^Up::^Home ; Mac の「cmd + ↑」風
^Down::^End ; Mac の「cmd + ↓」風

; Option+左右 の挙動を再現
!Left:: SendInput "^{Left}" ; Mac の「option + ←」風
!Right:: SendInput "^{Right}" ; Mac の「option + →」風
+!Left:: SendInput "^+{Left}" ; Mac の「option + shift + ←」風
+!Right:: SendInput "^+{Right}" ; Mac の「option + shift + →」風

; Mac の control + j,k,l,; が Windows では win + j,k,l,; になるので、macと同じ位置で使えるようにする
#j::^j
#k::^k
; win + l は画面ロック機能で上書きできない
; #l::^l
#;:: Send "{F10}"

; Mac の cmd + tab 的に使えるように変更
; cmd + shift ではうまくいかなかったので caps lock で代用
LCtrl & Tab::AltTab
LCtrl & sc03A::ShiftAltTab ; sc03A=caps lock

; 削除系
!Backspace:: Send "{LCtrl Down}{Backspace}{LCtrl Up}" ; 単語削除
^Backspace:: Send "{LShift Down}{Home Down}{Backspace}{Home Up}{LShift Up}" ; 行頭まで削除
;=============================================
; IME や Ule4Jis など文字入力関連の設定
;---------------------------------------------
~LCtrl:: Send "{Blind}{vk07}"
~RCtrl:: Send "{Blind}{vk07}"

; 左 Ctrl 単押しで IME を OFF
~LCtrl Up:: {
    if (A_Priorkey != "LControl") {
        return
    }
    IME_SET(0)
}

; 右 Ctrl 単押しで IME を ON
~RCtrl Up:: {
    if (A_Priorkey != "RControl") {
        return
    }
    IME_SET(1)
}

; caps lock の２連打で Ule4Jis の有効/無効を切り替える
~sc03A:: {
    ; REF: <https://ahkscript.github.io/ja/docs/v2/FAQ.htm#DoublePress>
    if (ThisHotkey != A_PriorHotkey || A_TimeSincePriorHotkey > 200) {
        return
    }

    if (Utils.isActiveWindow(Configs.windowTitles.ule4Jis)) {
        WinClose(Configs.windowTitles.ule4Jis)
        MsgBox ("ULE4JIS を終了しました")
        return
    }
    Run(Configs.paths.ule4Jis)
}
; ============================================
; window 操作関連
; FancyZones の設定も必要
; Mac では BetterTouchTool で行っている設定
; --------------------------------------------
; ウィンドウを最大化
^!,:: WinMaximize("A")
; ウィンドウを最大化してから、次のディスプレイに移動
^!m:: {
    WinMaximize("A")

    Send("{LWin Down}")
    Send("+{Right}")
    Send("{LWin Up}")
}

; ウィンドウを FancyZones 上の左に移動
^!j:: {
    Send("{LWin Down}")
    Send("{Left}")
    Send("{LWin Up}")
}
; ウィンドウを FancyZones 上の右に移動
^!k:: {
    Send("{LWin Down}")
    Send("{Right}")
    Send("{LWin Up}")
}
; ============================================
; アプリの終了や最小化関連の操作
; --------------------------------------------
; Mac では cmd + Q でアプリの終了
^q:: WinClose("A")

; Mac では cmd + h で非表示、 cmd + m で最小化
; Windows では 非表示出来ないので最小化のみ
; 最小化したウィンドウを復元するために配列に格納しておく
minimizedWindows := []
^h::
^m:: {
    activeWindow := WinActive("A")
    WinMinimize(activeWindow)
    minimizedWindows.Push(activeWindow)
}
^+h::
^+m:: {
    if minimizedWindows.Length <= 0 {
        MsgBox "最小化されたウィンドウがありません。"
        return
    }
    lastMinimizedWindow := minimizedWindows.Pop()

    ; もしウィンドウが最小化状態であれば復元
    if WinGetMinMax(lastMinimizedWindow) == -1 {
        WinRestore(lastMinimizedWindow)
    }
}

applications.ahk

#Requires AutoHotkey v2.0

#Include utils.ahk
; ============================================
; Chrome 専用
; --------------------------------------------
#HotIf WinActive("ahk_exe chrome.exe")

; alt + ctrl + i で開発者ツール
^!i::+^i

#HotIf
; ============================================
; Excel 専用
; --------------------------------------------
#HotIf WinActive("ahk_exe EXCEL.EXE")

; Shift + Enter でセルを編集する
+Enter::F2

; Ctrl + Enter で改行する
^Enter::!Enter

; Ctrl + Shift + z でやり直す
^+z::^y

; alt の２連打でコンテキストメニューを表示する
~LAlt:: {
    ; REF: https://ahkscript.github.io/ja/docs/v2/FAQ.htm#DoublePress
    if (A_ThisHotkey != A_PriorHotkey || A_TimeSincePriorHotkey > 200) {
        return
    }

    Send "{Shift Down}{F10}{Shift Up}"
}

#HotIf
; ============================================
; Slack 専用
; --------------------------------------------
#HotIf WinActive("ahk_exe slack.EXE")

; ctrl + [ で go back
^sc01A::!Left
; ctrl + ] で go forward
^sc02b::!Right

#HotIf
; ============================================
; VSCode 専用
; --------------------------------------------
#HotIf WinActive("ahk_exe Code.exe")

; ctrl + [ で go back
^sc01A::!Left
; ctrl + ] で go forward
^sc02b::!Right

#HotIf

utils.ahk

#Requires AutoHotkey v2.0

#SingleInstance Force

class Utils {
    static isActiveWindow(windowTitle) {
        DetectHiddenWindows(true)
        window := WinExist(windowTitle)
        if (window > 0) {
            return true
        }
        return false
    }
}

configs.ahk

#Requires AutoHotkey v2.0

class Configs {
    static windowTitles := {
        ule4Jis: "ahk_exe Ule4Jis.exe",
    }
    static paths := {
        ule4Jis: "C:\\Path\\To\\Ule4Jis.exe", ; ← 実際のパスをここに記入してください
    }
}

lib/IMEv2.ahk

https://github.com/k-ayaki/IMEv2.ahk/blob/master/IMEv2.ahk を利用させていただきました。

各種ツール

その他導入した便利なツールを紹介します。

• QL-Win/QuickLook: Bring macOS “Quick Look” feature to Windows
  • MacのQuickLook的なもの
  • 毎回ファイルを開かなくて良くなる（動作は少し遅いかも）
• Power Toys
  • Microsoftが出しているユーティリティセット
  • Power Toys Run
    • Macでいうspotlight検索
      • MacではRaycastを利用しています
      • Windowsにもいつか来るかも → Raycast for Windows
    • EveryThingのプラグインも導入
      • lin-ycv/EverythingPowerToys: Everything search plugin for PowerToys Run
    • Windowsで他に使えそうなランチャーアプリ
      • Ueli - A Cross-Platform Keystroke Launcher
        • おしゃれで良さそう
  • FancyZones(Power Toys)の設定
    • 左1/3と右2/3でゾーンを作成して使用
    • MacではRaycastでの「First Third と Last Two Thirds」や「BTTのスナップエリア」を利用
  • 他にもColor Pickerなど色々あるので必要なものを有効化して利用
  • 参考たサイト
    • PowerToys のインストール | Microsoft Learn
    • 情シスがPowerToys全機能をさわってみたよ
• Clibor | クリップボード履歴ソフト「Clibor」の公式サイト
  • クリップボードアプリ
    • MacではBTTのクリップボードを利用
  • CliborだけでなくWindows公式のクリップボードの履歴も併用
    • Cliborではリッチテキストや画像の履歴を保持できないため
      • 「設定 > システム > クリップボード」でクリップボードの履歴をONにすると使えます
    • Power ToysにAdvanced Pasteというのもあるのでそちらを利用する手も
  • 設定内容
    • 画面表示制御
      • 画面表示時に1行目にフォーカスを移すを ON に
    • ホットキー
      • メイン画面の呼び出し: Win + Ctrl + Alt + J
        • AutoHotKeyが動いているとうまく設定できない場合があるので、その場合一時停止させる（設定後はAutoHotKeyを戻しても動作する）
      • MacではBetterTouchToolのクリップボードツールを Ctrl + Option + command + J で開く
        • 最初はcommand + Shift + V にしていたが、Google Docsのショートカットなどと被るため、絶対に使わないキーに
    • Cliborもスタートアップへ登録すると快適
• CubeICE
  • Macであればダブルクリックでよしなにやってくれるが、Windowsは右クリックから展開しないといけない？
  • 設定を以下のようにすることでMacと同じ操作感に
    • 保存場所: 元のファイルと同じフォルダ
    • 解凍後に保存先フォルダを開く: OFF
  • zipのデフォルトアプリをCubeICEに設定する
• VS Code
  • Scroll Sensitivityを3にする（Editor, Workbenchの両方）
    • デフォルトだとトラックパッドでのスクロールが遅いため

おわりに

今回紹介した設定やツールを駆使することで、WindowsをMacのように扱えるようになりました。

Windowsを使い始めて半年が経ちますが、業務終了後や休日にMacで違和感なく作業ができています。

最初はWindows自体と戦っていましたが、今ではWindowsで戦えるようになりました🔥
快適な環境になりとてもハッピーです。

みなさんも良いWindowsライフを！🍎

おまけ：Macに導入したWindows的ツール

最後に、逆にMacに導入した便利ツールもご紹介。

• AltTab

普段Macでは、エディタやターミナルを各リポジトリごとに仮想デスクトップに割り当てています。これは使いやすく便利なのですが、command + tabでのアプリ切り替え時に「同じアプリだけど別のウィンドウ」に遷移してしまうことが多く、手間に感じていました。

AltTabを導入することで、1つ前のウィンドウを確実に開いたり、同じアプリ内でもウィンドウを選択できるようになり、かなり快適になりました🎉

はじめに

製造エネルギー事業部の後藤です。

初めてシステムの運用引き継ぎを経験しました。その中で得た知見や工夫した点を、「春の入門祭り2025」にあわせて共有します。

システムの運用を引き継ぐ立場の方はもちろん、日常的にシステム開発に携わっている方にも、参考になる点があれば幸いです。

1. システム運用引き継ぎとは？

通常システムは何かしらの目的を果たすために作られ稼働しているはずです。大前提としてシステムが何のために作られ、何を実現することが期待されているのかを理解しておく必要があります。

その目的を達成するために、引き継ぎを行った後でも、滞りなくシステムが運用される必要があります。そのためにも最低限「定常作業対応」「非定常作業対応」、「障害対応」を行える必要があります。

できる限り作業を自動化して「定常作業対応」「非定常作業対応」を減らしていくことは重要ですが、費用対効果の観点から難しい部分があるのも現実です。またどんなに良いプログラムを書いても、連携先のシステムのエラーやネットワークのエラーなど、どうしても障害対応に人の手が必要な場合があります。

システムを一度作って、そこで終わりでないケースがほとんどだと思います。利用しているライブラリなどにセキュリティの問題があればアップデートや修正が必要ですし、さらに高い目標の達成のためにシステムを改善したいという気持ちが湧いてくるのも自然でしょう。

詳細な手順書を用意すれば、ある程度の作業を任せられるようにはなりますが、未知の障害にぶつかった時、機能改修や機能追加を行う時には背景や全体像をしっかり理解していないと歯が立ちません。

運用引き継ぎを行う際に準備しておくべきこと、引き継ぎ手順、工夫した点、注意事項などをお伝えできればと思います。

2. 引き継ぎ概要

どんなシステムをどのくらいの期間でどんな手順で引き継いだのか概要をまとめています。

• 引き継ぎ手順
  • キックオフ&概要説明
  • 環境構築説明
  • システム全体像説明
  • IF連携説明
  • 定常作業説明&非定常作業説明
  • 障害対応手順説明
  • 定例会議資料作成＆ファシリテーション引き継ぎ
  • コードリーティング&ハンズオン
  • タスク引き継ぎ
  • 課題&その他共有

3. ドキュメント化の重要性

運用引き継ぎで何が重要かと問われれば「丁寧なドキュメント整備」と即答します。知りたい情報がドキュメントにまとまっていれば、時間がかかっても業務を進めることができます。

運用引き継ぎのためだけにドキュメントを書くのではなく、日頃から丁寧に整備する意識を持ち、チームで徹底することが重要です。急ぎの作業の時にソースコードさえ修正されていればいいと考える人もいると思いますが、実装の背景や経緯を記載していないと後々調査に時間がかかったり、誰も手がつけられないコードが増えてしまい、開発効率やサービスの質を落とすことにも繋がってしまいます。

ドキュメントの徹底的な整備は正直なところ辛い部分もありますが、結果的に自分たちの助けにもなります。私のチームではソースコードを変更した際には必ずレビュアーが設計書などのドキュメントが修正されたかを確認してPRをApproveするようにしていました。またドキュメントに不備があった場合には積極的に修正するなどチーム内での文化の形成が重要です。当たり前のことをしっかりやることがとても大切です。リンターやAIなど便利なツールも沢山あるので、なるべく楽をしつつドキュメントを整備していけるといいと思います。

ドキュメント管理

私のチームでは設計書や開発者向けの情報はGitHubのドキュメントフォルダ配下にまとめていました。参考までに下記のようにドキュメントをまとめていました。

ドキュメント/
├── 01_システム設計/
├── 02_インフラ設計/
├── 03_フロントエンド設計/
├── 04_フロントエンドアプリ利用ガイド/
├── 05_IF仕様書/
├── 06_データモデル/
├── 07_API設計書/
├── 08_ジョブ設計書/
├── 09_帳票一覧/
├── 10_定型運用/
├── 11_非定型運用/
├── 12_障害対応/
├── 13_リリース対応/
├── 14_開発規約/
└── 15_環境構築/

4. 引き継ぎ手順

実際にどのような順序で引き継ぎを行っていったかと工夫した点を説明していきます。大まかな流れは引き継ぎ概要に書いた通りです。

4.1. キックオフ&概要説明

実施事項

• メンバーの自己紹介
• 会議帯の設定
• 各種ツール準備
  • GitHubリポジトリ招待
  • AWSアカウント発行
  • チャットツール招待（Slack, Google Chatなど）
  • チケット管理ツール招待（Backlog、Jiraなど）
  • ストレージサービス招待（Google Driveなど）
• システムの概要の説明

ポイント

• 利用するツールやチャンネル一覧情報はGitHubのトップページに集約
• ツール準備はできるだけ早い段階で実施
• 基本的にドキュメントはGitHubに集約するが、特に重要な箇所や、困った時に参照すべき場所を伝えるため、簡単なスライドも用意

4.2. 環境構築説明

実施事項

• 環境構築手順の説明（どのドキュメントを見ればいいか）
• 環境構築のサポート

ポイント

• 環境構築が終了しないと改修タスクの依頼ができないため優先
• GitHubに環境構築用のページを用意
• コンテナやMakefileなどを利用して同じ環境を短時間で構築
• 環境構築の概要の説明をしたら基本はドキュメントに従って実行。サポートが必要な場合は会議を実施
• プロキシが存在する場合、その関係で詰まるケース多いので早い時期から対応

4.3. システム全体像説明

実施事項

• システム概要図説明
  • データの発生源や流れを意識して説明
• システム概念図説明
  • どのような関連システムがありどのような種類のデータを何のためにやり取りしているか大枠を説明
• データモデル説明
  • DB定義などどのようなデータを扱っていて、どのように関連しているのか説明。ER図なども有効
• 特に重要な処理の説明
  • システムで一番重要なデータや業務影響が大きい処理から説明

ポイント

• システム構成図の準備
  • 全てのJobやサービスを記載できると良い。大枠の構成図を１つ作成して詳細部分は複数に分けるのもあり
  • draw.ioでの作成がおすすめ（.drawio.png形式でマークダウンページに埋め込む）
• システム概念図
  • IF連携しているシステムを全て記載
  • 全てのやり取りを詳細に記載できなくても良いので、どんな情報を何のために連携するのか記載
• 用語集の準備
  • GitHubのトップページにスプレッドシートのリンクを貼り、スプレッドシートに用語集を作成。不明な用語を書いてもらい解説を記入（まずはリアルタイムでやり取りしやすいスプレッドシートで共有し、後にGitHubへ反映する運用）
• データの発生源から順にデータの流れを説明することで大枠の流れを伝える
• 業務影響が大きい処理を説明する際は、この処理が失敗すると、「○円かかる」「○人の顧客に影響がある」「復旧に○人の作業が必要」など具体的な影響を説明すると伝わりやすい

4.4. IF連携説明

実施事項

• IF仕様書説明
  • IF一覧説明
  • 重要なIF連携説明

ポイント

• 最悪詳細な仕様書がなくてもIF一覧は用意
  • API連携がある場合、どのエンドポイントをどのシステムが利用しているかまとめられるとなお良い
• システム改修時の影響範囲調査の際に利用するのでIF仕様の整理はしっかりと行う

（IF一覧例）

• 受信

  機能ID	機能名	連携システム	形式	頻度	日時	未着チェック	冪等	Path Prefix	説明
  IF_IN_01	A受信	Aシステム	S3	日次	0:00	○	○	prod-xxx-bucket/
  IF_IN_02	B受信	Bシステム	Kinesis	随時	-	-	○	prod-xxx-kinesis

• 配信

  機能ID	機能名	連携システム	形式	頻度	日時	Path Prefix	説明
  IF_OUT_01	X配信	Xシステム	S3	日次	0:00	prod-system-x-bucket/

4.5. 定常作業説明&非定常作業説明

実施事項

• 定常作業説明&実行
• 非定常作業説明&実行

ポイント

• 引き継ぎ前に可能な限り作業の自動化や簡略化を行う
• 作業一覧と作業手順書をGitHubに作成
• できるだけはない段階で引き継ぎ先に実行して慣れてもらう
• 説明会の内容を録画してGitHubにリンクを貼るのがおすすめ

4.6. 障害対応手順説明

実施事項

• 監視設計説明
• 障害発生時対応方法説明

ポイント

• 障害が発生した際にどのように通知されどのような対応が必要なのかを説明
• 最低過去6ヶ月に発生した障害の対応手順書をGitHubに作成する
  • 誰が見ても作業できるように画面のスクリーンショットを付ける
  • 引き継ぎ先に内容をレビューしてもらい作業が誰でもできる状態を一緒に目指す
• 可能であればJobエラーアクションリストを作成し全てのJobの全てのエラーを一覧化する
  • スプレッドシートを作成してGitHubにリンクを貼る
  • 全ての対応手順を作成するの難しいので全てを埋める必要はないが、過去どのように障害対応をしたのかわかるようにBacklogチケットなどのリンクを貼ると良い（普段から記録をしっかりと残すことが重要）
• 障害発生を見逃さぬようにメール送信、Slack通知、担当者設定など工夫が必要
  • 日次で障害の見過ごしがないか時間を取るのもおすすめ

（Jobエラーアクションリスト例）

4.7. 定例会議資料作成＆ファシリテーション引き継ぎ

実施事項

• 定例会議の資料作成法引き継ぎ
• 定例会議への参加
• 会議ファシリテーション引き継ぎ

ポイント

• 定例会議で顧客への報告などがある場合は、どのような資料を用意しているのかを共有する（過去の会議の資料はGoogle Driveなどに集約する）
• いきなり全てを引き継ぐのでなく、まずは会議の参加から部分的なタスクの進捗報告などから徐々に引き継ぐ
• いきなり全てを任せようとすると引き継ぎ先としては辛いので、気持ちに寄り添って伴走する姿勢も重要

4.8. コードリーティング&ハンズオン

実施事項

• システム構成と具体的なソースコードの処理内容を説明
• 開発規約の説明
  • テストの実施方針、コードレビューの方針なども含めて説明
• リリース手順説明&リリース作業

ポイント

• 重要なJobや改修タスクに関連するJobから順にソースコードリーディングを実施
  • なぜその実装をしているのか背景をソースコードにコメントがあると良い。GitHubのIssueのリンクをコメントに貼るのもおすすめ。引き継がれる側からするとコメントが充実している方が安心
• しっかりとした設計思想があると引き継ぎの際にも説明しやすく、すべての指針となるので、設計思想は重要
• リリース作業の引き継ぎは時間をかけて行う
  • リリース作業は引き継ぎ先と一緒に行い徐々に作業を任せていく
  • 週に１度リリース作業をしていたが、念のため毎回引き継ぎ期間にはリリース作業に立ち会った

4.9. タスク引き継ぎ

実施事項

• 機能改修説明
• レビュー
• リリース

ポイント

• できる限り早い段階で機能改修を任せるようにすると、システムへの理解が進む
• GitHubのissueに背景、修正対象のソースコード、対応方法、テスト方法、検証方法などを詳細に記載して、対面でタスクの説明をしてタスクの依頼をする
• 「困ったことがあればいつでも聞いてください」と伝え続けてよい関係性を作る
• 対応手順がわかっているタスクであれば、相手に考えさせるのではなく自分ならどうするかと、なぜそうするのかを説明してタスクを進めてもらう
  • 自分の力で考えてもらうことも時には必要ですが、より良い答えを持っているのであれば、出し惜しみをせずに全て伝えましょう
• ソースコードなどのレビューは手を抜かない
  • いくら不慣れだからといってレビューを甘くしてしまうと、結果的にサービスの質の低下につながってしまうので、しっかりと気になるところは伝えるようにしましょう
  • 大量の指摘事項をもらう側は辛いと思うので、伝え方には注意しましょう

4.10. 課題&その他共有

実施事項

• 課題共有（GitHub Issueにまとめて説明）
  • ユーザーが数倍に増えた時には○○の改修が必要なども説明できると良い
• バージョンアプ対応説明
  • プログラミング言語やツールのバージョンアップの方針の説明

ポイント

• 課題や問題がある場合には包みかくさずに全てを伝える

5. コミュニケーション

最終的にシステムを利用するのも運用していくのも人であり、システムの運用を引き継ぐのも人になるので、コミュニケーションは欠かせません。最後に引き継ぎにおいて特に重要だと思うコミュニケーション面のお話を共有します。

引き継がれる側は他の人が育てた未知のシステムの面倒を見ることになると理解する

システムを引き継ぐ側としては背景や問題点など熟知した身近な存在かもしれませんが、引き継がれる側からするとそうではありません。

引き継がれる側としては、いつ機嫌を悪くして暴れ回るかもわからない、性格も機嫌の取り方もわからない猛獣に見えるかもしれません。暴れ回った責任を育ててもいない自分達が負わなければならないという不安を抱えているかもしれません。

そんな相手の気持ちを理解して、システムの特徴や問題点などを根気よく説明していく必要があります。引き継ぎ元の担当者がしっかりとした人間だと思ってもらえれば、その人が見ているシステムもしっかりしていると思って貰いやすくなるので初めのコミュニケーションは大切です。

相手の中にある不安要素を理解して、それに寄り添いながらコミュニケーションを取っていこうという姿勢がとても大切だと思います。

いつでも情報を共有してもらうように関係性を構築する

円滑に引き継ぎを進めていく上で相手が何を理解できていなかを把握することはとても重要です。物事を理解しないままタスクを進めてしまうと、時間の無駄が発生したり障害を発生させてしまったりマイナスな影響を与える可能性があります。

相手がわからないことがあればすぐに解決できる体制を作ることで、システムへの理解度、タスクの進捗、信頼度を上げることができるので、「わからないことがあればいつでも聞いてください」と引き続き期間中に言い続けていました。困っていそうな時にはこちらから確認して会議を設定したり、チャットで情報共有をすることで、コミュニケーションを円滑に行うことができたと思います。

運用引き継ぎというプロジェクトを成功させるためにお互いに協力してゆくことがとても大切です。

3度説明しただけで理解してもらおうという思いは捨てる

引き継ぎ期間中、「前にも同じ説明を何度かしたな」と思うことが複数回ありました。もちろんドキュメントにも同じ説明を記載していますが、会話ベースで説明した方が伝わりやすいと思うことが多々ありました。

３度同じ説明をしたら理解して欲しいという気持ちはよくわかるのですが、引き継ぎ先としては日々膨大なインプットを行い情報の紐付けと整理に苦労していることを理解する必要があります。

３度同じ説明をしたら理解して欲しいではなく、15回同じ説明を別のアプローチで行いなんとか相手の頭の中に情報を整理してもらおうとする姿勢が大切だと思います。タスクを通して理解を進めるのが一番の近道だとは思いますが、根気よく重要な情報は複数回共有するべきたど思います。関係性ができてきたらクイズ大会を実施するのもいいと思います。

引き継ぎ前と引き継ぎ後で同じパフーマンスが出ないことを理解してもらう

長く引き継ぎの期間を取ったとしても、引き継ぎ後に引き継ぎ前と同じパフォーマンスを出すことは難しいことが多いです。ステークホルダーにはそのことを根気強く説明して理解してもらうことが大切です。

まとめ

システムの運用引き継ぎで学んだことを共有しました。

普段から自動化し、ドキュメントを整備し、情報を集約することで、引き継ぎの有無に関係なく業務を効率化できると思います。有識者が不在な場合や移動になった場合にも、滞りなく業務が進められる必要があるので、今回まとめた内容を参考にしていただければと思います。ドキュメントの整理など当たり前のことをしっかり続けていくことが大切です。辛い部分もあるかもしれませんが結果的に自分達のためになると思います。

またコミュニケーションについてもお話ししましたが、一番大切なのは相手の気持ちを理解しつつゴールに向かって互い協力し合うことが大切だと思います。

最後まで読んでいただきありがとうございました。

こんにちは、村田です。

有志の社員が集まってコードレビューガイドラインを作成、公開したのでご紹介します。

本ガイドラインを読むにあたって

コードレビューガイドラインは、既に公開しているGitブランチフロー規約にて推奨されているブランチ戦略や設定が施されていることを想定して作成されています。

前提条件の章を確認の上で本編をご確認ください。

ガイド作成の背景

みなさんは普段どのよう心構えでレビューをしていますか？

フューチャーでも当然毎日のようにたくさんのコードレビューが実施されているのですが、実際問題としてコードレビューにおける立ち振舞いはチームや人によってマチマチであることが多いです。もちろん世間でもそういうケースは多く散見されるだろうなと思います。

「レビューはコミュニケーションである。コメント記載時には相手への敬意を忘れないこと」

これは今回作成したガイドラインに明記したグラウンドルールです。私が一番好きなパートでもあります。改めて考えてみれば当然なのですが、この当たり前を忘れてしまっているレビューがたまに見受けられるのもまた事実。レビューのキャッチボールにおいて双方の発言や行動をあとほんの少しだけアップデートしてあげればよりスムーズなキャッチボールになるのにな…なんて場面、みなさんも多かれ少なかれ思い当たるのではないでしょうか？

ゆえに今回作成したガイドラインでは、「レビュイー」および「レビュアー」それぞれの立場（役割）において推奨される行動をまとめていくスタイルをとりました。

ちなみに、今回のガイドラインの中ではレビュー観点について網羅的に列挙・記載することは行っていません。開発しているプロダクトの性質・開発体制・採用技術などで観点が大きく変動するためです。

レビュイーとレビュアー双方の「推奨行動」

ここからは少しガイドラインの中身をご紹介します。この記事においては焦点を絞って簡単にかいつまむ形で紹介しますが、ぜひ詳細はガイド本体をご覧いただけると幸いです。

レビュイーの推奨行動

本章における記載はマインド面よりも実務的な内容が多いです。つまり読んだ直後から実践可能な内容が多く含まれています。

プルリクエストの単位を小さくする

レビュアーの負荷を必要以上に高くしてしまう行動のひとつに「複数の改修内容を単一のプルリクエストに含む」ことが挙げられます。

あくまでプルリクエストは小さく保つように心がけましょう。

プルリクエストのタイトルにプレフィックスを入れる

プルリクエストのタイトルに命名規則をもたせることで、レビュアーの認知負荷を軽減することに繋がります。例えば新機能追加であれば feat など、決まった文言をつけるルールをチーム内で決めておくと良いでしょう。

レビュアーの推奨行動

レビュイーの推奨行動がより具体的なアクションについての記載だったのに対し、レビュアーの推奨行動は比較的マインドセットや心構えについての記載が多めです。読んで即実践、というよりも、読んでその意図を理解しつつ日々の行動を少しずつアップデートしていく、といった使い方をしてもらえればと思います。

コメント記載時には相手への敬意を忘れないこと

先の章でも触れましたが、このパートが私は一番好きです。レビューは相手を詰問する場ではありません。より良いものをチーム一丸となって作っていく、その意識を忘れないようにしましょう。

指摘内容は具体的であればあるだけ良い

時間に追われるレビュアーが簡素なコメントのみでレビューを終わらせてしまうケースがあると思います。もしレビュイーがその指摘から具体的な修正方針を読み取れなかった場合、結局追加のコミュニケーションラリーが発生してしまいますし、往々にしてそういった場面ではレビュイーがその指摘の意図を再度レビュアーへ伺うこと自体の心理的負荷が高くなってしまいがちです。

指摘内容はできる限り具体的に記載されている方が建設的です。

まとめ

さて、今回はコードレビューガイドラインを紹介させていただきました。このガイドラインが、皆さんのチームにおける開発体験の向上に繋がることを期待しています。ぜひご活用ください！

▼ フューチャーアーキテクト コードレビューガイドラインはこちら
https://future-architect.github.io/arch-guidelines/documents/forCodeReview/code_review.html

ガイドラインに関するご意見やフィードバックも、もちろんウェルカムです。お待ちしております。

はじめに

こんにちは。tanai（棚井龍之介）です。
2025年からは、FutureVuls の SRE 領域で活動しています。

少し前に、Connpass のイベント を眺めていたところ、Datadog のユーザ会が「札幌現地のみ、オフライン開催！」との見出しを見つけました。

最近、担当サービスへの Datadog 導入に成功 しまして、その「導入成功に至るまでのプロセス」をなんらかの方法でナレッジ化しておきたいと考えていました。なので、このイベントを契機に「自分の経験の言語化する」->「スライド作成を通してナレッジ化する」の経験学習サイクルを回しました。また、「オフライン限定」という利点を活かして、オンライン環境では話せないような「SaaS運用保守担当者としてのリアルな苦労話」にまで踏み込んだ内容となり、Datadog に限らず「オブザーバビリティツール導入時の、胃がキュッとなるような実体験談」を共有できました。

会場は、クラスメソッド株式会社さんの「札幌オフィス」でした！

イベント内容などは「Japan Datadog User Group Meetup#8@札幌 のページ」をご覧ください。

イベント当日のタイムテーブルはこちらでした。

私の登壇内容について、一部のみとなりますが抜粋してご紹介します。

現場の課題分析からDatadog導入に繋げるまでの話

今回は、オブザーバビリティツールの利用状況を「利用開始前」と「利用開始後」の2つに分けた上で、今回は「利用開始前の状況から、Datadog 導入に至るまで」の部分にフォーカスしました。

オライリー本の「オブザーバビリティ・エンジニアリング」など、可観測性がいかに重要か、なぜ重要かを説く本は多数あります。ただし、それらの内容は、書籍という制約上どうしても「一般的な話」に留まってしまうか、もしくは、ビックテックの事例集になっている感があります。Datadog などの「実際のところ、業務を回すのに必須とは言い難い」ツールを導入した担当者であれば、誰もが「（予算獲得に向けた社内説得などでの）個別の苦労話」を抱えているはず（ありますよね？）と思い、その部分にフォーカスしました。

以下のスライドは、プロジェクトの前提条件から、どのような経緯で監視ツールの必要性を強く意識するようになったかを説明しています。

私の場合は、「サービスがスケールし始めた地点」から、チーム体制が「役割分担せずに、全員で取り組む」配置から「各領域ごとに、専任の担当者を決める」体制へと移行し始めました。それぞれが専門性を深める中で、「業務効率化の一環」として、監視ツールの必要性を感じ始めました。

※本ブログでは「オブザーバビリティツール」と「監視ツール」の表記揺れがありますが、どちらも同じ意味で利用しています。

その中で私が強く実感したのは「情報不足」という点です。

チーム体制が「役割分担せずに、全員で取り組む」のであれば、「オレが知らないことは、アイツが知っている」で乗り切れますし、以心伝心とは言わないまでもツーカーでの意思疎通が可能です。この体制がうまく回っている間は、コミュニケーションコストが少ないので圧倒的なアウトプットに繋がるのだとも思いますし、最新の状況を自動トレースできないドキュメントは「むしろ不要」になります。ただし、メンバー増員によりチームがスケールし始めると「この情報は、誰が知っているんだ？」のルーティング処理に工数が取られ始めて、ドキュメンテーションへのニーズが高まります。

そこで私は、以下の3ポイントを「解決したい課題リスト」として設定し、オブザーバビリティツールの導入により解決を試みました。

• 課題リスト
  • 必要な情報が、どこにあるのか分からない
  • 情報はあるのに、必要な情報に辿り着けない
  • 情報が断片的で、全体像を把握できない

導入候補のツールとしては、以下3つのサービスを検討しました。