GitHub で NGINX 設定を管理する

ソフトウェアの設定、オプション、構成にはさまざまな形式があります。 スペクトルの一方の端には、無効な状態に対するガードレールを提供しながら直感的に操作できるように設計された、洗練された応答性の高い GUI があります。 もう一方の端はテキスト ファイルです。 テキスト ファイルは、その明瞭性、自動化の可能性、および最小限の使用要件 (おそらくターミナル ウィンドウをいくつか開いているでしょう) により、エンジニアと DevOps チームの両方から高く評価されていますが、テキスト ファイルを使用してソフトウェアを構成することには明らかなトレードオフがあります。 たとえば、テキスト ファイルを誤って構成してソフトウェア パッケージをクラッシュさせたことがないLinux ユーザーを探してみてください。

唯一のオールインワン ソフトウェア プロキシ、ロード バランサー、Web サーバー、API ゲートウェイである NGINX は、現代のインターネット インフラストラクチャの重要なコンポーネントです。 ほとんどの場合、Linux カーネルを基盤とするオペレーティング システムに基づくインフラストラクチャ。 このエコシステムとそれをサポートする専門家に準拠するために、NGINX はテキストベースの構成に大きく依存しています。

F5 NGINX インスタンス マネージャー モジュールは、長い間、NGINX 関連の構成オーケストレーションの頼みの綱でした。 直感的なユーザー インターフェイスと API を通じて、リモートでのバッチ構成管理のための高度な機能を提供し、サポート ドキュメントとガードレールも用意されています。 ただし、個々の NGINX 構成ファイルはコードと非常によく似ており、ソフトウェア チームにはすでにコードを管理するための優れたツールがあります。 ギット。 Git は、開発者と運用チームに、テキスト ファイル ワークフローの管理に特化した多数の機能を提供します。

Instance Manager と Git およびその他の外部システムとの新たな統合により、バージョン管理、分散型貢献、承認ワークフロー、チーム調整などの機能が可能になります。 GitHub や GitLab などのプラットフォームは、この機能セットを継続的インテグレーション/継続的デプロイメント (CI/CD)、コラボレーション、問題追跡、および Web ベースのユーザー インターフェイスを介したその他の貴重な機能に拡張します。

このブログ記事では、GitHub を使用して NGINX 構成を管理し、変更が行われるたびにインスタンスに自動的にプッシュする方法を説明します。

インスタンス マネージャー API

Instance Manager は、Web ユーザー インターフェイスを補完する豊富な REST API セットを提供します。 API の主な利点は、管理下にあるデータ プレーン インスタンスの構成ファイルを更新できることです。 最近、構成の更新を特定のバージョンのファイルに関連付ける機能を有効にすることで、この機能を拡張しました。 Git リポジトリで管理する場合、構成に Git コミット ハッシュのタグを付けることができます。 さらに、外部で管理されている構成に対してインスタンス マネージャー内に新しい状態を実装し、構成が外部管理下にあることをファイル エディターに警告します。

GitHubアクション

GitHub では、開発者はActionsと呼ばれる機能を使用して、リポジトリ内にカスタム デプロイメント パイプラインを作成できます。 ユーザーは、独自のアクションを定義するか、 YAML 定義を介して既存のスクリプトを呼び出すかを選択できます。 これらのパイプラインは、コミットやプル リクエストのマージによってリポジトリが更新されたときなど、さまざまな方法でトリガーできます。

このブログの例では、すぐに使用できる GitHub Actions と Linux コマンドを活用しています。 これらを使用して、インスタンス マネージャー API を介して NGINX インスタンス上の GitHub 管理の NGINX 構成ファイルを更新する方法を学習します。まず、 GitHub ドキュメントの手順に従って、リポジトリでアクションを実行するための新しい YAML を作成します。

アクションの秘密の設定

インスタンス マネージャーはさまざまな形式の認証をサポートしています。 この例では、基本認証方式を使用していますが、実稼働環境では OIDC 認証をプロビジョニングすることをお勧めします。

GitHub では、インスタンス マネージャーの資格情報をリポジトリに保存するのではなく、シークレットをリポジトリ変数として定義できます。 これらの変数はアクション環境からアクセスできますが、ログでは非表示になります。 次の手順に従って、Instance Manager のユーザー名とパスワード キーをシークレットとして保存し、API 呼び出しの認証に使用できるようにします。

ここでは、これらの変数をNMS_USERNAMEとNMS_PASSWORDに設定しています。

アクション変数の設定

同様に、YAML で定数変数を定義するのではなく、GitHub ユーザー インターフェースで管理できるようにそれらを分離すると便利です。 「変数」ページでは、すべてのリポジトリアクションにまたがる変数を定義する方法についての説明が見つかります。 この例では、この機会を利用して、インスタンス マネージャーの FQDN または IP ( NMS_HOSTNAME )、NGINX が実行されているシステムの識別子 ( SYSTEM_ID )、および更新する特定の NGINX インスタンスの識別子 ( INSTANCE_ID ) を定義します。

注記： これらの変数は例を簡略化するために設定しましたが、インスタンス マネージャー、システム、および NGINX の識別情報を他の方法で管理することもできます。 たとえば、リポジトリ内にさまざまなインスタンスに固有の構成を含むディレクトリを作成し、これらのディレクトリにシステム ID またはインスタンス ID の名前を付けることができます。 その後、YAML またはアクション スクリプトを変更して、ディレクトリ名を読み取り、対応するインスタンス上の構成ファイルを更新できます。

NGINX 構成を更新するためのインスタンス マネージャー REST API 呼び出しの詳細

インスタンス マネージャー構成更新REST API 呼び出しが機能するには、いくつかの主要コンポーネントが必要です。 YAML では、これらの各パラメータを定義し、適切な形式で API 呼び出しにパッケージ化する必要があります。

この例では、単一のインスタンスを更新するために API 呼び出しを使用します。 ただし、インスタンス マネージャー内でインスタンス グループを構成することもできます。 こうすることで、GitHub から新しい構成がプッシュされるたびに、グループ内のすべてのインスタンスを更新できるようになります。 詳細については、設定の公開に関するハウツーガイドを参照してください。

以下は、インスタンス マネージャーの構成更新REST API 呼び出しの内訳です。

https://{インスタンス マネージャー ホスト名}/api/platform/v1/systems/{システム ID}/instances/{インスタンス ID}/config' 
--header "accept: application/json" 
--header "Authorization: 基本的な {ログイン認証情報}"
--header 'Content-Type: application/json'
--data '{
"configFiles": '{
"rootDir": "/etc/nginx",
"files": [{
"contents": "{NGINX 構成ファイル}",
"name": "{システム上の構成ファイルへのパス}"
}]
},
"externalIdType": "{構成のソース}",
"externalId": "{コミット ハッシュ}",
"updateTime": "{タイムスタンプ}"
}'}'

URI パラメータ

• システム識別子 – NGINX が実行されているシステムを識別する一意のキー。 この例では、このデータは GitHub Actions Variables インターフェースで定義されています。
• NGINX インスタンス識別子 –システム上の特定の NGINX インスタンスを識別する一意のキー。 この例では、このデータは GitHub Actions Variables インターフェースで定義されています。

ヘッダーパラメータ

• 承認 – Instance Manager が API 呼び出しを認証するために使用する承認方法と Base64 でエンコードされた資格情報。 この例では、リポジトリに設定されたシークレットから取得される資格情報データを使用して基本認証を使用します。

JSONデータパラメータ

• configFiles –更新される設定ファイルの Base64 エンコードされた内容と、NGINX を実行しているシステム上の場所。また、NGINX 設定ファイルのルート ディレクトリへのパスも指定する必要があります。通常は/etc/nginxとして設定されます。
• externalIdType –インスタンス マネージャーに対して構成ファイルのソースを識別するラベル。 可能な値はgitまたはotherです。 この例では、このパラメータをgitにハードコードします。
• externalId –構成ファイルへの変更を識別する Git コミット セキュア ハッシュ アルゴリズム (SHA)。
• updateTime –現在の日付と時刻を%Y-%m-%dT%H:%M:%SZ形式で含む文字列。

Base64 エンコーディング

Instance Manager の API 仕様に対応するには、特定のデータを Base64 形式にエンコードして変換する必要があります。 既存の GitHub Actions でこれを実現するネイティブな方法はありませんが、YAML からアクセスできる Linux ツールに頼ることができます。

インスタンス マネージャーの資格情報

まず、以前にシークレットとして定義されたインスタンス マネージャーのログイン資格情報を参照して連結します。 次に、文字列を Base64 に変換し、Linux 変数 ( NMS_LOGIN ) としてエコーし、その結果を、Actions ランナーがアクセスできる定義済みの環境変数 ( GITHUB_ENV ) に追加します。

実行: echo "NMS_LOGIN=`echo -n "${{ secrets.NMS_USERNAME }}:${{ secrets.NMS_PASSWORD }}" | base64`" >> $GITHUB_ENV

タイムスタンプ

インスタンス マネージャー API では、特定の API ペイロードとともに特別な形式のタイムスタンプが送信される必要があります。 Linux のdateコマンドを使用して、その形式でタイムスタンプを作成できます。 前の例と同様に、構築された文字列を変数として Linux 環境に追加します。

実行: echo "NMS_TIMESTAMP=`date -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV

NGINX 構成

次に、管理する予定の NGINX 構成をリポジトリに追加します。 GitHub リポジトリにファイルを追加する方法は多数あります。 詳細については、GitHub のドキュメントのこのガイドに従ってください。 この例に従って、インスタンスのディレクトリ構造をミラーリングするディレクトリ構造を GitHub リポジトリに作成できます。

以下の YAML エントリは、リポジトリから構成ファイルを読み取り、その内容を Base64 にエンコードし、結果を前と同様に環境変数に追加します。

実行: echo "NGINX_CONF_CONFIG_FILE=`cat nginx-server/etc/nginx/nginx.conf | base64 -w 0`" >> $GITHUB_ENV

この例では、GitHub リポジトリ内のすべての構成ファイルに対してこれを繰り返します。

すべてをまとめる

最後に、GitHub のサンプルリファレンス実装を使用して、学習した内容を実用的な YAML ファイルにまとめることができます。 ファイルに定義されているように、ユーザーがコミットまたはプル リクエストを通じてリポジトリを更新するたびに、関連付けられているすべての GitHub Actions スクリプトが実行されます。 YAML の最後のエントリは、インスタンス マネージャーが関連するすべての構成ファイルを更新するために必要なデータを含む適切な API 呼び出しを行うcurlコマンドを実行します。

注記： YAML で複数行の実行エントリ ( run: | ) を使用してcurlコマンドを実行します。これにより、YAML インタープリターはエントリのパラメーター部分でコロン「:」をテキストとして扱うように指示されます。

名前： GitHub と GitHub Actions を使用した NGINX 構成の管理 
# ワークフローが実行されるタイミングを制御します 
on: 
# プッシュまたはプル リクエスト イベントでワークフローをトリガーしますが、"main" ブランチに対してのみトリガーします 
push: 
branches: [ "main" ] 
pull_request: 
branches: [ "main" ] 

# このワークフローを [アクション] タブから手動で実行できるようにします 
workflow_dispatch: 

# ワークフロー実行は、順次または並行して実行できる 1 つ以上のジョブで構成されます 
jobs: 
# このワークフローには、"build" という 1 つのジョブが含まれています 
build: 
# ジョブが実行されるランナーのタイプ 
runs-on: ubuntu-latest 

# ステップは、ジョブの一部として実行される一連のタスクを表します 
steps: 
# $GITHUB_WORKSPACE の下のリポジトリをチェックアウトして、ジョブがアクセスできるようにします 
- uses: actions/checkout@v4 

- 名前： NMS API ログイン認証情報の環境変数を設定します 
実行: echo "NMS_LOGIN=`echo -n "${{ secrets.NMS_USERNAME }}:${{ secrets.NMS_PASSWORD }}" | base64`" >> $GITHUB_ENV 

- name: NMS API タイムスタンプの環境変数を設定します 
実行: echo "NMS_TIMESTAMP=`date -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV 

- 名前: base64 エンコードされた設定ファイルの環境変数を設定します 
実行: echo "NGINX_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/nginx.conf | base64 -w 0`" >> $GITHUB_ENV 

- 名前: base64 エンコードされた設定ファイルの環境変数を設定します 
実行: echo "MIME_TYPES_CONFIG_FILE=`cat app-sfo-01/etc/nginx/mime.types | base64 -w 0`" >> $GITHUB_ENV 

- 名前: base64 エンコードされた設定ファイルの環境変数を設定します 
実行: echo "DEFAULT_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/default.conf | base64 -w 0`" >> $GITHUB_ENV 

- 名前: base64 エンコードされた設定ファイルの環境変数を設定します 
実行: echo "SSL_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/ssl.conf | base64 -w 0`" >> $GITHUB_ENV 

- 名前: インスタンス マネージャーへの API 呼び出し 
実行: | 
curl --location 'https://${{ vars.NMS_HOSTNAME }}/api/platform/v1/systems/${{ vars.SYSTEM_ID }}/instances/${{ vars.INSTANCE_ID }}/config' --header "accept: application/json" --header "Authorization: 基本 ${{ env.NMS_LOGIN }}" --header 'Content-Type: application/json' --data '{"configFiles": {"rootDir": "/etc/nginx","files": [{"contents": "${{ env.NGINX_CONF_CONFIG_FILE }}","name": "/etc/nginx/nginx.conf"},{"contents": "${{ env.MIME_TYPES_CONFIG_FILE }}","name": "/etc/nginx/mime.types"},{"contents": "${{ env.DEFAULT_CONF_CONFIG_FILE }}","name": "/etc/nginx/conf.d/default.conf"},{"contents": "${{ env.SSL_CONF_CONFIG_FILE }}","name": "/etc/nginx/conf.d/ssl.conf"}]},"externalIdType": "git","externalId": "${{ github.sha }}","updateTime": "${{ env.NMS_TIMESTAMP }}"}' 

NGINX リファレンス実装

ファイルが変更された後に構成更新API 呼び出しを実行するには、さまざまな方法があります。 GitHub Actions は GitHub を使用する人にとって最も便利な方法ですが、GitLab やスタンドアロンの Git 実装では機能しません。 これらのユースケースに対処するために、コマンド ラインからトリガーしたり、カスタム スクリプトから呼び出したりできる、コンパニオン シェル スクリプトのリファレンス実装を開発しました。

結論として、Instance Manager API の新しい拡張機能は、構成の更新、ロールバック、およびバージョン履歴を最新の分散型の方法で管理するための強力なツールを提供します。 拡張機能を GitHub などのサードパーティのテキスト ファイルおよびコード管理プラットフォームと組み合わせると、直感的な Web ベースのユーザー インターフェイスを通じて、追加のワークフロー、CI/CD、コラボレーション、問題追跡機能が有効になります。

あなたのご意見をぜひお聞かせください！ ぜひお試しいただき、コメント欄またはNGINX コミュニティ Slack チャンネルに参加してご感想をお聞かせください。