つまり、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の入力仕様に追加するだけです。 これがまだ完全に意味をなさなくても心配しないでください。前進するにつれて明らかになります。

コスト

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

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

リポジトリを理解する

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

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

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

プロバイダーの構築

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

1. リポジトリのクローンを作成します（ここでは、SSHを使用）。

$ git clone [email protected]:logicmonitor/automated-terraform-provider.git

2. リポジトリのディレクトリに移動し、プロバイダーを構築します。

$ cd automated-terraform-provider/
$ make

3. 次に、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ポータルに新しいデバイスが表示されます。

これで、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によって作成されました。