1.4.1.1. 类型

表达式的结果是一个值。所有的值都有一个类型，这个类型决定了这个值可以在哪里使用以及可以对它应用哪些转换。

Terraform 的某些类型之间存在隐式类型转换规则，如果无法隐式转换类型，那么不同类型数据间的赋值将会报错。

Terraform 类型分为原始类型、复杂类型，以及 null。

1.4.1.1.1. 原始类型

原始类型分三类：string、number、bool。

  • string 代表一组 Unicode 字符串，例如："hello"。
  • number 代表数字，可以为整数，也可以为小数。
  • bool 代表布尔值，要么为 true，要么为 false。bool 值可以被用做逻辑判断。

number 和 bool 都可以和 string 进行隐式转换，当我们把 number 或 bool 类型的值赋给 string 类型的值，或是反过来时，Terraform 会自动替我们转换类型，其中：

  • true 值会被转换为 "true"，反之亦然
  • false 值会被转换为 "false"，反之亦然
  • 15 会被转换为 "15"，3.1415 会被转换为 "3.1415"，反之亦然

1.4.1.1.2. 复杂类型

复杂类型是一组值所组成的符合类型，有两类复杂类型。

一种是集合类型。一个集合包含了一组同一类型的值。集合内元素的类型成为元素类型。一个集合变量在构造时必须确定集合类型。集合内所有元素的类型必须相同。

Terraform 支持三种集合：

  • list(...)：列表是一组值的连续集合，可以用下标访问内部元素，下标从 0 开始。例如名为 l 的 list，l[0] 就是第一个元素。list 类型的声明可以是 list(number)、list(string)、list(bool)等，括号中的类型即为元素类型。

  • map(...)：字典类型(或者叫映射类型)，代表一组键唯一的键值对，键类型必须是 string，值类型任意。map(number) 代表键为 string 类型而值为 number 类型，其余类推。map 值有两种声明方式，一种是类似 {"foo": "bar", "bar": "baz"}，另一种是 {foo="bar", bar="baz"}。键可以不用双引号，但如果键是以数字开头则例外。多对键值对之间要用逗号分隔，也可以用换行符分隔。推荐使用 = 号(Terraform 代码规范中规定按等号对齐，使用等号会使得代码在格式化后更加美观)

  • set(...)：集合类型，代表一组不重复的值。

以上集合类型都支持通配类型缩写，例如 list 等价于 list(any)，map 等价于 map(any)，set 等价于 set(any)。any 代表支持任意的元素类型，前提是所有元素都是一个类型。例如，将 list(number) 赋给 list(any) 是合法的，list(string) 赋给 list(any) 也是合法的，但是 list 内部所有的元素必须是同一种类型的。

第二种复杂类型是结构化类型。一个结构化类型允许多个不同类型的值组成一个类型。结构化类型需要提供一个 schema 结构信息作为参数来指明元素的结构。

Terraform 支持两种结构化类型：

  • object(...)：对象是指一组由具有名称和类型的属性所构成的符合类型，它的 schema 信息由 { \<KEY\>=\<TYPE\>, \<KEY\>=\<TYPE\>,...} 的形式描述，例如 object({age=number, name=string})，代表由名为 "age“ 类型为number，以及名为 "name" 类型为 string 两个属性组成的对象。赋给 object 类型的合法值必须含有所有属性值，但是可以拥有多余的属性(多余的属性在赋值时会被抛弃)。例如对于 object({age=number,name=string}) 来说，{ age=18 } 是一个非法值，而 { age=18, name="john", gender="male" } 是一个合法值，但赋值时 gender 会被抛弃
  • tuple(...)：元组类似 list，也是一组值的连续集合，但每个元素都有独立的类型。元组同 list 一样，也可以用下标访问内部元素，下标从 0 开始。元组 schema 用 [\<TYPE\>, \<TYPE\>, ...] 的形式描述。元组的元素数量必须与 schema 声明的类型数量相等，并且每个元素的类型必须与元组 schema 相应位置的类型相等。例如，tuple([string, number, bool]) 类型的一个合法值可以是 ["a", 15, true]

复杂类型也支持隐式类型转换。

Terraform 会尝试转换相似的类型，转换规则有：

  • object 和 map：如果一个 map 的键集合含有 object 规定的所有属性，那么 map 可以被转换为 object，map 里多余的键值对会被抛弃。由 map -> object -> map 的转换可能会丢失数据。
  • tuple 和 list：当一个 list 元素的数量正好等于一个 tuple 声明的长度时，list 可以被转换为 tuple。例如：值为 ["18", "true", "john"] 的 list 转换为 tuple([number,bool, string]) 的结果为 [18, true, "john"]
  • set 和 tuple：当一个 list 或是 tuple 被转换为一个 set，那么重复的值将被丢弃，并且值原有的顺序也将丢失。如果一个 set 被转换到 list 或是 tuple，那么元素将按照以下顺序排列：如果 set 的元素是 string，那么将按照字段顺序排列；其他类型的元素不承诺任何特定的排列顺序。

复杂类型转换时，元素类型将在可能的情况下发生隐式转换，类似上述 list 到 tuple 转换举的例子。

如果类型不匹配，Terraform 会报错，例如我们试图把object({name = ["Kristy", "Claudia", "Mary Anne", "Stacey"], age = 12})转换到 map(string) 类型，这是不合法的，因为 name 的值为 list，无法转换为 string。

1.4.1.1.3. any

any 是 Terraform 中非常特殊的一种类型约束，它本身并非一个类型，而只是一个占位符。每当一个值被赋予一个由 any 约束的复杂类型时，Terraform 会尝试计算出一个最精确的类型来取代 any。

例如我们把 ["a", "b", "c"] 赋给 list(any)，它在 Terraform 中实际的物理类型首先被编译成 tuple([string, string, string])，然后 Terraform 认为 tuple 和 list 相似，所以会尝试将它转换为 list(string)。然后 Terraform 发现 list(string) 符合 list(any) 的约束，所以会用 string 取代 any，于是赋值后最终的类型是 list(string)。

由于即使是 list(any)，所有元素的类型也必须是一样的，所以某些类型转换到 list(any) 时会对元素进行隐式类型转换。例如将 ["a", 1, "b"] 赋给 list(any)，Terraform 发现 1 可以转换到 "1"，所以最终的值是 ["a", "1", "b"]，最终的类型会是 list(string)。再比如我们想把 ["a", \[\], "b"] 转换成 list(any)，由于 Terraform 无法找到一个一个合适的目标类型使得所有元素都能成功隐式转换过去，所以 Terraform 会报错，要求所有元素都必须是同一个类型的。

声明类型时如果不想有任何的约束，那么可以用 any：

1
2
3
variable "no_type_constraint" {
  type = any
}

这样的话，Terraform 可以将任何类型的数据赋予它。

1.4.1.1.4. null

存在一种特殊值是无类型的，那就是 null。null 代表数据缺失。如果我们把一个参数设置为 null，Terraform 会认为你忘记为它赋值。如果该参数有默认值，那么 Terraform 会使用默认值；如果没有又恰巧该参数是必填字短，Terraform 会报错。null 在条件表达式中非常有用，你可以在某项条件不满足时跳过对某参数的赋值。

1.4.1.1.5. object 的 optional 成员

自 Terraform 1.3 开始，我们可以在 object 类型定义中使用 optional 修饰属性。

在 1.3 之前，如果一个 variable 的类型为 object，那么使用时必须传入一个结构完全相符的对象。例如：

1
2
3
4
5
6
7
variable "an_object" {
  type = object({
    a = string
    b = string
    c = number
  })
}

如果我们想传入一个对象给 var.an_object，但不准备给 b 和 c 赋值，我们必须这样：

1
2
3
4
5
{
  a = "a"
  b = null
  c = null
}

传入的对象必须完全匹配类型定义的结构，哪怕我们不想对某些属性赋值。这使得我们如果想要定义一些比较复杂，属性比较多的 object 类型时会给用户在使用上造成一些麻烦。

Terraform 1.3 允许我们为一个属性添加 optional 声明，还是用上面的例子：

1
2
3
4
5
6
7
variable "with_optional_attribute" {
  type = object({
    a = string                # a required attribute
    b = optional(string)      # an optional attribute
    c = optional(number, 127) # an optional attribute with default value
  })
}

在这里我们将 b 声明为 optional，如果传入的对象没有 b，则会使用 null 作为值；c 不但声明为 optional 的，还添加了 127 作为默认值，传入的对象如果没有 c，那么会使用 127 作为它的值。

optional 修饰符有这样两个参数：

  • 类型：（必填）第一个参数标明了属性的类型
  • 默认值：（选填）第二个参数定义了 Terraform 在对象中没有定义该属性值时使用的默认值。默认值必须与类型参数兼容。如果没有指定默认值，Terraform 会使用 null 作为默认值。

一个包含非 null 默认值的 optional 属性在模块内使用时可以确保不会读到 null 值。当用户没有设置该属性，或是显式将其设置为 null 时，Terraform 会使用默认值，所以模块内无需再次判断该属性是否为 null。

Terraform 采用自上而下的顺序来设置对象的默认值，也就是说，Terraform 会先应用 optional 修饰符中的指定的默认值，然后再为其中可能存在的内嵌对象设置默认值。

1.4.1.1.5.1. 例子：带有 optional 属性和默认值的内嵌结构

下面的例子演示了一个输入变量，用来描述一个存储了静态网站内容的存储桶。该变量的类型包含了一系列的 optional 属性，包括 website，不但其自身是 optional 的，其内部包含了数个 optional 的属性以及默认值。

1
2
3
4
5
6
7
8
9
10
11
variable "buckets" {
  type = list(object({
    name    = string
    enabled = optional(bool, true)
    website = optional(object({
      index_document = optional(string, "index.html")
      error_document = optional(string, "error.html")
      routing_rules  = optional(string)
    }), {})
  }))
}

以下给出一个样例 terraform.tfvars 文件，为 var.buckets 定义了三个存储桶：

  • production 配置了一条重定向的路由规则
  • archived 使用了默认配置，但被关闭了
  • docs 使用文本文件取代了索引页和错误页

production 桶没有指定索引页和错误页，archived 桶完全忽略了网站配置。Terraform 会使用 bucket 类型约束中指定的默认值。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
buckets = [
  {
    name = "production"
    website = {
      routing_rules = <<-EOT
      [
        {
          "Condition" = { "KeyPrefixEquals": "img/" },
          "Redirect"  = { "ReplaceKeyPrefixWith": "images/" }
        }
      ]
      EOT
    }
  },
  {
    name = "archived"
    enabled = false
  },
  {
    name = "docs"
    website = {
      index_document = "index.txt"
      error_document = "error.txt"
    }
  },
]

该配置会产生如下的 variable 值：

  • 对 production 和 docs 桶，Terraform 会将 enabled 设置为 true。Terraform 会同时使用默认值配置 website，然后使用 docs 中指定的值来覆盖默认值。
  • 对 archived 和 docs 桶，Terraform 会将 routing_rules 设置为 null。当 Terraform 没有读取到 optional 的属性，并且属性上没有设置默认值时，Terraform 会将这些属性设置为 null。
  • 对于 archived 桶，Terraform 会将 website 属性设置为 buckets 类型约束中定义的默认值。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
tolist([
  {
    "enabled" = true
    "name" = "production"
    "website" = {
      "error_document" = "error.html"
      "index_document" = "index.html"
      "routing_rules" = <<-EOT
      [
        {
          "Condition" = { "KeyPrefixEquals": "img/" },
          "Redirect"  = { "ReplaceKeyPrefixWith": "images/" }
        }
      ]

      EOT
    }
  },
  {
    "enabled" = false
    "name" = "archived"
    "website" = {
      "error_document" = "error.html"
      "index_document" = "index.html"
      "routing_rules" = tostring(null)
    }
  },
  {
    "enabled" = true
    "name" = "docs"
    "website" = {
      "error_document" = "error.txt"
      "index_document" = "index.txt"
      "routing_rules" = tostring(null)
    }
  },
])

1.4.1.1.5.2. 例子：有条件地设置一个默认属性

有时我们需要根据其他数据的值来动态决定是否要为一个 optional 参数设置值。在这种场景下，发起调用的 module 块可以使用条件表达式搭配 null 来动态地决定是否设置该参数。

还是上一个例子中的 variable "buckets" 的例子，使用下面演示的例子可以根据新输入参数 var.legacy_filenames 的值来有条件地覆盖 website 对象中 index_document 以及 error_document 的设置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
variable "legacy_filenames" {
  type     = bool
  default  = false
  nullable = false
}

module "buckets" {
  source = "./modules/buckets"

  buckets = [
    {
      name = "maybe_legacy"
      website = {
        error_document = var.legacy_filenames ? "ERROR.HTM" : null
        index_document = var.legacy_filenames ? "INDEX.HTM" : null
      }
    },
  ]
}

当 var.legacy_filenames 设置为 true 时，调用会覆盖 document 的文件名。当它的值为 false 时，调用不会指定这两个文件名，这样就会使得模块使用定义的默认值。

1.4.2.1. 配置语法

这里讲的仍然是 HCL 的语法，但我们只讲一些关键语法。如果读者有兴趣了解完整信息可以访问 HCL 语法规约

HCL 的语法由两个关键元素构成：参数(Argument)与块(Block)

1.4.2.1.1. 参数

HCL 中的参数就是将一个值赋给一个特定的名称：

1
image_id = "abc123"

等号前的标识符就是参数名，等号后的表达式就是参数值。参数赋值时 Terraform 会检查类型是否匹配。参数名是确定的，参数值可以是确定的字面量硬编码，也可以是一组表达式，用以通过其他的值加以计算得出结果值。

1.4.2.1.2. 块

一个块是包含一组其他内容（参数和块）的容器，例如：

1
2
3
4
5
6
7
resource "aws_instance" "example" {
  ami = "abc123"

  network_interface {
    # ...
  }
}

一个块有一个类型(上面的例子里类型就是 resource)。每个块类型都定义了类型关键字后面要跟多少标签，例如 resource 块规定了后面要跟两个标签 —— 在例子里就是 aws_instance 和 example。一个块类型可以规定任意多个标签，也可以没有标签，比如内嵌的 network_interface 块。

在块类型及其后续标签之后，就是块体。块体必须被包含在一对花括号中间。在块体中可以进一步定义各种参数和其他的块。

Terraform 规范定义了有限个顶级块类型，也就是可以游离于任何其他块独立定义在配置文件中的块。大部分的 Terraform 功能(例如 resource, variable, output, data等)都是顶级块。

1.4.2.1.3. 标识符（Identifiers）

参数名、块类型名以及其他 Terraform 规范中定义的结构的名称，例如 resource、variable 等，都是标识符。

合法的标识符可以包含字母、数字、下划线(_)以及连字符(-)。标识符首字母不可以为数字。

要了解完整的标识符规范，请访问 Unicode 标识符语法。

1.4.2.1.4. 注释

Terraform支持三种注释：

  • # 单行注释，其后的内容为注释
  • // 单行注释，其后的内容为注释
  • /* 和 */，多行注释，可以注释多行

默认情况下单行注释优先使用 #。自动化格式整理工具会自动把 // 替换成 #。

1.4.2.1.5. 编码以及换行

Terraform 配置文件必须始终使用 UTF-8 编码。分隔符必须使用 ASCII 符号，其他标识符、注释以及字符串字面量均可使用非 ASCII 字符。

Terraform 兼容 Unix 风格的换行符（LF）以及 Windows 风格的换行符（CRLF），但是理想状态下应使用 Unix 风格换行符。

1.4.3.1. 输入变量

在前面的例子中，我们在代码中都是使用字面量硬编码的，如果我们想要在创建、修改基础设施时动态传入一些值呢？比如说在代码中定义 Provider 时用变量替代硬编码的访问密钥，或是由创建基础设施的用户来决定创建什么样尺寸的主机？我们需要的是输入变量。

如果我们把一组 Terraform 代码想像成一个函数，那么输入变量就是函数的入参。输入变量用 variable 块进行定义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
variable "image_id" {
  type = string
}

variable "availability_zone_names" {
  type    = list(string)
  default = ["us-west-1a"]
}

variable "docker_ports" {
  type = list(object({
    internal = number
    external = number
    protocol = string
  }))
  default = [
    {
      internal = 8300
      external = 8300
      protocol = "tcp"
    }
  ]
}

这些都是合法的输入参数定义。紧跟 variable 关键字的就是变量名。在一个 Terraform 模块(同一个文件夹中的所有 Terraform 代码文件，不包含子文件夹)中变量名必须是唯一的。我们在代码中可以通过var.<NAME>的方式引用变量的值。有一组关键字不可以被用作输入变量的名字：

  • source
  • version
  • providers
  • count
  • for_each
  • lifecycle
  • depends_on
  • locals

输入变量只能在声明该变量的目录下的代码中使用。

输入变量块中可以定义一些属性。

1.4.3.1.1. 类型 (type)

可以在输入变量块中通过 type 定义类型，例如：

1
2
3
4
5
6
variable "name" {
    type = string
}
variable "ports" {
    type = list(number)
}

定义了类型的输入变量只能被赋予符合类型约束的值。

1.4.3.1.2. 默认值 (default)

默认值定义了当 Terraform 无法获得一个输入变量得到值的时候会使用的默认值。例如：

1
2
3
4
variable "name" {
    type    = string
    default = "John Doe"
}

当 Terraform 无法通过其他途径获得name的值时，var.name 的值为 "John Doe"。

1.4.3.1.3. 描述 (description)

可以在输入变量中定义一个描述，简单地向调用者描述该变量的意义和用法：

1
2
3
4
variable "image_id" {
  type        = string
  description = "The id of the machine image (AMI) to use for the server."
}

如果在执行 terraform plan 或是 terraform apply 时 Terraform 不知道某个输入变量的值，Terraform 会在命令行界面上提示我们为输入变量设置一个值。例如上面的输入变量代码，执行 terraform apply 时：

1
2
3
4
5
$ terraform apply
var.image_id
  The id of the machine image (AMI) to use for the server.

  Enter a value:

为了使得代码的使用者能够准确理解输入变量的意义和用法，我们应该站在代码使用者而非代码维护者的角度编写输入变量的描述。描述并不是注释！

1.4.3.1.4. 断言 (validation)

输入变量的断言是 Terraform 0.13.0 开始引入的新功能，在过去，Terraform 只能用类型约束确保输入参数的类型是正确的，曾经有不少人试图通过奇技淫巧来实现更加复杂的变量校验断言。如今 Terraform 终于正式添加了相关的功能。

1
2
3
4
5
6
7
8
9
variable "image_id" {
  type        = string
  description = "The id of the machine image (AMI) to use for the server."

  validation {
    condition     = length(var.image_id) > 4 && substr(var.image_id, 0, 4) == "ami-"
    error_message = "The image_id value must be a valid AMI id, starting with \"ami-\"."
  }
}

condition 参数是一个 bool 类型的参数，我们可以用一个表达式来定义如何界定输入变量是合法的。当 condition 为 true 时输入变量合法，反之不合法。condition 表达式中只能通过 var.\<NAME\> 引用当前定义的变量，并且它的计算不能产生错误。

假如表达式的计算产生一个错误是输入变量验证的一种判定手段，那么可以使用 can 函数来判定表达式的执行是否抛错。例如：

1
2
3
4
5
6
7
8
9
10
variable "image_id" {
  type        = string
  description = "The id of the machine image (AMI) to use for the server."

  validation {
    # regex(...) fails if it cannot find a match
    condition     = can(regex("^ami-", var.image_id))
    error_message = "The image_id value must be a valid AMI id, starting with \"ami-\"."
  }
}

上述例子中，如果输入的 image_id 不符合正则表达式的要求，那么 regex 函数调用会抛出一个错误，这个错误会被 can 函数捕获，输出 false。

condition 表达式如果为 false，Terraform 会返回 error_message 中定义的错误信息。error_message 应该完整描述输入变量校验失败的原因，以及输入变量的合法约束条件。

1.4.3.1.5. 临时输入变量（ephemeral）

注意：临时输入变量是 Terraform v1.10 开始引入的功能

将变量设置为 ephemeral 的结果是，该输入值在运行时可用，但 Terraform 不会在状态和计划文件中记录这种临时值。将输入变量标记为 ephemeral 变量对于仅需要暂时存在的数据非常有用，例如短生命周期的令牌或会话标识符。

要将输入变量标记为临时变量，只通过将 ephemeral 参数设置为 true：

1
2
3
4
variable "session_token" {
  type      = string
  ephemeral = true
}

临时变量在当前 Terraform 运行期间可用，并且 Terraform 不会将它们存储在状态或计划文件中。因此，与 sensitive 输入不同，Terraform 确保临时值在当前 Terraform 运行结束后无法读取。

您只能在特定上下文中引用临时变量，否则 Terraform 会返回错误。以下是引用临时变量的有效上下文：

1.4.3.1.6. 在命令行输出中隐藏值 (sensitive)

该功能于 Terraform v0.14.0 开始引入。

将变量设置为 sensitive 可以防止我们在配置文件中使用变量时 Terraform 在 plan 和 apply 命令的输出中展示与变量相关的值。

Terraform 仍然会将敏感数据记录在状态文件中，任何可以访问状态文件的人都可以读取到明文的敏感数据值。

声明一个变量包含敏感数据值需要将 sensitive 参数设置为 true：

1
2
3
4
5
6
7
8
9
10
11
12
variable "user_information" {
  type = object({
    name    = string
    address = string
  })
  sensitive = true
}

resource "some_resource" "a" {
  name    = var.user_information.name
  address = var.user_information.address
}

任何使用了敏感变量的表达式都将被视为敏感的，因此在上面的示例中，resource “some_resource” “a”的两个参数也将在计划输出中被隐藏：

1
2
3
4
5
6
7
8
9
Terraform will perform the following actions:

  # some_resource.a will be created
  + resource "some_resource" "a" {
      + name    = (sensitive)
      + address = (sensitive)
    }

Plan: 1 to add, 0 to change, 0 to destroy.

在某些情况下，我们会在嵌套块中使用敏感变量，Terraform 可能会将整个块视为敏感的。这发生在那些包含有要求值是唯一的内嵌块的资源中，公开这种内嵌块的部分内容可能会暗示兄弟块的内容。

1
2
3
4
5
6
7
# some_resource.a will be updated in-place
 ~ resource "some_resource" "a" {
     ~ nested_block {
         # At least one attribute in this block is (or was) sensitive,
         # so its contents will not be displayed.
       }
   }

Provider 还可以将资源属性声明为敏感属性，这将导致 Terraform 将其从常规输出中隐藏。

如果打算使用敏感值作为输出值的一部分，Terraform 将要求您将输出值本身标记为敏感值，以确认确实打算将其导出。

1.4.3.1.6.1. Terraform 可能暴露敏感变量的情况

sensitive 变量是一个以配置文件为中心的概念，值被不加混淆地发送给 Provider。如果该值被包含在错误消息中，则 Provider 报错时可能会暴露该值。例如，即使 "foo" 是敏感值，Provider 也可能返回以下错误："Invalid value 'foo' for field"

如果将资源属性用作、或是作为 Provider 定义的资源 ID 的一部分，则 apply 将公开该值。在下面的示例中，前缀属性已设置为 sensitive 变量，但随后该值（"jae"）作为资源 ID 的一部分公开：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
  # random_pet.animal will be created
  + resource "random_pet" "animal" {
      + id        = (known after apply)
      + length    = 2
      + prefix    = (sensitive)
      + separator = "-"
    }

Plan: 1 to add, 0 to change, 0 to destroy.

...

random_pet.animal: Creating...
random_pet.animal: Creation complete after 0s [id=jae-known-mongoose]

1.4.3.1.7. 禁止输入变量为空 (nullable)

该功能自 Terraform v1.1.0 开始被引入

输入变量的 nullable 参数控制模块调用者是否可以将 null 赋值给变量。

1
2
3
4
variable "example" {
  type     = string
  nullable = false 
}

nullable 的默认值为 true。当 nullable 为 true 时，null 是变量的有效值，并且模块代码必须始终考虑变量值为 null 的可能性。将 null 作为模块输入参数传递将覆盖输入变量上定义的默认值。

将 nullable 设置为 false 可确保变量值在模块内永远不会为空。如果 nullable 为 false 并且输入变量定义有默认值，则当模块输入参数为 null 时，Terraform 将使用默认值。

nullable 参数仅控制变量的直接值可能为 null 的情况。对于集合或对象类型的变量，例如列表或对象，调用者仍然可以在集合元素或属性中使用 null，只要集合或对象本身不为 null。

1.4.3.1.8. 对输入变量赋值

1.4.3.1.8.1. 命令行参数

对输入变量赋值有几种途径，一种是在调用 terraform plan 或是 terraform apply 命令时以参数的形式传入：

1
2
3
$ terraform apply -var="image_id=ami-abc123"
$ terraform apply -var='image_id_list=["ami-abc123","ami-def456"]'
$ terraform plan -var='image_id_map={"us-east-1":"ami-abc123","us-east-2":"ami-def456"}'

可以在一条命令中使用多个 -var 参数。

1.4.3.1.8.2. 参数文件

第二种方法是使用参数文件。参数文件的后缀名可以是 .tfvars 或是 .tfvars.json。.tfvars 文件使用 HCL 语法，.tfvars.json 使用 JSON 语法。

以 .tfvars 为例，参数文件中用 HCL 代码对需要赋值的参数进行赋值，例如：

1
2
3
4
5
image_id = "ami-abc123"
availability_zone_names = [
  "us-east-1a",
  "us-west-1c",
]

后缀名为 .tfvars.json 的文件用一个 JSON 对象来对输入变量赋值，例如：

1
2
3
4
{
  "image_id": "ami-abc123",
  "availability_zone_names": ["us-west-1a", "us-west-1c"]
}

调用 terraform 命令时，通过 -var-file 参数指定要用的参数文件，例如：

1
terraform apply -var-file="testing.tfvars"
1
terraform apply -var-file="testing.tfvars.json"

有两种情况，你无需指定参数文件：

  • 当前模块内有名为 terraform.tfvars 或是 terraform.tfvars.json 的文件
  • 当前模块内有一个或多个后缀名为 .auto.tfvars 或是 .auto.tfvars.json 的文件

Terraform 会自动使用这两种自动参数文件对输入参数赋值。

1.4.3.1.8.3. 环境变量

可以通过设置名为 TF_VAR_<NAME> 的环境变量为输入变量赋值，例如：

1
2
3
$ export TF_VAR_image_id=ami-abc123
$ terraform plan
...

在环境变量名大小写敏感的操作系统上，Terraform 要求环境变量中的 <NAME> 与 Terraform 代码中定义的输入变量名大小写完全一致。

环境变量传值非常适合在自动化流水线中使用，尤其适合用来传递敏感数据，类似密码、访问密钥等。

1.4.3.1.8.4. 交互界面传值

在前面介绍断言的例子中我们看到过，当我们从命令行界面执行 terraform 操作，Terraform 无法通过其他途径获取一个输入变量的值，而该变量也没有定义默认值时，Terraform 会进行最后的尝试，在交互界面上要求我们给出变量值。

1.4.3.1.9. 输入变量赋值优先级

当上述的赋值方式同时存在时，同一个变量可能会被赋值多次。Terraform 会使用新值覆盖旧值。

Terraform 加载变量值的顺序是：

  1. 环境变量
  2. terraform.tfvars 文件(如果存在的话)
  3. terraform.tfvars.json 文件(如果存在的话)
  4. 所有的 .auto.tfvars 或者 .auto.tfvars.json 文件，以字母顺序排序处理
  5. 通过 -var 或是 -var-file 命令行参数传递的输入变量，按照在命令行参数中定义的顺序加载

假如以上方式均未能成功对变量赋值，那么 Terraform 会尝试使用默认值；对于没有定义默认值的变量，Terraform 会采用交互界面方式要求用户输入一个。对于某些 Terraform 命令，如果执行时带有 -input=false 参数禁用了交互界面传值方式，那么就会报错。

重要提示：在 Terraform 0.12 及更高版本中，类型为 map 或 object 的输入变量的读取行为与其他变量相同：后找到的值会覆盖之前的值。这与 Terraform 的早期版本不同，早期版本会合并 map，而不是覆盖它们。

1.4.3.1.9.1. Terraform 测试中的输入变量值

在 Terraform 测试文件中，您可以在 variable 块中指定变量值，这些 variable 块可以嵌套在 run 块中，也可以直接在文件中定义。

以这种方式定义的变量在测试执行期间优先于所有其他机制，其中在 run 块中定义的变量优先于在文件中定义的变量。

1.4.3.1.10. 复杂类型传值

通过参数文件传值时，可以直接使用 HCL 或是 JSON 语法对复杂类型传值，例如 list 或 map。

对于某些场景下必须使用 -var 命令行参数，或是环境变量传值时，可以用单引号引用 HCL 语法的字面量来定义复杂类型，例如：

1
export TF_VAR_availability_zone_names='["us-west-1b","us-west-1d"]'

由于采用这种方法需要手工处理引号的转义，所以这种方法比较容易出错，复杂类型的传值建议尽量通过参数文件。

1.4.4.1. 输出值

我们在介绍输入变量时提到过，如果我们把一组 Terraform 代码想像成一个函数，那么输入变量就是函数的入参；函数可以有入参，也可以有返回值，同样的，Terraform 代码也可以有返回值，这就是输出值。

大部分语言的的函数只支持无返回值或是单返回值，但是 Terraform 支持多返回值。在当前模块 apply 一段 Terraform 代码，运行成功后命令行会输出代码中定义的返回值。另外我们也可以通过 terraform output 命令来输出当前模块对应的状态文件中的返回值。

1.4.4.1.1. 输出值的声明

输出值的声明使用输出块，例如：

1
2
3
output "instance_ip_addr" {
  value = aws_instance.server.private_ip
}

output 关键字后紧跟的就是输出值的名称。在当前模块内的所有输出值的名字都必须是唯一的。output 块内的 value 参数即为输出值，它可以像是上面的例子里那样某个 resource 的输出属性，也可以是任意合法的表达式。

输出值只有在执行 terraform apply 后才会被计算，光是执行 terraform plan 并不会计算输出值。

Terraform 代码中无法引用本目录下定义的输出值。

output 块还有一些可选的属性：

1.4.4.1.1.1. 描述 description

1
2
3
4
output "instance_ip_addr" {
  value       = aws_instance.server.private_ip
  description = "The private IP address of the main server instance."
}

与输入变量的description类似，我们不再赘述。

1.4.4.1.1.2. 临时值（ephemeral）—— 避免将值存储到状态或计划文件中

注意：临时输出值是 Terraform v1.10 开始引入的功能

我们可以在子模块中将 output 标记为 ephemeral，以在模块之间传递临时值，同时避免将这些值保留到状态或计划文件中。这对于管理我们不想存储在 Terraform 状态文件中的凭据、令牌或其他临时资源非常有用。

我们可以通过将 ephemeral 属性设置为 true 将子模块中的输出标记为临时输出值：

1
2
3
4
5
6
7
# modules/db/main.tf

output "secret_id" {
  value       = aws_secretsmanager_secret.secret_id
  description = "Temporary secret ID for accessing database in AWS."
  ephemeral   = true
}

Terraform 可以在 plan 和 apply 操作期间访问 output 块的值。在 plan 或 apply 操作结束时，Terraform 不会保存任何临时输出的值。

我们只能在特定上下文中引用临时输出，否则 Terraform 会返回错误。以下是引用临时输出的有效上下文：

注意：我们不可以在根模块中将 output 声明为 ephemeral。

1.4.4.1.1.3. 在命令行输出中隐藏值 sensitive

一个输出值可以标记 sensitive 为 true，表示该输出值含有敏感信息。被标记 sensitive 的输出值只是在执行 terraform apply 命令成功后会打印 "<sensitive>" 以取代真实的输出值，执行 terraform output 时也会输出"<sensitive>"，但仍然可以通过执行 terraform output -json 看到实际的敏感值。

需要注意的是，标记为 sensitive 输出值仍然会被记录在状态文件中，任何有权限读取状态文件的人仍然可以读取到敏感数据。

1.4.4.1.1.4. depends_on

关于 depends_on 的内容将在 resource 章节里详细介绍，所以这里我们只是粗略地介绍一下。

Terraform 会解析代码所定义的各种 data、resource，以及他们之间的依赖关系，例如，创建虚拟机时用的 image_id 参数是通过 data 查询而来的，那么虚拟机实例就依赖于这个镜像的 data，Terraform 会首先创建 data，得到查询结果后，再创建虚拟机 resource。一般来说，data、resource 之间的创建顺序是由 Terraform 自动计算的，不需要代码的编写者显式指定。但有时有些依赖关系无法通过分析代码得出，这时我们可以在代码中通过 depends_on 显式声明依赖关系。

一般 output 很少会需要显式依赖某些资源，但有一些特殊场景，例如某些资源的属性必须在另外一些资源被创建后才能被读取，这种情况下我们可以通过 depends_on 来显式声明依赖关系。

depends_on 的用法如下：

1
2
3
4
5
6
7
8
9
10
output "instance_ip_addr" {
  value       = aws_instance.server.private_ip
  description = "The private IP address of the main server instance."

  depends_on = [
    # Security group rule must be created before this IP address could
    # actually be used, otherwise the services will be unreachable.
    aws_security_group_rule.local_access,
  ]
}

我们不鼓励针对 output 定义depends_on，只能作为最后的手段加以应用。如果不得不针对 output 定义depends_on，请务必通过注释说明原因，方便后人进行维护。

1.4.4.1.1.5. 断言 precondition

output 块从 Terraform v1.2.0 开始也可以包含一个 precondition 块。

output 块上的 precondition 对应于 variable 块中的 validation 块。validation 块检查输入变量值是否符合模块的要求，precondition 则确保模块的输出值满足某种要求。我们可以通过 precondition 来防止 Terraform 把一个不合法的输入值写入状态文件。我们可以在合适的场景下通过 precondition 来保护上一次 apply 留下的合法的输出值。

Terraform 在计算输出值的 value 表达式之前执行 precondition 检查，这可以防止 value 表达式中的潜在错误被激发。

1.4.5.1. 局部值

有时我们会需要用一个比较复杂的表达式计算某一个值，并且反复使用之，这时我们把这个复杂表达式赋予一个局部值，然后反复引用该局部值。如果说输入变量相当于函数的入参，输出值相当于函数的返回值，那么局部值就相当于函数内定义的局部变量。

局部值通过 locals 块定义，例如：

1
2
3
4
locals {
  service_name = "forum"
  owner        = "Community Team"
}

一个 locals 块可以定义多个局部值，也可以定义任意多个 locals 块。赋给局部值的可以是更复杂的表达式，也可以是其他 data、resource 的输出、输入变量，甚至是其他的局部值：

1
2
3
4
5
6
7
8
9
10
11
12
locals {
  # Ids for multiple sets of EC2 instances, merged together
  instance_ids = concat(aws_instance.blue.*.id, aws_instance.green.*.id)
}

locals {
  # Common tags to be assigned to all resources
  common_tags = {
    Service = local.service_name
    Owner   = local.owner
  }
}

引用局部值的表达式是 local.<NAME> (注意，虽然局部值定义在 locals 块内，但引用是务必使用 local 而不是 locals)，例如：

1
2
3
4
5
resource "aws_instance" "example" {
  # ...

  tags = local.common_tags
}

局部值只能在同一模块内的代码中引用。

局部值可以帮助我们避免重复复杂的表达式，提升代码的可读性，但如果过度使用也有可能增加代码的复杂度，使得代码的维护者更难理解所使用的表达式和值。适度使用局部值，仅用于反复引用同一复杂表达式的场景，未来当我们需要修改该表达式时局部值将使得修改变得相当轻松。

1.4.5.1.1. 临时（Ephemeral）局部值

注意：临时局部值是 Terraform v1.10 开始引入的功能

如果局部值的表达式中引用了临时值，则本地值会隐式地变为临时值。例如，您可以创建引用临时输入变量 service_token 的局部值：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
variable "service_name" {
  type    = string
  default = "forum"
}

variable "environment" {
  type    = string
  default = "dev"
}

variable "service_token" {
  type      = string
  ephemeral = true
}

locals {
  service_tag   = "${var.service_name}-${var.environment}"
  session_token = "${var.service_name}:${var.service_token}"
}

表达式 local.session_token 的值隐式地成为了临时值，因为它依赖于临时输入变量 var.service_token。

1.4.6.1. 资源

资源是 Terraform 最重要的组成部分，而本节亦是本教程最重要的一节。资源通过 resource 块来定义，一个 resource 可以定义一个或多个基础设施资源对象，例如 VPC、虚拟机，或是 DNS 记录、Consul 的键值对数据等。

1.4.6.1.1. 资源语法

资源通过 resource 块定义，我们首先讲解通过 resource 块定义单个资源对象的场景。

1
2
3
4
5
6
7
8
resource "aws_vpc" "main" {
  cidr_block = var.base_cidr_block
}

<BLOCK TYPE> "<BLOCK LABEL>" "<BLOCK LABEL>" {
  # Block body
  <IDENTIFIER> = <EXPRESSION> # Argument
}
  • 块 是其他内容的容器，通常代表某种对象的配置，比如资源。块有一个块类型，可以有零个或多个标签，有一个包含任意数量的参数和嵌套块的块体。Terraform 的大部分功能都是由配置文件中的顶级块控制的。
  • 参数 为一个名称赋值。它们出现在块内。
  • 表达式 表示一个值，可以是字面量，也可以是引用和组合其他值。它们出现在参数的值中，或者在其他表达式中。

Terraform 是一种声明式语言，描述的是一个期望的资源状态，而不是达到期望状态所需要的步骤。块的顺序和它们所在的文件通常不重要；Terraform 只在确定操作顺序时考虑资源之间的隐式和显式关系。

在下面的例子里：

1
2
3
4
resource "aws_instance" "web" {
  ami           = "ami-a1b2c3d4"
  instance_type = "t2.micro"
}

紧跟 resource 关键字的是资源类型，在上面的例子里就是 aws_instance。后面是资源的 Local Name，例子里就是 web。Local Name 可以在同一模块内的代码里被用来引用该资源，但类型加 Local Name 的组合在当前模块内必须是唯一的，不同类型的两个资源 Local Name 可以相同。随后的花括号内的内容就是块体，创建资源所用到的各种参数的值就在块体内定义。例子中我们定义了虚拟机所使用的镜像 id 以及虚拟机的尺寸。

请注意：资源名称必须以字母或下划线开头，只能包含字母、数字、下划线(_)和连字符(-)。

1.4.6.1.2. 资源类型

每个资源都与一个资源类型相关联，资源类型决定了它管理的基础设施对象的类型，以及资源支持的参数和其他属性。

1.4.6.1.2.1. Providers

Provider 是 Terraform 用以提供一组资源类型的插件。每个资源类型都是由一个 Provider 实现的。Provider 提供了管理单个云或本地基础设施平台的资源。Provider 与 Terraform 分开发布，但 Terraform 可以在初始化工作目录时自动安装大多数 Provider。

要管理资源，Terraform 模块必须指定所需的 Provider。有关更多信息，请参阅Provider 的声明。

大部分 Provider 需要一些配置来访问远程 API，这些配置是在根模块中配置的。有关更多信息，请参阅Provider 配置。

根据一个 resource 块的类型名，Terraform 通常可以确定使用哪个 Provider。按照约定，资源类型名以其 Provider 的首选 Local Name 开头。当使用一个 Provider 的多个配置或非首选的本地 Provider 名称时，你必须使用 provider 元参数 来手动选择一个 Provider 配置。

1.4.6.1.2.2. 资源参数

不同资源定义了不同的可赋值的属性，官方文档将之称为参数(Argument)，有些参数是必填的，有些参数是可选的。使用某项资源前可以通过阅读相关文档了解参数列表以及他们的含义、赋值的约束条件。

参数值可以是简单的字面量，也可以是一个复杂的表达式。

1.4.6.1.2.3. 资源类型的文档

每一个 Terraform Provider 都有自己的文档，用以描述它所支持的资源类型种类，以及每种资源类型所支持的属性列表。

大部分公共的 Provider 都是通过 Terraform Registry 连带文档一起发布的。当我们在 Terraform Registry 站点上浏览一个 Provider 的页面时，我们可以点击 “Documentation” 链接来浏览相关文档。Provider 的文档都是版本化的，我们可以选择特定版本的 Provider 文档。

需要注意的是，Provider 文档曾经是直接托管在 terraform.io 站点上的，也就是 Terraform 核心主站的一部分，有些 Provider 的文档目前依然托管在那里，但目前 Terraform Registry 才是所有公共 Provider 文档的主站。

1.4.6.1.3. 资源的行为

一个 resource 块声明了作者想要创建的一个确切的基础设施对象，并且设定了各项属性的值。如果我们正在编写一个新的 Terraform 代码文件，那么代码所定义的资源仅仅只在代码中存在，并没有与之对应的实际的基础设施资源存在。

对一组 Terraform 代码执行 terraform apply 可以创建、更新或者销毁实际的基础设施对象，Terraform 会制定并执行变更计划，以使得实际的基础设施符合代码的定义。

每当 Terraform 按照一个 resource 块创建了一个新的基础设施对象，这个实际的对象的 id 会被保存进 Terraform 状态中，使得将来 Terraform 可以根据变更计划对它进行更新或是销毁操作。如果一个 resource 块描述的资源在状态文件中已有记录，那么 Terraform 会比对记录的状态与代码描述的状态，如果有必要，Terraform 会制定变更计划以使得资源状态能够符合代码的描述。

这种行为适用于所有资源而无关其类型。创建、更新、销毁一个资源的细节会根据资源类型而不同，但是这个行为规则却是普适的。

1.4.6.1.4. 访问资源输出属性

资源不但可以通过参数传值，成功创建的资源还对外输出一些通过调用 API 才能获得的只读数据，经常包含了一些我们在实际创建一个资源之前无法获知的数据，比如云主机的 id 等，官方文档将之称为属性(Attribute)。我们可以在同一模块内的代码中引用资源的属性来创建其他资源或是表达式。在表达式中引用资源属性的语法是<RESOURCE TYPE>.<NAME>.<ATTRIBUTE>。

要获取一个资源类型输出的属性列表，我们可以查阅对应的 Provider 文档，一般在文档中会专门记录资源的输出属性列表。

1.4.6.1.4.1. 敏感的资源属性

在为资源类型定义架构时，Provider 开发着可以将某些属性标记为 sensitive，在这种情况下，Terraform 将在展示涉及该属性的计划时显示占位符标记(sensitive) 而不是实际值。

标记为 sensitive 的 Provider 属性的行为类似于声明为 sensitive 的输入变量，Terraform 将隐藏计划中的值，还将隐藏从该值派生出的任何其他敏感值。但是，该行为存在一些限制，如 Terraform 可能暴露敏感变量。

如果使用资源属性中的敏感值作为输出值的一部分，Terraform 将要求将输出值本身标记为 sensitive，以确认确实打算将其导出。

Terraform 仍会在状态中记录敏感值，因此任何可以访问状态数据的人都可以以明文形式访问敏感值。

注意：Terraform 从 v0.15 开始将从敏感资源属性派生的值视为敏感值本身。早期版本的 Terraform 将隐藏敏感资源属性的直接值，但不会自动隐藏从敏感资源属性派生的其他值。

1.4.6.1.5. 资源的依赖关系

我们在介绍输出值的depends_on的时候已经简单介绍过了依赖关系。一般来说在 Terraform 代码定义的资源之间不会有特定的依赖关系，Terraform 可以并行地对多个无依赖关系的资源执行变更，默认情况下这个并行度是 10。

然而，创建某些资源所需要的信息依赖于另一个资源创建后输出的属性，又或者必须在某些资源成功创建后才可以被创建，这时资源之间就存在依赖关系。

大部分资源间的依赖关系可以被 Terraform 自动处理，Terraform 会分析 resource 块内的表达式，根据表达式的引用链来确定资源之间的引用，进而计算出资源在创建、更新、销毁时的执行顺序。大部分情况下，我们不需要显式指定资源之间的依赖关系。

然而，有时候某些依赖关系是无法从代码中推导出来的。例如，Terraform 必须要创建一个访问控制权限资源，以及另一个需要该权限才能成功创建的资源。后者的创建依赖于前者的成功创建，然而这种依赖在代码中没有表现为数据引用关联，这种情况下，我们需要用 depends_on 来显式声明这种依赖关系。

1.4.6.1.6. 元参数

resource 块支持几种元参数声明，这些元参数可以被声明在所有类型的 resource 块内，它们将会改变资源的行为：

  • depends_on：显式声明依赖关系
  • count：创建多个资源实例
  • for_each：迭代集合，为集合中每一个元素创建一个对应的资源实例
  • provider：指定非默认 Provider 实例
  • lifecycle：自定义资源的生命周期行为
  • provisioner 和 connection：在资源创建后执行一些额外的操作

下面我们将逐一讲解他们的用法。

1.4.6.1.6.1. depends_on

使用 depends_on 可以显式声明资源之间哪些 Terraform 无法自动推导出的隐含的依赖关系。只有当资源间确实存在依赖关系，但是彼此间又没有数据引用的场景下才有必要使用 depends_on。

使用 depends_on 的例子是这样的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
resource "aws_iam_role" "example" {
  name = "example"

  # assume_role_policy is omitted for brevity in this example. See the
  # documentation for aws_iam_role for a complete example.
  assume_role_policy = "..."
}

resource "aws_iam_instance_profile" "example" {
  # Because this expression refers to the role, Terraform can infer
  # automatically that the role must be created first.
  role = aws_iam_role.example.name
}

resource "aws_iam_role_policy" "example" {
  name   = "example"
  role   = aws_iam_role.example.name
  policy = jsonencode({
    "Statement" = [{
      # This policy allows software running on the EC2 instance to
      # access the S3 API.
      "Action" = "s3:*",
      "Effect" = "Allow",
    }],
  })
}

resource "aws_instance" "example" {
  ami           = "ami-a1b2c3d4"
  instance_type = "t2.micro"

  # Terraform can infer from this that the instance profile must
  # be created before the EC2 instance.
  iam_instance_profile = aws_iam_instance_profile.example

  # However, if software running in this EC2 instance needs access
  # to the S3 API in order to boot properly, there is also a "hidden"
  # dependency on the aws_iam_role_policy that Terraform cannot
  # automatically infer, so it must be declared explicitly:
  depends_on = [
    aws_iam_role_policy.example,
  ]
}

我们来分段解释一下这个场景，首先我们声明了一个 AWS IAM 角色，将角色绑定在一个主机实例配置文件上：

1
2
3
4
5
6
7
8
9
10
11
12
13
resource "aws_iam_role" "example" {
  name = "example"

  # assume_role_policy is omitted for brevity in this example. See the
  # documentation for aws_iam_role for a complete example.
  assume_role_policy = "..."
}

resource "aws_iam_instance_profile" "example" {
  # Because this expression refers to the role, Terraform can infer
  # automatically that the role must be created first.
  role = aws_iam_role.example.name
}

虚拟机的声明代码中的这个赋值使得 Terraform 能够判断出虚拟机依赖于主机实例配置文件：

1
2
3
4
5
6
7
resource "aws_instance" "example" {
  ami           = "ami-a1b2c3d4"
  instance_type = "t2.micro"

  # Terraform can infer from this that the instance profile must
  # be created before the EC2 instance.
  iam_instance_profile = aws_iam_instance_profile.example

至此，Terraform 规划出的创建顺序是 IAM 角色 -> 主机实例配置文件 -> 主机实例。但是我们又为这个 IAM 角色添加了对 S3 存储服务的完全控制权限：

1
2
3
4
5
6
7
8
9
10
11
12
resource "aws_iam_role_policy" "example" {
  name   = "example"
  role   = aws_iam_role.example.name
  policy = jsonencode({
    "Statement" = [{
      # This policy allows software running on the EC2 instance to
      # access the S3 API.
      "Action" = "s3:*",
      "Effect" = "Allow",
    }],
  })
}

也就是说，虚拟机实例由于绑定了主机实例配置文件，从而在运行时拥有了一个 IAM 角色，而这个 IAM 角色又被赋予了 S3 的权限。但是虚拟机实例的声明代码中并没有引用 S3 权限的任何输出属性，这将导致 Terraform 无法理解他们之间存在依赖关系，进而可能会并行地创建两者，如果虚拟机实例被先创建了出来，内部的程序开始运行时，它所需要的 S3 权限却还没有创建完成，那么就将导致程序运行错误。为了确保虚拟机创建时 S3 权限一定已经存在，我们可以用 depends_on 显式声明它们的依赖关系：

1
2
3
4
5
6
7
# However, if software running in this EC2 instance needs access
  # to the S3 API in order to boot properly, there is also a "hidden"
  # dependency on the aws_iam_role_policy that Terraform cannot
  # automatically infer, so it must be declared explicitly:
  depends_on = [
    aws_iam_role_policy.example,
  ]

depends_on 的赋值必须是包含同一模块内声明的其他资源名称的列表，不允许包含其他表达式，例如不允许使用其他资源的输出属性，这是因为 Terraform 必须在计算资源间关系之前就能理解列表中的值，为了能够安全地完成表达式计算，所以限制只能使用资源实例的名称。

depends_on 只能作为最后的手段使用，如果我们使用 depends_on，我们应该用注释记录我们使用它的原因，以便今后代码的维护者能够理解隐藏的依赖关系。

1.4.6.1.6.2. count

一般来说，一个 resource 块定义了一个对应的实际基础设施资源对象。但是有时候我们希望创建多个相似的对象，比如创建一组虚拟机。Terraform 提供了两种方法实现这个目标：count 与 for_each。

count 参数可以是任意自然数，Terraform 会创建 count 个资源实例，每一个实例都对应了一个独立的基础设施对象，并且在执行 Terraform 代码时，这些对象是被分别创建、更新或者销毁的：

1
2
3
4
5
6
7
8
9
10
resource "aws_instance" "server" {
  count = 4 # create four similar EC2 instances

  ami           = "ami-a1b2c3d4"
  instance_type = "t2.micro"

  tags = {
    Name = "Server ${count.index}"
  }
}

我们可以在 resource 块中的表达式里使用 count 对象来获取当前的 count 索引号。count 对象只有一个属性：

  • count.index：代表当前对象对应的 count 下标索引(从 0 开始)

如果一个 resource 块定义了 count 参数，那么 Terraform 会把这种多资源实例对象与没有 count 参数的单实例资源对象区别开：

  • 访问单资源实例对象：<TYPE>.<NAME>(例如：aws_instance.server)
  • 访问多资源实例对象：<TYPE>.<NAME>[<INDEX>] (例如：aws_instance.server[0]，aws_instance.server[1])

声明了 count 或 for_each 的资源必须使用下标索引或者键来访问。

count 参数可以是任意自然数，然而与 resource 的其他参数不同，count 的值在 Terraform 进行任何远程资源操作(实际的增删改查)之前必须是已知的，这也就意味着赋予 count 参数的表达式不可以引用任何其他资源的输出属性(例如由其他资源对象创建时返回的一个唯一的 ID)。

1.4.6.1.6.3. for_each

for_each 是 Terraform 0.12.6 开始引入的新特性。一个 resource 块不允许同时声明 count 与 for_each。for_each 参数可以是一个 map 或是一个 set(string)，Terraform 会为集合中每一个元素都创建一个独立的基础设施资源对象，和 count 一样，每一个基础设施资源对象在执行 Terraform 代码时都是独立创建、修改、销毁的。

使用 map 的例子：

1
2
3
4
5
6
7
8
resource "azurerm_resource_group" "rg" {
  for_each = {
    a_group = "eastus"
    another_group = "westus2"
  }
  name     = each.key
  location = each.value
}

使用 set(string) 的例子：

1
2
3
4
resource "aws_iam_user" "the-accounts" {
  for_each = toset( ["Todd", "James", "Alice", "Dottie"] )
  name     = each.key
}

我们可以在声明了 for_each 参数的 resource 块内使用 each 对象来访问当前的迭代器对象：

  • each.key：map 的键，或是 set 中的值
  • each.value：map 的值，或是 set 中的值

如果 for_each 的值是一个 set，那么 each.key 和 each.value 是相等的。

使用 for_each 时，map 的所有键、set 的所有 string 值都必须是已知的，也就是状态文件中已有记录的值。所以有时候我们可能需要在执行 terraform apply 时添加 -target 参数，实现分步创建。另外，for_each 所使用的键集合不能够包含或依赖非纯函数，也就是反复执行会返回不同返回值的函数，例如 uuid、bcrypt、timestamp 等。

当一个 resource 声明了 for_each 时，Terraform 会把这种多资源实例对象与没有 count 参数的单资源实例对象区别开：

  • 访问单资源实例对象：<TYPE>.<NAME>(例如：aws_instance.server)
  • 访问多资源实例对象：<TYPE>.<NAME>[<KE>] (例如：aws_instance.server["ap-northeast-1"]，aws_instance.server["ap-northeast-2"])

声明了count或 for_each 的资源必须使用下标索引或者键来访问。

由于 Terraform 没有用以声明 set 的字面量，所以我们有时需要使用 toset 函数把 list(string) 转换为 set(string)：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
locals {
  subnet_ids = toset([
    "subnet-abcdef",
    "subnet-012345",
  ])
}

resource "aws_instance" "server" {
  for_each = local.subnet_ids

  ami           = "ami-a1b2c3d4"
  instance_type = "t2.micro"
  subnet_id     = each.key # note: each.key and each.value are the same for a set

  tags = {
    Name = "Server ${each.key}"
  }
}

在这里我们用 toset 把一个 list(string) 转换成了 set(string)，然后赋予 for_each。在转换过程中，list 中所有重复的元素会被抛弃，只剩下不重复的元素，例如 toset(["b", "a", "b"]) 的结果只有"a"和"b"，并且 set 的元素没有特定顺序。

如果我们要把一个输入变量赋予 for_each，我们可以直接定义变量的类型约束来避免显式调用 toset 转换类型：

1
2
3
4
5
6
7
8
9
variable "subnet_ids" {
  type = set(string)
}

resource "aws_instance" "server" {
  for_each = var.subnet_ids

  # (and the other arguments as above)
}

1.4.6.1.6.4. 在 for_each 和 count 之间选择

如果创建的资源实例彼此之间几乎完全一致，那么 count 比较合适。如果彼此之间的参数差异无法直接从 count 的下标派生，那么使用 for_each 会更加安全。

在 Terraform 引入 for_each 之前，我们经常使用 count.index 搭配 length 函数和 list 来创建多个资源实例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
variable "subnet_ids" {
  type = list(string)
}

resource "aws_instance" "server" {
  # Create one instance for each subnet
  count = length(var.subnet_ids)

  ami           = "ami-a1b2c3d4"
  instance_type = "t2.micro"
  subnet_id     = var.subnet_ids[count.index]

  tags = {
    Name = "Server ${count.index}"
  }
}

这种实现方法是脆弱的，因为资源仍然是以他们的下标而不是实际的字符串值来区分的。如果我们从 subnet_ids 列表的中间移除了一个元素，那么从该位置起后续所有的 aws_instance 都会发现它们的 subnet_id 发生了变化，结果就是所有后续的 aws_instance 都需要更新。这种场景下如果使用 for_each 就更为妥当，如果使用 for_each，那么只有被移除的 subnet_id 对应的 aws_instance 会被销毁。

1.4.6.1.6.5. provider

关于 provider 的定义我们在前面介绍 Provider 的章节已经提到过了，如果我们声明了同一类型 Provider 的多个实例，那么我们在创建资源时可以通过指定 provider 参数选择要使用的 Provider 实例。如果没有指定 provider 参数，那么 Terraform 默认使用资源类型名中第一个单词所对应的 Provider 实例，例如 google_compute_instance 的默认 Provider 实例就是 google，aws_instance 的默认 Provider 就是 aws。

指定 provider 参数的例子：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# default configuration
provider "google" {
  region = "us-central1"
}

# alternate configuration, whose alias is "europe"
provider "google" {
  alias  = "europe"
  region = "europe-west1"
}

resource "google_compute_instance" "example" {
  # This "provider" meta-argument selects the google provider
  # configuration whose alias is "europe", rather than the
  # default configuration.
  provider = google.europe

  # ...
}

provider参数期待的赋值是<PROVIDER>或是<PROVIDER>.<ALIAS>，不需要双引号。因为在Terraform开始计算依赖路径图时，provider关系必须是已知的，所以除了这两种以外的表达式是不被接受的。

1.4.6.1.6.6. lifecycle

通常一个资源对象的生命周期在前面“资源的行为”一节中已经描述了，但是我们可以用 lifecycle 块来定一个不一样的行为方式，例如：

1
2
3
4
5
6
7
resource "azurerm_resource_group" "example" {
  # ...

  lifecycle {
    create_before_destroy = true
  }
}

lifecycle 块和它的内容都属于元参数，可以被声明于任意类型的资源块内部。Terraform 支持如下几种 lifecycle：

  • create_before_destroy (bool)：默认情况下，当 Terraform 需要修改一个由于服务端 API 限制导致无法直接升级的资源时，Terraform 会删除现有资源对象，然后用新的配置参数创建一个新的资源对象取代之。create_before_destroy 参数可以修改这个行为，使得 Terraform 首先创建新对象，只有在新对象成功创建并取代老对象后再销毁老对象。这并不是默认的行为，因为许多基础设施资源需要有一个唯一的名字或是别的什么标识属性，在新老对象并存时也要符合这种约束。有些资源类型有特别的参数可以为每个对象名称添加一个随机的前缀以防止冲突。Terraform 不能默认采用这种行为，所以在使用 create_before_destroy 前你必须了解每一种资源类型在这方面的约束。
  • prevent_destroy (bool)：这个参数是一个保险措施，只要它被设置为 true 时，Terraform 会拒绝执行任何可能会销毁该基础设施资源的变更计划。这个参数可以预防意外删除关键资源，例如错误地执行了 terraform destroy，或者是意外修改了资源的某个参数，导致 Terraform 决定删除并重建新的资源实例。在 resource 块内声明了 prevent_destroy = true 会导致无法执行 terraform destroy，所以对它的使用要节制。需要注意的是，该措施无法防止我们删除 resource 块后 Terraform 删除相关资源，因为对应的 prevent_destroy = true 声明也被一并删除了。
  • ignore_changes (list(string))：默认情况下，Terraform 检测到代码描述的配置与真实基础设施对象之间有任何差异时都会计算一个变更计划来更新基础设施对象，使之符合代码描述的状态。在一些非常罕见的场景下，实际的基础设施对象会被 Terraform 之外的流程所修改，这就会使得 Terraform 不停地尝试修改基础设施对象以弥合和代码之间的差异。这种情况下，我们可以通过设定 ignore_changes 来指示 Terraform 忽略某些属性的变更。ignore_changes 的值定义了一组在创建时需要按照代码定义的值来创建，但在更新时不需要考虑值的变化的属性名，例如：
1
2
3
4
5
6
7
8
9
10
11
resource "aws_instance" "example" {
  # ...

  lifecycle {
    ignore_changes = [
      # Ignore changes to tags, e.g. because a management agent
      # updates these based on some ruleset managed elsewhere.
      tags,
    ]
  }
}

你也可以忽略 map 中特定的元素，例如 tags["Name"]，但是要注意的是，如果你是想忽略 map 中特定元素的变更，那么你必须首先确保 map 中含有这个元素。如果一开始 map 中并没有这个键，而后外部系统添加了这个键，那么 Terraform 还是会把它当成一次变更来处理。比较好的方法是你在代码中先为这个键创建一个占位元素来确保这个键已经存在，这样在外部系统修改了键对应的值以后 Terraform 会忽略这个变更。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
resource "aws_instance" "example" {
  # ...

  tags = {
    # Initial value for Name is overridden by our automatic scheduled
    # re-tagging process; changes to this are ignored by ignore_changes
    # below.
    Name = "placeholder"
  }

  lifecycle {
    ignore_changes = [
      tags["Name"],
    ]
  }
}

除了使用一个 list(string)，也可以使用关键字 all ，这时 Terraform 会忽略资源一切属性的变更，这样 Terraform 只会创建或销毁一个对象，但绝不会尝试更新一个对象。你只能在 ignore_changes 里忽略所属的 resource 的属性，ignore_changes 不可以赋予它自身或是其他任何元参数。

  • replace_triggered_by (包含资源引用的列表)：强制 Terraform 在引用的资源或是资源属性发生变更时替换声明该块的父资源，值为一个包含了托管资源、实例或是实例属性引用表达式的列表。当声明该块的资源声明了 count 或是 for_each 时，我们可以在表达式中使用 count.index 或是 each.key 来指定引用实例的序号。

replace_triggered_by 可以在以下几种场景中使用：

  • 如果表达式指向多实例的资源声明（例如声明了 count 或是 for_each 的资源），那么这组资源中任意实例发生变更或被替换时都将引发声明 replace_triggered_by 的资源被替换
  • 如果表达式指向单个资源实例，那么该实例发生变更或被替换时将引发声明 replace_triggered_by 的资源被替换
  • 如果表达式指向单个资源实例的单个属性，那么该属性值的任何变化都将引发声明 replace_triggered_by 的资源被替换

我们在 replace_triggered_by 中只能引用托管资源。这允许我们在不引发强制替换的前提下修改这些表达式。

1
2
3
4
5
6
7
8
9
10
resource "aws_appautoscaling_target" "ecs_target" {
  # ...
  lifecycle {
    replace_triggered_by = [
      # Replace `aws_appautoscaling_target` each time this instance of 
      # the `aws_ecs_service` is replaced.
      aws_ecs_service.svc.id
    ]
  }
}

lifecycle 配置影响了 Terraform 如何构建并遍历依赖图。作为结果，lifecycle 内赋值仅支持字面量，因为它的计算过程发生在 Terraform 计算的极早期。这就是说，例如 prevent_destroy、create_before_destroy 的值只能是 true 或者 false，ignore_changes、replace_triggered_by 的列表内只能是硬编码的属性名。

1.4.6.1.6.7. Precondition 与 Postcondition

请注意，Precondition 与 Postcondition 是从 Terraform v1.2.0 开始被引入的功能。

在 lifecycle 块中声明 precondition 与 postcondition 块可以为资源、数据源以及输出值创建自定义的验证规则。

Terraform 在计算一个对象之前会首先检查该对象关联的 precondition，并且在对象计算完成后执行 postcondition 检查。Terraform 会尽可能早地执行自定义检查，但如果表达式中包含了只有在 apply 阶段才能知晓的值，那么该检查也将被推迟执行。

每一个 precondition 与 postcondition 块都需要一个 condition 参数。该参数是一个表达式，在满足条件时返回 true，否则返回 false。该表达式可以引用同一模块内的任意其他对象，只要这种引用不会产生环依赖。在 postcondition 表达式中也可以使用 self 对象引用声明 postcondition 的资源实例的属性。

如果 condition 表达式计算结果为 false，Terraform 会生成一条错误信息，包含了 error_message 表达式的内容。如果我们声明了多条 precondition 或 postcondition，Terraform 会返回所有失败条件对应的错误信息。

下面的例子演示了通过 postcondition 检测调用者是否不小心传入了错误的 AMI 参数：

1
2
3
4
5
6
7
8
9
10
11
data "aws_ami" "example" {
  id = var.aws_ami_id

  lifecycle {
    # The AMI ID must refer to an existing AMI that has the tag "nomad-server".
    postcondition {
      condition     = self.tags["Component"] == "nomad-server"
      error_message = "tags[\"Component\"] must be \"nomad-server\"."
    }
  }
}

在 resource 或 data 块中的 lifecycle 块可以同时包含 precondition 与 postcondition 块。

  • Terraform 会在计算完 count 和 for_each 元参数后执行 precondition 块。这使得 Terraform 可以对每一个实例独立进行检查，并允许在表达式中使用 each.key、count.index 等。Terraform 还会在计算资源的参数表达式之前执行 precondition 检查。precondition 可以用来防止参数表达式计算中的错误被激发。
  • Terraform 在计算和执行对一个托管资源的变更之后执行 postcondition 检查，或是在完成数据源读取后执行它关联的 postcondition 检查。postcondition 失败会阻止其他依赖于此失败资源的其他资源的变更。

在大多数情况下，我们不建议在同一配置文件中同时包含表示同一个对象的 data 块和 resource 块。这样做会使得 Terraform 无法理解 data 块的结果会被 resource 块的变更所影响。然而，当我们需要检查一个 resource 块的结果，恰巧该结果又没有被资源直接输出时，我们可以使用 data 块并在块中直接使用 postcondition 来检查该对象。这等于告诉 Terraform 该 data 块是用来检查其他什么地方定义的对象的，从而允许 Terraform 以正确的顺序执行操作。

1.4.6.1.6.8. provisioner 和 connection

某些基础设施对象需要在创建后执行特定的操作才能正式工作。比如说，主机实例必须在上传了配置或是由配置管理工具初始化之后才能正常工作。

像这样创建后执行的操作可以使用预置器(Provisioner)。预置器是由 Terraform 所提供的另一组插件，每种预置器可以在资源对象创建后执行不同类型的操作。

使用预置器需要节制，因为他们采取的操作并非 Terraform 声明式的风格，所以 Terraform 无法对他们执行的变更进行建模和保存。

预置器也可以声明为资源销毁前执行，但会有一些限制。

作为元参数，provisioner 和 connection 可以声明在任意类型的 resource 块内。

举一个例子：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
resource "aws_instance" "web" {
  # ...

  provisioner "file" {
  source       = "conf/myapp.conf"
  destination  = "/etc/myapp.conf"

    connection {
      type     = "ssh"
      user     = "root"
      password = var.root_password
      host     = self.public_ip
    }
  }
}

我们在 aws_instance 中定义了类型为 file 的预置器，该预置器可以本机文件或文件夹拷贝到目标机器的指定路径下。我们在预置器内部定义了connection块，类型是ssh。我们对connection的host赋值self.public_ip，在这里self代表预置器所在的母块，也就是aws_instance.web，所以self.public_ip代表着aws_instance.web.public_ip，也就是创建出来的主机的公网ip。

file 类型预置器支持 ssh 和 winrm 两种类型的 connection。

预置器根据运行的时机分为两种类型，创建时预置器以及销毁时预置器。

1.4.6.1.7. 创建时预置器

默认情况下，创建时资源对象会运行预置器，在对象更新、销毁时则不会运行。预置器的默认行为是为了引导一个系统。

如果创建时预置器失败了，那么资源对象会被标记污点(我们将在介绍 terraform taint 命令时详细介绍)。一个被标记污点的资源在下次执行 terraform apply 命令时会被销毁并重建。Terraform 的这种设计是因为当预置器运行失败时标志着资源处于半就绪的状态。由于 Terraform 无法衡量预置器的行为，所以唯一能够完全确保资源被正确初始化的方式就是删除重建。

我们可以通过设置 on_failure 参数来改变这种行为。

1.4.6.1.8. 销毁时预置器

如果我们设置预置器的 when 参数为 destroy，那么预置器会在资源被销毁时执行：

1
2
3
4
5
6
7
8
resource "aws_instance" "web" {
  # ...

  provisioner "local-exec" {
    when    = destroy
    command = "echo 'Destroy-time provisioner'"
  }
}

销毁时预置器在资源被实际销毁前运行。如果运行失败，Terraform 会报错，并在下次运行 terraform apply 操作时重新执行预置器。在这种情况下，需要仔细关注销毁时预置器以使之能够安全地反复执行。

注意：销毁时预置器不会在 resource 块配置了 create_before_destroy = true 时运行。

销毁时预置器只有在存在于代码中的情况下才会在销毁时被执行。如果一个 resource 块连带内部的销毁时预置器块一起被从代码中删除，那么被删除的预置器在资源被销毁时不会被执行。要解决这个问题，我们需要使用多个步骤来绕过这个限制：

  • 修改资源声明代码，添加 count = 0 参数
  • 执行 terraform apply，运行删除时预置器，然后删除资源实例
  • 删除 resource 块
  • 重新执行 terraform apply，此时应该不会有任何变更需要执行

该限制在未来将会得到解决，但目前来说我们必须节制使用销毁时预置器。

注意：一个被标记污点的 resource 块内的销毁时预置器不会被执行。这包括了因为创建时预置器失败或是手动使用 terraform taint 命令标记污点的资源。

1.4.6.1.9. 预置器失败行为

默认情况下，预置器运行失败会导致terraform apply执行失败。可以通过设置on_failure参数来改变这一行为。可以设置的值为：

  • continue：忽视错误，继续执行创建或是销毁
  • fail：报错并终止执行变更(这是默认行为)。如果这是一个创建时预置器，则在对应资源对象上标记污点

样例：

1
2
3
4
5
6
7
8
resource "aws_instance" "web" {
  # ...

  provisioner "local-exec" {
    command    = "echo The server's IP address is ${self.private_ip}"
    on_failure = continue
  }
}

1.4.6.1.10. 删除资源

注意：removed 块是在 Terraform v1.7 引入的功能。对于早期的 Terraform 版本，您可以使用 terraform state rm 命令来处理。

要从 Terraform 中删除资源，只需从 Terraform 代码中删除 resource 块即可。

默认情况下，删除 resource 块后，Terraform 将计划销毁该资源管理的所有实际基础设施对象。

有时，我们可能希望从 Terraform 配置中删除资源，而不破坏它管理的实际基础设施对象。在这种情况下，资源将从 Terraform 状态中删除，但真正的基础设施对象不会被破坏。

要声明资源已从 Terraform 配置中删除，但不应销毁其托管对象，请从配置中删除 resource 块并将其替换为 removed 块：

1
2
3
4
5
6
7
removed {
  from = aws_instance.example

  lifecycle {
    destroy = false
  }
}

from 参数是您要删除的资源的地址，没有任何实例键（例如 aws_instance.example[1]）。

lifecycle 块是必需的。 destroy 参数确定 Terraform 是否会尝试销毁资源管理的对象。 false 值表示 Terraform 将从状态中删除资源而不销毁实际的远程资源。

removed 块还可以包含销毁时预置器，以便即使 resource 块已被删除，预制器也可以保留在代码中。

1
2
3
4
5
6
7
8
9
10
11
12
removed {
  from = aws_instance.example

  lifecycle {
    destroy = true
  }

  provisioner "local-exec" {
    when    = destroy
    command = "echo 'Instance ${self.id} has been destroyed.'"
  }
}

与普通的销毁时预置器中的引用规则相同，仅允许使用 count.index、each.key 和 self。预置器必须指定 when = destroy，并且 removed 块必须声明 destroy = true 才能执行预置器。

1.4.6.1.11. 本地资源

虽然大部分资源类型都对应的是通过远程基础设施 API 控制的一个资源对象，但也有一些资源对象他们只存在于 Terraform 进程自身内部，用来计算生成某些结果，并将这些结果保存在状态中以备日后使用。

比如说，我们可以用 tls_private_key 生成公私钥，用 tls_self_signed_cert 生成自签名证书，或者是用 random_id 生成随机 id。虽不像其他“真实”基础设施对象那般重要，但这些本地资源也可以成为连接其他资源有用的黏合剂。

本地资源的行为与其他类型资源是一致的，但是他们的结果数据仅存在于 Terraform 状态文件中。“销毁”这种资源只是将结果数据从状态中删除。

1.4.6.1.12. 操作超时设置

有些资源类型提供了特殊的 timeouts 内嵌块参数，它允许我们配置我们允许操作持续多长时间，超时将被认定为失败。比如说，aws_db_instance 资源允许我们分别为 create，update，delete 操作设置超时时间。

超时完全由资源对应的 Provider 来处理，但支持超时设置的 Provider 一般都遵循相同的传统，那就是由一个名为 timeouts 的内嵌块参数定义超时设置，timeouts 块内可以分别设置不同操作的超时时间。超时时间由 string 描述，比如 "60m" 代表 60 分钟，"10s" 代表 10 秒，"2h" 代表 2 小时。

1
2
3
4
5
6
7
8
resource "aws_db_instance" "example" {
  # ...

  timeouts {
    create = "60m"
    delete = "2h"
  }
}

可配置超时的操作类别由每种支持超时设定的资源类型自行决定。大部分资源类型不支持设置超时。使用超时前请先查阅相关文档。

1.4.7.1. 数据源

数据源允许查询或计算一些数据以供其他地方使用。使用数据源可以使得 Terraform 代码使用在 Terraform 管理范围之外的一些信息，或者是读取其他 Terraform 代码保存的状态。

每一种 Provider 都可以在定义一些资源类型的同时定义一些数据源。

1.4.7.1.1. 使用数据源

数据源通过一种特殊的资源访问：data 资源。数据源通过 data 块声明：

1
2
3
4
5
6
7
8
9
data "aws_ami" "example" {
  most_recent = true

  owners = ["self"]
  tags = {
    Name   = "app-server"
    Tested = "true"
  }
}

一个 data 块请求 Terraform 从一个指定的数据源 aws_ami 读取指定数据并且把结果输出到 Local Name 为 example 的实例中。我们可以在同一模块内的代码中通过数据源名称来引用数据源，但无法从模块外部直接访问数据源。

同资源类似，一个数据源类型以及它的名称一同构成了该数据源的标识符，所以数据源类型加名称的组合在同一模块内必须是唯一的。

在 data 块体({ 与 } 中间的内容)是传给数据源的查询条件。查询条件参数的种类取决于数据源的类型，在上述例子中，most_recent、owners 和 tags 都是定义查询 aws_ami 数据源时使用的查询条件。

与数据源这种特殊资源不同的是，我们在上一节介绍的主要资源(使用 resource 块定义的)是一种“托管资源”。这两种资源都可以接收参数并对外输出属性，但托管资源会触发 Terraform 对基础设施对象进行增删改操作，而数据源只会触发读取操作。简单来说，我们一般说的“资源”就是特指托管资源。

1.4.7.1.2. 数据源参数

每一种数据源资源都关联到一种外部数据源，数据源类型决定了它接收的查询参数以及输出的数据。每一种数据源类型都属于一个 Provider。大部分 data 块内的数据源参数都是由对应的数据源类型定义的，这些参数的赋值可以使用完整的 Terraform 表达式能力或其他 Terraform 语言的功能。

然而类似资源，Terraform 也为所有类型的数据源定义了一些元参数。这些元参数的限制和功能我们将在后续节当中叙述。

1.4.7.1.3. 数据源行为

如果数据源的查询参数涉及到的表达式只引用了字面量或是在执行 terraform plan 时就已知的数据(比如输入变量)，那么数据源会在执行 Terraform 的 “refersh” 阶段时被读取，然后 Terraform 会构建变更计划。这保证了在制定变更计划时 Terraform 可以使用这些数据源的返回数据。

如果查询参数的表达式引用了那些只有执行部分执行变更计划以后才能知晓的数据，比如另一个还未被创建的托管资源的输出，那么数据源的读取操作会被推迟到 “apply” 阶段。以下几种情况下 Terraform 会推迟数据源的读取：

  • 给定的参数中至少有一个是一个托管资源的属性或是其他值，Terraform 在执行步骤之前无法预测。
  • data 块内的查询参数引用了一个还未被创建的托管资源的输出。
  • data 块内声明的 precondition 或 postcondition 直接或间接地依赖了一个在当前计划中有变更的托管资源。

任何引用该数据源输出的表达式的值在执行到数据源被读取完之前都是未知的。

1.4.7.1.4. 本地数据源

虽然绝大多数数据源都对应了一个通过远程基础设施 API 访问的外部数据源，但是也有一些特殊的数据源仅存在于 Terraform 进程内部，计算并对外输出一些数据。

比如说，本地数据源有 template_file、local_file、aws_iam_policy_document 等。

本地数据源的行为与其他数据源完全一致，但他们输出的结果数据只是临时存在于 Terraform 运行时，每次计算一个新的变更计划时这些值都会被重新计算。

1.4.7.1.5. 数据源的依赖关系

数据源有着与资源一样的依赖机制，我们也可以在 data 块内设置 depends_on 元参数来显式声明依赖关系，在此不再赘述。

注意：在 Terraform 0.12 及更早版本中，由于 data 会将尚不知晓值的读取推迟到 Apply 阶段，因此将 dependent_on 与 data 一起使用将强制将数据的读取推迟到 Apply 阶段，因此，使用 depends_on 的 data 数据源配置永远无法收敛。由于这种行为，我们不建议对 data 使用 depends_on。

1.4.7.1.6. Precondition 与 Postcondition

您可以使用 precondition 和 postcondition 块来指定有关 data 如何运行的假设和验证。以下实力创建一个 postcondition 来检查 AMI 是否具有正确的标签：

1
2
3
4
5
6
7
8
9
10
11
data "aws_ami" "example" {
  id = var.aws_ami_id

  lifecycle {
    # The AMI ID must refer to an existing AMI that has the tag "nomad-server".
    postcondition {
      condition     = self.tags["Component"] == "nomad-server"
      error_message = "tags[\"Component\"] must be \"nomad-server\"."
    }
  }
}

自定义条件检查可以声明对数据的假设，帮助未来的维护人员了解代码的设计和意图。它们还可以更早地在上下文中返回有关错误的有用信息，帮助使用者更轻松地诊断其配置中的问题。

1.4.7.1.7. 生命周期

同资源不一样，数据源目前的 lifecycle 块中只支持 precondition 和 postcondition 块。

1.4.7.1.8. 多数据源实例

与资源一样，数据源也可以通过设置 count、for_each 元参数来创建一组多个数据源实例，并且 Terraform 也会把每个数据源实例单独创建并读取相应的外部数据，对 count.index 与 each 的使用也是一样的，在 count 与 for_each 之间选择的原则也是一样的。

1.4.7.1.9. 指定特定 Provider 实例

同资源一样，数据源也可以通过 provider 元参数指定使用特定 Provider 实例，在此不再赘述。

1.4.7.1.10. 例子

一个数据源定义例子如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Find the latest available AMI that is tagged with Component = web
data "aws_ami" "web" {
  filter {
    name   = "state"
    values = ["available"]
  }

  filter {
    name   = "tag:Component"
    values = ["web"]
  }

  most_recent = true
}

1.4.7.1.11. 引用数据源

引用数据源数据的语法是data.<TYPE>.<NAME>.<ATTRIBUTE>：

1
2
3
4
resource "aws_instance" "web" {
  ami           = data.aws_ami.web.id
  instance_type = "t1.micro"
}

1.4.8.1. 表达式

表达式用来在配置文件中进行一些计算。最简单的表达式就是字面量，比如 "hello"，或者 5。Terraform 也支持一些更加复杂的表达式，比如引用其他 resource 的输出值、数学计算、布尔条件计算，以及一些内建的函数。

Terraform 配置中很多地方都可以使用表达式，但某些特定的场景下限制了可以使用的表达式的类型，例如只准使用特定数据类型的字面量，或是禁止使用 resource 的输出值。

您可以通过运行 terraform console 命令，从 Terraform 表达式控制台测试 Terraform 表达式的行为。

我们在类型章节中已经基本介绍了类型以及类型相关的字面量，下面我们来介绍一些其他的表达式。

1.4.8.1.1. 下标和属性

list 和 tuple 可以通过下标访问成员，例如 local.list[3]、var.tuple[2]。map 和 object 可以通过属性访问成员，例如 local.object.attrname、local.map.keyname。由于 map 的键是用户定义的，可能无法成为合法的 Terraform 标识符，所以访问 map 成员时我们推荐使用方括号：local.map["keyname"]。

1.4.8.1.2. 引用命名值

Terraform 中定义了多种命名值，表达式中的每一个命名值都关联到一个具体的值，我们可以用单一命名值作为一个表达式，或是组合多个命名值来计算出一个新值。

命名值有如下种类：

  • <RESOURCE TYPE>.<NAME>：表示一个资源对象。凡是不符合后面列出的命名值模式的表达式都会被 Terraform 解释为一个托管资源。如果资源声明了 count 元参数，那么该表达式表示的是一个对象实例的 list。如果资源声明了 for_each 元参数，那么该表达式表示的是一个对象实例的 map。
  • var.<NAME>：表示一个输入变量
  • local.<NAME>：表示一个局部值
  • module.<MODULE_NAME>.<OUTPUT_NAME>：表示一个模块的一个输出值
  • data.<DATA_TYPE>.<NAME>：表示一个数据源实例。如果数据源声明了 count 元参数，那么该表达式表示的是一个数据源实例 list。如果数据源声明了 for_each 元参数，那么该表达式表示的是一个数据源实例 map。
  • path.module：表示当前模块在文件系统中的路径
  • path.root：表示根模块(调用 Terraform 命令行执行的代码文件所在的模块)在文件系统中的路径
  • path.cwd：表示当前工作目录的路径。一般来说该路径等同于 path.root，但在调用 Terraform 命令行时如果指定了代码路径，那么二者将会不同。
  • terraform.workspace：当前使用的 Workspace (我们在状态管理的"状态的隔离存储"中介绍过)

虽然这些命名表达式可以使用 .<NAME> 号来访问对象的各种属性，但实际上他们实际类型并不是我们在类型章节里提到过的 object。两者的区别在于，object 同时支持使用 .<NAME> 或者 ["<NAME>"] 两种方式访问对象成员属性，而上述命名表达式仅支持 .<NAME>。

1.4.8.1.3. 局部命名值

在某些特定表达式或上下文当中，有一些特殊的命名值可以被使用，他们是局部命名值。几种比较常见的局部命名值有：

  • count.index：表达当前 count 下标序号
  • each.key：表达当前 for_each 迭代器实例
  • self：在预置器中指代声明预置器的资源

1.4.8.1.4. 命名值的依赖关系

构建资源或是模块时经常会使用含有命名值的表达式赋值，Terraform 会分析这些表达式并自动计算出对象之间的依赖关系。

1.4.8.1.5. 引用资源输出属性

最常见的引用类型就是引用一个 resource 或 data 块定义的对象的输出属性。由于这些资源与数据源对象结构可能非常复杂，所以对它们的输出属性的引用表达式也可能非常复杂。

比如下面这个例子：

1
2
3
4
5
6
7
8
9
10
11
12
13
resource "aws_instance" "example" {
  ami           = "ami-abc123"
  instance_type = "t2.micro"

  ebs_block_device {
    device_name = "sda2"
    volume_size = 16
  }
  ebs_block_device {
    device_name = "sda3"
    volume_size = 20
  }
}

aws_instance 文档列出了该类型所支持的所有输入参数和内嵌块，以及对外输出的属性列表。所有这些不同的资源类型 Schema 都可以在引用中使用，如下所示：

  • ami 参数可以在可以在其他地方用 aws_instance.example.ami 表达式来引用
  • id 属性可以用 aws_instance.example.id 的表达式来引用
  • 内嵌的 ebs_block_device 参数可以通过后面会介绍的展开表达式(splat expression)来访问，比如我们获取所有的 ebs_block_device 的 device_name 列表：aws_instance.example.ebs_block_device[*].device_name
  • 在 aws_instance 类型里的内嵌块并没有任何输出属性，但如果 ebs_block_device 添加了一个名为 "id" 的输出属性，那么可以用 aws_instance.example.ebs_block_device[*].id 表达式来访问含有所有 id 的列表
  • 有时多个内嵌块会各自包含一个逻辑键来区分彼此，类似用资源名访问资源，我们也可以用内嵌块的名字来访问特定内嵌块。假如 aws_instance 类型有一个假想的内嵌块类型 device 并规定 device 可以赋予这样的一个逻辑键，那么代码看起来就会是这样的：
1
2
3
4
5
6
device "foo" {
  size = 2
}
device "bar" {
  size = 4
}

我们可以使用键来访问特定块的数据，例如：aws_instance.example.device["foo"].size

要获取一个 device 名称到 device 大小的映射，可以使用 for 表达式：

1
{for k, device in aws_instance.example.device : k => device.size}

当一个资源声明了 count 参数，那么资源本身就成了一个资源对象列表而非单个资源。这种情况下要访问资源输出属性，要么使用展开表达式，要么使用下标索引：

  • aws_instance.example[*].id：返回所有 instance 的 id 列表
  • aws_instance.example[0].id：返回第一个 instance的 id

当一个资源声明了 for_each 参数，那么资源本身就成了一个资源对象字典而非单个资源。这种情况下要访问资源的输出属性，要么使用特定键，要么使用 for 表达式：

  • aws_instance.example["a"].id：返回 "a" 对应的实例的 id
  • [for value in aws_instance.example: value.id]：返回所有 instance 的 id

注意不像使用 count，使用 for_each 的资源集合不能直接使用展开表达式，展开表达式只能适用于列表。你可以把字典转换成列表后再使用展开表达式：

  • values(aws_instance.example)[*].id

1.4.8.1.6. 尚不知晓的值

当 Terraform 在计算变更计划时，有些资源输出属性无法立即求值，因为他们的值取决于远程API的返回值。比如说，有一个远程对象可以在创建时返回一个生成的唯一 id，Terraform 无法在创建它之前就预知这个值。

为了允许在计算变更阶段就能计算含有这种值的表达式，Terraform 使用了一个特殊的"尚不知晓(unknown value)"占位符来代替这些结果。大部分时候你不需要特意理会它们，因为 Terraform 语言会自动处理这些尚不知晓的值，比如说使两个尚不知晓的值相加得到的会是一个尚不知晓的值。

然而，有些情况下表达式中含有尚不知晓的值会有明显的影响：

  • count 元参数不可以为尚不知晓，因为变更计划必须明确地知晓到底要维护多少个目标实例
  • 如果尚不知晓的值被用于数据源，那么数据源在计算变更计划阶段就无法读取，它会被推迟到执行阶段读取。这种情况下，在计划阶段该数据源的一切输出均为尚不知晓
  • 如果声明 module 块时传递给模块输入变量的表达式使用了尚不知晓值，那么在模块代码中任何使用了该输入变量值的表达式的值都将是尚不知晓
  • 如果模块输出值表达式中含有尚不知晓值，任何使用该模块输出值的表达式都将是尚不知晓
  • Terraform 会尝试验证尚不知晓值的数据类型是否合法，但仍然有可能无法正确检查数据类型，导致执行阶段发生错误

尚不知晓值在执行 terraform plan 时会被输出为 “(not yet known)”。

1.4.8.1.7. 算数和逻辑操作符

一个操作符是一种用以转换或合并一个或多个表达式的表达式。操作符要么是把两个值计算为第三个值，也就是二元操作符；要么是把一个值转换成另一个值，也就是一元操作符。

二元操作符位于两个表达式的中间，类似 1+2。一元操作符位于一个表达式的前面，类似 !true。

Terraform 的 HCL 语言支持一组算数和逻辑操作符，它们的功能类似于 JavaScript 或 Ruby 里的操作符功能。

当一个表达式中含有多个操作符时，它们的优先级顺序为：

  1. !，- (负号)
  2. *，/，%
  3. +，- (减号)
  4. >，>=，<，<=
  5. ==，!=
  6. &&
  7. ||

可以使用小括号覆盖默认优先级。如果没有小括号，高优先级操作符会被先计算，例如 1+2*3 会被解释成 1+(2*3) 而不是 (1+2)*3。

不同的操作符可以按它们之间相似的行为被归纳为几组，每一组操作符都期待被给予特定类型的值。Terraform 会在类型不符时尝试进行隐式类型转换，如果失败则会抛错。

1.4.8.1.7.1. 算数操作符

  • a + b：返回 a 与 b 的和
  • a - b：返回 a 与 b 的差
  • a * b：返回 a 与 b 的积
  • a / b：返回 a 与 b 的商
  • a % b：返回 a 与 b 的模。该操作符一般仅在 a 与 b 是整数时有效
  • -a：返回 a 与 -1 的商

1.4.8.1.7.2. 相等性操作符

  • a == b：如果 a 与 b 类型与值都相等返回 true，否则返回 false
  • a != b：与 == 相反

1.4.8.1.7.3. 比较操作符

  • a < b：如果 a 比 b 小则为 true，否则为 false
  • a > b：如果 a 比 b 大则为 true，否则为 false
  • a <= b：如果 a 比 b 小或者相等则为 true，否则为 false
  • a >= b：如果 a 比 b 大或者相等则为 true，否则为 false

1.4.8.1.7.4. 逻辑操作符

  • a || b：a 或 b 中有至少一个为 true 则为 true，否则为 false
  • a && b：a 与比都为 true 则为 true，否则为 false
  • !a：如果 a 为 true 则为 false，如果 a 为 false 则为 true

1.4.8.1.8. 条件表达式

条件表达式是判断一个布尔表达式的结果以便于在后续两个值当中选择一个：

1
condition ? true_val : false_val

如果 condition 表达式为 true，那么结果是 true_value，反之则为 false_value。

一个常见的条件表达式用法是使用默认值替代非法值：

1
var.a != "" ? var.a : "default-a"

(注：以上表达式目前推荐写为：coalesce(var.a, "default-a"))

如果输入变量 a 的值是空字符串，那么结果会是 default-a，否则返回输入变量 a 的值。

条件表达式的判断条件可以使用上述的任意操作符。供选择的两个值也可以是任意类型，但它们的类型必须相同，这样 Terraform 才能判断条件表达式的输出类型。

1.4.8.1.9. 函数调用

Terraform 支持在计算表达式时使用一些内建函数，函数调用表达式类似操作符，通用语法是：

1
<FUNCTION NAME>(<ARGUMENT 1>, <ARGUMENT 2>)

函数名标明了要调用的函数。每一个函数都定义了数量不等、类型不一的入参以及不同类型的返回值。

有些函数定义了不定长的入参表，例如，min 函数可以接收任意多个数值类型入参，返回其中最小的数值：

1
min(55, 3453, 2)

1.4.8.1.9.1. 展开函数入参

如果想要把列表或元组的元素作为参数传递给函数，那么我们可以使用展开符：

1
min([55, 2453, 2]...)

展开符使用的是三个独立的 . 号组成的 ...，不是 Unicode 中的省略号 …。展开符是一种只能用在函数调用场景下的特殊语法。

有关完整的内建函数我们可能会在今后撰写相应的章节介绍。

1.4.8.1.10. for 表达式

for 表达式是将一种复杂类型映射成另一种复杂类型的表达式。输入类型值中的每一个元素都会被映射为一个或零个结果。

举例来说，如果 var.list 是一个字符串列表，那么下面的表达式将会把列表元素全部转为大写：

1
[for s in var.list : upper(s)]

在这里 for 表达式迭代了 var.list 中每一个元素(就是 s)，然后计算了 upper(s)，最后构建了一个包含了所有 upper(s) 结果的新元组，元组内元素顺序与源列表相同。

for 表达式周围的括号类型决定了输出值的类型。上面的例子里我们使用了方括号，所以输出类型是元组。如果使用的是花括号，那么输出类型是对象，for 表达式内部冒号后面应该使用以 => 符号分隔的表达式：

1
{for s in var.list : s => upper(s)}

该表达式返回一个对象，对象的成员属性名称就是源列表中的元素，值就是对应的大写值。

一个 for 表达式还可以包含一个可选的 if 子句用以过滤结果，这可能会减少返回的元素数量：

1
[for s in var.list : upper(s) if s != ""]

被 for 迭代的也可以是对象或者字典，这样的话迭代器就会被表示为两个临时变量：

1
[for k, v in var.map : length(k) + length(v)]

最后，如果返回类型是对象(使用花括号)那么表达式中可以使用 ... 符号实现 group by：

1
{for s in var.list : substr(s, 0, 1) => s... if s != ""}

1.4.8.1.11. 展开表达式(Splat Expression)

展开表达式提供了一种类似 for 表达式的简洁表达方式。比如说 var.list 包含一组对象，每个对象有一个属性 id，那么读取所有 id 的 for 表达式会是这样：

1
[for o in var.list : o.id]

与之等价的展开表达式是这样的：

1
var.list[*].id

这个特殊的 [*] 符号迭代了列表中每一个元素，然后返回了它们在 . 号右边的属性值。

展开表达式只能被用于列表(所以使用 for_each 参数的资源不能使用展开表达式，因为它的类型是字典)。然而，如果一个展开表达式被用于一个既不是列表又不是元组的值，那么这个值会被自动包装成一个单元素的列表然后被处理。

比如说，var.single_object[*].id 等价于 [var.single_object][*].id。大部分场景下这种行为没有什么意义，但在访问一个不确定是否会定义 count 参数的资源时，这种行为很有帮助，例如：

1
aws_instance.example[*].id

上面的表达式不论 aws_instance.example 定义了 count 与否都会返回实例的 id 列表，这样如果我们以后为 aws_instance.example 添加了 count 参数我们也不需要修改这个表达式。

1.4.8.1.11.1. 遗留的旧有展开表达式

曾经存在另一种旧的展开表达式语法，它是一种比较弱化的展开表达式，现在应该尽量避免使用。

这种旧的展开表达式使用 .* 而不是 [*]：

1
var.list.*.interfaces[0].name

要特别注意该表达式与现有的展开表达式结果不同，它的行为等价于：

1
[for o in var.list : o.interfaces][0].name

而现有 [*] 展开表达式的行为等价于：

1
[for o in var.list : o.interfaces[0].name]

注意两者右方括号的位置。

1.4.8.1.12. dynamic 块

在顶级块，例如 resource 块当中，一般只能以类似 name = expression 的形式进行一对一的赋值。大部分情况下这已经够用了，但某些资源类型包含了可重复的内嵌块，无法使用表达式循环赋值：

1
2
3
4
5
6
7
resource  "aws_elastic_beanstalk_environment" "tfenvtest" {
  name = "tf-test-name" # can use expressions here

  setting {
    # but the "setting" block is always a literal block
  }
}

你可以用 dynamic 块来动态构建重复的 setting 这样的内嵌块：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
resource "aws_elastic_beanstalk_environment" "tfenvtest" {
  name                = "tf-test-name"
  application         = "${aws_elastic_beanstalk_application.tftest.name}"
  solution_stack_name = "64bit Amazon Linux 2018.03 v2.11.4 running Go 1.12.6"

  dynamic "setting" {
    for_each = var.settings
    content {
      namespace = setting.value["namespace"]
      name = setting.value["name"]
      value = setting.value["value"]
    }
  }
}

dynamic 可以在 resource、data、provider 和 provisioner 块内使用。一个 dynamic 块类似于 for 表达式，只不过它产生的是内嵌块。它可以迭代一个复杂类型数据然后为每一个元素生成相应的内嵌块。在上面的例子里：

  • dynamic 的标签(也就是 "setting")确定了我们要生成的内嵌块种类
  • for_each 参数提供了需要迭代的复杂类型值
  • iterator 参数(可选)设置了用以表示当前迭代元素的临时变量名。如果没有设置 iterator，那么临时变量名默认就是 dynamic 块的标签(也就是 setting)
  • labels 参数(可选)是一个表示块标签的有序列表，用以按次序生成一组内嵌块。有 labels 参数的表达式里可以使用临时的 iterator 变量
  • 内嵌的 content 块定义了要生成的内嵌块的块体。你可以在 content 块内部使用临时的 iterator 变量

由于 for_each 参数可以是集合或者结构化类型，所以你可以使用 for 表达式或是展开表达式来转换一个现有集合的类型。

iterator 变量(上面的例子里就是 setting)有两个属性：

  • key：迭代容器如果是 map，那么就是当前元素的键；迭代容器如果是 list，那么就是当前元素在 list 中的下标序号；如果是由 for_each 表达式产出的 set，那么 key 和 value 是一样的，这时我们不应该使用 key。
  • value：当前元素的值

一个 dynamic 块只能生成属于当前块定义过的内嵌块参数。无法生成诸如 lifecycle、provisioner 这样的元参数，因为 Terraform 必须在确保对这些元参数求值的计算是成功的。

for_each 的值必须是不为空的 map 或者 set。如果你需要根据内嵌数据结构或者多个数据结构的元素组合来声明资源实例集合，你可以使用 Terraform 表达式和函数来生成合适的值。

1.4.8.1.12.1. dynamic 块的最佳实践

过度使用 dynamic 块会导致代码难以阅读以及维护，所以我们建议只在需要构造可重用的模块代码时使用 dynamic 块。尽可能手写内嵌块。

1.4.8.1.13. 字符串字面量

Terraform 有两种不同的字符串字面量。最通用的就是用一对双引号包裹的字符，比如 "hello"。在双引号之间，反斜杠 \ 被用来进行转义。Terraform 支持的转义符有：

Sequence Replacement
\n 换行
\r 回车
\t 制表符
\" 双引号 (不会截断字符串)
\\ 反斜杠
\uNNNN 普通字符映射平面的Unicode字符(NNNN代表四位16进制数)
\UNNNNNNNN 补充字符映射平面的Unicode字符(NNNNNNNN代表八位16进制数)

另一种字符串表达式被称为 “heredoc” 风格，是受 Unix Shell 语言启发。它可以使用自定义的分隔符更加清晰地表达多行字符串：

1
2
3
4
<<EOT
hello
world
EOT

<< 标记后面直到行尾组成的标识符开启了字符串，然后 Terraform 会把剩下的行都添加进字符串，直到遇到与标识符完全相等的字符串为止。在上面的例子里，EOT 就是标识符。任何字符都可以用作标识符，但传统上标识符一般以 EO 开头。上面例子里的 EOT 代表"文本的结束(end of text)"。

上面例子里的 heredoc 风格字符串要求内容必须对齐行头，这在块内声明时看起来会比较奇怪：

1
2
3
4
5
6
block {
  value = <<EOT
hello
world
EOT
}

为了改进可读性，Terraform 也支持缩进的 heredoc，只要把 << 改成 <<-：

1
2
3
4
5
6
block {
  value = <<-EOT
  hello
    world
  EOT
}

上面的例子里，Terraform 会以最靠近行头的行作为基准来调整行头缩进，得到的字符串是这样的：

1
2
hello
  world

heredoc 中的反斜杠不会被解释成转义，而只会是简单的反斜杠。

双引号和 heredoc 两种字符串都支持字符串模版，模版的形式是 ${...} 以及 %{...}。如果想要表达 ${ 或者 %{ 的字面量，那么可以重复第一个字符：$${ 和 %%{ 。

1.4.8.1.14. 字符串模版

字符串模版允许我们在字符串中嵌入表达式，或是通过其他值动态构造字符串。

1.4.8.1.14.1. 插值(Interpolation)

一个 ${...} 序列被称为插值，插值计算花括号之间的表达式的值，有必要的话将之转换为字符串，然后插入字符串模版，形成最终的字符串：

1
"Hello, ${var.name}!"

上面的例子里，输入变量 var.name 的值被访问后插入了字符串模版，产生了最终的结果，比如："Hello, Juan!"

1.4.8.1.14.2. 命令(Directive)

一个 %{...} 序列被称为命令，命令可以是一个布尔表达式或者是对集合的迭代，类似条件表达式以及 for 表达式。有两种命令：

  • if \<BOOL\> / else /endif 命令根据布尔表达式的结果在两个模版中选择一个：
1
"Hello, %{ if var.name != "" }${var.name}%{ else }unnamed%{ endif }!"

else 部分可以省略，这样如果布尔表达结果为false那么就会插入空字符串。

  • for \<NAME\> in \<COLLECTION\> / endfor 命令迭代一个结构化对象或者集合，用每一个元素渲染模版，然后把它们拼接起来：
1
2
3
4
5
<<EOT
%{ for ip in aws_instance.example.*.private_ip }
server ${ip}
%{ endfor }
EOT

for 关键字后紧跟的名字被用作代表迭代器元素的临时变量，可以用来在内嵌模版中使用。

为了在不添加额外空格和换行的前提下提升可读性，所有的模版序列都可以在首尾添加 ~ 符号。如果有 ~ 符号，那么模版序列会去除字符串左右的空白(空格以及换行)。如果 ~ 出现在头部，那么会去除字符串左侧的空白；如果出现在尾部，那么会去除字符串右边的空白：

1
2
3
4
5
<<EOT
%{ for ip in aws_instance.example.*.private_ip ~}
server ${ip}
%{ endfor ~}
EOT

上面的例子里，命令符后面的换行符被忽略了，但是 server ${ip} 后面的换行符被保留了，这确保了每一个元素生成一行输出：

1
2
3
server 10.1.16.154
server 10.1.16.1
server 10.1.16.34

当使用模版命令时，我们推荐使用 heredoc 风格字符串，用多行模版提升可读性。双引号字符串内最好只使用插值。

1.4.8.1.15. Terraform 插值

Terraform 曾经只支持在表达式中使用插值，例如

1
2
3
4
resource "aws_instance" "example" {
  ami           = var.image_id
  # ...
}

这种语法是在 Terraform 0.12 后才被支持的。在 Terraform 0.11 及更早的版本中，这段代码只能被写成这样：

1
2
3
4
resource "aws_instance" "example" {
  ami           = "${var.image_id}"
  # ...
}

Terraform 0.12 保持了向前兼容，所以现在这样的代码也仍然是合法的。读者们也许会在一些 Terraform 代码和文档中继续看到这样的写法，但请尽量避免继续这样书写纯插值字符串，而是直接使用表达式。

1.4.9.1. 重载文件

一般来说 Terraform 会加载模块内所有的 .tf 和 .tf.json 文件，并要求文件内定义了一组无重复的对象。如果两个文件尝试定义同一个对象，那么 Terraform 会报错。

在某些少见场景中，能够用单独的文件重载已有对象配置的特定部分将会十分有用。比如说，由工程师编写的配置文件能够在运行时被程序生成的 JSON 文件部分重载。

为支持这些少见场景，Terraform 会对后缀名为 override.tf 和 override.tf.json 的代码文件进行特殊处理。对于名为 override.tf 和 override.tf.json 的代码文件也会进行相同的特殊处理。

Terraform 一开始加载代码文件时会跳过这些重载文件，然后才会按照字典序一个一个处理重载文件。对重载文件中定义的所有顶级块(resource、data等)，Terraform 会尝试找到对应的已有对象并且将重载内容合并进已有对象。

重载文件只应使用于特殊场景，过度使用会使得读者在阅读原始代码文件时被迫还要阅读所有的重载文件才能理解对象配置，从而降低了代码的可读性。使用重载文件时，请在原始文件被重载的部分添加相应注释，提醒未来的读者哪些部分会被重载文件修改。

1.4.9.1.1. 例子

如果我们有一个名为 example.tf 的代码文件：

1
2
3
4
resource "aws_instance" "web" {
  instance_type = "t2.micro"
  ami           = "ami-408c7f28"
}

然后我们创建一个名为 override.tf 的文件：

1
2
3
resource "aws_instance" "web" {
  ami = "foo"
}

Terraform 随后会合并两者，实际的配置会是这样的：

1
2
3
4
resource "aws_instance" "web" {
  instance_type = "t2.micro"
  ami           = "foo"
}

1.4.9.1.2. 合并行为

不同的块类型有着些微不同的合并行为，某些特定块内的特殊构造会以特殊形式被合并。

一般来说：

  • 重载文件内的顶级块会和普通文件内同类型同名的顶级块合并
  • 重载文件内的顶级块配置册参数会覆盖普通文件内对应块内的同名参数
  • 重载块内的内嵌块会取代普通文件内对应块内的所有同类型内嵌块。所有重载块内没有定义的内嵌块在普通文件内保持不变
  • 内嵌块的内容不会进行合并
  • 合并后的块仍然需要符合对应块类型的所有验证规则

如果有多个重载文件定义了同一个顶级块，那么重载效果是叠加的，后加载的重载块会在先前加载的重载块生效的基础上合并。重载操作首先按照文件名的字典序其次是在重载文件中的位置决定执行顺序。

有一些针对特定顶级块类型的特殊合并行为规则，我们将重载文件中定义的块称为重载块，重载块在普通文件中对应的块称为源块：

1.4.9.1.2.1. 合并 resource 块以及合并 data 块

在 resource 块内，所有 lifecycle 块的内容会按照参数逐条合并。比如说，一个重载块只定义了 create_before_destroy 参数而源块定义了 ignore_changes，那么 create_before_destroy 被合并的同时 igonore_changes 将会被保留。

如果重载的 resource 块包含了一个或多个 provisioner，那么源块内所有的 provisioner 会被忽略。

如果重载的 resource 块内包含了一个 connection 块，那么它将会完全覆盖所有源块内定义的 connection 块

不允许在重载块内定义 depends_on 参数，那将会引发一个错误。

1.4.9.1.2.2. 合并 variable 块

variable 块内参数的合并遵循上述的标准流程，但对于 type 和 default 参数的处理会有一些特殊的考虑。

如果源块定义了 default 值而重载块修改了变量的 type，Terraform 会尝试将 default 值转换成新类型，如果转换失败则会报错。

同样的，如果源块定义了 type 参数而重载块修改了 default 值，那么新的 default 值必须能够被转换成原先的类型。

1.4.9.1.2.3. 合并 output 块

不允许在重载块内定义 depends_on 参数，这会引发一个错误。

1.4.9.1.2.4. 合并 locals 块

所有的 locals 块都定义了一个或多个命名值。针对 locals 的合并会是按照命名值的名字逐条执行的，不论命名值是在哪个 locals 块内被定义的。

1.4.9.1.2.5. 合并 terraform 块

如果重载块定义了 required_providers 参数，那么它的值会被逐条合并，这就允许重载块在不影响其他Provider的情况下调整单个 Provider 的版本约束。

重载块内的 requeired_version 和 required_providers 里的配置完全覆盖源块内的相应配置。如果源块和重载块都定义了 required_version，那么源块的配置会被完全忽略。

1.4.10.1. 代码风格规范

Terraform 推荐以下代码规范：

  • 使用两个空格缩进
  • 同一缩进层级的多个赋值语句以等号对齐：
1
2
ami           = "abc123"
instance_type = "t2.micro"
  • 当块体内同时有参数赋值以及内嵌块时，请先编写参数赋值，然后是内嵌块。参数与内嵌块之间空一行分隔
  • 对于同时包含参数赋值以及元参数赋值的块，请先编写元参数赋值语句，然后是参数赋值语句，之间空一行分隔。元参数块请置于块体的最后，空一行分隔：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
resource "aws_instance" "example" {
  count = 2 # meta-argument first

  ami           = "abc123"
  instance_type = "t2.micro"

  network_interface {
    # ...
  }

  lifecycle { # meta-argument block last
    create_before_destroy = true
  }
}

1.4.11.1. Checks

check 块是 Terraform 1.5 开始引入的新功能。

过去我们可以在 resource 块里的 lifecycle 块中验证基础设施的状态。check 块填补了在 Terraform apply 后验证基础设施状态这一功能中的一块空白。

check 块允许我们定义在每次 plan 以及 apply 操作后执行的自定义的验证。check 块定义的验证逻辑是作为 plan 和 apply 操作的最后一步执行的。

1.4.11.1.1. 语法

你可以定义一个包含本地名称的 check 块，其中可以定义一个 有限作用范围的 data 块，以及至少一个的断言。

下面的例子演示了加载 Terraform 官网并验证 HTTP 返回状态码为 200。

1
2
3
4
5
6
7
8
9
10
check "health_check" {
  data "http" "terraform_io" {
    url = "https://www.terraform.io"
  }

  assert {
    condition = data.http.terraform_io.status_code == 200
    error_message = "${data.http.terraform_io.url} returned an unhealthy status code"
  }
}

1.4.11.1.1.1. 有限作用范围的数据源

我们可以在 check 块使用任意 Provider 提供的任意数据源作为一个有限作用范围的数据源。

一个 check 块可以配一个可选的内嵌（也叫有限作用范围）数据源。该 data 块和普通的 data 块行为类似，但你不能在定义它的 check 块以外引用它。另外，如果一个有限作用范围的数据源运行时触发了任意错误，这些错误将被标记为警告，不会阻止 Terraform 继续执行操作。

你可以使用有限作用范围的数据源在 resource 的 lifecycle 外验证相关基础设施片段的状态。在上面的例子里，如果 terraform_io 数据源在加载时发生错误，那么我们将会收到一个警告而不是中断执行的错误。

元参数

有限作用域的数据源支持 depends_on 和 provider 元参数，但不支持 count 或 for_each 元参数。

depends_on

depends_on 元参数配合有限作用域数据源可以提供非常强大的能力。

假设上述例子中的 Terraform 网站是我们即将用同一目录下的 Terraform 代码部署的，在第一次创建 Plan 时因为网站还没有被创建，所以验证会失败，Terraform 总是会在一开始显示一条让人分心的警告信息。

我们可以给该内嵌数据源添加 depends_on 来确保该数据源依赖于某项组成基础设施的必要资源，例如负载均衡器。这样对该数据源的检查结果将保持 known after apply 直到依赖项创建完成。该策略避免了在配置阶段产生无意义的警告信息，直到在 plan 和 apply 操作的合适阶段执行检查。

该策略的一个问题是如果有限作用域数据源所依赖的资源发生了变化，那么 check 块将返回 known after apply 直到 Terraform 完成了对被依赖资源的更新。在某些情况下，这种行为将会引发一些问题。

我们推荐只有在内嵌数据源依赖于某项资源，但又没有显式的引用其数据时使用 depends_on 元参数。

1.4.11.1.1.2. 断言

我们在 check 块中使用 assert 块定义自定义的断言条件。每个 check 块必须声明至少一个或更多的 assert 块。每个 assert 块都包含了一个 condition 属性与一个 error_message 属性。

与其他自定义检查（variable 中的 validation 以及 lifecycle 中的 precondition 和 postcondition）不同，assert 的断言不会影响 Terraform 执行操作。失败的断言将以警告信息的形式输出而不会中断后续的操作。这与其他诸如 postcondition 这样的自定义检查形成了对比，因为它们的检查失败会立即终止后续的 plan 以及 apply 操作，返回错误信息。

assert 块中的断言条件表达式可以引用同一 check 块里的内嵌数据源数据，以及同一模块中的任意输入参数、资源、数据源、模块的输出值。

1.4.11.1.1.3. check 块的元参数

check 块目前不支持元参数。Terraform 团队目前正在收集有关这一功能的反馈。

1.4.11.1.2. 是使用 check 块还是其他自定义条件检查

check 块提供了 Terraform 中最灵活的验证功能。我们可以在其中引用输出值、输入参数、资源以及数据源的值。我们的确可以使用 check 块取代所有其他的自定义条件检查，但这并不意味着我们应该要这么做。

check 与其他检查最大的区别在于 check 块不会中断 Terraform 的执行。我们需要将这种非阻塞性的行为特点计入考量来决定采取何种检查。

1.4.11.1.2.1. 输出值与输入参数

输出值的 precondition 以及 输入变量的 validation都可以对输入输出值进行断言。

这些检查是用来阻止 Terraform 在数据有问题时继续执行的。

举例来说，如果输入参数的值是无效的那么任由 Terraform 执行整个配置文件并没有什么意义，这种情况下，check 块只会输出有关无效输入参数的警告，不会打断 Terraform 的执行，而 validation 块则会警告输入参数值非法，并终止 Terraform 执行 plan 或 apply 操作。

1.4.11.1.2.2. resource 块的 precondition 与 postcondition

check 块与 precondition 和 postcondition 的区别更加微妙。

precondition 是自定义条件检查中最特殊的，因为它们是在资源的变更被计算或应用之前执行的检查。决定使用 precondition 还是 postcondition 的考量也适用于选择是使用 precondition 还是 check 块。

我们可以在 postcondition 与 check 块之间互换来验证资源和数据源。例如，我们可以把上述例子中的 check 块改写成 postcondition，以下的 postcondition 块将会验证对 Terraform 网站的请求是否返回了状态码 200：

1
2
3
4
5
6
7
8
9
10
data "http" "terraform_io" {
  url = "https://www.terraform.io"

  lifecycle {
    postcondition {
        condition = self.status_code == 200
        error_message = "${self.url} returned an unhealthy status code"
    }
  }
}

check 和 postcondition 块都在 plan 或 apply 操作中验证了 Terraform 网站是否返回 200 状态码，它们的区别是发生错误时的行为。

如果是 postcondition 失败，那么将无法继续执行。Terraform 会阻止任意后续的 plan 或 apply 操作。

我们推荐使用 check 块来验证基础设施的整体状态，仅在希望确保单一资源状态符合预期时使用 postcondition。

1.4.12.1. Ephemeral 资源

临时（Ephemeral）资源是本质上是临时的（Temporary） Terraform 资源。临时资源具有独特的生命周期，Terraform 不会将它们存储在其状态文件中。每个 ephemeral 块描述一个或多个临时资源，例如临时密码或与另一个系统的连接。

ephemeral 块的声明包含了临时资源的类型以及本地名，就像 resource 块那样。 Terraform 使用临时资源的名称来引用同一模块中的该资源，但临时资源的名称在该模块的范围之外没有任何意义。

1.4.12.1.1. 生命周期

ephemeral 的生命周期与 resource 和 data 不同。当 Terraform 创建临时资源时，它会执行以下步骤：

  1. 如果 Terraform 需要访问临时资源的结果，它将“打开”该临时资源。例如，如果 Terraform “打开”一个包含了 Vault 机密的临时资源，则 Vault 的 Provider 将获取租约并返回一个机密。
  2. 如果 Terraform 需要访问临时资源的时间比远程系统为机密设置的过期时间还长，Terraform 会要求 Provider 定期续约。例如，如果 Terraform 对包含了 Vault 机密的临时资源续约，则 Vault Provider 程序将调用 Vault 的租约续约 API 来延长到期时间。
  3. 一旦 Terraform 不再需要临时资源，Terraform 就会将其关闭。这种情况发生在依赖于某个临时资源的 Provider 完成当前 Terraform 运行阶段的所有工作之后。例如，关闭 Vault 机密临时资源意味着 Vault Provider 明确吊销租约，从而使得 Vault 立即撤销相关凭证。

Terraform 对于给定配置中的每个临时资源实例都遵循这些生命周期步骤。

1.4.12.1.2. 依赖图

临时资源对应了 Terraform 依赖关系图中的节点，其交互方式与 resource 和 data 类似。例如，当 resource 或 data 依赖于临时资源的属性时，Terraform 首先自动配置临时资源。

1.4.12.1.3. 临时资源的声明

ephemeral 块中的绝大多数参数是由您正在定义的临时资源类型所决定的。与 resource 和 data 一样，Terraform 注册表中的每个 Provider 程序都包含其支持的临时资源（如果有）的文档。临时资源类型的文档列出了可用的参数以及应如何配置的格式。

临时资源由两部分组成：

  • 属性
  • 元参数

ephemeral 块的结构如下：

1
2
3
4
ephemeral "<resource_type>" "<resource_name>" {
  <attributes>
  <meta-arguments>
}

1.4.12.1.4. 引用临时资源

只允许在特定的临时上下文中引用临时资源，否则 Terraform 会返回错误。以下是可以引用临时资源的上下文：

1.4.12.1.5. 元参数

我们可以将在临时资源块内声明以下元参数，来更改这些资源的行为。以下元参数对于资源、数据源和临时资源的工作方式相同：

临时资源不支持 provisioner 元参数。

1.4.12.1.6. 示例

以下示例使用临时资源的凭据配置 postgresql Provider 程序。由于这些凭据由临时资源管理，因此 Terraform 不会将它们存储在状态或计划文件中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
ephemeral "aws_secretsmanager_secret_version" "db_master" {
  secret_id = data.aws_db_instance.example.master_user_secret[0].secret_arn
}

locals {
  credentials = jsondecode(ephemeral.aws_secretsmanager_secret_version.db_master.secret_string)
}

provider "postgresql" {
  host     = data.aws_db_instance.example.address
  port     = data.aws_db_instance.example.port
  username = local.credentials["username"]
  password = local.credentials["password"]
}