OpenResty Edge は、それ自体で包括的な設定管理機能を備えています。Admin コンソールの UI または API を介した変更はすべて、その完全な履歴を追跡でき、レビューおよびリリースプロセスも組み込まれています。ほとんどのチームや利用シーンにおいて、この標準提供の仕組みは、信頼性および使いやすさの点で十分なものとなっています。

しかし、お客様と対話する中で、ある特定のニーズが浮かび上がってきました。それは特に、Kubernetes エコシステムを本格的に活用しているチームや、すでに GitOps の仕組みを確立しているチームから多く聞かれるものです。

  • すべてのインフラ設定をテキストファイルとして Git リポジトリで管理し、PR/MR プロセスを通じて変更を適用する、という運用に慣れている。
  • CI/CD パイプラインが確立されており、ゲートウェイ設定の変更も、独立した UI 操作ではなく、既存の自動化された仕組みに組み込みたい。
  • 開発、テスト、本番といった複数の環境間で設定を頻繁にコピーする必要があり、その作業をスクリプトで自動化できる方法を求めている。
  • 構造が類似する設定項目が大量にある場合、UI で一つひとつクリックするよりも、テキストファイルを直接編集する方を好む。

これらのニーズの本質は、OpenResty Edge の設定管理を、OpenResty Edge Admin とは別の独立したプロセスとして運用するのではなく、チームが既存で運用している「Configuration as Code」のワークフローに統合したい、という点にあります。

現在、主に Admin UI で設定を管理しているチームにとって、本記事で紹介するツールは必須ではありません。標準提供の仕組みをそのままお使いください。GitOps の導入、複数環境間での設定同期、あるいは設定の一括編集といったニーズが生じた際に、edge2yaml の利用をご検討いただければと思います。

OpenResty Edge の試用を申請する

edge2yaml とは

edge2yaml は、OpenResty Edge が公式に提供するコマンドラインツールです。ローカルの YAML ファイルと OpenResty Edge プラットフォーム間で、設定の双方向変換を実現します。主な操作は、以下の3種類です。

  • インポート（import）：ローカルの YAML 設定ファイルを Edge Admin にプッシュし、対応する設定を新規作成または更新します。
  • エクスポート（export）：Edge Admin 上の既存設定をローカルに取得し、構造化された YAML ファイルを生成します。エクスポート時、SSL 秘密鍵やユーザーパスワードなどの機密情報はプレースホルダーに置き換えられます。
  • クリーンアップ（cleanup）：指定した範囲で Edge Admin の設定項目を削除します。「アプリケーション全体」から「特定アプリケーション内の特定種別の設定のみ」といった、様々な粒度での操作をサポートしています。注意点として、Edge で「他パーティションへの自動同期」が有効な場合、複数のローカル設定環境との互換性を維持するため、関連するグローバル設定はクリーンアップ操作によって実際にはリセット・削除されません。一方、この機能が無効な場合は、ローカルに存在しない余分な設定がリセットまたは削除されます。

このツールは Edge Admin の API を介してプラットフォームと通信し、認証には API Token が必要です。設定ファイルはパーティションとアプリケーション単位で構成され、その明確なディレクトリ構造により、バージョン管理システムでの追跡が容易になります。機能面では、グローバル設定、グローバル/アプリケーションレベルのアップストリーム、ページルールなど、OpenResty Edge の主要な設定項目を広範囲にカバーしており、日常の運用業務で必要とされるほとんどのオブジェクトの管理に対応しています。

注意：edge2yamlは、現在エンタープライズ版のOpenResty Edge にのみ対応しています。

主なユースケース

1. GitOps ワークフロー

エクスポートした YAML ファイルを Git リポジトリに保存し、設定変更は PR/MR として提出します。コードレビュー後、CI/CD パイプラインが edge2yaml を呼び出して自動的にインポートを実行します。このアプローチにより、ゲートウェイ設定の変更フローとアプリケーションコードのリリースフローの一貫性が保たれるため、すでに GitOps の体制が確立されているチームに最適です。

2. 複数環境間での設定同期

本番環境から設定をエクスポートし、アップストリームのアドレスやドメイン名といった環境固有のパラメータを変更した後、テスト環境やステージング環境にインポートします。複数の UI で手動の繰り返し操作を行う場合に比べ、この方法では変更を管理しやすく、環境間の差異の特定も容易になります。

3. バージョン管理システムによる外部バックアップ

エクスポートコマンドを定期的に実行し、生成された YAML ファイルを Git リポジトリにコミットします。Git の変更履歴を活用することで、任意の時点における設定のスナップショットを確認し、必要に応じていつでもリストア（再インポート）できます。

4. 一括編集

多数の設定項目に対して構造的に類似した変更（例：アップストリームのタイムアウト値の一括調整、特定のルールの複数追加など）を行う場合、YAML ファイルを直接編集、またはスクリプトで生成してから一括でインポートする方が、UI で一つずつ操作するよりも効率的です。インポート時に YAML ファイルに不正なフィールドなどの問題があった場合でも、ツールが具体的なファイル名と行番号を含むエラーを出力するため、迅速な修正が可能です。

edge2yaml と OpenResty Edge Admin のネイティブ機能との関係

edge2yaml の導入を決定する前に、まずOpenResty Edge Admin に組み込まれている構成管理機能と、それに対する edge2yaml の位置付けおよび限界についてご理解いただくことが重要です。

OpenResty Edge Adminの標準機能

OpenResty Edge Admin の構成管理はデータベースを基盤に実装されており、以下の特徴を備えています。

  • 完全な変更履歴: 各操作の担当者、日時、変更内容がすべて記録されるため、コンテキストが明確です。
  • 承認・リリースプロセスの内蔵: 変更の承認と管理されたリリース（デプロイ）をサポートし、操作のステータスはリアルタイムで確認できます。
  • プラットフォームレベルの信頼性とデータバックアップ: データの一貫性はプラットフォームによって保証され、対応するバックアップおよびリストア機能も備わっています。
  • 同時実行時の安全性: 複数人が同時に操作を行っても、データベースのトランザクション機能により、設定の上書きや消失が発生することはありません。

ほとんどの構成管理要件においては、Edge Admin の標準機能を利用する方法が、最も信頼性が高く包括的な選択肢となります。

edge2yaml は、OpenResty Edge の設定を Git や CI/CD のワークフローに統合する際に適していますが、その一方で、以下のような固有の制約がある点を理解しておく必要があります。エクスポートされる YAML ファイルはあくまで特定時点のスナップショットです。そのため、バージョン履歴の粒度や完全性はチームのコミット運用に依存し、プラットフォームが自動で維持する変更履歴ほど精緻ではありません。また、一部のランタイム状態やプラットフォーム内部の関連情報も、静的な YAML ファイルで完全に表現することは不可能です。

また、SSL 秘密鍵やユーザーパスワードといった機密情報は、セキュリティ上の理由により、エクスポート時にはプレースホルダーに置き換えられます。そのため、環境間で設定を移行する際には、これらの項目について別途対応が必要になる点にご注意ください。

推奨される利用方法

OpenResty Edge Admin を日常の構成管理における主要なインターフェースとして活用し、その組み込みのバージョン管理、レビュー公開、およびバックアップ機能を最大限に利用してください。以下の特定のシナリオでは、edge2yaml を補完ツールとして利用することが可能です。

  • チームが既に成熟した GitOps システムを導入しており、Edge の構成を統一的に管理したい場合。
  • 複数の環境間で構成を移行する必要がある場合。
  • 既存の CI/CD パイプラインに構成変更を連携させたい場合。
  • 外部システムに構成のテキストバックアップを保管する必要がある場合。

両者は競合せず、適切な役割分担を行うことで、ワークフローの要件とプラットフォームの信頼性を両立させることが可能です。

まとめ

edge2yaml は、GitOps ワークフローを好むチームに対し、OpenResty Edge の構成管理を Git および CI/CD システムに統合するための公式な手段を提供します。もし貴社チームが Git を用いたインフラストラクチャ構成の管理に慣れている、または複数の環境間で構成を一括同期する必要がある場合、edge2yaml は検討する価値があります。

より詳細なインストール手順、コマンドパラメータ、および構成ディレクトリ構造については、公式ドキュメントの YAML ファイルに基づく OpenResty Edge 構成のミラーリング および対応する 使用例 をご参照ください。

OpenResty Edge の試用を申請する

OpenResty Edge について

OpenResty Edge は、マイクロサービスと分散トラフィックアーキテクチャ向けに設計された多機能ゲートウェイソフトウェアで、当社が独自に開発しました。トラフィック管理、プライベート CDN 構築、API ゲートウェイ、セキュリティ保護などの機能を統合し、現代のアプリケーションの構築、管理、保護を容易にします。OpenResty Edge は業界をリードする性能と拡張性を持ち、高並発・高負荷シナリオの厳しい要求を満たすことができます。K8s などのコンテナアプリケーショントラフィックのスケジューリングをサポートし、大量のドメイン名を管理できるため、大規模ウェブサイトや複雑なアプリケーションのニーズを容易に満たすことができます。

著者について

章亦春（Zhang Yichun）は、オープンソースの OpenResty® プロジェクトの創始者であり、OpenResty Inc. の CEO および創業者です。

章亦春（GitHub ID: agentzh）は中国江蘇省生まれで、現在は米国ベイエリアに在住しております。彼は中国における初期のオープンソース技術と文化の提唱者およびリーダーの一人であり、Cloudflare、Yahoo!、Alibaba など、国際的に有名なハイテク企業に勤務した経験があります。「エッジコンピューティング」、「動的トレーシング」、「機械プログラミング」 の先駆者であり、22 年以上のプログラミング経験と 16 年以上のオープンソース経験を持っております。世界中で 4000 万以上のドメイン名を持つユーザーを抱えるオープンソースプロジェクトのリーダーとして、彼は OpenResty® オープンソースプロジェクトをベースに、米国シリコンバレーの中心部にハイテク企業 OpenResty Inc. を設立いたしました。同社の主力製品である OpenResty XRay動的トレーシング技術を利用した非侵襲的な障害分析および排除ツール）と OpenResty Edge（マイクロサービスおよび分散トラフィックに最適化された多機能ゲートウェイソフトウェア）は、世界中の多くの上場企業および大企業から高い評価を得ております。OpenResty 以外にも、章亦春は Linux カーネル、Nginx、LuaJIT、GDB、SystemTap、LLVM、Perl など、複数のオープンソースプロジェクトに累計 100 万行以上のコードを寄与し、60 以上のオープンソースソフトウェアライブラリを執筆しております。

翻訳

英文版 の原文と日本語訳版（本文）をご用意しております。読者の皆様による他の言語への翻訳版も歓迎いたします。全文翻訳で省略がなければ、採用を検討させていただきます。心より感謝申し上げます！