iT邦幫忙

2021 iThome 鐵人賽
DAY 13
0
DevOps

Terraform Workshop - Infrastructure as Code for Public Cloud 疫情警戒陪你度過 30 天系列 第 15 篇

Day 13-用了十幾天，總算回頭看 Language Syntax 文件

13th鐵人賽 terraform infrastructure as code devops azure
2056 瀏覽

  • 分享至 

  • xImage
    •  

本篇介紹 Terraform syntax，為何 .tf 內容是這個格式

課程內容與代碼會放在 Github 上: https://github.com/chechiachang/terraform-30-days

賽後文章會整理放到個人的部落格上 http://chechia.net/

追蹤粉專可以收到文章的主動推播

https://ithelp.ithome.com.tw/upload/images/20210901/20120327NvpHVr2QC0.jpg

lecture retrospective

寫到現在，應該都可以寫出能夠工作的 terraform。

到目前為止，課程對學生的期待是『能夠 google 到社群分享的 .tf，並且會正確的複製貼上，轉化成自己的 .tf 內容』。

做到現在，想必也累積了一些問題。之前的內容，或許有些邏輯還不是很清楚，課程都簡單帶過，許多複雜的部分略過不提;目的先讓學生對語言有個基礎的了解，有實際操作的經驗跟手感，之後做深入的討論時，更能理解內容。

接下來要繼續深入，我們會花一點篇幅，回頭細講細節，把關防文件細細地走過

Terraform syntax

先從這篇出發Terraform Syntax，介紹 Terraform syntax。這裡又分為兩部分：一個是Configuration Syntax，另一個是Json Configuration Syntax。乍看之下有點疑惑，json 是從哪跑出來的？我們可以從幾個角度看這件事：

Terraform 底層 low-level syntax 是由 Hashicorp Configuration Language 定義的

  • HCL 又是什麼東西？不精確的說，他就是過去幾堂課我們寫的 .tf 的內容語法
    • 精確的說應該反過來，.tf 的語法底層是由 hcl 定義
  • Hashicorp 當初推出 HCL 的目的，而不直接用 json 或 yaml
    • 許多高階程式語言(ex. ruby, golang, c...) 不易描述多階層結構資料(ex. json)，與宣告式(declarative)的資料內容
      • 而這兩者在定義 infrastructure 等 configuration / state 時很重要
      • 這也是許多應用的 conf 不會用高階語言來直接定義，例如：
        • kubernetes 與 CNCF 專案使用 yaml / json
        • nginx.conf 的語法很有趣，對 hcl 的設計影響很大
    • json 作為 data-interchange format，設計本身已經是人類可讀，語法結構非常清晰，也是泛用的 api 溝通格式
      • 然而太複雜的結構可讀性變差。例如 json key 深度越多層，可讀性大幅下降，必須使用外部 tool parse （ex. 本課程愛用的 jq）
      • json 不易描述更多增益功能性語法，例如：沒有 native comment，loop，data type，escape...等
      • yaml 也是有同樣的問題
  • HCL 依循 key-value 與階層 block {} 設計(類似 json)
  • 並增加許多功能性的語法定義，讓使用 HCL 語言的應用（ex. terraform ）

這裡要講古一下：歷史來看， hashicorp 在 2014 年發表 terraform，同時也釋出 hcl 語言 spec

  • hashicorp 2014 前的產品採用不同的 conf
    • vagrant 也是 configuration 工具採用 ruby
    • packer 使用 json。然而隨著 hcl 逐漸穩定，新版 packer 也支援 hcl 的 template
  • terraform configuration 是第一個套用 hcl spec 的產品，hcl spec 也隨 terraform 的更新而演進
  • 後面的產品（consul，vault）都變成 hcl 的形狀了

用範例講解一下上面一大段，回頭看 _poc/security_group/security_group.tf

  • 他是 terraform configuration syntax，底下是 hcl
  • 支援 .tf native 格式，也支援 .tf.json json 格式

使用 cli 的 global option -json 來輸出 json

  • 比較 hcl 與 json 的輸出差異
  • json 乍看之下有點凌亂，使用 jq parse 後，會發現輸出內容相同
  • double quote 的跳脫字元 (escape)
terraform plan

  # azurerm_network_security_group.main will be created
  + resource "azurerm_network_security_group" "main" {
      + id                  = (known after apply)
      + location            = "southeastasia"
      + name                = "poc-chechia"
      + resource_group_name = "terraform-30-days"
      + security_rule       = (known after apply)
      + tags                = {
          + "environment" = "poc"
        }
    }

  # azurerm_network_security_rule.main["homeport22"] will be created
  + resource "azurerm_network_security_rule" "main" {
      + access                      = "Allow"
      + destination_address_prefix  = "*"
      + destination_port_range      = "22"
      + direction                   = "Inbound"
      + id                          = (known after apply)
      + name                        = "Port_22"
      + network_security_group_name = "poc-chechia"
      + priority                    = 100
      + protocol                    = "*"
      + resource_group_name         = "terraform-30-days"
      + source_address_prefix       = "17.110.101.57"
      + source_port_range           = "*"
    }

terraform plan -json

{"@level":"info","@message":"azurerm_network_security_group.main: Plan to create","@module":"terraform.ui","@timestamp":"2021-08-18T22:58:26.459366+08:00","change":{"resource":{"addr":"azurerm_network_security_group.main","module":"","resource":"azurerm_network_security_group.main","implied_provider":"azurerm","resource_type":"azurerm_network_security_group","resource_name":"main","resource_key":null},"action":"create"},"type":"planned_change"}
{"@level":"info","@message":"azurerm_network_security_rule.main[\"homeport22\"]: Plan to create","@module":"terraform.ui","@timestamp":"2021-08-18T22:58:26.461178+08:00","change":{"resource":{"addr":"azurerm_network_security_rule.main[\"homeport22\"]","module":"","resource":"azurerm_network_security_rule.main[\"homeport22\"]","implied_provider":"azurerm","resource_type":"azurerm_network_security_rule","resource_name":"main","resource_key":"homeport22"},"action":"create"},"type":"planned_change"}
{"@level":"info","@message":"Plan: 2 to add, 0 to change, 0 to destroy.","@module":"terraform.ui","@timestamp":"2021-08-18T22:58:26.461227+08:00","changes":{"add":2,"change":0,"remove":0,"operation":"plan"},"type":"change_summary"}

# format with jq

{
  "@level": "info",
  "@message": "azurerm_network_security_rule.main[\"homeport22\"]: Plan to create",
  "@module": "terraform.ui",
  "@timestamp": "2021-08-18T22:58:26.461178+08:00",
  "change": {
    "resource": {
      "addr": "azurerm_network_security_rule.main[\"homeport22\"]",
      "module": "",
      "resource": "azurerm_network_security_rule.main[\"homeport22\"]",
      "implied_provider": "azurerm",
      "resource_type": "azurerm_network_security_rule",
      "resource_name": "main",
      "resource_key": "homeport22"
    },
    "action": "create"
  },
  "type": "planned_change"
}

{
  "@level": "info",
  "@message": "Plan: 2 to add, 0 to change, 0 to destroy.",
  "@module": "terraform.ui",
  "@timestamp": "2021-08-18T22:58:26.461227+08:00",
  "changes": {
    "add": 2,
    "change": 0,
    "remove": 0,
    "operation": "plan"
  },
  "type": "change_summary"
}

.tf 與 .tf.json 的格式轉換，我們可以用一個小工具 kvz/json2hcl來做轉換

# azure/_poc/security_group/provider.tf

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 2.65.0"
    }
  }

  required_version = ">= 1.0.1"

  # remote Backend
  backend "azurerm" {
    resource_group_name  = "terraform-30-days-poc"
    storage_account_name = "tfstate8b8bff248c5c60c0"
    container_name       = "tfstate"
    key                  = "_poc/security_group/terraform.tfstate"
  }
}

provider "azurerm" {
  features {}
}

安裝 json2hcl

# azure/_poc/security_group/provider.tf

curl -SsL https://github.com/kvz/json2hcl/releases/download/v0.0.6/json2hcl_v0.0.6_darwin_amd64 \
  | sudo tee /usr/local/bin/json2hcl > /dev/null && sudo chmod 755 /usr/local/bin/json2hcl && json2hcl -version

v0.0.6

json2hcl -reverse < azure/_poc/security_group/provider.tf
{
  "provider": [
    {
      "azurerm": [
        {
          "features": [
            {}
          ]
        }
      ]
    }
  ],
  "terraform": [
    {
      "backend": [
        {
          "azurerm": [
            {
              "container_name": "tfstate",
              "key": "_poc/security_group/terraform.tfstate",
              "resource_group_name": "terraform-30-days-poc",
              "storage_account_name": "tfstate8b8bff248c5c60c0"
            }
          ]
        }
      ],
      "required_providers": [
        {
          "azurerm": [
            {
              "source": "hashicorp/azurerm",
              "version": "~\u003e 2.65.0"
            }
          ]
        }
      ],
      "required_version": "\u003e= 1.0.1"
    }
  ]
}

然而輸入 _poc/security_group/security_group.tf 則會出錯

  • json 沒有辦法辨識 hcl 的功能性語法
    • variable 如：local. each.，是 hcl 送進 terraform 後才能有效 evaluate
    • for_each 在 json 中也不存在
json2hcl -reverse < azure/_poc/security_group/security_group.tf

unable to parse HCL: At 2:25: Unknown token: 2:25 IDENT local.name

我們可以依據hcl readme 補上 double quote ""，讓格式符合 json 的格式，這樣就可以順利轉換

  • 轉換成標準 json
  • "${ }" 對 terraform 有額外意義，會自動 evaluate 變數值
cat _poc/security_group/security_group_json.tf

resource "azurerm_network_security_rule" "main" {
  for_each                    = "${local.rules}"
  name                        = "${each.value.name}"
  priority                    = "${each.value.priority}"
  direction                   = "${each.value.direction}"
  access                      = "${each.value.access}"
  protocol                    = "${each.value.protocol}"
  source_port_range           = "${each.value.source_port_range}"
  destination_port_range      = "${each.value.destination_port_range}"
  source_address_prefix       = "${each.value.source_address_prefix}"
  destination_address_prefix  = "${each.value.destination_address_prefix}"
  resource_group_name         = "${local.resource_group_name}"
  network_security_group_name = "${local.name}"
}

json2hcl -reverse < azure/_poc/security_group/security_group_json.tf

{
  "resource": [
    {
      "azurerm_network_security_rule": [
        {
          "main": [
            {
              "access": "${each.value.access}",
              "destination_address_prefix": "${each.value.destination_address_prefix}",
              "destination_port_range": "${each.value.destination_port_range}",
              "direction": "${each.value.direction}",
              "for_each": "${local.rules}",
              "name": "${each.value.name}",
              "network_security_group_name": "${local.name}",
              "priority": "${each.value.priority}",
              "protocol": "${each.value.protocol}",
              "resource_group_name": "${local.resource_group_name}",
              "source_address_prefix": "${each.value.source_address_prefix}",
              "source_port_range": "${each.value.source_port_range}"
            }
          ]
        }
      ]
    }
  ]
}

這也是舊版 terraform 常出現 "${}" 語法的原因。新版 terraform 已經能自動 parse 沒有 double quote 的 hcl 語法，並且 validate 時會對有不必要 double quote 的 "${}" 語法跳出 warning。

Review terraform resource

了解 terraform syntax 後，我們要回頭重新檢視 hcl 中描述的 terraform resources，以及為什麼 resources 會有這些行為

resource block {}

  • hcl parse 後是一層 json node
  • block 內有許多參數 Resource Arguments，包含：
    • resource 遠端物件的 arguments
      • 例如：resource.azurerm_linux_virtual_machine 的 name, size ...等是雲端物件的參數
      • 這些物件與參數，透過 provider 實作，轉成公有雲 api 接受的 json payload，向 api 發出 request，變更遠端 resource
      • terraform 可以管理或變更這些雲端物件參數
    • 另外還有 resource meta-argument （ex. provider, for_each, lifecycle,...）
      • 這些 meta-argument 是 terraform 的參數，也就是上面提到的功能性參數，用來改變 resource 行為，方便使用者透過 terraform 做更高階的 resource 的管理
      • 例如：在 terraform 內操作迴圈控制 resource
      • meta-argument 只在 terraform 內部有效，作用時間與其他參數不同

我們在編寫 hcl 內容時應善用 meta-argument，應注意

  • 哪些參數是 terraform 內參數，哪些是 meta-argument
  • terraform cli workflow 的各個階段，argument 會作用
  • module 間的 depends_on 與 variable + argument 的使用，會造成 module 彼此的依賴性
    • 造成 apply 時候，terraform 送出 request 的先後順序有差異
  • for each 與 count 是強大的工具，但使用上需要注意的地方，我們下一章節會說明

Source code

如果對 Terraform 原始碼有興趣，可以看與 hcl config parse

Homework

官方文件閱讀測驗

  • Terraform: configuration syntax
    • 了解平時使用的 .tf 內容底層是如何定義的
    • 自己的理解，與官方文件描述內容是否相符
    • 被一些單字，官方是如何用英文描述功能，描述元件，描述語法
      • 之後遇到問題 google 找問題時，使用對的單字問對的問題，才搜尋的到解答

References

Next session

meta-argument 只在 terraform 內部有效，細節範例我們下一章節會說明


上一篇
Day 12-DevOpSec 正夯，沒做 security check 的 module 不要用
下一篇
Day 14-for (i=0; i < 100; i++) createVM(i); infrastructure 也可以 for each 之一
系列文
Terraform Workshop - Infrastructure as Code for Public Cloud 疫情警戒陪你度過 30 天 共 32 篇
  1. 28
    Day 26-如何測試 terraform 之一：長 code 短 code，能過測試的 code 才是好 code
  2. 29
    Day 27-如何測試 terraform 之二：自動化測試寫起來辛苦，但跑起來就是一個爽
  3. 30
    Day 28-天下無沒有 bug 的 code，如何 debug terraform
  4. 31
    Day 29-給我無限多的預算我就能撐起全世界，infracost 教你吃米知米價
  5. 32
    Day 30-完賽結論，所有公有雲的問題，我一率建議 Terraform
完整目錄
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言
iThome鐵人賽
參賽組數
1064 組
團體組數
40 組
累計文章數
22217 篇
完賽人數
602 人
iT+看影片追技術 看影片追技術 看更多
熱門tag 看更多
15th鐵人賽 16th鐵人賽 13th鐵人賽 14th鐵人賽 12th鐵人賽 11th鐵人賽 鐵人賽 2019鐵人賽 javascript 2018鐵人賽 python 2017鐵人賽 windows php c# windows server linux css react vue.js
熱門問題
熱門回答
熱門文章
IT邦幫忙