Terraform快速参考

Terraform用于实现基础设施即代码（infrastructure as code）—— 通过代码（配置文件）来描述基础设施的拓扑结构，并确保云上资源和此结构完全对应。Terraform有三个版本，我们主要关注Terraform CLI。

Terraform CLI主要包含以下组件：

1. 命令行前端
2. Terraform Language（以下简称TL，衍生自HashiCorp配置语言HCL）编写的、描述基础设施拓扑结构的配置文件。配置文件的组织方式是模块。本文使用术语“配置”（Configuration）来表示一整套描述基础设施的Terraform配置文件
3. 针对各种云服务商的驱动（Provider），实现云资源的创建、更新和删除

云上资源不单单包括基础的IaaS资源，还可以是DNS条目、SaaS资源。事实上，通过开发Provider，你可以用Terraform管理任何资源。

Terraform会检查配置文件，并生成执行计划。计划描述了那些资源需要被创建、修改或删除，以及这些资源之间的依赖关系。Terraform会尽可能并行的对资源进行变更。当你更新了配置文件后，Terraform会生成增量的执行计划。

直接到https://www.terraform.io/downloads.html下载，存放到$PATH下即可。

使用选项  -chdir=DIR

使用 terraform -install-autocomplete安装自动完成脚本，使用 terraform -uninstall-autocomplete删除自动完成脚本。

很多子命令接受资源地址参数，下面是一些例子：

配置文件的路径可以通过环境变量 TF_CLI_CONFIG_FILE设置。非Windows系统中， $HOME/.terraformrc为默认配置文件路径。配置文件语法类似于TF文件：

配置工作目录，为使用其它命令做好准备。

Terraform命令需要在一个编写了Terraform配置文件的目录（配置根目录）下执行，它会在此目录下存储设置、缓存插件/模块，以及（默认使用Local后端时）存储状态数据。此目录必须进行初始化。

初始化后，会生成以下额外目录/文件：

.terraform目录，用于缓存provider和模块
如果使用Local后端，保存状态的terraform.tfstate文件。如果使用多工作区，则是terraform.tfstate.d目录。

对配置的某些变更，需要重新运行初始化，包括provider需求的变更、模块源/版本约束的变更、后端配置的变更。需要重新初始化时，其它命令可能会无法执行并提示你进行初始化。

命令 terraform get可以仅仅下载依赖的模块，而不执行其它init子任务。

运行 terraform init -upgrade会强制拉取最新的、匹配约束的版本并更新依赖锁文件。

校验配置是否合法。

显示执行计划，即当前配置将请求（结合state）哪些变更。Terraform的核心功能时创建、修改、删除基础设施对象，使基础设施的状态和当前配置匹配。当我们说运行Terraform时，主要是指plan/apply/destroy这几个命令。

terraform plan命令评估当前配置，确定其声明的所有资源的期望状态。然后比较此期望状态和真实基础设施的当前状态。它使用state来确定哪些真实基础设施对象和声明资源的对应关系，并且使用provider的API查询每个资源的当前状态。当确定到达期望状态需要执行哪些变更后，Terraform将其打印到控制台，它并不会执行任何实际的变更操作。

terraform plan命令得到的计划可以保存起来，并被后续的terraform apply使用：

plan命令支持两种备选的工作模式：

1. 销毁模式：创建一个计划，其目标是销毁所有当前存在于配置中的远程对象，留下一个空白的state。对应选项 -destroy
2. 仅刷新模式：创建一个计划，其目标仅仅是更新state和根模块的输出值，以便和从Terraform之外对基础设施对象的变更匹配。对应选项 -refresh-only

使用选项 -var 'NAME=VALUE'可以指定输入变量，该选项可以使用多次。

使用选项 -var-file=FILENAME可以从文件读取输入变量，某些文件会自动读取，参考输入变量一节。

选项 -parallelism=n限制操作最大并行度，默认10。

选项	说明
-refresh=false	默认情况下，Terraform在检查配置变更之前，会将state和远程基础设施进行同步。此选项禁用此行为 该选项可能会提升性能，因为减少了远程API请求数量。但是可能会无法识别某些Terraform外部对基础设施资源的变更
-replace=ADDRESS	提示Terraform去计划替换掉具有指定ADDRESS的单个资源。对于0.15.2+可用，老版本可以使用terraform taint命令代替 ADDRESS就是针对某个资源实例的引用表达式，例如 aws_instance.example[0]
-target=ADDRESS	提示Terraform仅仅针对指定ADDRESS的资源（以及它依赖的资源）指定执行计划
-input=false	禁止Terraform交互式的提示用户提供根模块的输入变量，对于批处理方式运行Terraform很重要

应用执行计划，创建、更新设施对象。

apply会做plan的任何事情，并在其基础上，直接执行变更操作。默认情况下，apply即席的执行一次plan，你也可以直接使用已保存的plan

命令格式： terraform apply [options] [plan file]

选项 -auto-approve可以自动确认并执行所需操作，不需要人工确认。

如果指定plan file参数，则读取先前保存的计划并执行。

支持plan命令中关于计划模式的选项。

-input=false、-parallelism=n等选项含义和plan命令相同。特有选项：

选项	说明
-lock-timeout=DURATION	对状态加锁的最大时间

删除先前创建的基础设施对象。

当前配置（+工作区）管理的所有资源都会被删除，destroy会使用状态数据确定哪些资源需要删除。

在交互式命令中估算Terraform表达式。

格式化配置文件

强制解除当前工作区的状态锁。当其它terraform进程锁定状态后，没有正常解锁时使用。如果其它进程仍然在运作，可能导致状态不一致。

安装或升级远程Terraform模块。格式： terraform get [options] PATH。

选项：

-update 检查已经下载的模块的新版本，如果存在匹配约束的新版本则更新
-no-color 禁用彩色输出

生成操作中包含步骤的图形化表示。

导入现有的基础设施对象，让其关联到配置中的资源定义。

获取并保存远程服务（例如模块私服）的登录凭证。

删除远程服务（例如模块私服）的登录凭证。

显示根模块的输出值。格式： terraform output [options] [NAME]

显示此模块依赖的providers

更新状态，使其和远程基础设施匹配。

显示当前状态或保存的执行计划。

将资源实例标记为“非功能完备（fully functional）”的。

所谓非功能完备，通常意味着资源创建过程出现问题，存在部分失败。此外taint子命令也可以强制将资源标记为非功能完备。

因为上述两种途径，进入tainted状态的资源，不会立即影响基础设施对象。但是在下一次的plan中，会销毁并重新创建对应基础设施对象。

命令格式： terraform [global options] taint [options] <address>

解除资源的tainted状态。

管理和切换工作区。

配置文件由若干块（Block）组成，块的语法如下：

块是一个容器，它的作用取决于块的类型。块常常用来描述某个资源的配置。

取决于块的类型，标签的数量可以是0-N个。对于resource块，标签数量为两个。某些特殊的块，可能支持任意数量的标签。某些内嵌的块，例如network_interface，则不支持标签。

块体中可以包含若干参数（Argument），或者其它内嵌的块。参数用于将一个表达式分配到一个标识符，常常对应某个资源的一条属性。表达式可以是字面值，或者引用其它的值，正是这种引用让Terraform能够识别资源依赖关系。

直接位于配置文件最外层的块，叫做顶级块（Top-level Block），Terraform支持有限种类的顶级块。大部分Terraform特性，例如resource，基于顶级块实现。

下面是一个例子：

在HCL语言中，Argument被称作Attribute。但是在TL中，Attribute术语另有它用。例如各种resource都具有一个名为id的属性，它可以被参数表达式饮用，但是不能被赋值（因而不是参数）。

参数其实一个赋值表达式，它将一个值分配给一个名称。

上下文决定了哪些参数可用，其类型是什么。不同的资源（由resource标签识别）支持不同的参数集。

参数名、块类型名、大部分Terraform特有结构的名字（例如resource名，即其第二标签），都是标识符。

标识符由字母、数字、-、_组成，第一个字符不能是数字。

#或者 //开头的是单行注释。 /**/作为多行注释的边界。 

类型	说明
string	Unicode字符序列，基本形式  "hello"
number	数字，形式 6.02
bool	true或 false
list/tuple	一系列的值，形式 ["us-west-1a", "us-west-1c"]
map/object	键值对，形式 {name = "Mabel", age = 52}

空值使用 null表示。

转义字符：

\n 换行
\r 回车
\t 制表
\" 引号
\\ 反斜杠
\uNNNN Unicode字符
\UNNNNNNNN Unicode字符

注意，在Heredoc中反斜杠不用于转义，可以使用：

$${ 字符串插值标记${
%%{ 模板指令标记%{

支持Unix的Heredoc风格的字符串：

Heredoc还支持缩进编写：

要将对象转换为JSON或YAML，可以调用函数：

不管在普通字符串格式，还是Heredoc中，都可以使用字符串模板。模板需要包围在 ${ 或 %{}中：

可以在模板指令开始或结尾添加 ~，用于去除前导或后缀的空白符：

<RESOURCE TYPE>.<NAME>引用指定类型、名称的资源。 其值可能是：

1. 如果资源没有count/for_each参数，那么值是一个object，可以访问资源的属性
2. 如果资源使用count参数，那么值是list
3. 如果资源使用for_each参数，那么值是map

var.<NAME>引用指定名称的输入变量。如果变量使用type参数限定其类型，对此引用进行赋值时，Terraform会自动进行必要的类型转换。

local.<NAME>引用指定名称的本地值。本地值可以引用其它本地值，甚至是在同一个local块中，唯一的限制就是不得出现循环依赖。

module.<MODULE NAME>引用指定子模块声明的结果输出。如果module块（表示对目标模块的调用）没有count/for_each参数，则其值是一个object，可以直接访问某个输出值： module.<MODULE NAME>.<OUTPUT NAME>

如果module块使用了for_each，则引用的值是一个map，其key是for_each中的每个key，其值是子模块输出。

如果module块使用了count，则引用的值是一个list，其元素是子模块输出。

data.<DATA TYPE>.<NAME>引用指定类型的数据资源，取决于数据资源是否使用count/foreach，其值可能是object/list/map。

path.module 表达式所在模块的路径。

path.root表示当前配置根模块的路径。

path.cwd 表示当前工作模块的路径，默认情况下和path.root一样。但是Terraform CLI可以指定不同的工作目录。

terraform.workspace是当前选择的工作区的名称。

在特定的块内部，在特定的上下文下（例如使用count/for_each的情况下），可以引用一些特殊值：

count.index 使用count原参数时，表示当前索引
each.key / each.value 使用for_each原参数时，表示当前迭代的键值
self可以在provisioner和connection块中使用，表示当前上下文资源

逻辑操作符： !  &&  ||
算数操作符： *  /  % +  -
比较操作符： >, >=, <, <= ==, !=

函数调用：

使用for表达式可以通过转换一种复杂类型输出，生成另一个复杂类型结果。输入中的每个元素，可以对应结果的0-1个元素。任何表达式可以用于转换，下面是使用upper函数将列表转换为大写：

作为for表达式的输入的类型可以是list / set / tuple / map / object。可以为for声明两个临时符号，前一个表示index或key：

结果的类型取决于包围for表达式的定界符：

[] 表示生成的结果是元组
{} 表示生成的结果是object，你必须使用 =>符号： {for s in var.list : s => upper(s)}

包含一个可选的if子句可以对输入元素进行过滤： [for s in var.list : upper(s) if s != ""]

示例：

for表达式可能将无序类型（map/object/set）转换为有序类型（list/tuple）：

对于map/object，键/属性名的字典序，决定结果的顺序
对于set，如果值是字符串，则使用其字典序。如果值是其它类型，则结果的顺序可能随着Terraform的版本改变

如果输出是对象，通常要求键的唯一性。Terraform支持分组模式，允许键重复。要激活此模式，在表达式结尾添加 ...： 

对于顶级块，表达式仅能在给参数赋值的时候，用在右侧。某些情况下，我们需要在特定条件下，重复、启用/禁用某个子块，表达式就没法实现了，此时可以利用dynamic块。

dynamic块可以遍历一个列表，为每个元素生成一个块：

注意dynamic块仅可能为resource、data、provider、provisioner块生成参数（子块），不能用于生成源参数块，例如lifecycle。

允许dynamic块的多级嵌套。

splat表达式提供了更简单语法，在某些情况下代替for表达式：

注意splat表达式仅仅用于列表，不能用于map/object

splat表达式还有个特殊用途，将单值转换为列表：

module/provider的作者可以利用类型约束来校验用户输入。Terraform的类型系统比较强大，比如他不但可以限制类型为map，还可以规定其中有哪些键，每个键的值是什么类型。

复杂类型可以将多个值组合为单个值，复杂类型由类型构造器（type constructor）定义，复杂类型分为两类：

1. 集合类型：组合相似（类型）的值
2. 结构类型：组合可能不同的值

集合类型包括map/list/set等，我们可以限制集合的成员类型：

结构类型包括object和tuple。

object定义了多个命名的属性，以及属性的类型：

元组则是定义了限定元素个数、每个元素类型的列表： 

大部分情况下，相似的集合类型和结构类型的行为类似。Terraform文档某些时候也不去区分，这是由于以下类型转换行为：

1. 可能的情况下，Terraform会自动在相似复杂类型之间进行转换：
   1. object和map是相似的，只要map包含object的schema所要求的键集合，即可自动转换。多余的键在转换过程中被丢弃，这意味着map - object - mapl两重转换可能丢失信息
   2. tuple和list是相似的，但是转换仅仅在list元素数量恰好满足tuple的schema时发生
   3. set和tuple/list是相似的：
      1. 当list/tuple转换为set，重复的值会被丢弃，元素顺序消失
      2. 当set转换为list/tuple，元素的顺序是任意的，一个例外是set(string)，将会按照元素字典序生成list/tuple
2. 可能的情况下，Terraform会自动转换复杂类型的元素的类型，如果元素是复杂类型，则递归的处理

每当提供的值，和要求的值类型不一致时，自动转换都会发生。

module/provider的作者应该注意不同类型的差别，特别是在限制输入方面能力的不同。

特殊关键字any用做尚未决定的类型的占位符，其本身并非一个类型。当解释类型约束的时候，Terraform会尝试寻找单个的实际类型，替换any关键字，并满足约束。

例如，对于list(any)这一类型约束，对于给定的值["a", "b", "c"]其实际类型是tuple([string, string, string])，当将该值赋值给list(any)变量时，Terraform分析过程如下：

1. tuple和list是相似类型，因此应用上问的tuple-list转换规则
2. tuple的元素类型是string，满足any约束，因此将其替换，结果类型是list(string)

从0.14开始，支持这一实验特性。可以在object类型约束中，标注某个属性为可选的： 

默认情况下，对于必须属性来说，如果类型转换时的源（例如map）不具备对应的键，会导致报错。

版本约束是一个特殊的字符串值，在引用module、使用provider时，或者通过terraform块的required_version时，需要用到版本约束：

所有可用函数：https://www.terraform.io/docs/language/functions/index.html

资源是TL语言中最重要的元素，由resource块定义。正如其名字所示，资源声明了某种云上基础设施的规格，这些基础设施可以是虚拟机、虚拟网络、DNS记录，等等。

数据源是一种特殊的资源，由data块定义。

当你第一次为某个资源编写配置时，它值存在于配置文件中，尚未代表云上的某个真实基础设施对象。通过应用Terraform配置，触发创建/更新/销毁等操作，实现云上环境和配置文件的匹配。

当一个新的资源被创建后，对应真实基础设施对象的标识符被保存到Terraform的State中。这个标识符作为后续更新/删除的依据。对于State中已经存在关联的标识符的那些Resource块，Terraform会比较真实基础设施对象和Resource参数的区别，并在必要的时候更新对象。

概括起来说，当Terraform配置被应用时：

1. 创建存在于配置文件中，但是在State中没有关联真实基础设施对象的资源
2. 销毁存在于State中，但是不存在于配置文件的资源
3. 更新参数发生变化的资源
4. 删除、重新创建参数发生变化，但是不能原地（in-palce）更新的资源。不能更新通常是因为云API的限制，例如腾讯云VPC的CIDR不支持修改

以上4点，适用于所有资源类型。但是需要注意，底层发生的事情，取决于Provider，Terraform只是去调用Provider的相应接口。

在相同模块中，你可以在表达式中访问某个资源的属性，语法 <RESOURCE TYPE>.<NAME>.<ATTRIBUTE>

除了配置文件中列出的资源参数之外，资源还提供一些只读的属性。属性表示了一些提供云API拉取到的信息。这些信息通畅需要在资源创建后才可获知，例如随机生成的资源ID vpc-d8o3c8vq

很多Provider还提供特殊的数据源（data）资源，这种特殊的资源仅仅用来查询信息。

某些资源必须在另外一些资源之后创建，例如CVM必须在其所属Subnet创建后才能创建，这意味着某些资源存在依赖关系。

Terraform能够自动分析资源依赖关系，其分析依据就是资源的参数的值表达式。如果表达式中引用了另一个资源，则当前资源依赖于该资源。

对于无法通过配置文件分析的隐含依赖，需要你手工配置 depends_on元参数。

Terraform会自动并行处理没有依赖关系的资源。

这类特殊的资源不会对应某个云上基础设施对象，而是仅仅存在于Terraform本地State中。Local-Only资源用于一些中间计算过程，包括生成随机ID、创建私钥等。

Local-Only资源的行为和普通资源一致，只是其结果数据仅仅存在于State中，删除时也仅仅是从State中移除对应数据。

两个标签分别代表资源的类型和本地名称。

资源类型提示正在描述的是那种云上基础设施，资源类型决定可用的参数集。本地名称用于在模块的其它地方饮用该资源，此外没有意义。资源类型+本地名称是资源的唯一标识，必须在模块范围内唯一。

每一种资源都由一个Provider来实现。Provider是Terraform的插件，它提供若干资源类型。通常一个云服务商提供提供一个Provider。初始化工作目录时Terraform能够自动从Terraform仓库下载大部分所需的Provider。

模块需要知道，利用哪些Provider才能管理所有的资源。此外Provider还需要经过配置才能工作，例如设置访问云API的凭证。这些配置由根模块负责。

元参数可以用于任何资源类型。

该元参数用于处理隐含的资源/模块依赖，这些依赖无法通过分析Terraform配置文件得到。从0.13版本开始，该元参数可用于模块。之前的版本仅仅用于资源。

depends_on的值是一个列表，其元素具必须是其它资源的引用，不支持任意表达式。

depends_on应当仅仅用作最后手段，避免滥用。

示例：

默认情况下，一个resource块代表单个云上基础设施对象。如果你想用一个resource块生成多个类似的资源，可以用count或for_each参数。

设置了此元参数的上下文中，可以访问名为 count的变量，它具有属性 index，为从0开始计数的资源实例索引。 示例：

在当前模块的其它地方，可以用这样的语法访问如上资源实例：

如果资源的规格几乎完全一致，可以用count，否则，需要使用更加灵活的for_each元参数。

for_each的值必须是一个映射或set(string)，你可以在上下文中访问 each对象， 它具有 key和 value两个属性，如果for_each的值是集合，则key和value相等。示例：

调用子模块时使用for_each的示例：

关于for_each的值的元素，有如下限制：

1. 键必须是确定的值，如果应用配置前值无法确定会报错。例如，你不能引用CVM的ID，因为这个ID必须在配置应用之后才可知
2. 如果键是函数调用，则此函数不能是impure的（非幂等），impure函数包括uuid/bcrypt/timestamp等
3. 敏感（Sensitive）值不能用做键值。需要注意，大部分函数，在接受敏感值参数后，返回值仍然是敏感的

当使用集合的时候，你必须明确的将值转换为集合。例如通过 toset函数将列表、元组转换为集合。使用 flatten函数可以将多层次的嵌套结构转换为列表。

for_each所在块定义的资源A，可以赋值给另一个资源B的for_each参数。这时，B那个for_each的键值对，值是资源的完整（创建或更新过的）实例。这种用法叫chaining：

引用for_each创建的资源的实例时，使用如下语法： 

这个参数用于指定使用的provider配置。可以覆盖Terraform的默认行为：将资源类型名的第一段（下划线分隔）作为provider的本地名称。同时使用provider的默认配置。例如资源类型google_compute_instance默认识别为google这个provider。

每个provider可以提供多个配置，配置常常用于管理多区域服务中的某个特定Region。每个provider可以有一个默认配置。

该参数的值必须是不被引号包围的 <PROVIDER>.<ALIAS>。使用该参数你可以显式的指定provider及其配置：

注意：资源总是隐含对它的provider的依赖，这确保创建资源前provider被配置好。 

该参数可以对资源的生命周期进行控制。示例：

lifecycle作为一个块，只能出现在resources块内。可用参数包括：

参数	说明
create_before_destroy	默认情况下， 当Terraform无法进行in-place更新时，会删除并重新创建资源 该参数可以修改此行为：先创建新资源，然后删除旧资源
prevent_destroy	如果设置为true，并且配置会导致基础设施中某个对象被删除，则报错
ignore_changes	默认情况下，Terraform会对比真实基础设施中对象和当前配置文件中的所有字段，任何字段的不一致都会引发更新操作 该参数指定，在Terraform评估是否需要更新时，资源的哪些字段被忽略 如果设置为特殊值 all，则Terraform不会进行任何更新操作

某些资源类型提供了特殊的 timeouts内嵌块，用于指定多长时间后认定操作失败：

资源的绝大部分参数由资源类型决定。需要翻阅Provider的文档了解哪些参数可用。

对于大部分公共的、托管在Terraform仓库的Provider来说，其文档可以直接在仓库网站上获得。

对于一些无法使用Terraform声明式模型来表达的某些行为，可以使用Provisioner作为最后（总是不推荐的）手段。

使用Provisioner会引入复杂性和不确定性：

1. Terraform无法将Provisioner执行的动作，作为计划的一部分。因为Provisioner理论上可以做任何事情
2. Provisioner通常需要使用更多细节信息，例如直接访问服务器的网络、使用Terraform的登录凭证

Provisioner块不能用名字访问其所在的上下文资源，你必须使用 self对象。这个对象就指代对应的资源，你可以访问它的参数和属性。

该参数指定何时（create/update/destroy）运行Provisioner，下面是一个仅仅在删除资源时才执行的Provisioner：

默认情况下，Provisioner在资源创建的时候调用，在更新/删除时不会调用。最常见的用法是使用Provisioner来初始化系统。如果Provisioner失败，则资源被标记为tainted，并且会在下一次 terraform apply时删除、重新创建。

定制Provisioner失败时的行为：

1. continue 忽略错误
2. fail 默认行为，导致配置应用立即失败，如果正在创建资源，则taint该资源

大部分Provisioner要求通过SSH或WinRM来访问远程资源。你可以在 connection块中声明如何连接。connection块可以内嵌在以下位置：

1. resource，对资源的所有Provisioner生效
2. provisioner，仅仅对当前Provisioner生效

在connection块中，你也可以使用 self来访问包含它的resource，这一点类似于provisioner

示例：

关于如何通过证书进行身份验证，如何通过堡垒机连接，参考官方文档。 

如果你希望运行一个Provisioner，但是不想在任何真实的资源的上下文下运行，可以使用这种特殊的资源。

Provisioner	说明
file	从运行Terraform的机器，复制文件或目录到新创建的资源（通常是虚拟机）。示例： 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 resource "aws_instance" "web" {   # ...     # 文件到文件   provisioner "file" {     source      = "conf/myapp.conf"     destination = "/etc/myapp.conf"   }     # 字符串到文件   provisioner "file" {     content     = "ami used: ${self.ami}"     destination = "/tmp/file.log"   }     # 目录到目录，拷贝后生成/etc/configs.d目录   provisioner "file" {     source      = "conf/configs.d"     destination = "/etc"   }     # Windows下的路径语法   provisioner "file" {     # apps/app1/下的所有文件拷贝到D:/IIS/webapp1下     source      = "apps/app1/"     destination = "D:/IIS/webapp1"   } } 关于整个目录的拷贝，需要注意： 如果连接type是ssh，则目标目录必须已经存在。你可能需要使用remote-exec预先创建好目录 原路径以/结尾，则拷贝目录下的所有文件，而非目录本身
local-exec	在资源创建之后，调用一个本地（运行Terraform的机器）可执行程序 注意：即使是在资源创建之后，但是不保证sshd这样的服务已经可用了。因此不要尝试在local-exec中调用ssh命令登录到资源 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 resource "aws_instance" "web" {   # ...     provisioner "local-exec" {     command = "echo ${self.private_ip} >> private_ips.txt"     # 可选的工作目录     working_dir = "/root"     # 可选的解释器     interpreter = [ "/bin/bash", "-c" ]     # 可选的环境变量     environment = {       FOO = "bar"     }   } }
remote-exec	在资源创建之后，登录到新创建的资源，执行命令 1 2 3 4 5 6 7 8 9 10 11 12 13 resource "aws_instance" "web" {   provisioner "remote-exec" {     # 命令列表，逐个执行     inline = [       "puppet apply",       "consul join ${aws_instance.web.private_ip}",     ]     # 单个脚本路径     script = ""     # 多个脚本路径     scripts = []   } }

数据资源，由data块来描述，让Terraform从数据源读取信息。Data是一种特殊的Resource，也是由Provider来提供。Data只支持读取操作，相对的，普通的Resource支持增删改查操作，普通资源也叫受管（Manged）资源，一般简称Resource。

数据资源要求Terraform去特定数据源（第1标签）读取数据，并将结果导出为本地名称（第2标签）：

两个标签组合起来是data在模块中的唯一标识。

如果数据资源的查询约束（参数）都是常量值，或者是已知的变量值，那么数据资源的状态会在Terraform的Refresh阶段更新，这个阶段在创建执行计划之前。

查询约束可能引用了某些值，这些值在应用配置文件之前无法获知（例如资源ID）。这种情况下，读取数据源的操作将推迟到Apply之后。在Data读取完成之前，所有对它结果（导出名称）的引用都是不可用的。

大部分数据源都对应了某种云上基础设施，需要通过云API远程的读取。

某些特殊数据源仅仅供Terraform自己使用，例如Hashicorp的Provider template，它提供的template_file数据源，用于在本地渲染模板文件。这类数据源叫Local-Only数据源，其行为和一般数据源没有区别。

数据资源的依赖解析行为，和受管资源一致。

数据资源支持的元参数，和受管资源一致。

和传统编程语言对比，模块类似于函数，输入变量类似于函数参数，输出值类似于返回值，本地值则类似于函数内的局部变量。

输入变量作为Terraform模块的参数，从而实现模块的参数化、可跨多个配置复用。

对于定义在根模块中的变量，其值可以从Terraform CLI选项传入。对于子模块中定义的变量，则必须通过module块传入其值。

支持的简单类型： string、 number、 bool

支持的容器类型：

1. 列表： list(<TYPE>)
2. 集合： set(<TYPE>)
3. 映射： map(<TYPE>)
4. 对象： object({<ATTR NAME> = <TYPE>, ... })
5. 元组： tuple([<TYPE>, ...])

关键字 any表示，任何类型都允许。

如果同时指定了类型和默认值，则提供的默认值必须可以转换为类型。

validation是一个块，其中condition是一个bool表达式：

在声明输入变量的模块中，可以使用 var.<NAME>引用输入变量的值：

要给根模块中定义的变量赋值，有以下几种方式：

1. 使用 -var命令行选项，可以多次使用，每次赋值一个变量，示例：
   
   Shell

   1 2 3

   terraform apply -var="image_id=ami-abc123" terraform apply -var='image_id_list=["ami-abc123","ami-def456"]' -var="instance_type=t2.micro" terraform apply -var='image_id_map={"us-east-1":"ami-abc123","us-east-2":"ami-def456"}'

2. 作为环境变量传入，示例：
   
   1 2	# 环境变量需要TF_VAR_前缀 export TF_VAR_image_id=ami-abc123

3. 使用 .tfvars文件，此文件可以自动载入或者通过命令行选项显式载入，示例：
   
   testing.tfvars

   1 2 3 4 5

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

   
   
   Shell

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

   注意以下文件可以自动识别并载入：

   1. 名为 terraform.tfvars或 terraform.tfvars.json的文件
   2. 以 .auto.tfvars或 .auto.tfvars.json结尾的文件

如果通过多种方式给变量赋值，则优先级高的生效。优先级顺序从低到高：

1. 环境变量文件
2. terraform.tfvars
3. terraform.tfvars.json
4. *.auto.tfvars和*.auto.tfvars.json文件，多个文件，按字典序，后面的优先级高
5. -var或-var-file命令行选项，多个选项，后面的优先级高

输出值是模块的“返回值”，具有以下用途：

1. 子模块使用输出值将它创建的资源的属性的子集暴露给父模块
2. 根模块可以利用输出值，将一些信息在terraform apply之后打印到控制台上
3. 当使用远程状态（remote state）时，根模块的输出可以被其它配置通过 terraform_remote_state 数据源捕获到

子模块的输出值，通过这样的表达式访问：

使用depends_on参数可以明确指定输出值依赖什么：

在一个模块内部，将表达式分配给一个名称。你可以同时声明多个本地值：

引用本地值时，使用表达式：  local.<NAME>

一套完整的配置文件（Configuration，简称配置），由1个根目录和若干文件/子目录组成。配置文件的扩展名为 .tf，此外HCL语言还提供了基于JSON的变体，这种配置文件的扩展名为 .tf.json。配置文件的编码方式为UTF-8，使用Unix风格的换行符。

所谓模块（Module）是存放在一个目录中的配置文件的集合。子目录中的文件不属于模块，不会自动包含到配置中。

将块存放在不同配置文件中仅仅是方便人类的阅读，和Terraform的行为无关。Terraform总是会评估模块中的所有文件，并将它们合并为单一的文档来看待。

Terraform命令总是在单个根模块的上下文中运行，根模块的目录通常作为命令的工作目录。此根模块会调用其它模块，这种调用关系会递归的发生，从而形成一个子模块树结构。

一个模块（通常是根模块）可以调用其它模块，从而将这些模块中定义的资源包含到配置中。当一个模块被其它模块调用时，它的角色是子模块。

子模块可以被同一个配置调用多次，不同模块也可以同时调用一个子模块。

引用子模块时，除了可以从本地文件系统获取，还可以从公共/私有仓库下载。

Terraform Registry托管了大量公共模块，用于管理各种各样的基础设施，这些模块可以被免费使用。Terraform能够自动下载这些模块的正确版本。Terraform Cloud / Enterprise版本都包含一个私服模块可以托管组织私有的模块。

使用名为 override.tf或 override.tf.json，或者后缀为 _override.tf或 _override.tf.json的文件，可以覆盖既有配置的某一部分。这些文件叫做覆盖文件。

加载配置时，Terraform最初会跳过覆盖文件。加载完成功文件后，会按照字典序处理覆盖文件。对于覆盖文件中的每个顶级块，Terraform会尝试寻找已经存在的，定义在常规文件中的对应块，并将块的内容进行合并。内容合并规则如下：

1. 覆盖文件中的顶级块、普通配置文件中的顶级块，对应关系通过块头（块类型+标签）识别，相同块头的块被合并
2. 顶级块中的参数被替换
3. 顶级块中的内嵌块被替换，不会递归的进行合并
4. 多个覆盖文件覆盖了同一个块的定义时，按覆盖文件名的字典序依次合并

此外，对于resource / data块，有如下特殊规则：

1. 内嵌的lifecycle块不是简单的直接替换。假设覆盖文件仅仅设置了lifecycle的create_before_destroy属性，原始配置中任何ignore_changes参数保持原样
2. 对于内嵌的provisioner块，原始配置中的（不管有几个）provisioner块直接被忽略
3. 原始配置中的内嵌connection块被完全覆盖
4. 元参数（meta-argument）depends_on不能出现在覆盖文件中

对于variable（变量）块，有如下特殊规则：

1. 如果原始块定义了default参数（默认值）并且覆盖块修改了变量的type，则Terraform尝试将default转换为新的type，如果转换无法自动完成则报错
2. 如果覆盖块修改了default，那么其值必须匹配原始块中的type

不建议过多的使用覆盖文件，这会降低配置的可读性。

对于output块，有如下特殊规则：

1. 元参数depends_on不能出现在覆盖文件中

对于local块，有如下特殊规则：

1. 每个local块定义（或修改）了若干具有名字的值，覆盖时使用value-by-value的方式，至于值在何处定义不影响

对于terraform块，有如下特殊规则：

1. required_providers的值，按element-by-element的方式进行覆盖。这样，覆盖块可以仅仅调整单个provider的配置，而不影响其他providers
2. 覆盖required_version、required_providers时，被覆盖的元素被整个替换

下面是原始文件+覆盖文件的示例：

所谓调用，就是将特定的值传递给子模块作为输入变量，从而将子模块中的配置包含进来。

元参数	说明
count	用于创建多个模块实例，参考资源(resources)的元参数
for_each	用于创建多个模块实例，参考资源(resources)的元参数
providers	将Provider配置传递给子模块： 1 2 3 4 5 6 7 8 9 10 11 12 13 14 provider "aws" {   alias  = "usw2"   region = "us-west-2" }   module "example" {   source    = "./example"   providers = {     # 配置名称由provider块的第1标签（+可选的alias参数）构成     # 键是子模块中的Provider配置名称     # 值是父模块中的Provider配置名称     aws = aws.usw2   } } 如果子模块没有定义任何Provider alias，则该元参数是可选的。不指定该元参数时，子模块会从父模块继承所有默认Provider配置，所谓默认配置就是没有alias的provider块所定义的配置
depends_on	显式指定整个模块对特定目标的依赖，参考资源(resources)的元参数

module块的source参数指定了从何处下载子模块的代码。

terraform init中有一个步骤，专门负责模块的安装。它支持从本地路径、Terraform Registry、GitHub、一般性Git仓库、HTTP URL、S3桶等多种来源下载模块。

对于紧密相关的模块，例如为了减少代码重复，从单一模块拆分得到的，建议使用本地路径方式存储。

本地路径的源具有一个特殊的地方，它没有“安装”这个步骤。

对于希望公开分享的模块，可以存放在这个Terraform仓库中。这种仓库的源地址格式为 <HOSTNAME>/<NAMESPACE>/<NAME>/<PROVIDER>。示例： 

为了访问私有仓库，你可能需要在CLI配置中添加访问令牌。

如果source以github.com开头，则Terraform会尝试到GitHub拉取模块源码：

如果source以 git::开头，则Terraform认为模块托管在一般性的Git服务器中：

Terraform使用git clone命令下载模块，因此本地机器的任何Git配置都可用，包括凭证信息。

默认情况下，使用Git仓库的HEAD，要选择其它修订版，使用ref参数：

任何可以作为git checkout参数的值，都可以作为ref参数。

如果source指定为一个普通的URL，那么Terraform会：

1. 附加GET参数 terraform-get=1，请求那个URL
2. 如果得到2xx应答，那么尝试从以下位置读取模块实际地址：
   1. 响应头 X-Terraform-Get
   2. HTML元素：
      
      XHTML

      1	<meta name="terraform-get" content="github.com/hashicorp/example" />

如果URL的结尾是可识别的压缩格式扩展名（zip tar.bz2  tbz2 tar.gz  tgz tar.xz txz）则Terraform会跳过上面处理过程，直接下载压缩包：

如果需要的模块位于源的子目录中，可以使用特殊的 //语法来引用：

hashicorp/consul/aws//modules/consul-cluster
git::https://example.com/network.git//modules/vpc
https://example.com/network-module.zip//modules/vpc
s3::https://s3-eu-west-1.amazonaws.com/examplecorp-terraform-modules/network.zip//modules/vpc
git::https://example.com/network.git//modules/vpc?ref=v1.2.0

开发模块就是构思和编写TF文件的过程，你需要考虑模块的输入（变量）、输出（值），模块读取和创建哪些资源。你只需要将这些TF文件放在一个目录中就可以了。

如果开发的模块可能被很多配置复用，建议在独立的版本库中管理。

尽管内嵌多个子目录（作为子模块）是允许的，但是建议尽可能的让目录扁平化，可以使用模块组合，而避免深层次的目录树，这可以增强可复用性。

过度的模块化容易让配置难以理解。

一个好的模块应该通过描述架构中新概念来提升抽象层次，这个概念由一些Provider中的基本元素组成。例如，我们想基于一些CVM、一个CLB构建一个Redis集群，这样的集群就适合封装在一个模块中。

永远不要开发那种仅仅为了包装单个其它资源的模块。

一个简单的Terraform配置，仅仅包含一个根模块，我们在这个扁平的结构中创建所有资源： 

当引入 modules块后，配置变成层次化的，每个模块可以创建自己的资源，甚至有自己的下级子模块。 无节制的使用子模块会导致很深的树状配置结构，这是反模式。

Terraform建议保持配置的扁平，仅仅引入一层子模块。假设我们需要在AWS上创建一个Consul集群，它依赖一个子网。我们可以将子网的创建封装到模块：

将Consul集群的创建封装到另外一个模块：

根模块通过上面两个module块使用这两个子模块，这种简单的单层结构叫模块组合（ module composition）

上面这个例子也体现了依赖反转的原则： consul_cluster需要一个网络，但是不是它（这个模块）自己去创建网络，而是由外部创建并注入给它。

在未来进一步的重构中，可能由另外一个配置负责创建网络，而仅仅通过数据资源将读取网络信息：

开发可复用模块时，一个很常见的情况是，某个依赖的资源在某些条件下不需要创建 —— 例如在某些环境下，资源预先已经存在。

这种情况下同样要应用依赖反转原则：将这些可能需要创建的依赖资源作为模块的输入参数：

由模块的调用者决定创建依赖资源：

还是直接使用已经存在的依赖资源：

因为，只有调用者才清楚实际环境是什么样的。 

Terraform本身没有提供适配多个云服务商的相似资源的抽象，这会屏蔽云服务商的差异性。尽管如此，作为Terraform用户来说，进行多云抽象是常见需求，特别是云迁移这样的应用场景。 

举例来说，任何一个云服务商的域名系统都支持域名解析。但是某些云服务商可能提供智能负载均衡、地理位置感知的解析这样高级特性。我们可以将域名系统的公共特性抽象为模块：

上面的recordset，抽象了所有域名系统都应该支持的DNS记录集资源。

当针对某个云服务商实现此资源时，我们可以开发一个模块。

需要切换云服务商时，只需要替换上述dns_records模块的source即可，指向对应的模块即可。所有这些模块都需要定义输入参数：

大部分模块都会描述需要被创建和管理的基础设施对象，偶尔的情况下，模块仅仅去抓取需要的信息。

其中一种情况是，一套系统被划分为多个子系统，这些子系统都需要获取某种信息，这些信息可以用由一个data-only模块抓取。

出于复用目的的模块可以发布到Terraform Registry， 这样模块可以很容易被所有人使用。如果仅仅在组织内部共享，可以发布到私有仓库。

通过Git、S3、HTTP等方式发布模块也是可以的，模块支持多种源。

所谓提供者，就是Terraform的插件/驱动，负责和特定云厂商的API或者其它任何API打交道。

每个Provider都可以提供若干受管资源、数据资源，供Terraform使用。 反过来说，任何资源都是由Provider提供，没有Provider，Terraform什么都做不了。

Provider和Terraform完全独立的分发，公共的Provider托管在Terraform仓库（Registry）。

在每次Terraform运行过程中，需要的Provider会自动被安装。

Terraform CLI会在初始化工作目录的时候安装Provider，它能够自动从Terraform Registry下载Provider，或者从本地镜像/缓存加载。要指定缓存位置，在CLI配置文件中设置 plugin_cache_dir。或者设置环境变量 TF_PLUGIN_CACHE_DIR

为了保证，针对一套配置，总是安装相同版本的Provider，可以使用CLI创建一个依赖锁文件，并将此文件和配置一起纳入版本管理。

每个模块都必须声明它需要哪些Provider，这样Terraform才能够安装和使用它们。声明在 required_providers块中进行：

在required_providers块之外，Terraform总是使用本地名称来引用Provider：

Provider的源地址，是它的全局标识符，这个地址当然也指明了应该从何处下载Provider。

源地址的格式为： [<HOSTNAME>/]<NAMESPACE>/<TYPE>，各字段说明如下： 

1. 可选的主机名，默认registry.terraform.io，即Terraform Registry的主机名
2. 命名空间，通常是发布Provider的组织
3. 类型，通常是Provider管理的平台/系统的简短名称

>= 1.0表示要求1.0或更高版本。 ~> 1.0.4表示仅仅允许1.0.x版本。

目前仅有一个内置于Terraform的Provider，名为terraform_remote_state。你不需要再配置文件中引入它，尽管如此它还是有自己的源地址terraform.io/builtin/terraform。

某些组织可能会开发自己的Provider，以管理特殊的基础设施。他们可能希望在Terraform中使用这些Provider，但是却不将其发布到公共仓库中。这种情况下，，构建自己的私有仓库。更简单的，可以使用更简单的Provider安装方法，例如自己将其存放在本地文件系统的特定目录。

任何Provider都必须有源地址，源地址必须包含（或者隐含默认值）一个主机名。如果通过本地文件系统分发Provider，则这个主机名只是个占位符，甚至不需要可解析。你通常可以使用terraform.yourcompany.com作为主机名。你可以这样引入私有Provider：

选择一个隐式本地镜像目录（implied local mirror directories ），并创建目录terraform.example.com/examplecorp/ourcloud/1.0.0，在此目录中创建一个代表运行平台的子目录，例如linux_amd64，并将Provider的可执行文件、以及任何其它需要的文件存放到其中即可。对于Windows，可执行文件的路径可能是terraform.example.com/examplecorp/ourcloud/1.0.0/windows_amd64/terraform-provider-ourcloud.exe

除了引入Provider，你可能还需要对其进行配置才能使用。

配置时，使用provider块。只有根模块才可以配置一个Provider。子模块会自动从根模块继承Provider配置。示例：

具体哪些配置参数可用，取决于Provider。配置时可以使用表达式，但是只能引用那些应用配置之前即可知的值 —— 可以安全的引用输入变量，但是不能使用那些由资源导出的属性。

Provider支持两个元参数，其中一个是alias，用于定义备选的Provider配置：

声明资源时，可以指定使用备选的Provider配置： 

这个元参数已经弃用，是旧的管理Provider版本的方式。 

Terraform配置文件可以引用两类外部依赖：

1. Providers，如上个章节所述，用于和外部系统交互的插件
2. Modules，可复用的配置文件集合

这两类依赖都可以独立发布，并进行版本管理。引用这些依赖时，Terraform需要知道使用什么版本。

配置文件中的版本约束，指定了潜在的兼容性版本范围。但是到底选择（并锁定使用）依赖的哪个版本，由名为.terraform.lock.hcl的依赖锁文件决定。注意，当前依赖锁文件仅仅管理Provider的版本，对于Module，仍然总是拉取匹配版本约束的最新版本。

每当运行 terraform init命令时，依赖锁文件会自动创建/更新。此文件应该纳入版本管理。依赖锁文件使用和TF类似的语法。

运行terraform init时，如果：

1. 依赖没有记录在依赖锁文件中，则尝试拉取匹配版本约束的最新版本。并将获取到的版本信息记录到依赖锁文件
2. 依赖已经记录，则使用记录的版本

运行 terraform init -upgrade会强制拉取最新的、匹配约束的版本并更新依赖锁文件。

Terraform逻辑上划分为两个部分：核心和插件。Terraform核心通过RPC来调用插件。Terraform支持多种发现和加载插件的方式。Terraform插件有两类

1. Provider：通常用于对接到某特定云服务商，在其上创建基础设施对象
2. Provisioner：对接到某种provisioner，例如Bash

核心的职责包括：

1. 基础设施即代码：读取和解释配置文件和模块
2. 资源状态管理
3. 构造资源依赖图
4. 执行计划
5. 通过RPC和插件交互

插件和核心一样，基于Go语言编写。Terraform使用的所有Provider和Provisioner都是插件，它们在独立进程中运行。

Provider插件的职责是：

1. 初始化任何必要的库，用于进行API调用
2. 与基础设施提供者进行交互
3. 定义映射到特定服务的资源

Provisioner插件的职责是：

1. 在特定资源创建后、销毁前执行命令或脚本

当 terraform init运行后，Terraform会读取工作目录中的配置文件，确定需要哪些插件。并在多个位置搜索以及安装的插件，下载缺失的插件，确定使用插件的什么版本，并且更新依赖锁文件，锁定插件版本。

关于插件发现，有以下规则：

1. 如果已经安装了满足版本约束的插件，Terraform会使用其中最新的。即使Terraform Registry有更新的满足版本约束的插件，默认也不会主动下载。使用 terraform init -upgrade可以强制下载最新版本
2. 如果没有安装满足版本约束的插件，且插件托管在Registry，则下载并存放到 .terraform/providers/目录下

Provider应该基于单一API集合，或者SDK，例如仅仅针对腾讯云API，实现对腾讯云基础实施对象CRUD的封装。

Terraform插件定义的资源，应该对应单一的云资源，作为该云资源的声明式表示。资源通常应该提供创建/读取/删除，以及可选的更新方法。

对多个云资源的组合，或者其它高级特性，应该通过模块来实现。

名称、数据类型、结构，应当尽可能匹配，除非这样做会影响Provider用户的体验。

Terraform资源应该支持 terraform import操作。

一旦Provider发布，后续就面临向后兼容性问题。

开发Provider时，有两个SDK可供选择：

1. SDKv2：当前大部分现有的Provider基于此SDK开发，提供稳定的开发体验
2. Terraform Plugin Framework：新的SDK，还在积极的开发中。目标是提升开发体验，对齐Terraform新的架构

如何选择：

1. 如果维护既有Provider，沿用它当前使用的SDK。如果开发全新的Provider，可以考虑使用Framework
2. 如果使用的Terraform版本小于v1.0.3，则只能基于SDKv2开发。Framework基于Terraform Protocol Version 6构建，旧版本的Terraform不能下载基于Version 6的Provider
3. Framework的接口可能发生改变，考虑成本
4. 是否需要Framework提供的新特性：
   1. 支持获知一个值是否在配置、状态或计划中设置
   2. 支持获知一个值是否null、unknown，或者是空白值
   3. 支持object这样的结构化类型
   4. 支持嵌套属性
   5. 支持以any类型为元素的map
   6. 支持获知何时一个optional或计算出的字段从配置中移除了
5. 是否需要Framework尚未实现的，SDKv2已经支持的特性：
   1. 超时支持
   2. 定义资源状态upgraders

构建Provider的时候，使用go build命令，按照构建二进制文件的常规方式即可。你也可以使用GoReleaser来自动化构建多平台的、包含checksum的、自动签名的Provider。

每个发布包含以下文件：

1. 一个或多个zip文件，其命名格式为 terraform-provider-{NAME}_{VERSION}_{OS}_{ARCH}.zip
   1. zip中包含Provider的二进制文件，命名为 terraform-provider-{NAME}_v{VERSION}
2. 一个摘要文件 terraform-provider-{NAME}_{VERSION}_SHA256SUMS，包含每个zip的sha256：
   
   Shell

   1	shasum -a 256 *.zip > terraform-provider-{NAME}_{VERSION}_SHA256SUMS

3. 一个GPG二进制文件 terraform-provider-{NAME}_{VERSION}_SHA256SUMS.sig，使用密钥对上述摘要文件进行前面：
   
   Shell

   1	gpg --detach-sign terraform-provider-{NAME}_{VERSION}_SHA256SUMS

4. 发布必须是finalized的（不是一个私有的草稿）

本章开发和使用一个Provider，它和虚构的咖啡店应用Hashicups进行交互。此咖啡店应用支持查看和订购咖啡，它开放公共API端点：

1. 列出咖啡品种
2. 列出特定咖啡的成分

以及需要身份认证的API端点：

1. CRUD咖啡订单

HashiCups Provider基于一个Golang客户端库，利用REST API访问以上API端点，管理咖啡订单。

首先我们从用户角度来感受一下，如何使用HashiCups Provider管理咖啡订单。本章后续会分析和重构该Provider的源码。

执行下面的命令下载使用HashiCups Provider的Terraform配置的空白项目。此项目没有Terraform配置，但是提供了在本地运行HashiCup咖啡店应用的脚本。

执行下面的命令，在本地启动HashiCup咖啡店应用：

API监听端口是19090。检查并确认服务器正常工作：

从0.13+开始，必须在Terraform配置中声明所有依赖的Provider及其源（从哪里下载）。源的格式为[hostname]/[namespace]/[name]，对于Terraform Registry中的hashicorp命名空间，hostname和namespace都是可选的。Terraform Registry对应的hostname为registry.terraform.io

这里用到的Provider没有托管在Registry，需要手工下载：

或者从源码编译：

并且存放到：

~/.terraform.d/plugins/${host_name}/${namespace}/${type}/${version}/${target}
~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.3.1/linux_amd64/terraform-provider-hashicups_v0.3.1

登录以获得Token：

将Token设置到环境变量：

添加下面的代码到main.tf：

并进行初始化： terraform init

将以下内容添加到main.tf中：

执行下面的命令获取执行计划：

执行 terraform apply即可应用变更。 利用 terraform state show命令可以显示资源状态：

可以看到Schema中所有属性均被填充。

我们修改一下订单配置，将items[*].quantity改一下，然后看看执行计划：

通过apply命令应用上述执行计划。

本节我们来演示如何读取已经创建的订单的咖啡的配料表：

签出Provider源码：

注意SDKv2的依赖：

分支boilerplate包含一些样板文件。 程序的入口点如下：

Provider函数：

上面已经定义了Provider的骨架，这里我们实现一个咖啡数据源，此数据源能够从HasiCups服务拉取所有售卖的咖啡信息。

建议每个数据源都在独立的源文件中编写，并且文件名以 data_source_开头： 

下面我们完善此数据资源的Schema，根据Terraform的最佳实践，Schema应该尽量和基础实施匹配：

根据服务器返回的咖啡数据结构，编写对应的Schema并且添加到上面的dataSourceCoffees方法中：

定义好Schema后，我们需要实现读操作： 

数据资源的ID被设置为非空值，这提示Terraform，目标资源已经被创建。 作为一个列表，此数据资源没有真实的ID，因此我们这里设置为时间戳。

如果数据资源被从Terraform外部删除了，这里应该设置空ID：

这样Terraform会自动将state中的数据资源清除掉。

将上面的数据资源配置到Provider中：

现在我们开发一个模块，使用上面定义的咖啡数据源。首先需要编译好Provider： make install。 

根模块配置：

coffee子模块配置：

应用根模块：

本节我们来演示如何为Provider增加参数，Provider的实现又是如何读取这些参数的。

用户提供的username/password，如何被Provider的ReadContext函数访问呢？这需要配置Provider。配置过程是由 schema.Provider的 ConfigureContextFunc函数负责的：

可以看到配置Provider后，会返回一个interface{}，这个对象会传递给CRUD操作的最后一个参数：

一般情况下，这个interface{}是配置好的云API客户端，或者是云API配置结构。

本节我们演示如何在读操作中使用Provider参数，更精确的说是基于这些参数配置Provider后的结果。

首先我们创建几个咖啡订单（用于后续查询）：

看一下订单的数据结构：

下面我们定义对应的数据源：

注意这个数据源的Schema和API的结构没有做对应，进行了扁平化处理。

读取订单的操作如下：

将此资源注册到Provider：

在配置文件中使用该数据源：

本节演示如何基于日志来调试Provider，我们会添加定制的错误消息，并且显示详细的Terraform Provider日志。

开发Provider时需要实现很多函数，这些函数常常具有一个返回值 diag.Diagnostics，例如上面的CRUD操作，以及配置Provider的函数：

警告/错误级别的调试信息，都要放到diag.Diagnostics中，执行Terraform CLI命令时，这些信息会自动打印。

当创建HashiCups客户端失败时，我们可以添加一条针对信息：

执行命令时，错误信息会打印出来：

资源支持创建、修改、删除等写操作，上面编写的数据源则仅支持读。尽管资源、数据源可能指向同一类实体，但是Schema不能共用。

资源的文件名前缀通常使用 resource_，下面是订单资源的骨架代码：

我们需要将其注册到Provider：

不同于上问的订单数据源，这里我们设计了和API结构更加匹配的Schema：

注意和订单数据源Schema的其它几个重要区别：

1. 在资源Schema中，顶级的id属性不存在。这是因为资源中你无法提前知道id，也不能将id作为输入参数。id是在资源创建过程中自动生成的
2. 在资源Schema中，items是必须字段，而不是计算出的字段。这是因为我们在配置中声明订单资源时必须提供订单项信息