1はじめに
このチュートリアルの次の数章では、Terraformを使用してリソースを作成、変更および最後に破棄する冒険をガイドします。Terraformの体験に関する章で、この点について少し詳しく説明しますが、ここでは、トピックについて詳細に説明します。また、その方法について詳しく説明します。
他のOCIリソースをデプロイできる基礎となるOCIリソースであるVirtual Cloud Network (VCN)をデプロイすることで、Oracle Cloud Infrastructure (OCI)上でTerraformの使用を開始しましょう。
2前提条件
OCIアカウントの設定が必要です。新しいクラウド・アカウントを作成するには、ここをクリックしてください。
このチュートリアルではOCI Cloud Shellを使用します。このチュートリアルでは、Terraform (およびその他の多くのOCIインタフェースおよびツール)を迅速に操作するための優れたプラットフォームが提供されており、これらの多くのものが事前にインストールされ、すぐに利用できます。
3 Terraformコード
Terraformでは、Terraformコード(Terraform構成とも呼ばれる)を介して管理するリソースについて説明します。これらは、.tf拡張子を持つプレーン・テキスト・ファイルです。特定のプロジェクトのすべての.tfファイルは、単一のディレクトリに存在します。Terraformを実行すると、現在のディレクトリにある.tfファイルが読み取られます。各Terraformプロジェクトには独自のディレクトリが必要です。
これにより、Terraformコードの構成方法に関する柔軟性が大幅に向上します。すべてのコードを単一のファイルまたは複数のファイルに配置できます。単一のファイルが使用される場合、通常はmain.tfと呼ばれます。これは、小規模なプロジェクトでは問題ありませんが、多くのリソースを持つ大規模な環境で、少し困難で退屈な場合があります。
複数の異なるファイルにコードを分散する場合、通常、リソースは論理的にグループ化されます。これは、任意のカテゴリのリソースによる可能性がありますが、1つのお気に入りの方法では、リソース名と、そのリソース・タイプのすべてのリソースの位置を共有するファイル名を使用する方法があります。たとえば、すべてのコンパートメントをcompartments.tfで定義でき、すべてのセキュリティ・リストをsecurity_lists.tfなどで定義できます。ここでの重要なポイントは、環境について考え、コード自体を表す論理的な方法を識別することです。直感的かつ非常に簡単にナビゲートできます(プロジェクト内のリソースを見つけます)。
4新しいプロジェクトの開始
これは新しいプロジェクトになるため、このプロジェクトの新しいディレクトリを作成します。
cd ~
mkdir tf-101
cd tf-101
簡潔にするために、main.tfという1つのファイルのみを使用します。これは、非常に単純な環境を超えて推奨されませんが、それは私たちが今行っていることなので、これは問題ありません。
Terraformでは、コードに特定のファイル名を使用する必要はありません(.tfまたは.tfvars拡張子を持つ必要があります)が、少数のリソースしかないときにmain.tfが使用されるのが一般的です。簡易でない環境(多くのリソースを持つことが多い)場合は、様々なタイプのリソースまたはリソース・グループに対して異なるファイルが使用されるため、環境のナビゲートと管理が容易になります。Terraform探索チュートリアルで、リソースを独自のファイルに分離する方法を採用しました。
クラウド・シェル・セッション内から、main.tfを編集します(この新しいディレクトリにまだ存在しないため、これも作成されます):
nano main.tf
注: GNU nanoは使いやすいエディタとしてこのチュートリアルのテキストエディタとして使用されていますが、代わりにvi、vim、お気に入りのエディタを使用してください。
次のコードをmain.tf内に配置します。
terraform {
required_providers {
oci = {
source = "hashicorp/oci"
version = ">= 4.0.0"
}
}
}
provider "oci" {
region = "us-phoenix-1"
}
resource "oci_core_vcn" "tf_101" {
dns_label = "tf101"
cidr_block = "172.16.0.0/20"
compartment_id = "<your_compartment_OCID_here>"
display_name = "tf_101"
}
使用する値にcompartment_id属性を更新してください。最も基本的な実装では、テナンシOCIDを使用します(それを見つけるには、OCIドキュメントに記載されている指示に従ってください)。
上の例では、プロバイダ・リージョンがus-phoenix-1を使用するように構成されています。これをVCNをデプロイするOCIリージョンに更新します。使用可能なOCIリージョンのリストは、OCIドキュメントに記載されています。
今終わったことは別としておきましょう。
Terraformブロック
Terraformは拡張可能でモジュール化できるように構築されており、多数の異なるプラットフォームを管理するための単一のツールを提供します。プロバイダはTerraformの柔軟性とパワーを向上させ、TerraformがTerraformで管理される様々なプラットフォームにTerraformを適用できます。
プロバイダは、特定のプラットフォームの管理に使用されるTerraformインタフェースを定義し、プラットフォームAPIを直接操作する必要がありません。プロバイダは、Terraformインタフェースと基礎となるプラットフォームAPIの間で変換されます。
terraform {}ブロックは、TerraformレジストリからダウンロードするプロバイダをTerraformに通知します。この場合、Terraformは、OCIプロバイダをダウンロードするように指示されています(hashicorp/ociはregistry.terraform.io/hashicorp/ociの略です)。Terraformでは、デフォルトでパブリックTerraformレジストリが使用され、ローカル(プライベート)レジストリの使用もサポートされます(このチュートリアル・シリーズでは使用されないもの)。
バージョンは必須ではありませんが、機能がプロバイダのバージョン間で異なる可能性があるため、含めることをお薦めします。詳細は、Terraformプロバイダのドキュメントを参照してください。
プロバイダ
Terraformはこの構成を使用して、TerraformレジストリからOCIプロバイダを検索します。プロバイダはAPIキー(デフォルトのメソッド)を使用してOCIに認証します。追加の認証方法の詳細は、OCIプロバイダのドキュメントを参照してください。
前述のように、リソースをデプロイする正しいリージョンを指定してください。この例ではus-phoenix-1リージョンを使用していますが、必要に応じてこれを変更する必要がある場合があります。詳細は、OCIリージョンのドキュメントを参照してください。
リソース定義
Virtual Cloud Network (VCN)は、他の多くのOCIサービスに必要なOCIリソースです。これは、多くのOCIクラウド環境でのコアで基本的なリソースであり、論理ネットワーク定義を提供します。サブネット、コンピュート・インスタンス、ロード・バランサなどをデプロイする前に必要であるため、VCNの作成を開始します。ボーナスとして、VCNはOCIで1ペニーのコストはかかりません。そのため、OCIでTerraformを試すときに、料金が発生する可能性が最小限に抑えられます。
VCNを管理するには、oci_core_vcn Terraformリソースが使用されます。構成の例では、指定したコンパートメントにtf_101という名前のoci_core_vcnリソースが作成されます(コンパートメントOCIDを使用することを確認する必要があります)。CIDRブロックは172.16.0.0/20、DNSラベルはtf101、display_nameはtf_101です。Terraformリソース名はOCI表示名と一致する必要はありませんが、使い慣れた名前に対処しているインタフェース(API、OCIコンソール、Terraformなど)に関係なく、同じ名前を維持することをお薦めします。
compartment_id値を、使用するコンパートメントのOCIDに設定してください。
5 OCI認証の設定
OCI Cloud Shellの外部でTerraformを使用している場合、TerraformがOCI APIを使用してどのように認証されるかについて心配する必要があります。Cloud Shell内で実行することで、これらの詳細について心配する必要はありません。自動的に認証されます。
6構成の初期化
Terraformでは、適切に機能できるように様々なファイルが必要です。これは主に非表示になっているため、ニッティグリットの詳細でミールダウンする必要はありません。何が起こっているのかの概要を理解しておくことをお薦めします。Terraformに必要ないくつかの事項についてご紹介します。
Terraformはどのプロバイダとも出荷されないため、Terraformが最初に実行するのは、参照されているプロバイダを調べて、必要に応じてダウンロードすることです。この場合、OCI Terraformプロバイダを使用するようにTerraformに指示しましたが、このプロバイダはまだありません。これは、Terraform初期化プロセス中に処理されます。
Terraformでは、状態ファイルを使用してリソースの状態をキャッシュします。状態ファイルとTerraformコード・ベース(実装対象)およびOCIに実際の構成内容を比較します。3つのソースの違いを見ると、Terraformでは、構築されたまま(OCIに存在するもの)を必要なもの(コード内のもの)に取得する方法に関する攻撃の計画が明確に示されます。Terraform初期化プロセスでは、状態ファイルがチェックされます。見つからない場合は、先に進み、作成します。
次に、このプロジェクトでTerraformを初期化します:
$ terraform init
Initializing the backend...
Initializing provider plugins...
- Finding latest version of hashicorp/oci...
- Installing hashicorp/oci v4.45.0...
- Installed hashicorp/oci v4.45.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.
$
TerraformがOCIプロバイダをダウンロードし、環境用の新しい状態ファイルを作成しました。
7構成のフォーマットおよび検証
最初にmain.tf Terraformファイルを作成したとき、それは単なるプレーン・テキスト・ファイルでした。Terraformコードは単なるプレーン・テキストです。Terraformコードをほぼどこからでも簡単に作成して管理できます。
ほとんどの言語にはテキスト書式要件があります。Terraformは多くの書式設定プリファレンスに相当しますが、コードの書式を一貫して(特に行のインデント)保つことをお薦めします。適切なテキスト・エディタは、この負荷を最小限に抑えるのに役立ちますが、管理が困難である可能性もあります(特に、開発者のチームと協力する場合)。
プロバイダ・セクションは次のようになります。
provider "oci" {
region = "us-phoenix-1"
}
リージョン属性のインデントが適切でないことに注意してください。これは手動で変更できますが、かわりに、Terraformの組込み書式設定コマンドを使用してコードをクリーンアップします:
$ terraform fmt
main.tf
ここでmain.tfファイルを確認します。今、どのように賢くインデントされているのか。
$ cat main.tf
# ...
provider "oci" {
region = "us-phoenix-1"
}
# ...
Terraformコードをプログラム的に生成する方法は数多くありますが、Terraformコードは、多くの場合、人々によって作成および管理されます。人はミスを犯すが、それは悲惨かもしれない。包括的なTerraformコード構文違反を探す簡単な方法は、Terraformに組み込まれた検証を使用することです。これを実行中に表示するには、terraform validateを実行します。
$ terraform validate
Success! The configuration is valid.
これにより、Terraformコードの構文エラーについて説明します。誤ったCIDRや不正な名前などを使用しても何も実行しない場合、この検証は役立ちません。Terraform検証では、このような誤りを犯したことはわかりませんが、Terraformコードをリントして不適切な構文を探すのに最適な方法です。リリース・プロセス(自動化パイプラインを使用)には当然の価値があります。
8 Terraformプランの表示
これまでのところ、Terraformには必要なもの(OCIプロバイダ、状態ファイルなど)があり、コードは適切にフォーマットされており、コードが正確であるという自信が高レベルです。もう1つ踏み込んで、仕事の安全を守る。環境をデプロイするために実行する必要があると思われることをTerraformに確認します。これは、terraform planを実行して行います。
$ terraform plan
An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
+ create
Terraform will perform the following actions:
# oci_core_vcn.example will be created
+ resource "oci_core_vcn" "tf101" {
+ cidr_block = "172.16.0.0/20"
+ cidr_blocks = (known after apply)
+ compartment_id = "ocid1.compartment.oc1..<sanitized>"
+ default_dhcp_options_id = (known after apply)
+ default_route_table_id = (known after apply)
+ default_security_list_id = (known after apply)
+ defined_tags = (known after apply)
+ display_name = "tf101"
+ dns_label = "tf101"
+ freeform_tags = (known after apply)
+ id = (known after apply)
+ ipv6cidr_block = (known after apply)
+ ipv6public_cidr_block = (known after apply)
+ is_ipv6enabled = (known after apply)
+ state = (known after apply)
+ time_created = (known after apply)
+ vcn_domain_name = (known after apply)
}
Plan: 1 to add, 0 to change, 0 to destroy.
------------------------------------------------------------------------
Note: You didn't specify an "-out" parameter to save this plan, so Terraform
can't guarantee that exactly these actions will be performed if
"terraform apply" is subsequently run.
$
出力を見ると、Terraformは、OCIテナンシの現在の状態と指定したTerraformコードに基づいて、提案された内容を正確に提供します。
+は、予想されるVCNリソースを追加することを意味します。この単純な例(1つのVCNを作成する)には多少あるように見えますが、変更を行う前に、Terraformが提案する内容を確認することをお薦めします。
9インフラストラクチャの作成
terraform applyを実行して、main.tfで定義したVCNを作成します:
$ terraform apply
An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
+ create
Terraform will perform the following actions:
# oci_core_vcn.example will be created
+ resource "oci_core_vcn" "tf101" {
+ cidr_block = "172.16.0.0/20"
+ cidr_blocks = (known after apply)
+ compartment_id = "ocid1.compartment.oc1..<sanitized>"
+ default_dhcp_options_id = (known after apply)
+ default_route_table_id = (known after apply)
+ default_security_list_id = (known after apply)
+ defined_tags = (known after apply)
+ display_name = "tf101"
+ dns_label = "tf101"
+ freeform_tags = (known after apply)
+ id = (known after apply)
+ ipv6cidr_block = (known after apply)
+ ipv6public_cidr_block = (known after apply)
+ is_ipv6enabled = (known after apply)
+ state = (known after apply)
+ time_created = (known after apply)
+ vcn_domain_name = (known after apply)
}
Plan: 1 to add, 0 to change, 0 to destroy.
Do you want to perform these actions?
Terraform will perform the actions described above.
Only 'yes' will be accepted to approve.
Enter a value:
Terraformでは、インフラストラクチャを作成する前にプロンプトが表示されます。yesと入力して確認します。
# ...
Do you want to perform these actions?
Terraform will perform the actions described above.
Only 'yes' will be accepted to approve.
Enter a value: yes
oci_core_vcn.example: Creating...
oci_core_vcn.example: Creation complete after 5s [id=ocid1.vcn.oc1.phx.<sanitized>]
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
Terraformは、terraform planの実行時に確認した内容を基本的に示します。さらに、続行するかどうかを確認するプロンプトが表示されます(これにより、変更を行う前に最終レビューを受けることができます)。
ボイラ!これで終わりです。エラーがなく、すべてが正常にデプロイされました。
州を見る
Terraformは、Terraform構成で定義されていない属性を含む、状態ファイル内の各リソースの状態を追跡します。terraform showを実行して、VCNの状態を表示します。
$ terraform show
# oci_core_vcn.example:
resource "oci_core_vcn" "tf101" {
cidr_block = "172.16.0.0/20"
cidr_blocks = [
"172.16.0.0/20",
]
compartment_id = "ocid1.compartment.oc1..<sanitized>"
default_dhcp_options_id = "ocid1.dhcpoptions.oc1.phx.<sanitized>"
default_route_table_id = "ocid1.routetable.oc1.phx.<sanitized>"
default_security_list_id = "ocid1.securitylist.oc1.phx.<sanitized>"
defined_tags = {}
display_name = "tf101"
dns_label = "tf101"
freeform_tags = {}
id = "ocid1.vcn.oc1.phx.<sanitized>"
state = "AVAILABLE"
time_created = "2021-02-09 00:08:46.373 +0000 UTC"
vcn_domain_name = "tf101.oraclevcn.com"
}
$
ここには、Terraformコードで指定したより多くの情報があります。たとえば、OCIは、作成時にOCI識別子(OCID)をVCNに割り当てます。VCN OCIDは、構成で定義していない場合でも、id属性として状態ファイルに表示されます。
Terraformには、状態ファイル内の要素を追加または削除するメカニズムがありますが、直接変更しないでください。
10トラブルシューティング
terraform validateが成功し、適用がまだ失敗した場合、一般的なエラーが発生する可能性があります。問題を解決するには、次のトラブルシューティング・ステップを参照してください。
リージョンが無効です
terraform applyの実行時に次のエラーが表示された場合、無効な(存在しない)リージョン名を使用した可能性があります。
oci_core_vcn.tf_101: Creating...
Error: Post https://iaas.us-does-not-exist-1.oraclecloud.com/20160918/vcns: x509: certificate signed by unknown authority
on main.tf line 18, in resource "oci_core_vcn" "tf_101":
18: resource "oci_core_vcn" "tf_101" {
有効なリージョンを使用していることを確認してください。使用可能なOCIリージョンのリストは、OCIドキュメントに記載されています。
登録解除済リージョン
有効なリージョンを使用しようとしているが、テナンシがサブスクライブされていない場合に、次のエラーが発生する可能性があります。
$ terraform apply
# ...
oci_core_vcn.tf_101: Creating...
Error: Service error:NotAuthenticated. The required information to complete authentication was not provided or was incorrect.. http status code: 401. Opc request id: <sanitized>, The service for this resource encountered an error. Please contact support for help with that service
on main.tf line 18, in resource "oci_core_vcn" "tf_101":
18: resource "oci_core_vcn" "tf_101" {
無効な地域であるとは言えません。ただし、サブスクライブしていないリージョンと通信しようとしているため、OCIはユーザーを正しく認証できません。
不正なリソース属性
このシナリオは、属性を無効の値に設定しようとしたときに発生する可能性があります。
$ terraform apply
# ...
oci_core_vcn.tf_101: Creating...
Error: Service error:InvalidParameter. The requested CIDR 172.16.300.0/20 is invalid: unable to parse.. http status code: 400. Opc request id: <sanitized>
on main.tf line 18, in resource "oci_core_vcn" "tf_101":
18: resource "oci_core_vcn" "tf_101" {
問題を見つけ、意味のあるメッセージを返しました!計画(はいと言われる前の部分)がこれを捕捉しなかったことに注目してください。無効な属性値を設定することはできますが、属性が適用されるまで捕捉できません(計画はここではヘルプにならない場合があります)。
11次のステップ
Terraformを使用して新しいOCIリソースを作成する方法を確認できました。次に、Terraformを使用してOCIインフラストラクチャを変更する方法を学習します。
