OpenAPIを使用してカスタムTerraformプロバイダーを自動的に作成する方法

OpenAPIを使用してカスタムTerraformプロバイダーを自動的に作成する方法

つまり、Terraformプロバイダーの作成(または既存のプロバイダーのアップグレード)を行う必要があります。 プロジェクトの準備のために調査を行うと、「これは、APIのクライアント用にTerraform固有のラッパーを開発しているように見えます」とゆっくりと気づき始めます。

特に難しいことではありませんが、面倒なようです。

これを構築するためのより良い方法はありますか? たぶん、モジュール化して自動化できるものですか? 実際に実装するのに刺激的な方法はありますか?

それがあなたに話しかけるなら、あなたは私の同僚や私とそれほど違いはありません。 もっと良いものが欲しかった。 何か面白い。 メンテナンスが簡単で、すばやく拡張できるもの。

この記事では、次のことを行います。

  • OpenAPI仕様ファイルに基づいて自動生成されたコードを使用してTerraformプロバイダーを構築する方法について詳しく説明します。
  • コードのすべての行を順を追って説明するわけではありません。
  • 可動部分を理解できるように、コードのすべての主要コンポーネントについて説明します(さらに、コードには非常に多くの有用なコメントがあります)。
  • これを独自のAPIに適用するためのフレームワークを提供します。

この記事を最大限に活用するには、次の点に注意してください。

  • 前提条件を軽視しないでください。 この記事で使用されている各テクノロジーの一般的な理解が得られないと、すぐに迷子になります。
  • 別のウィンドウで選択したIDEで開いている付属のリポジトリを使用して、この記事を読んでください。 あなたはできる ここでリポジトリを見つけます.
  • コードを試して、この記事の最後に提案されている演習を行ってください。
  • 最後に、これを一度に実行することを期待しないでください。 カバーする資料がたくさんあるので、辛抱強く、情報を吸収する時間を取ってください。

それでは、いくつかの基本をカバーしましょう。

Terraformとは何ですか?

Terraform はオープンソースの Infrastructure as Code ツールです ハシコープが開発。 宣言型言語を使用して、クラウドとオンプレミスのリソースを安全かつ効率的に構築、変更、およびバージョン管理するために使用されます。 本質的に AWS CloudFormation に似ていますが、AWS だけに限定されません。

あなたはこれからもっと学ぶことができます Terraformの紹介。 次に、次のいずれかを試してください はじめにプロジェクト (デフォルトはAWSですが、ページの左側の列でDockerなどの他のオプションを選択できます。

Terraformプロバイダーとは何ですか?

プロバイダーが何かわからない? さて、あなたはそれを構築する前にそれを理解する方が良いです!

簡単に言うと、プロバイダーはTerraformのプラグインのバージョンです。 あなたはそれらについてもっと学ぶことができます HashiCorpから.

リソースとデータソースとは何ですか?

リソースとデータソースはTerraformの基本的なコンポーネントであり、プロバイダーを構築する前に理解することが非常に重要です。 リソースについて学ぶ こちらをクリックすると、ツールが開きます。。 データソースについて学ぶ こちらをクリックすると、ツールが開きます。.

どのようにプロバイダーを作成しますか? 注意すべき重要な設計原則はありますか?

あなたはこれ以上のことを学ぶことができます HashiCorpのプラグイン開発ページ.

OpenAPI仕様とは何ですか?

以前はSwagger仕様として知られていましたが(そのように参照されている場合があります)、OpenAPI仕様はRESTAPIを記述する正式な方法です。 Swaggerチームから詳細を学ぶことができます こちらをクリックすると、ツールが開きます。。 あなたがそんなに傾いているなら、あなたは仕様自体を覗き見することもできます ページ をご覧ください 最後に、LogicMonitorのAPI仕様を確認できます 右ここに.

Go-Swaggerとは何ですか?

Go-Swaggerは、GoコミュニティにSwagger2.0の実装を提供する素晴らしいGolangパッケージです。 これは主にGoテンプレートパッケージを使用して行われます。 このパッケージは非常に多くのことを実行しますが、主にAPIクライアントを生成する機能と、カスタムコード生成のサポート(ここでもGoテンプレートを使用)に関心があります。

Go-Swaggerについて詳しく知ることができます こちらをクリックすると、ツールが開きます。。 確認することが特に重要だと思われるセクションを次に示します。 仕様からのクライアント生成, カスタム生成カスタムテンプレート。 追加のクレジットについては、 スキーマ生成ルール。 最後に、リポジトリを見つけることができます こちらをクリックすると、ツールが開きます。.

Goテンプレートとは何ですか?

Goのテンプレートパッケージを使用すると、データ駆動型のテキスト出力(この場合はコード)を生成できます。 表記がわからない場合、Goテンプレートをダイジェストするのは非常に難しい場合があるため、ドキュメントを確認することを強くお勧めします。 こちらをクリックすると、ツールが開きます。。 手を汚したい場合は、gopheracademy.comにGoテンプレートの優れた紹介があります。 こちらをクリックすると、ツールが開きます。.

LogicMonitorポータルが必要ですか?

それはあなたの目標とあなたが私たちを信頼するかどうかに依存します🙂この記事で私たちが構築しているプロバイダーを完全にテストしたい場合は、LMポータルが必要になります。 プロバイダーは、実装しているプロセスを実行するために特定のポータルと通信する必要があります。 幸いなことに、LogicMonitorは 無料試用

新しいポータルを設定したら(またはすでにポータルを設定している場合)、いくつかのAPIトークンを生成する必要があります。 あなたはそれを行う方法を学ぶことができます こちらをクリックすると、ツールが開きます。.

これで、必ずしもこのプロバイダーをテストする必要がない場合(おそらく、プロセスを理解して独自のAPIに適用できるようにしたい場合)、LogicMonitorポータルは必要ありません。 この記事、プロバイダーのビルドプロセス、および付属のGitHubリポジトリのコードを確認しながら、多くのことを学ぶことができます。

インストールするテクノロジー

このプロジェクトの作業を開始するには、いくつかのツールをインストールしてセットアップする必要があります。

  • テラフォーム0.14.x
  • Go 1.16 (プロバイダープラグインを構築するため)
  • Go-Swagger v0.27.0 + (コードを生成するため)
  • 選択したコードエディター(Go拡張機能を備えたVS Codeに加えて、便利なGoテンプレートサポートとHashiCorp Terraform拡張機能をお勧めします)

なぜこのようにするのですか?

ああ、そうです、すべての中で最大の質問のXNUMXつです。

どうして?

LogicMonitor API用のTerraformプロバイダーをまとめるという任務を負ったとき、最初はより標準的なアプローチである手動実装を検討しました。 Go-Swaggerを発見したのは、デューデリジェンスの最中だった。

LogicMonitorAPI用のSDK/クライアントを手動で開発したくないことはわかっていたため、Go-Swaggerが最適なソリューションでした。

調査を続けると、かなり明白なことが明らかになりました。プロバイダーは、基本的に、Goで記述されたAPIクライアントのTerraform固有のラッパーにすぎません。

そのため、論点先取が行われました。そのAPIクライアントの作成を自動化できるのであれば、Terraformラッパーの作成も自動化してみませんか。 Go-Swaggerはカスタムコード生成をサポートしているため、飛躍することにしました。

福利厚生

このアプローチの主な利点は自動化です。

このプロジェクトに入ると、小規模から始めて、プロバイダーに機能を段階的に追加したいと考えていました。 さらに、既存のプロバイダー実装を調べた後、それらには多くの定型コードが含まれる傾向があることがわかりました(主に、あるオブジェクトから別のオブジェクトへのフィールドのマッピング)。

後で説明するように、このアプローチでは、APIのOpenAPI仕様を活用することで、プロバイダーを非常に簡単に拡張できます。 この(かなり大きな)仕様を個々の機能/コンポーネントに分割できます。 次に、機能を追加する必要があるときはいつでも、対応するコンポーネントをGo-Swaggerの入力仕様に追加するだけです。 これがまだ完全に意味をなさなくても心配しないでください。前進するにつれて明らかになります。

コスト

前提条件のセクションからすでに収集しているかもしれないので、このアプローチは複雑です! なじみのあるテクノロジーは数多くあり、それに加えて、生成されたコードを操作することは、公園を散歩することではありません。

否定的に聞こえるわけではありませんが、これはそれほど否定的なことではありませんでした。 実際、それは私たちの心の中で非常に前向きでした。 私たちは新しい挑戦と何か新しいことを学ぶ機会を探していました、そしてこのアプローチは完璧な解決策でした。

リポジトリを理解する

以下に、プロジェクトを構成するさまざまなディレクトリとファイルの概要を示します。 これは、これらの各コンポーネントの役割と責任を高レベルで理解するためのものです。 より詳細な情報はファイル自体にあります。 複雑な部分や、目的を理解するのが難しい部分を説明するために、コードに役立つコメントを追加しました。

/ MakefileMakefileは、主にコードを生成し、プロバイダーを構築してインストールするために使用されます。 また、開発プロセス中に役立ついくつかの代替ターゲットも含まれています。 主に、プロジェクト全体を完全にビルドするためのデフォルトのターゲット、またはGo-swaggerを介して実際にコードを生成せずに変更をテストするためのnogenターゲットのいずれかを実行する必要があります。
/config.ymlこの構成ファイルは、Go-Swaggerに実行方法と実行内容を指示するために使用されます。 これを説明することはこの記事の範囲外ですが、詳細についてはGo-Swaggerのドキュメントを参照してください。
/ templates /これは、カスタムコード生成に関連するすべてのテンプレートが存在する場所です。 Go-Swaggerは、config.ymlファイルを使用して、これらの各テンプレートを読み取り、それに応じてコードを生成します。
/templates/client/facade.gotmpl *ファサードテンプレートは、RESTAPIクライアントコードのメインエントリを生成します。 クライアントの構成、認証、および承認のための機能を定義します。 この例では、LogicMonitor REST APIを使用してクライアント認証を容易にする関数LMv1Authを定義します。テンプレートの出力は、client/logic_monitor_r_e_s_t_api_client.goにあります。 
/templates/client/client.gotmpl *クライアントテンプレートは、各Swaggerグループのクライアントコードエントリポイントを生成します(グループは仕様ファイルのタグに相当します)。 各グループに関連付けられた特定の機能を定義します。 一般的に、グループのCRUD操作を作成します。
/templates/datadump.gtplこのテンプレートは最終的な実装には何も提供しませんが、テンプレートに渡されるデータのデバッグに役立つため、このテンプレートを含めました。 Goテンプレートを使用した開発は、何を処理する必要があるかを正確に理解するのが困難になる可能性があります。 このテンプレートは、簡単に見つけることができます。 出力ファイルは見た目が特にきれいではありませんが、ピンチで間違いなく役立ちます! Go-Swaggerを実行すると、このテンプレートの出力がdata_profile/ディレクトリに表示されます。
/templates/main.gtplすべてのプロバイダーには、Terraformがアクセスできるメインファイルが必要です。 これは、そのファイルを作成するテンプレートです。 これは(ほとんど)静的コードであるため、ここでは特別なことは何も行われていません。したがって、技術的には生のGolangファイルに置き換えることができます。 しかし、この方法の方が楽しいです。
/templates/provider.gtplすべてのプロバイダーはどこかで定義する必要があり、それは通常プロバイダー関数にあります。 このテンプレートは、その関数の生成、返されたプロバイダーのスキーマの定義、およびプロバイダーの構成方法の決定に重点を置いています。 私たちのプロバイダーは、API ID、APIキー、および会社名(リクエストをルーティングするポータルを決定するため)を必要とします。 プロバイダーは、異なる資格情報や構成を使用する可能性があります。
/templates/resources.gtplTerraformプロバイダーの設計原則を読んだ後(まだ読んでいない場合は、上記の「プロバイダーをどのように構築しますか?」セクションを確認してください)、これまでにご存知のとおり、すべてのプロバイダーリソースは単一のAPIオブジェクトを表す必要があります。 この例では、出発点としてLogicMonitorデバイスAPIオブジェクトのみを使用しますが、この設計は、入力OpenAPI仕様にAPIオブジェクトを追加するだけで、新しいリソースを段階的に追加するのに役立ちます。 「なぜ?」で説明したようにセクションでは、これがこの設計を進めることを決定した主な理由のXNUMXつでした。 このテンプレートは、これらの各リソース構造体がどのように生成されるかを示しています。 これは、Terraform構成で定義された各リソースの作成、読み取り、更新、および削除メソッドと、対応するデータソースの読み取りメソッドを定義します。
/templates/schema.gtplこのテンプレートはスキーマオブジェクトの生成を担当します(Go-Swaggerにはすでにスキーマの概念があるため、より適切な用語がないため、XNUMXつを区別するためにschemataを使用しました)。 各Terraformリソースは構成可能なスキーマで表され、作成、更新、および読み取り操作のためのリソースデータ操作を可能にします。 スキーマオブジェクトは、キーが構成キーであり、値が構成値のスキーマを記述するマッピングです。 したがって、スキーマは、LogicMonitorAPIに対してデータを読み書きするためのインターフェイスと考えることができます。 まず、Terraform構成ファイルで定義されたリソースデータが、構成された値を使用してスキーマモデル構造体に変換され、次にLogicMonitor APIに送信されて、リソースが作成または更新されます。 リクエストが成功した場合、または既存のリソースが単に取得されている場合、応答データは上記のLogicMonitor APIに送信された同じモデル構造体に変換され、その値は、で定義された基になるリソースデータを作成または変更するために使用されます。 Terraform構成。
/templates/tf_responses.gotmpl *tf_responseテンプレートは、特定のエンドポイントから期待される応答構造を定義します。 また、応答を支援するためのさまざまなヘルパー関数も含まれています。
/templates/utils.gtpl多分それはコードの臭いです、多分そうではありません。 いずれにせよ、ほとんどのリポジトリには、ある種のユーティリティファイル(または多数!)があります。 Utilsテンプレートは、プロバイダーのさまざまな領域で呼び出される、ハードコードされたヘルパー関数です。
/ spec_files /spec_filesディレクトリには、LogicMonitorOpenAPI仕様ファイルに関連するすべてのものが含まれています。 Go-Swaggerは、コードを生成するときにこのディレクトリから仕様を読み取ります。
/ spec_files / components /このサブディレクトリには、個々のコンポーネントの仕様が格納されています。 このディレクトリには、device.jsonとdashboard.jsonのXNUMXつのファイルが含まれていることがわかります。 これらは、LogicMonitorOpenAPI仕様全体から関連情報を取得して自分で作成する必要のあるファイルです。 これらには、これらの各LogicMonitor APIオブジェクト(デバイスとダッシュボード)に関連する仕様データ(定義、パス、およびタグ)が含まれています。 最終的に、仕様をコンポーネントに分割することで、開発プロセスが簡素化されました。 LogicMonitor仕様全体を含めた場合、Go-Swaggerは、LogicMonitorエコシステム内のすべてのAPIオブジェクトとエンドポイントのサポートコードを生成します。 そのほとんどを使用しないので、このように仕様ファイルをスリム化することで、多くのノイズとかさばりをカットすることができました。 また、将来的にプロバイダーに機能を段階的に追加するという私たちの目標にも役立ちました。 新しいコンポーネントを追加する場合は、関連する仕様を抽出して、新しいコンポーネントファイルに追加するだけです。 後で、これらのコンポーネントから新しい仕様ファイルを作成する方法について説明します。
/ spec_files / ref /ここに参照仕様書があります。 この場合、lm-openapi-spec.jsonファイルが含まれているだけです。 このスペックファイルは、LogicMonitorのOpenAPI仕様全体です。 その内容を「OpenAPI仕様とは」に記載されているLogicMonitorAPI仕様URLの出力と比較することで確認できます。 その上。 このファイルが何であるかがわかったので、Componentsサブディレクトリ内のファイルと比較して、それらがどのように作成されたかを確認できます。 これは非常に簡単なカットアンドペースト操作ですが、データがどのように構造化されているかを調べる価値のある取り組みです。
/spec_files/current.jsonこれは、プロバイダーの生成に使用している現在のスペックファイル、つまりファイル名のjson表現です。 なんて独創的! これをComponentsディレクトリのdevice.jsonファイルと比較すると、これらXNUMXつのファイルがほぼ同じであることがわかります。 唯一の違いは、「externalDocs」、「info」、「securityDefinitions」などの定型仕様です。 それらがどこから来るのかについては、次のセクションで説明します。
/spec_files/createSpecFile.pyこれは、すべてをまとめたファイルです。 このスクリプトは、components/ディレクトリ内の任意の数のコンポーネントファイルから有効な仕様ファイルを生成します。 ボイラープレート仕様(上記のcurrent.jsonセクションで説明したものなど)を使用してベースライン仕様JSONを作成し、各コンポーネントからエントリを繰り返し追加して、重複するエントリを作成しないようにします。 今すぐ自分で実行してみることができますが、注意してください。 引数なしで実行すると、ダッシュボードコンポーネント情報がcurrent.jsonファイルに追加されます。 次に、プロジェクトをビルドしようとすると、エラーが発生する可能性があります(テンプレートを調整することでエラーを修正できます。詳細については、この記事の最後にある「提案された演習」セクションを参照してください)。 このスクリプトを実行するときにダッシュボードコンポーネントを除外する方法を確認するには、ファイルを開いて読んでみてください。 このファイルを実行するにはPython3が必要であることに注意してください。
/ logicmonitor /LogicMonitorディレクトリには、プロバイダー用に生成されたコードが含まれています。 これは、resources /、schemata /、utils /、およびprovider.goファイルに分割されます。これらのファイルについてはすでに説明しました。
/クライアント/これは、カスタムコード生成をまったく行わなかった場合のGo-Swagger出力の(ほぼ)ものです。 これで、LogicMonitorクライアント/SDKになります。 これはほとんど標準のGo-Swagger出力であるため、ここで確認できることはあまりありません。
/ models /このディレクトリには、Go-swaggerプロセスによって生成されたモデルが含まれています。 これらのモデルは、入力仕様ファイル(current.json)にリストされている定義を表したものです。
/テスト/ここには、テストに使用できるテストTerraform構成ファイルと、テスト中に便利なMakefileがあります。

太字のファイル/ディレクトリ =リポジトリのルートレベルで見つかったアイテム
灰色の背景行=これらのディレクトリの子アイテム

*=ベースのGo-Swaggerテンプレートに対応するテンプレート。 これらは、APIに合うように少し変更されています。 このフレームワークを独自のAPIに適用する場合は、少なくとも開始するために、config.ymlを変更して、私たちのテンプレートではなく元のテンプレートを指すようにする必要があります。

プロバイダーの構築

これと同じ情報はプロジェクトリポジトリのREADMEにありますが、便宜上、以下を含めました。 動作しない場合は、この記事の公開後にリポジトリが更新されているかどうかを確認してください。

  1. リポジトリのクローンを作成します(ここでは、SSHを使用)。
$ git clone [email protected]:logicmonitor/automated-terraform-provider.git
  1. リポジトリのディレクトリに移動し、プロバイダーを構築します。
$ cd automated-terraform-provider/
$ make
  1. 次に、makefileがコードを生成し、バイナリをビルドして、Terraformプラグインディレクトリにコピーします。

ビルドエラーが発生しなかったと仮定すると、テストを開始する準備が整いました。

プロバイダーのテスト

Makefileを実行した後、プロバイダーをインストールする必要があります。 つまり、プロバイダーを使用してTerraform構成ファイルを作成し、プロバイダーを初期化して実行するだけです。

これを支援するために、テストに使用できるtest.tfTerraform構成ファイルを含むtest/ディレクトリがすでに含まれています。 LogicMonitorプロバイダー定義内のapi_id、api_key、およびcompanyの値を入力して、必ずtest.tfファイルを編集してください。 APIキーとIDの生成の詳細については、「前提条件」セクションを参照してください。

実際にテストを実行するために、開発プロセス中に役立つと思われる便利なコマンドを提供するMakefileを含めました。

きれいにする

Terraformプラグインディレクトリに新しいプロバイダーをインストールした後、それを初期化する必要があります。 terraforminitを実行することでそれを行うことができます。 ただし、Terraformは、初期化後にプロバイダーのバージョンをロックします。 これにより、変更を加えることができなくなります。 たとえば、プロバイダーを初期化し、バージョンを変更せずにプロバイダーに変更を加えると、Terraformは変更されたバージョンを初期化できなくなり、エラーが表示されます。

開発中は、実際にバージョン番号を変更せずに段階的な変更を行う必要があることが多いため、この種の動作が問題になる可能性があります。 これを修正するために、クリーンなターゲットを追加しました。 ロックファイルを削除し、リポジトリ内の最新のビルドを使用してプロバイダーを再初期化します。

出力例

$ make clean

rm .terraform.lock.hcl
terraform init

Initializing the backend...

Initializing provider plugins...
- Finding logicmonitor.com/com/logicmonitor versions matching "0.1.0"...
- Installing logicmonitor.com/com/logicmonitor v0.1.0...
- Installed logicmonitor.com/com/logicmonitor v0.1.0 (unauthenticated)

Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

計画を立てて適用する

これらのXNUMXつのターゲットはあまり紹介する必要はありません。 必要に応じて参照用に計画を保存するために、ファイルlm.tfstateを使用しながら、それぞれterraformplanおよびterraformapplyステップを実行します。

出力例:計画

$ make plan

terraform plan -out=lm.tfstate

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create
<= read (data resources)

Terraform will perform the following actions:

  # data.logicmonitor_device.my_devices will be read during apply
  # (config refers to values not yet known)
<= data "logicmonitor_device" "my_devices"  {
      + filter = "displayName~\"Cisco Router\""
      + id     = (known after apply)
    }

  # logicmonitor_device.my_device will be created
  + resource "logicmonitor_device" "my_device" {
      + auto_properties                = (known after apply)
      ...
    }

Plan: 1 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + devices = {
      + auto_balanced_collector_group_id = null
      ...
    }

------------------------------------------------------------------------

This plan was saved to: lm.tfstate

To perform exactly these actions, run the following command to apply:
    terraform apply "lm.tfstate"

出力例:適用

$ make apply

terraform apply lm.tfstate
logicmonitor_device.my_device: Creating...
logicmonitor_device.my_device: Creation complete after 1s [id=6858]
data.logicmonitor_device.my_devices: Reading...
data.logicmonitor_device.my_devices: Read complete after 0s [id=6858]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

The state of your infrastructure has been saved to the path
below. This state is required to modify and destroy your
infrastructure, so keep it safe. To inspect the complete state
use the `terraform show` command.

State path: terraform.tfstate

Outputs:

devices = {
  "auto_balanced_collector_group_id" = 0
  ...
  }

デフォルト

デフォルトでは、Makefileはクリーンに実行され、計画されてから適用されます。

結果

テストを実行すると、LogicMonitorポータルに新しいデバイスが表示されます。

LogicMonitorのCiscoルーターダッシュボード

これで、test.tfファイルを編集して、新しいデバイスに変更を加えることができます。 または、terraformdestroyコマンドを実行してデバイスを削除することもできます。

プロバイダーの開発

これで、1。プロバイダーの生成に使用されるテンプレートを調べて理解しました。2。プロバイダーコードを生成しました。3。プロバイダーをテストしました。自信を持って独自の変更を行うことができます(詳細は次のセクションで説明します)。

その前に、LogicMonitorプロバイダーの開発中に非常に役立つヒントがあります。

テンプレートをすぐに微調整するのではなく、最初に生成されたソースコードに直接変更を加えることをお勧めします。 動作を開始してテストし(ここで、ルートディレクトリMakefileのmake nogenターゲットが非常に役立ちます)、テンプレートを変更して、行った手動の変更を複製します。 さらに良いことに、手動で変更を加えてから、作業中のGitブランチにコミットすることができます。 これにより、生成されたコードに加えた変更を後で参照できるように安全に保つことができます。

変更がテストされ、機能し、Gitブランチに保存されたら、テンプレートファイルを変更する必要があります。 生成されたコードに変更をコミットしたので、テンプレートファイルに変更を加えてコードをビルドする(ルートディレクトリMakefileのmakeビルドターゲットを使用する)方がはるかに安全です。 テンプレートファイルを変更し、コードを生成して、gitdiffのようなdiffコマンドを実行します。 これで、新しいテンプレートファイルが生成している変更を正確に識別できます。

機能の追加

ふぅ! それはたくさんの情報です! 一歩下がって、プロバイダーに機能を追加する高レベルのプロセスを確認しましょう。

  1. 追加するコンポーネントを特定します。
  2. 元のスペックファイルからコンポーネントjsonOpenAPIスペックファイルを手動でビルドします。
  3. createSpecFile.pyを実行して、current.jsonを新しいコンポーネントで更新します。
  4. makeを実行してコードを生成し、プロバイダーをビルドしてインストールします。
    • 生成エラーが発生する可能性があります。その場合、少なくともすべてのコードを出力するには、テンプレートに変更を加える必要があります。
    • ビルドエラーが発生する場合もあります。その場合は、生成されたコードを手動で変更して機能させることにより、前に概説したプロセスを使用し、適切なテンプレート内でそれらの変更を模倣する必要があります。
  5. それが機能していることを確認するためにそれをテストします。

提案された演習

これらすべてを理解できたので、実際に理解を深め、いくつかの追加の演習を通じて開発サイクルがどのように見えるかを示しましょう。

インポート機能を追加する

インポートは、中途半端なTerraformプロバイダーにとって重要な機能です。 自分で追加できるように、未実装のままにしておきます。 インポート機能の開発について詳しくは、こちらをご覧ください。 https://www.terraform.io/plugin/sdkv2/resources/import

プロバイダーの展開:ダッシュボード

既製のダッシュボードコンポーネントスペックファイルをGitHubリポジトリに含めましたが、その値はcurrent.jsonファイルに含まれていませんでした。 spec_filesディレクトリでcreateSpecFile.pyファイルを実行して追加し、プロバイダーを再構築してみてください。

正常にビルドされますか? ダッシュボードの追加をテストするとき、ダッシュボードリソースを使用してダッシュボードを作成、編集、および削除できますか? ダッシュボードのデータソースは正しく機能していますか?

問題が発生した場合は、自動化されたterraform-providerリポジトリに「adding-dashboards」というブランチがあり、どのように機能するかを示します。

プロバイダーの拡大:あなたの選択!

前述のように、このアプローチの主な利点のXNUMXつは、必要に応じてプロバイダーに新しいコンポーネントを簡単に追加できることです。 上記のダッシュボードの演習で簡単な例を取り上げましたが、今ではそれを選択できます。

参照LMOpenAPI仕様ファイルのさまざまな定義を調べて、興味のある定義があるかどうかを確認してください。 一部のオプション:管理者(LMのユーザーオブジェクト)、AlertAck、アラートルール、チェーン、コレクター、デバイスグループ、ダッシュボードグループ、ロール、SDT、およびWebCheck。

コンポーネントスペックファイルを作成するための全体的なプロセスは、リソースとなるオブジェクト(つまり、デバイス)を識別し、そのオブジェクトに関連するすべての定義(つまり、デバイス、DevicePaginationResponse、ErrorResponse、およびNameAndValue)をコピーし、すべてのパスをコピーすることです。必要(CRUDおよびgetListパス-つまり、GET / POST / device/devicesおよびGET/DELETE / PUT / device / devices / {id})、最後に適切なタグをコピーします。 これらのアイテムはすべて、spec_filesディレクトリのdevice.jsonファイルとdashboard.jsonファイルで確認できます。


最後に、選択したTerraformリソースにマップするフィールドをオブジェクトの定義に追加する必要があります。 追加するフィールドは「example」であり、値は「isResource」である必要があり、追加するリソースを表すオブジェクトの定義にのみ追加する必要があります。

例として、既存のコンポーネント仕様ファイルを確認できます(つまり、DevicePaginationResponse定義ではなくデバイス定義)。 リソースであるオブジェクトは、標準のデータオブジェクトとは異なる方法で処理する必要があります。 リポジトリで「isResource」を検索して、XNUMXつの違いを確認してください。

ドキュメンテーション

Terraformがプロバイダーを追加するとき、ユーザーがプロバイダーを最大限に活用するのに役立つドキュメントがプロバイダーに付属することを期待しています。 このプロセスは「自動化」することもできます。 私たちのフレームワーク内では、これは通常、適切なフィールドの仕様ファイルにドキュメントを追加し、新しいテンプレート(またはXNUMXつ)内でそれらにアクセスすることを意味します。 要約すると、この演習では、仕様ファイルの変更(ドキュメントの追加)、ドキュメントの新しいテンプレートの追加、およびこれらの新しいテンプレートを含むようにconfig.ymlファイルの更新が必要です。
Terraformが期待するドキュメントについて詳しくは、こちらをご覧ください。 https://www.terraform.io/registry/providers/docs

独自のAPIに適用してください!

エンドツーエンドのプロセスを十分に理解したので、それを独自の製品のAPIに適用してみてください。 必要なのは、APIのOpenAPI仕様を使用する新しいcurrent.jsonを構築し、元のGo-Swaggerクライアントテンプレートに切り替えて、コードを生成することだけです。 テンプレートにいくつかの調整を追加して、独自のオブジェクトをより適切に処理すると、本格的なカスタムビルドのTerraformプロバイダーを手に入れることができます。

確かに、これらの各演習を完了すると、特定のAPI用のTerraformプロバイダーの生成を自動化するマスターになります。

このブログは、CarlosAlvarengaとNedImmingの貢献により、AdamJohnsonによって作成されました。