创建 Terraform 模板

了解如何创建结构合理、可复用且全面的 Terraform 模板。

Terraform 模板由一个或多个 Terraform 配置文件组成，用于声明要为 IBM Cloud® 资源实现的状态。为了成功使用您的资源，您必须 IBM 配置为您的云提供商，并将资源添加到您的Terraform配置文件中。（可选）可以使用输入变量来定制资源。

您可以使用 HashiCorp Configuration Language (HCL) 或 JSON 格式编写 Terraform 配置文件。

在开始创建 Terraform 模板之前，请务必查看 IBM Cloud Schematics 限制。

配置 `provider` 块

在 Terraform 配置文件的 provider 块中指定要使用的云提供者。 provider 块包含 IBM Cloud® Provider for Terraform 插件供应资源所需的所有输入变量。

IBM Cloud API 密钥

IBM Cloud API 密钥对于向 IBM Cloud 平台认证至关重要。另外，Schematics 需要 IAM 令牌和 IAM 刷新令牌才能使用资源的 API，并确定授予您的许可权。使用本机 Terraform 时，必须始终提供 IBM Cloud API 密钥。在 Schematics中，将针对所有启用 IAM 的资源 (包括 IBM Cloud Kubernetes Service 集群和 VPC 基础架构资源) 检索 IAM 令牌。但是，不会针对经典基础架构资源检索 IAM 令牌，并且必须在 provider 块中提供 API 密钥。

provider 块中的不同 IBM Cloud API密钥

如果要使用与 IBM Cloud 帐户相关联的 API 密钥不同的 API 密钥，可以在 provider 块中提供此 API 密钥。如果在 provider 块中配置了 API 密钥，那么此密钥会优先于存储在 IBM Cloud 中的 API 密钥。

IBM Cloud 服务 ID 的 API 密钥

您可以为所有启用 IAM 的服务（包括 VPC 基础架构资源）提供服务标识的 API 密钥。经典基础架构资源不能使用服务 ID。

遵循指示信息以配置 provider 块。

选择要如何配置 provider 块。
- 方案 1 创建一个单独的 provider.tf 文件。 Terraform 和 IBM Cloud Schematics 会加载该文件中的信息，并将其应用于存在于同一 GitHub 目录或磁带归档文件 .tar 中的所有 Terraform 配置文件。如果将基础架构代码拆分成多个文件，那么此方法很有用。
- 方案 2 在 Terraform 配置文件中添加 provider 块。 如果希望在一个 Terraform 配置文件中指定提供程序以及变量和资源，可以选择此选项。
查看凭证和信息，必须在 provider 块中提供这些凭证和信息才能使用资源. Schematics 自动检索 IBM Cloud API 密钥的内容，以便您无需在 provider 块中指定此信息。

创建 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 的标识将可用。为 VPC 创建子网时，可以将此标识用作输入参数。如果在一个 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 密钥的目标帐户，具有认证和相应交叉帐户授权的服务标识。

通过 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，number 和复杂数据类型，例如 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
}

为声明的变量提供 IBM Cloud Schematics 的值

您可以在为 IBM Cloud Schematics 创建工作空间以在 Terraform 操作上用于模板中声明的变量后提供值。

对于 UI，您可以在 IBM Cloud > Schematics > 工作空间> 设置页面上提供值。 value 字段是 .tfvars 文件中提供的 HCL 格式值。
对于 CLI，您可以看到创建或更新复杂数据类型的值。然后，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`	否
`map(string)`	{key1 = "value1", key2 = "value2"}
`set(string)`	["hello"，"he"]
`map(number)`	{internal = 8080, external = 2020}
`list(string)`	["us-south"，"eu-gb"]
`list`	["value"，30]
`list(list(string))`	请参阅 String 示例列表(list of String example)。
`list(object({internal = number external = number protocol = string}))`	请参阅对象示例列表(list of Object example)。

字符串列表的示例

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

对象列表的示例

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

存储 Terraform 模板

Terraform 配置文件包含必须将其视为常规代码的基础架构代码。为支持协作、源代码和版本控制，请将文件存储在 GitHub 或 GitLab 存储库中。通过版本控制，可以还原为先前的版本，对更改进行审计以及与多个团队共享代码。如果不想将文件存储在 GitHub, 可从本地计算机上传 tape 存档文件或 .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 解决方案模板来创建基础架构、管理资源，并使用强大的工具来保护、管理和监控工作区和操作。

创建 Terraform 模板

配置 provider 块

将云资源添加到 resource 区块

在其他资源块中引用资源

管理其他帐户中的资源

使用 variable 块定制资源

引用变量

为声明的变量提供 IBM Cloud Schematics 的值

字符串列表的示例

对象列表的示例

存储 Terraform 模板

Terraform 解决方案示例

配置 `provider` 块

将云资源添加到 `resource` 区块

使用 `variable` 块定制资源