Azure API Management
Azure DevOps
Azure Pipelines
GitHub
APIOps は、GitOps と DevOps の概念を API デプロイに適用する手法です。 このアーキテクチャでは、APIOps CLI を使用して、Git ベースのワークフローを使用してAzure API Management構成を抽出、確認、昇格する方法を示します。 このアプローチを使用して、API ライフサイクルを管理し、API の品質を向上させ、承認された変更の監査可能な記録を維持します。
アーキテクチャ
次の図は、APIOps CLI 構成の昇格ワークフローの概要を示しています。 Teams は Git で API Management 成果物を確認し、継続的インテグレーションと継続的デリバリー (CI/CD) パイプラインによって、承認された構成がターゲット API Management 環境に昇格されます。
このアーキテクチャのVisio ファイルをダウンロードします。
Workflow
API Management の構成は、まず、既存の API Management 構成を抽出するか、CLI と互換性のある API Management 成果物を作成します。 運用ワークフローは、次のいずれかの成果物入力から始まります。 どちらのパスも、同じプル要求、検証、承認、デプロイ プロセスにつながります。
(A) 抽出優先: API オペレーターは、既存の API Management インスタンスに対して
apiops extract実行して、ローカル Git チェックアウト ブランチに API Management アーティファクト ファイルを作成します。 オペレーターは、これらの成果物を使用してベースラインを提案するか、承認された構成変更をキャプチャします。(B) コードファースト: API 開発者は、APIOps CLI と互換性のある API 仕様、情報ファイル、ポリシー、および関連する API Management 成果物をローカル Git チェックアウト ブランチで作成または更新します。
いずれかの入力には、次のライフサイクルを使用します。
構成の変更を作成します。 初回の抽出またはコードファーストのアーティファクト作成チェックイン後は、API 構成リポジトリが API Management 構成アーティファクトの信頼できる唯一の正しい情報源になります。 リポジトリは、各デプロイのバージョン履歴と監査レコードを保持します。 変更を加えるために、API オペレーターまたは開発者は、API 構成リポジトリの保護されたブランチからブランチを作成し、API に関連する 1 つの論理的な変更を行います。
変更を確認して検証します。 オペレーターまたは開発者は、自分のブランチを保護されたブランチにマージするために、プルリクエストを作成します。 API コントラクト、ポリシー、および API Management 構成の必須の所有者とレビュー担当者は、プル要求を確認します。 CI/CD システムは、次のチェックとテストを実行します。
- API仕様のリンティング
- 承認されたコントラクトに対する破壊的変更検出
- 仕様とリポジトリのコンテンツのセキュリティ スキャン
- 予想される動作、認証、ポリシー効果、バックエンドの依存関係を検証する API テスト
これらのチェックでは、Microsoftツールは必要ありません。 チームは、組織のサポート、セキュリティ、ライセンスの要件を満たす適切なツールを使用します。
変更できないデプロイ入力を承認します。 必要な所有者または校閲者が pull request を承認し、承認されたリポジトリ保守担当者は、必要なすべてのチェックとレビューが成功した後に、レビューされた変更をマージします。 マージされた不変コミットとその protected-branch 成果物は、リポジトリの監査可能な信頼できるソースになります。
チームは、保護されたリポジトリ ブランチを直接プッシュから保護し、機密性の高いターゲットに対して環境またはサービス接続の承認を必要とし、抽出と発行に個別の最小特権 ID を使用します。 承認されたコミットは、監査証跡を確保するため、対応するプルリクエスト、レビュー、検証結果とともに記録されます。
展開をプレビューします。 CI/CD パイプラインは、同じターゲットを使用して承認済みコミットの
apiops publish --dry-runを実行し、発行せずに ファイルをオーバーライド します。 リリース承認者は、ドライ ランによって作成、更新、削除、またはスキップされるリソースを確認します。 チームは、ドライ ランの成功を、自動化された API テストの代わりにではなく、デプロイ ゲートとして扱います。公開と宣伝。 ドライ ランが検証に合格すると、CI/CD パイプラインは
apiops publishを使用して、レビューされた同じコミットを発行します。 複数の環境の場合、プラットフォーム チームは共有成果物を安定した状態に保ち、バックエンド URL、リソース ID、シークレット参照などの値に対してレビューされたオーバーライド構成ファイルを使用します。 チームは、コミットを本番環境の前に非本番環境を経由して順に昇格させるとともに、複数のパイプラインが同時に同じターゲットに書き込むことを防ぎます。Note
この構成はワークスペースの子オーバーライドを受け付けますが、公開時には適用されません。 公開時には、オーバーライドはワークスペース コンテナー自体にのみ適用されます。 環境固有のワークスペース API、バックエンド、名前付き値、その他の子リソースを反映させる目的で、ワークスペースの子リソースによる上書きに依存しないでください。 これらのリソースの代替昇格アプローチを検証するか、 ワークスペース スコープのオーバーライド プロパティが適用されていない 既知の問題が解決されるまで昇格を延期します。
デプロイ後に検証と調整を行います。 発行後、運用チームは自動スモークおよび回帰テストを実行し、API Management とバックエンドの正常性を監視し、デプロイされた結果と承認済みのコミットを比較します。 チームは、運用環境を直接編集するのではなく、pull request を使用して予期しない変更を調査し、解決します。
API オペレーターが API Management で承認された緊急変更を直接行う場合、オペレーターは Git チェックアウトで抽出を実行し、ブランチで成果物の変更を確認してコミットし、ブランチをプッシュして、プル要求を開く必要があります。 必要なオーナーまたはレビュー担当者はプル リクエストをレビューして承認する必要があり、さらに、リポジトリの信頼性が保たれるよう、権限を持つリポジトリ メンテナーがそれをマージする必要があります。
コンポーネント
API Management は、バックエンド サービス用の一貫性のある API ゲートウェイを作成するマネージド サービスです。 このアーキテクチャでは、APIOps CLI が抽出するソース構成と、CLI が承認された API 定義、ポリシー、製品、診断、名前付き値、およびその他のサポートされている構成を公開するターゲット環境を提供します。
APIOps CLI は、オピニオンされた APIOps アプローチ用のツールを提供するオープンソース プロジェクトです。 このアーキテクチャでは、API Management 構成をアーティファクト ファイルに抽出し、成果物を API Management に発行し、CI/CD ワークフローをスキャフォールディングできます。
Git リポジトリには、API Management 成果物と、該当する場合は API コントラクトが格納されます。 パイプライン デプロイのレビュー履歴と承認された信頼のソースが提供されます。
CI/CD システムは、ワークロード ID またはその他のサポートされている非対話型資格情報を使用して、検証、抽出、発行を実行します。 このアーキテクチャでは、CI/CD ワークフローをGitHub ActionsまたはAzure Pipelines定義します。
代替案
ワークロードの機能要件と非機能要件に応じて、このアーキテクチャを他のAzure サービスまたはアプローチに置き換えたり、拡張したりできます。 次の代替手段とトレードオフを検討してください。
Bicepまたは Terraform と APIOps は、同じソリューションのさまざまな部分に対応できます。 API Management 構成とインフラストラクチャの両方を所有するチームは、コードとしてのインフラストラクチャ (IaC) を使用して API Management サービスとそのサポート インフラストラクチャをプロビジョニングし、同じ IaC パイプラインを使用して API Management 構成を管理できます。 インフラストラクチャと構成を一緒に変更してデプロイするとき、およびパラメーターが環境間の違いを表すことができる場合は、この方法を選択します。
API 定義、ポリシー、および関連する構成に、サービス インフラストラクチャに依存しない個別の所有者またはリリース ライフサイクルがある場合は、APIOps パターンを使用します。 APIOps は、既存の構成の抽出、API に重点を置いた成果物の確認、または複数の環境または API Management インスタンス間での同じ承認済み構成の昇格が必要な場合にも適しています。 API やポリシーの変更が頻繁に行われるか、より多くの環境で、この専用ワークフローの価値が高くなります。
これらの要因には固定しきい値はありません。 主に所有権、レビュー要件、デプロイの境界に基づいて決定します。 変更率が低い小規模な API 資産の場合は、手動の pull request ワークフローから始めて、リポジトリのベースラインと承認プロセスが確立された後にのみ抽出スケジュールまたはデプロイの自動化を追加します。
シナリオの詳細
APIOps では、バージョン管理を使用して API を管理し、API 定義、ポリシー、製品、診断、およびその他の API Management 構成に対する変更の監査証跡を作成します。 変更を以前に確認し、より多くの場合、チームはデプロイ前に API 標準からの逸脱を特定するのに役立ちます。 同じプロセスを使用する API が増えるにつれて、チームは API 資産全体の一貫性を向上させることができます。
このワークフローは、API Management の構成を API Management インスタンスにデプロイします。 API バックエンド、アプリケーションのコンピューティングリソースまたはデータ リソース、ネットワーク、API Management サービス インフラストラクチャはデプロイされません。 これらのレイヤーをデプロイするには、個別の管理された IaC パイプラインとアプリケーション パイプラインを使用します。
このソリューションは、チームが次の場合に役立ちます。
- 環境と API Management インスタンスの概要を維持します。
- API とポリシーに対する重要な変更を追跡します。
- 承認されたデプロイの監査証跡を作成します。
- リポジトリの外部から発生した承認された変更を調整します。
成果物のソースと所有権を選択する
デプロイを自動化する前に、アーティファクトがリポジトリに入り、それを所有するユーザーを次の方法から選択します。
- Extract-first: 既知の適切な API Management インスタンスを抽出して、初期成果物ベースラインを確立します。 リポジトリを信頼のソースとして扱う前に、チェックインで生成されたアーティファクトを確認します。
- コード優先: アプリケーション ソースまたは APIOps リポジトリを使用して、OpenAPI の説明などの API コントラクトを保持します。 パイプラインが発行する API Management 成果物にそのコントラクトを変換するユーザーを定義します。 非運用 API Management インスタンスを使用して、目的のインポートと成果物のワークフローを検証します。 任意のソース レイアウトが CLI によって直接消費可能であると想定しないでください。
- 共同責任: API 開発者、プラットフォームオペレーター、またはその両方がポリシー、製品、診断、名前付き値、および API 定義に対する変更を所有しているかどうかを確認します。 ベースラインが受け入れられたら、すべての変更を同じリポジトリにルーティングし、プロセスを確認します。
考えられるユース ケース
API Management を通じて公開される単一の API を持つ組織を含め、API を開発および管理する組織。
追跡可能なレビューと展開の記録を必要とする保険、銀行、金融、政府などの高度に規制されたセクター。
考慮事項
これらの考慮事項は、Azure Well-Architected Framework の柱を実装します。これは、ワークロードの品質を向上させるために使用できる一連の基本原則です。 詳細については、「 Well-Architected Framework」を参照してください。
Reliability
信頼性は、アプリケーションが顧客に対して行ったコミットメントを確実に満たすことができるのに役立ちます。 詳細については、「信頼性の設計レビュー チェックリスト」を参照してください。
互換性を損なわない API の変更の場合は、API Management revisions を使用して、まだ現在のリビジョンにしていないリビジョンをデプロイおよびテストしてから、それを現在のリビジョンにします。 リリース後に検証が失敗した場合は、以前のリビジョンを現在のリビジョンとして復元します。 既存のコンシューマーが以前のバージョンを引き続き使用できるように、コントラクトの変更を中断するために API バージョンを使用します。
API Management 構成の変更を、各 API バックエンドのデプロイ戦略に合わせて調整します。 APIOps コミットを元に戻す場合、そのコミットによって表される構成のみが復元されます。 互換性のない、または利用できないバックエンドは復元されません。 既知の適切な各デプロイを形成する APIOps コミット、API Management リビジョン、バックエンド リリースを記録します。 ポリシー、名前付き値、シークレット参照、依存関係、バックエンド互換性など、非運用環境で完全なロールバック 手順をテストします。
セキュリティ
セキュリティは、意図的な攻撃や貴重なデータとシステムの誤用に対する保証を提供します。 詳細については、「セキュリティの 設計レビューチェックリスト」を参照してください。
API Management の変更を適用するための通常のパスとして、リポジトリとパイプラインを使用します。 開発者とオペレーターは、運用 API Management インスタンスへの永続的な書き込みアクセス権を必要としません。 必要な場合にのみ昇格されたアクセス権を付与し、限られた時間のみ付与します。 生じた変更をリポジトリに反映します。
API Management 成果物を格納する Git リポジトリを保護するには、次のメカニズムを使用します。
- Pull request review: 構成をデプロイし、適切なレビュー担当者によるレビューを必要とするブランチを保護します。
- 資格情報の分離: 使用可能な場合は、フェデレーション ワークロード ID を優先します。 成果物またはパイプライン ファイルではなく、承認済みのシークレット ストアまたはリポジトリ環境に環境固有のシークレットを格納します。
- コミットの整合性: コミットの実績を確認するには、署名付きコミットが必要です。 プッシュとブランチの強制削除を防ぐためにブランチ保護を構成し、ユーザーが変更を承認またはマージするための多要素認証を要求し、デプロイのコミットとプル要求の履歴を保持します。
- 成果物のレビュー: 抽出出力と公開用入力を確認し、シークレット、マスキング済みマーカー、意図しない環境固有の値が含まれていないかを点検します。 変更によって API アクセスが広がったり、ポリシーが弱めたりしないことを検証します。
APIOps CLI をリポジトリの依存関係として管理します。
package.json 内で @azure-tools/apiops-cli をテスト済みのバージョンに固定し、ロックファイルをコミットして、npm ci を使用してください。 運用パイプラインを有効にする前に、生成された ID 設定、変数、トリガー、保護規則を確認します。
コストの最適化
コストの最適化では、不要な経費を削減し、運用効率を向上させる方法に重点を置いています。 詳細については、「 コストの最適化」のデザイン レビュー チェックリストを参照してください。
APIOps CLI はオープンソース ソフトウェアですが、このシナリオでは、API Management インスタンスと、選択したソース管理および CI/CD プラットフォームのコストが発生します。 API Management の価格は、リージョン、レベル、ユニット数、容量モデル、可用性ゾーンまたはマルチリージョンの構成、使用状況によって異なるため、1 つの固定見積もりは提供されません。 CI/CD の料金は、ランナーの種類、含まれる分数、コンカレンシー、ストレージ、リテンション期間によっても異なります。
Azure料金計算ツールでシナリオ固有の見積もりを作成し、アーキテクチャの決定に次の前提条件を記録します。
| 入力を見積もる | 記録する前提 |
|---|---|
| API Management リージョン | 開発、テスト、ステージング、運用の各インスタンスのデプロイ リージョン。 |
| 階層と容量 | 各環境のレベルまたは v2 レベル、ユニットまたはゲートウェイの数、および稼働時間。 |
| Resiliency | 可用性ゾーンまたは追加リージョンへのデプロイ（各ロケーション内のユニットを含む） |
| 使用量ベースの料金 | 想定されるリクエスト数またはオペレーション数、および適用されるワークスペース、セルフホステッド ゲートウェイ、ネットワーク、監視、またはデータ転送の料金。 |
| CI/CD プラットフォーム | GitHub ホステッド エージェント、セルフホステッド エージェント、または Azure Pipelines エージェント。 想定されるパイプライン実行数、実行時間、同時実行数、ストレージ、およびログまたはアーティファクトの保持期間。 |
| ソース管理とライセンス | ユーザー数と有料のGitHubまたはAzure DevOpsプランの機能。 |
現在の API Management の価格の詳細 を使用して、該当する課金モデルを選択します。 CI/CD とソース管理の前提条件については、Azure DevOps価格とGitHub価格に関するページを参照してください。 レビュー担当者が再現して更新できるように、電卓の見積もり、通貨、価格日、およびすべての前提条件をエクスポートまたはキャプチャします。 デプロイの前に、リージョン、階層、ユニット数、環境、またはパイプラインの使用状況が変更されたときに再計算します。
オペレーショナル エクセレンス
オペレーショナル エクセレンスは、アプリケーションをデプロイし、それを運用環境で実行し続ける運用プロセスをカバーします。 詳細については、「 オペレーショナル エクセレンスの設計レビュー チェックリスト」を参照してください。
APIOps を使用すると、デプロイが繰り返し可能になり、変更後の分析のためのコミット履歴が作成されます。 タグを付けるか、または各環境が受け取るコミットを記録し、パイプライン ログを保持し、デプロイ後に API Management インスタンスと依存 API を監視します。
複数の環境については、レビュー済みの同じアーティファクトのコミットを、開発環境、ステージング環境、運用環境へと順次展開します。 環境のオーバーライドは、環境間で異なる必要がある値にのみ使用し、成果物と同じ注意を払ってそれらのファイルを確認します。 ワークスペースの子オーバーライドは公開時には適用されないため、環境昇格には使用しないでください。 インシデントが発生する前にロールバック手順をテストします。 Git の元に戻すには、引き続き検証と、API Management を復元するための制御された発行が必要です。
CLI は、init、extract、およびpublishコマンドを提供し、GitHub ActionsまたはAzure DevOpsパイプラインをスキャフォールディングできます。
APIOps CLI ドキュメントでコマンドの詳細を確認します。
レガシ APIOps Toolkit から安全に移行する
APIOps プロセスで従来の APIOps Toolkit を使用している場合は、アップグレードを計画してください。 このアプローチでは、別個の Extractor とPublisherバイナリとパイプライン テンプレートが使用されます。 APIOps CLI では 1 つの Node.js CLI を使用しますが、その成果物形式は既存のツールキット成果物と互換性を持つよう設計されています。 移行は、インプレース運用アップグレードとしてではなく、制御されたカットオーバーとして扱います。
既知の適切なツールキット成果物とパイプラインにタグを付け、既存のパブリッシャーをロールバック オプションとして保持します。 従来の発行元を変更せず、同じ展開で新しい発行元を導入してください。
移行ブランチでは、最新の APIOps CLI バージョンを使用し、
--forceを使用せずにapiops initを実行します。 このコマンドは、競合するファイルを検出し、上書きするのではなく終了します。 生成されたパイプライン、ID ガイダンス、フィルター、オーバーライド ファイルを比較して意図的に統合します。apiops publish --dry-runを含むアーティファクトと、ターゲット環境のオーバーライドを、運用環境以外の API Management インスタンスに対して使用します。 CLI が作成、更新、または削除するリソースを確認します。 1 つの制御された発行をテストし、デプロイされた API、ポリシー、名前付き値、依存関係を検証します。発行時には適用されないワークスペースの子要素のオーバーライドを、移行やプロモーションの設計の一部として使用しないでください。 影響を受ける子リソースの代替昇格アプローチを検証するか、 ワークスペース スコープのオーバーライド プロパティが適用されていない 既知の問題が解決されるまで移行を延期します。
カットオーバー時に、API Management インスタンスへの書き込みを許可する発行元は 1 つだけです。 CLI パブリッシャーを有効にする前に、レガシ パブリッシャー トリガーを無効にします。 レビューされたコミットをデプロイし、結果を監視します。 タグ付けされたツールキット パイプラインと成果物のベースラインは、新しいワークフローが正常なリリース サイクルを完了するまで保持します。
互換性の詳細とコマンドごとの移行の例については、「 APIOps Toolkit からの移行」を参照してください。
このシナリオを展開する
APIOps CLI GitHub リポジトリの APIOps CLI ドキュメントに従います。 非運用 API Management インスタンスから開始し、現在の APIOps CLI リリース ガイダンスを使用します。 非運用環境の使用を開始するには、 APIOps CLI を使用して API Management 構成を管理する方法に関するページを参照してください。
貢献者
Microsoft では、この記事を保持しています。 この記事を書いたのは、以下の寄稿者です。
主要な著者:
- Pat Altimore |シニア コンテンツ 開発者
- ワエル・クドゥ |シニア プリンシパル ソリューション アーキテクト
- リシャブ・サハ |シニア プリンシパル ソリューション アーキテクト
公開されていない LinkedIn プロフィールを見るには、LinkedIn にサインインしてください。