建立 Terraform 範本

瞭解如何建立結構良好、可重複使用的綜合性 Terraform 範本。

Terraform 範本由一個以上 Terraform 配置檔組成，用於宣告要為 IBM Cloud® 資源達到的狀態。 要成功使用您的資源，您 必須將 IBM 設定為您的雲端提供者，並將資源新增至 Terraform 配置檔案。 （選用）可以使用輸入變數來自訂資源。

您可以使用 HashiCorp 配置語言 (HCL) 或 JSON 格式來撰寫 Terraform 配置檔案。 您也可以使用 Terraform IBM Modules(TIM)，它提供預先建立的基礎架構元件，有助於標準化和簡化部署流程。

在開始建立 Terraform 範本之前，請務必詳閱 IBM Cloud Schematics 中的限制事項。

配置 provider 區塊

在 Terraform 配置檔的 provider 區塊中指定要使用的雲端提供者。 provider 區塊包含 IBM Cloud® Provider for Terraform 外掛程式佈建資源所需的所有輸入變數。

IBM Cloud API 金鑰

IBM Cloud API 金鑰是 IBM Cloud 平台驗證的必要條件。 此外，Schematics 與資源的 API 搭配使用時，需要 IAM 令牌和 IAM 更新令牌，以確定您被授予的權限。 使用本機 Terraform 時，您必須提供 IBM Cloud API 金鑰。 在 Schematics 中，所有啟用 IAM 的資源（包括 IBM Cloud Kubernetes Service 群集和 VPC 基礎結構資源）都會擷取 IAM 令牌。 但是，經典基礎結構資源不會擷取 IAM 令牌，API 金鑰必須在 provider 區塊中提供。

provider 區塊中不同的 IBM Cloud API 金鑰

如果您要使用的 API 金鑰不同於與 IBM Cloud 帳戶相關聯的 API 金鑰，則您可以在 provider 區塊中提供此 API 金鑰。 如果在 provider 區塊中配置 API 金鑰，則此金鑰的優先順序高於 IBM Cloud 中所儲存的 API 金鑰。

IBM Cloud 某個服務 ID 的 API 金鑰

您可以針對所有已啟用 IAM 的服務（包括 VPC 基礎架構資源）提供服務 ID 的 API 金鑰。 您無法對傳統基礎架構資源使用服務識別碼。

依照指示設定 provider 區塊。

  1. 選擇要如何配置 provider 區塊。

    • 選項 1：建立一個獨立的 provider.tf 檔案。 此檔案中的資訊會由 Terraform 及 IBM Cloud Schematics 載入，並套用至所有位於同一 GitHub 目錄中，或存於磁帶存檔檔案 .tar 中的 Terraform 配置檔案。 如果將基礎架構程式碼分割成多個檔案，則此方法很有用。
    • 選項 2：在您的 Terraform 配置檔案中加入一個 provider 區塊。 如果您希望在同一個 Terraform 配置檔案中，將提供者與變數及資源一併指定，則可選擇此選項。

  2. 查看 您必須提供的證書和信息 provider 此模組用於操作您的資源。Schematics 會自動擷取您的 IBM Cloud API 金鑰，因此您無需在組態中指定此資訊。provider 堵塞。

  3. 建立 provider.tf 檔案或將下列程式碼新增到 Terraform 配置檔。 如需 provider 區塊中可設定的支援參數完整清單，請參閱 IBM Cloud 提供者參考。

    VPC 基礎架構資源的範例

    provider "ibm" {
    generation = 1
    region = "<region_name>"
}

    經典基礎架構資源的範例

    variable "iaas_classic_username" {
    type = "string"
}
variable "iaas_classic_api_key" {
    type = "string"
}
provider "ibm" {
    region = "<region_name>"
    iaas_classic_username = var.iaas_classic_username
    iaas_classic_api_key  = var.iaas_classic_api_key
}

    所有 IBM Cloud Kubernetes Service 資源的範例

    provider "ibm" {
}

    其他所有資源的範例

    provider "ibm" {
    region = "<region_name>"
}

將雲端資源新增至「resource」區塊

請使用「resource」區塊來定義您希望透過 IBM Cloud Schematics 進行管理的雲端資源。

為了支援多雲端方法，Terraform 與多個雲端提供者合作。 雲端提供者負責瞭解您可以佈建的資源、其 API，以及在雲端公開這些資源的方法。 為了讓使用者能夠運用這些知識，每個受支援的雲端服務供應商都必須提供一個 Terraform 命令列外掛程式，供使用者用來管理相關資源。 若要瞭解您可在 IBM Cloud 中提供的資源概覽，請參閱 IBM Cloud Provider Plug-in for Terraform 參考資料。

用於配置 VPC 的基礎架構程式碼範例

resource ibm_is_vpc "vpc" {
    name = "myvpc"
}

在其他資源區塊中參照資源

檢閱在 Terraform 配置檔的其他資源區塊中參照現有資源時可使用的選項。

IBM Cloud Provider 外掛程式參照包含兩種類型的物件：資料來源和資源。 可以使用這兩種物件來參照其他資源區塊中的資源。

  • 資源：若要建立資源，請使用 IBM Cloud Provider 外掛程式參照中的資源定義。 資源定義包含用於配置雲端資源的語法，以及「屬性參考」——該參考列出了您可在其他資源區塊中作為輸入參數引用的屬性。 例如，建立 VPC 後，VPC 的 ID 將可用。 為 VPC 建立子網路時，可以將此 ID 用作輸入參數。 如果在一個 Terraform 配置檔中結合使用多個資源，請使用此選項。

    基礎結構代碼範例

    resource ibm_is_vpc "vpc" {
    name = "myvpc"
}
resource ibm_is_security_group "sg1" {
    name = "mysecuritygroup"
vpc  = ibm_is_vpc.vpc.id
}

  • 資料來源：您也可以使用《 IBM Cloud 提供者外掛程式參考》中的資料來源，來擷取有關現有雲端資源的資訊。 請檢閱 IBM Cloud Provider 外掛程式參照中的引數參照區段，以瞭解必須提供哪些輸入參數來擷取現有資源。 然後，檢閱屬性參照區段，以尋找可用參數以及可以在 resource 區塊中參照的參數的概觀。 如果要存取在其他 Terraform 配置檔中配置的資源的詳細資料，請使用此選項。

    基礎結構代碼範例

    data ibm_is_image "ubuntu" {
    name = "ubuntu-18.04-amd64"
}
resource ibm_is_instance "vsi1" {
    name    = "$mysi"
vpc     = ibm_is_vpc.vpc.id
zone    = "us-south1"
keys    = [data.ibm_is_ssh_key.ssh_key_id.id]
image   = data.ibm_is_image.ubuntu.id
profile = "cc1-2x4"
primary_network_interface {
    subnet          = ibm_is_subnet.subnet1.id
    security_groups = [ibm_is_security_group.sg1.id]
}
}

管理其他帳戶的資源

您可以使用 IBM Cloud 源帳戶中的工作區執行 Terraform 作業，以在目標帳戶中創建資源。 要在目標帳戶中提供資源，必須提供目標帳戶的身分和存取權限。 這可能是使用具有目標帳戶權限的使用者的身分。 或使用 API 金鑰為目標帳戶進行驗證和適當的跨帳戶授權的服務 ID。

當透過 UI 執行工作而不傳輸 API 金鑰時，會假設登入使用者的身分來執行作業。

使用 variable 區塊來自訂資源

您可以使用 variable 區塊來建立基礎架構程式碼的範本。 例如，您不需要為要部署在多個資料中心的資源建立多個 Terraform 配置檔案。 您只需重複使用具有輸入變數的相同組態，即可定義資料中心。

儲存變數

您可以決定是在指定要佈建的資源的同一個 Terraform 配置檔中宣告變數，還是建立包含所有變數宣告的個別 variables.tf 檔案。 建立工作區時，IBM Cloud Schematics 會自動剖析整個 Terraform 配置檔以尋找變數宣告。

宣告變數

當您宣告輸入變數時，您必須根據 Terraform 版本提供變數名稱和資料類型。 您可以選擇提供變數的預設值。 當輸入變數匯入 Schematics 並指定預設值時，您可以選擇覆蓋預設值。 \n IBM Cloud Schematics 對於原始類型，例如 bool, number, string, 和 HCL 格式的複雜變數，接受字串形式的值。 - Terraform v1.5 支援字串、list、map、bool、數字和複雜資料類型，例如 list(type)、map(type)、object( {attribute name=type,.} )、set(type)、tuple( [type] )。

限制輸入變數

是。 如果您在 Terraform 配置檔中定義輸入變數，則請注意為這些變數所輸入的值最多可以為 2049 個字元。 如果輸入變數所需的值超出此限制，則會在 2049 個字元之後截斷值。

未指定預設值的變數宣告範例

variable "datacenter" {
    type        = "string"
    description = "The data center that you want to deploy your Kubernetes cluster in."
}

帶有預設值的變數宣告範例

variable "datacenter" {
    type        = "string"
    description = "The data center that you want to deploy your Kubernetes cluster in."
    default = "dal10"
}

參照變數

您可以透過使用 "${var.<variable_name>}" 語法，在 Terraform 配置檔案的其他區塊中引用該變數的值。

引用 datacenter 變數的範例

resource ibm_container_cluster "test_cluster" {
    name         = "test"
    datacenter   = var.datacenter
}

利用 Terraform IBM 模組加快開發速度

您可以選擇使用 Terraform IBM 模組(TIM) 來建立範本。 它有助於快速建立複雜的基礎架構、幫助簡化資源相依性、應用 IBM Cloud 最佳實務，並透過 IBM Cloud 社群的貢獻而演進。

範例：使用 TIM 的 VPC 模組

module "vpc" {
  source  = "terraform-ibm-modules/vpc/ibm"
  version = "1.1.0"
  
  vpc_name                    = "my-production-vpc"
  resource_group_id           = "Default"
  classic_access              = false
  default_address_prefix      = "auto"
  default_network_acl_name    = "my-default-acl"
  default_security_group_name = "my-default-sg"
  default_routing_table_name  = "my-default-rt"
}

探索可用模組：

為已宣告的變數提供值到 IBM Cloud Schematics

您可以在建立 IBM Cloud Schematics 的工作區後，針對範本中宣告的變數，提供值供 Terraform 動作使用。

  • 對於 UI，您可以在 IBM Cloud > Schematics > 工作區 > 設定頁面上提供數值。 value 欄位是 .tfvars 檔案中提供的 HCL 格式值。

  • 對於 CLI，您可以看到建立或更新 Complex 資料類型 的值。 然後，value 欄位必須包含變數儲存的轉義字串，如範例所示。

  • 在 API 網站上，您可以在「template_data」欄位中看到 建立或更新這些值 > variablestore.「value」欄位即為 .tfvars 檔案中所提供的「HCL」格式值。 對於任何類型的變數，它永遠是一個 JSON 字串。

    範例

    "variablestore": [
            {
                "value": "[\n    {\n      internal = 800\n      external = 83009\n      protocol = \"tcp\"\n    }\n  ]",
                "description": "",
                "name": "docker_ports",
                "type": "list(object({\n    internal = number\n    external = number\n    protocol = string\n  }))"
            },
            {
                "name": "worker_pool_labels",
                "type": "map(string)",
                "value": "{\n        \"label-name1\": \"label-value1\",\n        \"label-name2\": \"label-value2\"\n}"
            },
            {
                "name": "docker_ports",
                "type": "list(object({\n    internal = number\n    external = number\n    protocol = string\n  }))",
                "value": "[\n    {\n      internal = 800\n      external = 83009\n      protocol = \"tcp\"\n    }\n  ]",
                "description": ""
            }
    ]

我可以看看如何在檔案中宣告複雜的變數嗎？

是的，當您宣告並賦予變數值時，您可以在 UI 中檢視工具提示。 表中提供了幾個複雜資料類型的範例，這些複雜資料類型可以在變數儲存器中宣告。

複雜的變數類型與範例
類型 範例
number 4.56
string 範例值
bool False
map(string) {key1 = "value1", key2 = "value2"}
set(string) [「你好」、「他」]
map(number) {internal = 8080, external = 2020}
list(string) ["US-South"、"EU-GB"]
list [「值」、30]
list(list(string)) 請參閱 字串範例清單。
list(object({internal = number external = number protocol = string})) 請參閱 物件範例清單。

字串清單範例

[
        "test", "env:prod", "env:agent:test"
]

物件清單範例

[
    {
        internal = 8300
        external = 8300
        protocol = "tcp"
    },
    {
        internal = 8301
        external = 8301
        protocol = "ldp"
    }
]

儲存 Terraform 範本

Terraform 配置檔包含必須將其視為正規程式碼的基礎架構程式碼。 為了支援協作、原始碼及版本控制，請將您的檔案儲存於 GitHub 或 GitLab 儲存庫中。 使用版本控制，可以回復為先前的版本，對變更進行審核以及與多個團隊共用程式碼。 如果您不想將檔案儲存於 GitHub,，請從本機上 傳磁帶存檔檔案或 .tar，以提供您的範本。 如果要複製文件，請查看 允許和禁止克隆的文件副檔名。

GitHub 倉庫中 Terraform 模版的目錄結構，最新更新時間列於表中。

Terraform 模板目錄結構
檔案 說明
README.md 建立 README.md
main.tf 建立 main.tf
output.tf 建立 output.tf
provider.tf 建立 provider.tf
variables.tf 建立 variables.tf

Terraform 解決方案範例

各種解決方案顯示出 IBM Cloud® Schematics 和 IBM Cloud® 服務一起使用時的優勢。 這些解決方案使用簡單的 Terraform 模板或模組設定基礎架構。 儘管每種解決方案都是透過特定應用案例的角度來呈現，但這些基礎架構在各行各業中都相當普遍。

透過 IBM Cloud Schematics 使用已發佈的 Terraform 解決方案範本來 建立基礎架構、管理資源，並使用強大的工具來保護、管理和監控您的工作區和行動。