Posts

GitHub Actions再利用ワークフロー運用設計：属人化を防ぎつつ開発速度を上げる実践ガイド 複数リポジトリを運用していると、ほぼ同じ CI 設定を各リポジトリにコピーし続ける状態になりがちです。最初は早く見えますが、半年後には「どこに正解があるのかわからない」状態になります。セキュリティパッチを当てたいだけなのに 20 リポジトリを横断修正し、1つだけ取りこぼして監査で指摘される、というのは珍しくありません。 この問題に効くのが GitHub Actions の workflow_call を使った再利用ワークフローです。ただし、単に共通化するだけでは逆に運用事故が増えることがあります。重要なのは、共通化の粒度、権限境界、変更リリース方法を最初に設計することです。 本記事では、実運用で詰まりやすいポイントを中心に、導入から定着までを具体的に解説します。 1. 再利用ワークフローの基本方針 まず押さえるべき方針は次の 3 つです。 再利用ワークフローは「プラットフォーム製品」として扱う 呼び出し側（各アプリ repo）は薄く保つ 破壊的変更はバージョンを切って段階移行する 「共通化＝1ファイルに全部詰め込む」ではありません。lint, test, build, deploy を1個にまとめると、対象外プロジェクトまで影響します。まずは小さく分割し、必要なものだけ組み合わせられる構造にします。 2. 推奨ディレクトリ構成 共通ワークフローを専用 repo に分離しておくと、監査や変更履歴の管理が容易になります。 1 2 3 4 5 6 7 8 9 org-ci-workflows/ .github/workflows/ ci-node.yml ci-python.yml security-scan.yml release-tag.yml docs/ onboarding.md migration-checklist.md 呼び出し側は以下のように最小化します。 ...

MCPサーバー本番設計ガイド：AIエージェント連携を安全・安定に運用するアーキテクチャ MCP（Model Context Protocol）は、LLM と外部ツールを接続する強力な仕組みです。便利な一方で、本番運用では「権限の過剰付与」「監査不能」「障害時の暴走」が起きやすく、設計を誤ると一気にリスクが跳ね上がります。 本記事では、MCP サーバーを業務利用する前提で、安全性・可観測性・運用性を満たす設計パターンをまとめます。PoC から本番へ上げる際のチェックリストとして使える構成にしています。 1. MCP本番運用で先に決めるべきこと 最初に決めるべきは、技術スタックではなく「権限境界」です。 どのエージェントが、どのツールを使えるか 書き込み系操作（作成・更新・削除）の承認方式 外部送信（メール、投稿、通知）の監査ルール 失敗時の停止条件（fail-open か fail-closed か） ここを決めずに実装を始めると、あとから制約を入れられず、結果として運用停止になります。 2. 推奨アーキテクチャ：Control Plane と Tool Plane の分離 MCP 構成は最低でも2層に分けると安全です。 Control Plane: 認証、認可、監査、レート制御 Tool Plane: 実際のツール実行（DB、GitHub、Browser、Messaging） 2-1. なぜ分離するのか Tool 実装に認可ロジックを埋め込むと、ツール追加のたびにセキュリティ品質がブレます。Control Plane で一元化すれば、ポリシー変更時も1箇所で反映できます。 2-2. リクエストフロー例 1 2 3 4 Agent -> MCP Gateway(Control Plane) -> Policy Engine (allow/deny, scope check) -> Tool Adapter (Tool Plane) -> Audit Logger deny の場合も必ず監査ログに記録し、試行の痕跡を残します。 ...

Python asyncioバックプレッシャー設計：落ちない非同期バッチを作る実装パターン asyncio は速く作れる一方で、負荷が上がった瞬間に崩壊する設計を作りやすいという側面があります。特に「処理待ちが無限に積み上がる」「外部API遅延で全体が詰まる」「リトライ嵐でさらに遅くなる」は典型的です。 本記事では、非同期ワーカーを本番運用する前提で、バックプレッシャーを実装に落とす方法を解説します。単なる概念ではなく、すぐ使えるコード断片を中心に進めます。 1. なぜバックプレッシャーが必要か バックプレッシャーは「これ以上は受けない」仕組みです。これがない設計は、ピーク時に次の順で壊れます。 入力が処理速度を超える キューが無限増加してメモリ圧迫 GC増加でスループット低下 タイムアウト増加→リトライ増加 システム全体が雪崩れる つまり、受けすぎないことは性能ではなく可用性の話です。 2. 基本設計：3つの制限を必ず入れる 2-1. キュー上限（bounded queue） 1 2 3 4 import asyncio QUEUE_MAX = 1000 queue: asyncio.Queue[dict] = asyncio.Queue(maxsize=QUEUE_MAX) maxsize なしは原則禁止です。業務要件で「捨てられない」場合でも、無限キューより「受け付け停止 + 明示エラー」のほうが復旧可能です。 2-2. 同時実行数上限（semaphore） 1 2 3 4 5 6 CONCURRENCY = 20 semaphore = asyncio.Semaphore(CONCURRENCY) async def guarded_call(fn, *args, **kwargs): async with semaphore: return await fn(*args, **kwargs) CPU でも I/O でも、同時実行数に上限を持たせると遅延の尾が短くなります。 ...

Kubernetes障害対応ランブック実践編：15分で切り分け、60分で復旧するための現場手順 Kubernetes で障害が起きたとき、技術力より先に問われるのは「順序」です。順序が崩れると、正しいコマンドを打っていても復旧が遅れます。逆に、判断フレームが決まっていれば、難しい障害でも被害を最小化できます。 本記事では、実運用で使える障害対応ランブックを、初動 15 分・復旧 60 分を目安に具体化します。対象は EKS/GKE/AKS を含む一般的な Kubernetes 本番環境です。 1. 最初の5分：人と情報の交通整理 まずやるべきは技術調査ではなく、交通整理です。 インシデントの指揮者（IC）を1人決める ログ担当、メトリクス担当、アプリ担当を分ける Slack/Discord の専用チャンネルを作る 5分ごとの時系列ログ（タイムライン）を残す この段階で「誰が何を見ているか」が曖昧だと、同じ調査を3人で繰り返し、誰も復旧判断をしない状態になります。ICは手を動かさず、意思決定に集中するのが基本です。 2. 5〜15分：影響範囲の特定 次に「どのユーザーに、どの機能で、何%の影響があるか」を確定します。 2-1. まず全体の健康状態 1 2 3 kubectl get nodes kubectl get pods -A --field-selector=status.phase!=Running kubectl get events -A --sort-by=.lastTimestamp | tail -n 50 見るポイント: Node が NotReady になっていないか 特定 namespace だけで CrashLoopBackOff が増えていないか 直近イベントに FailedScheduling や Back-off restarting failed container がないか 2-2. SLO/SLIから影響を数値化 「遅い気がする」ではなく、以下を数値で押さえます。 ...

RAG評価基盤の作り方：精度・再現率・運用コストを同時に最適化する実践手順 RAG（Retrieval Augmented Generation）は導入が進んでいますが、運用で最も難しいのは「改善したつもり」が頻発する点です。embedding モデルを変えた、chunk サイズを変えた、reranker を追加した。どれも良さそうに見えるのに、ユーザー満足は上がらない。このギャップを埋めるのが評価基盤です。 本記事では、RAG を継続改善するための評価パイプラインを、データセット設計から CI 統合まで具体的に解説します。 RAG評価で見るべき3層 RAG の品質は 1 指標では測れません。最低でも次の3層を分けて評価します。 Retrieval層: 正しい文書を取れているか Generation層: 回答が正確で有用か System層: レイテンシ・コスト・安定性 この分離がないと、生成品質低下の原因が retrieval なのか prompt なのか判別できません。 ステップ1：評価データセットを設計する 1-1. 問い合わせカテゴリを分割 例として次の5カテゴリに分けます。 定義確認（用語説明） 手順質問（How-to） 例外対応（エラー解決） 比較検討（A vs B） 根拠提示（出典必須） カテゴリごとに難易度と重要度を持たせ、偏りを防ぎます。 1-2. 正解の持ち方 正解は「理想回答1つ」では不十分です。RAGでは表現揺れが自然なので、次を保存します。 期待要素（必須ポイント） 禁止要素（誤情報、過剰断定） 参照すべき文書ID この形式にすると、自動評価と人手レビューを両立できます。 ステップ2：Retrieval評価を自動化 代表指標: Recall@k MRR nDCG 例えば、正解文書IDを持つ場合は次のように計算します。 1 2 3 def recall_at_k(retrieved_ids, gold_ids, k=5): topk = set(retrieved_ids[:k]) return 1.0 if len(topk.intersection(gold_ids)) > 0 else 0.0 運用では平均値だけでなく、カテゴリ別分布を見ることが重要です。手順質問だけ recall が低い場合、chunk 戦略や見出し抽出に問題がある可能性が高いです。 ...

GitHub Actionsセルフホストランナー防衛術：CI/CDの供給網リスクを減らす実装ガイド セルフホストランナーは高速で柔軟です。特定ツールチェーンや社内ネットワーク接続が必要な環境では、ほぼ必須といえます。一方で、設定を誤ると CI/CD が攻撃経路になります。 近年のインシデントでは、依存パッケージ汚染だけでなく「Actions workflow の権限過多」「fork 由来PRでの秘密情報流出」「ランナー残存データ」が問題化しています。 本記事では、セルフホストランナーを安全に運用するための防衛策を、設計レイヤごとに整理します。 脅威モデルを先に定義する まず守る対象を明確にします。 リポジトリのソースコード Secrets（クラウド鍵、署名鍵、トークン） 配布物の完全性（改ざん防止） 社内ネットワーク接続経路 攻撃経路は主に次です。 悪意ある PR が workflow を悪用 Marketplace Action の supply chain 汚染 ランナー上に残る credential / build artifact 過剰な GITHUB_TOKEN 権限 この4点を潰す設計が防御の中心になります。 1. ランナーは「使い捨て」を前提にする 長寿命ランナーは便利ですが、攻撃後の残留リスクが高いです。可能ならジョブ単位で破棄できる ephemeral 構成を採用します。 Kubernetes + Actions Runner Controller VMテンプレートから都度起動 ジョブ終了後に完全破棄 少なくとも /tmp と workspace を確実に消去し、Docker layer cache の共有範囲を制御してください。 2. workflow 権限を最小化する permissions: write-all は禁止レベルです。workflowごとに最小権限を明記します。 1 2 3 4 permissions: contents: read pull-requests: write id-token: write 特に id-token: write は OIDC 連携に必要ですが、不要ジョブで許可しないこと。権限漏れがクラウド侵害に直結します。 ...

FastAPI本番運用ハードニング完全ガイド：セキュリティ・性能・障害対応を実装で固める FastAPI は開発速度が高く、PoC から本番まで一気に進めやすいフレームワークです。しかし、早く作れることと安全に運用できることは別問題です。実際の障害は、コードの正しさよりも運用の隙から発生します。 本記事では、FastAPI を本番で安心して運用するためのハードニング手順を、実装可能な形でまとめます。対象は「すでにAPIが動いているが、運用強度を上げたい」チームです。 1. 入口防御：TLS、ヘッダ、レート制限 TLS終端とForwardedヘッダ ロードバランサ配下で動かす場合、X-Forwarded-For と X-Forwarded-Proto の扱いを明確にします。誤るとクライアントIPが取れず、監査も制限も機能しません。 1 2 3 4 5 from fastapi import FastAPI from starlette.middleware.trustedhost import TrustedHostMiddleware app = FastAPI() app.add_middleware(TrustedHostMiddleware, allowed_hosts=["api.example.com", "*.example.com"]) allowed_hosts をワイルドにしすぎると Host Header Injection の温床になります。 セキュリティヘッダ 最低限次を返します。 Strict-Transport-Security X-Content-Type-Options: nosniff X-Frame-Options: DENY Referrer-Policy APIでも無関係ではありません。管理画面やドキュメントUIを守る意味があります。 レート制限 ブルートフォースと突発負荷に備え、IPまたはAPIキー単位でレート制限を設定します。 認証系: 5 req/min 通常API: 60 req/min 高負荷検索: 20 req/min Redis バックエンド方式にして、アプリ再起動でカウンタが失われないようにします。 ...

Kubernetesコスト最適化の実務：FinOps視点で無駄を可視化し、性能を落とさず削減する方法 Kubernetes を導入した直後は「自動で効率化される」と期待されがちですが、実際には逆です。適切な運用ルールがないと、クラウド請求は静かに膨らみ続けます。 典型例は次の通りです。 リクエスト/リミットが過大でノードが常時スカスカ 夜間トラフィック減少時も同じ台数を維持 開発環境が週末ずっと起動 HPA が CPU しか見ておらず、キュー滞留を無視 過剰なストレージクラス（IOPS課金）を全環境で使用 本記事では、FinOps の考え方を用いて、Kubernetesコストを「見える化→改善→定着」の順に進める方法を解説します。 コスト削減の前に定義すべき指標 削減施策が失敗する理由は、目標が「安くする」しかないからです。最低でも次の 4 指標を定義します。 Unit Cost: 1リクエストあたりコスト / 1ジョブあたりコスト Utilization: CPU・Memoryの実効使用率 Reliability: SLO 達成率（削減で品質を落とさない） Waste Ratio: 予約/実使用の差分率 この4つを同時に追うと、単なるコストカットでなく「健全な最適化」になります。 ステップ1：可視化基盤を整える 1-1. Kubecost または OpenCost の導入 EKS/GKE/AKS いずれでも、namespace / deployment / label 単位で費用を把握できる状態にします。重要なのは team, service, env ラベルを強制することです。 推奨ラベル: cost-center owner environment（prod/stg/dev） criticality ラベルがないと請求分析ができず、改善責任が曖昧になります。 1-2. 観測ダッシュボード 最初のダッシュボードは次を必須にします。 Namespace別コスト（当日/前日比） Pod別 request/usage ギャップ ノード空き率（CPU、Memory） 時間帯別トラフィックとレプリカ数 ここまでで「どこが高いか」は見えます。次は「なぜ高いか」を潰します。 ステップ2：最も効果が高い改善施策 2-1. Right Sizing（最優先） 多くの環境で最大効果が出るのは request/limit の見直しです。VPA recommendation を参考に、まずは read-only で 2 週間観測します。 ...

PostgreSQLインデックス最適化の現場手順：遅いクエリを再現・診断・改善する実践プレイブック 「CPUは余っているのに画面が遅い」「特定時間帯だけ API が詰まる」。この手の問題の多くは、アプリではなく SQL の実行計画に原因があります。特に PostgreSQL では、インデックス設計と統計情報の状態が性能をほぼ決めます。 本記事では、実務で使う手順に沿って、遅延クエリの改善を再現可能な形で解説します。単なる理論紹介ではなく、調査順序、判断基準、リリース時の注意点まで含めてまとめます。 まず守るべき3原則 推測でインデックスを作らない 体感で追加すると write 性能とストレージが悪化します。必ず実行計画を見てから判断します。 改善前後を数値で比較する P95、rows、shared read blocks を記録し、効果を証明します。 本番反映は CONCURRENTLY を基本にする テーブルロックで事故らないため、CREATE INDEX CONCURRENTLY を優先します。 ケース設定：注文一覧APIが遅い 次のクエリが遅いとします。 1 2 3 4 5 6 7 SELECT id, user_id, status, total_amount, created_at FROM orders WHERE tenant_id = $1 AND status IN ('paid', 'shipped') AND created_at >= NOW() - INTERVAL '30 days' ORDER BY created_at DESC LIMIT 50; データ量は orders 1.2億件、1テナントあたり数百万件。現象は「特定テナントだけ 3〜6 秒」です。 ...

LLM運用の可観測性を実装する：OpenTelemetryでつくるPrompt/Token/Latency監視の実践 LLMアプリは「動く」だけでは本番品質になりません。運用を始めると、次のような問題が必ず発生します。 昨日まで 1.2 秒だった応答が突然 4 秒台になる コストが月末に急増したが、どの機能が原因かわからない 回答品質が落ちたと言われるが、どのプロンプト変更が影響したか追えない リトライ回数や外部API待ちの偏りが可視化されていない この課題を解く鍵が「可観測性（Observability）」です。本記事では OpenTelemetry を軸に、LLM アプリの監視をゼロから構築する実装を、実際に運用で使える粒度で説明します。 なぜ APM だけでは LLM を見切れないのか 従来の Web アプリ監視（CPU、HTTP レイテンシ、エラーレート）だけでは、LLM 特有の故障点が見えません。理由は、LLM の品質とコストが「入力テキスト」と「推論設定」に強く依存するためです。 少なくとも次の軸が必要です。 Prompt 可視化: システム/ユーザー/ツール呼び出しの構成 Token 可視化: input/output token、モデル別単価、キャッシュヒット率 推論経路可視化: retrieval → rerank → generation の各ステップ時間 品質シグナル: hallucination 率、参照文書一致率、ユーザー評価 つまり、HTTP 1 本のログでは不十分で、トレース単位で LLM 実行を分解する必要があります。 アーキテクチャの全体像 最初に、実装対象を次の構成とします。 API: FastAPI LLM: OpenAI / Azure OpenAI（抽象化） RAG: pgvector + reranker Observability: OpenTelemetry SDK + OTLP Exporter + Grafana Tempo/Loki/Prometheus 処理フローは次の通りです。 ...