1.7.1. Terraform命令行

我们在前面的的章节中主要介绍了如何书写和组织Terraform代码，下面我们要介绍一下如何使用Terraform命令行工具来应用这些代码，并且管理和操作我们的云端基础设施。

Terraform是用Go语言编写的，所以它的交付物只有一个可执行命令行文件：terraform。在Terraform执行发生错误时，terraform进程会返回一个非零值，所以在脚本代码中我们可以轻松判断执行是否成功。

我们可以在命令行中输入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
29
30
31
32
33
34
35
36
37
38
39
$ terraform
Usage: terraform [-version] [-help] <command> [args]

The available commands for execution are listed below.
The most common, useful commands are shown first, followed by
less common or more advanced commands. If you're just getting
started with Terraform, stick with the common commands. For the
other commands, please read the help and docs before usage.

Common commands:
    apply              Builds or changes infrastructure
    console            Interactive console for Terraform interpolations
    destroy            Destroy Terraform-managed infrastructure
    env                Workspace management
    fmt                Rewrites config files to canonical format
    get                Download and install modules for the configuration
    graph              Create a visual graph of Terraform resources
    import             Import existing infrastructure into Terraform
    init               Initialize a Terraform working directory
    login              Obtain and save credentials for a remote host
    logout             Remove locally-stored credentials for a remote host
    output             Read an output from a state file
    plan               Generate and show an execution plan
    providers          Prints a tree of the providers used in the configuration
    refresh            Update local state file against real resources
    show               Inspect Terraform state or plan
    taint              Manually mark a resource for recreation
    untaint            Manually unmark a resource as tainted
    validate           Validates the Terraform files
    version            Prints the Terraform version
    workspace          Workspace management

All other commands:
    0.12upgrade        Rewrites pre-0.12 module source code for v0.12
    0.13upgrade        Rewrites pre-0.13 module source code for v0.13
    debug              Debug output management (experimental)
    force-unlock       Manually unlock the terraform state
    push               Obsolete command for Terraform Enterprise legacy (v1)
    state              Advanced state management

1.7.1.1. 通过 -chdir 参数切换工作目录

运行Terraform时一般要首先切换当前工作目录到包含有想要执行的根模块.tf代码文件的目录下（比如使用cd命令），这样Terraform才能够自动发现要执行的代码文件以及参数文件。

在某些情况下——尤其是将Terraform封装进某些自动化脚本时，如果能够从其他路径直接执行特定路径下的根模块代码将会十分的方便。为了达到这一目的，Terraform目前支持一个全局参数-chdir=...，你可以在任意子命令的参数中使用该参数指定要执行的代码路径：

1
$ terraform -chdir=environments/production apply

-chdir参数指引Terraform在执行具体子命令之前切换工作目录，这意味着使用该参数后Terraform将会在指定路径下读写文件，而非当前工作目录下的文件。

在两种场景下Terraform会坚持使用当前工作目录而非指定的目录，即使是我们通过-chdir指定了一个目标路径：

  • Terraform处理命令行配置文件中的设置而非执行某个具体的子命令时，该阶段发生在解析-chdir参数之前
  • 如果你需要使用当前工作目录下的文件作为你配置的一部分时，你可以通过在代码中使用path.cwd变量获得对当前工作路径的引用，而不是-chdir所指定的路径。可以通过使用path.root来获取代表根模块所在的路径。

1.7.1.2. 自动补全

如果你使用的是bash或是zsh，那么可以轻松安装自动补全：

1
$ terraform -install-autocomplete

卸载自动补全也很容易：

1
$ terraform -uninstall-autocomplete

目前自动补全并没有覆盖到所有子命令。

1.7.1.3. 版本信息

Terraform命令行会与HashiCorp的Checkpoint服务交互来检查当前版本是否有更新或是关键的安全公告。

可以通过执行terraform version命令来检查是否有新版本可用。

1.7.1.4. Checkpoint服务

Terraform会收集一些不涉及用户身份信息或是主机信息的数据发送给Checkpoint服务。一个匿名ID会被发送到Checkpoint来消除重复的告警信息。我们可以关闭与Checkpoint的交互。

我们可以设置CHECKPOINT_DISABLE环境变量的值为任意非空值来完全关闭HashiCorp所有产品与Checkpoint的交互。另外，我们也可以通过设置命令行配置文件来关闭这些功能：

1.7.1.1. 命令行配置文件(.terraformrc 或 terraform.rc)

命令行配置文件为每个用户配置了命令行的行为，适用于所有的 Terraform 工作目录，这与我们编写的 Terraform 代码是分开的。

1.7.1.1.1. 位置

配置文件的位置取决于用户使用的操作系统：

  • Windows 平台上，文件名必须是 terraform.rc，位置必须在相关用户的 %APPDATA% 目录下。这个目录的物理路径取决于 Windows 的版本以及系统配置；在 PowerShell 中查看 $env:APPDATA 可以找到对应的路径
  • 在其他操作系统上，文件名必须是 .terraformrc(注意第一个是 .)，位置必须是在相关用户的 HOME 目录

在 Windows 上创建配置文件时，要注意 Windows Explorer 默认隐藏文件扩展名的行为。Terraform 不会把 terraform.rc.txt 文件识别为命令行配置文件，而默认情况下 Windows Explorer 会将它的文件名显示为 terraform.rc (隐藏了扩展名的缘故)。可以在 PowerShell 或命令行中使用 dir 命令来确认文件名。

可以通过设置 TF_CLI_CONFIG_FILE 环境变量的方式来修改配置文件的位置。

1.7.1.1.2. 配置文件语法

配置文件本身如同 .tf 文件那样也采用HCL语法，但使用不同的属性和块。以下是常见语法的演示，后续的部分会详细介绍这些配置项：

1
2
plugin_cache_dir   = "$HOME/.terraform.d/plugin-cache"
disable_checkpoint = true

1.7.1.1.3. 可用配置

命令行配置文件中可以设置的配置项有：

  • credentials：使用 Terraform Cloud 服务或 Terraform 企业版时使用的凭据
  • credentials_helper：配置一个外部的用于读写 Terraform Cloud 或 Terraform 企业版凭据的帮助程序
  • disable_checkpoint：设置为 true 可以完全关闭与 Checkpoint 的交互
  • disable_checkpoint_signature：设置为 true 可以阻止向 Checkpoint 发送匿名 ID
  • plugin_cache_dir：开启插件缓存，我们在介绍 Provider 的章节中介绍过
  • provider_installation：定制化执行 terraform init 时安装插件的行为

鉴于本教程无意涉及与 Terraform Cloud 或企业版相关的部分，所以我们会略过对 credentials 和 credentials_helper 的介绍；插件缓存的相关知识我们在 Provider 章节中已做过介绍，在此先偷懒略过。感兴趣的读者可以自行查阅相关文档

1.7.1.1.4. Provider 的安装

默认情况下 Terraform 从官方 Provider Registry 下载安装 Provider 插件。Provider 在 Registry 中的原始地址采用类似 registry.terraform.io/hashicorp/aws 的编码规则。通常为了简便，Terraform 允许省略地址中的主机名部分 registry.terraform.io，所以我们可以直接使用地址 hashicorp/aws。

有时无法直接从官方 Registry 下载插件，例如我们要在一个与公网隔离的环境中运行 Terraform 时。为了允许 Terraform 工作在这样的环境下，有一些可选方法允许我们从其他地方获取 Provider 插件。

1.7.1.1.4.1. 显式安装方法配置

可以在命令行配置文件中定义一个 provider_installation 块来修改 Terraform 默认的插件安装行为，命令 Terraform 使用本地的 Registry 镜像服务，或是使用一些用户修改过的插件。

通常 provider_installation 块的结构如下：

1
2
3
4
5
6
7
8
9
provider_installation {
  filesystem_mirror {
    path    = "/usr/share/terraform/providers"
    include = ["example.com/*/*"]
  }
  direct {
    exclude = ["example.com/*/*"]
  }
}

provider_installation 块中每一个内嵌块都指定了一种安装方式。每一种安装方式都可以同时包含 include 与 exclude 模式来指定安装方式使用的 Provider 类型。在上面的例子里，我们把所有原先位于 example.com 这个 Registry 存储中的 Provider 设置成只能从本地文件系统的 /usr/share/terraform/providers 镜像存储中寻找并安装，而其他的 Provider 只能从它们原先的 Registry 存储下载安装。

如果你为一种安装方式同时设置了 include 与 exclude，那么 exclude 模式将拥有更高的优先级。举例：包含registry.terraform.io/hashicorp/*但排除registry.terraform.io/hashicorp/dns将对所有hashicorp空间下的插件有效，但是hashicorp/dns除外。

和Terraform代码文件中Provider的source属性一样的是，在provider_installation里你也可以省略registry.terraform.io/的前缀，甚至是使用通配符时亦是如此。比如，registry.terraform.io/hashicorp/*和hashicorp/*是等价的；*/*是registry.terraform.io/*/*的缩写，而不是*/*/*的缩写。

目前支持的安装方式如下：

  • direct：要求直接从原始的Registry服务下载。该方法不需要额外参数。
  • filesystem_mirror：一个本地存有 Provider 插件拷贝的目录。该方法需要一个额外的参数 path 来指定存有插件拷贝的目录路径。 Terraform 期待给定路径的目录内通过路径来描述插件的一些元信息。支持一下两种目录结构：
    • 打包式布局： HOSTNAME/NAMESPACE/TYPE/terraform-provider-TYPE_VERSION_TARGET.zip 的格式指定了一个从原始 Registry 获取的包含插件的发行版 zip 文件
    • 解压式布局：HOSTNAME/NAMESPACE/TYPE/VERSION/TARGET 式一个包含有 Provider 插件发行版 zip 文件解压缩后内容物的目录 这两种布局下，VERSION 都是代表着插件版本的字符串，比如 2.0.0；TARGET 则指定了插件发行版对应的目标平台，例如 darwin_amd64、linux_arm、windows_amd64 等等。

如果使用解压式布局，Terraform 在安装插件时会尝试创建一个到镜像目录的符号连接来避免拷贝文件夹。打包式布局则不会这样做，因为 Terraform 必须在安装插件时解压发行版文件。

你可以指定多个filesystem_mirror块来指定多个不同的目录。

  • network_mirror：指定一个 HTTPS 服务地址提供 Provider 插件的拷贝，不论这些插件原先属于哪些 Registry 服务。该方法需要一个额外参数 url 来指定镜像服务的地址，url 地址必须使用 https: 作为前缀，以斜杠结尾。 Terraform期待该地址指定的服务实现了 Provider网络镜像协议，这是一种被设计用来托管插件拷贝的网站所需要实现的协议，在此我们不展开讨论。

需要特别注意的是，请不要使用不可信的 network_mirror 地址。Terraform 会验证镜像站点的 TLS 证书以确认身份，但一个拥有合法 TLS 证书的镜像站可能会提供包含恶意内容的插件文件。

  • dev_overrides：指定使用本地的开发版本插件。有时我们想要对 Provider 代码做一些修改，为了调试本地代码编译后的插件，可以使用 dev_overrides 指定使用本地编译的版本。

例如，我们想要调试本地修改过的 UCloud Provider 插件，我们可以从 github 上克隆该项目源代码，修改完代码后，编译一个可执行版本(以Mac OS为例)：

1
2
$ GOOS=darwin GOARCH=arm64 go build -o bin/terraform-provider-ucloud
$ chmod +x bin/terraform-provider-ucloud

然后编写如下provider_installation配置：

1
2
3
4
5
provider_installation{
  dev_overrides {
    "ucloud/ucloud" = "PATH_TO_PROJECT/terraform-provider-ucloud/"
  }
}

当 Terraform 代码中要求了 source 为 ucloud/ucloud 的 Provider 时，执行 terraform init 仍然会报错，抱怨找不到 ucloud/ucloud 这个 Provider，但执行 terraform plan 或是 terraform apply 等操作时可以顺利执行，此时 Terraform 会使用路径指定的本地 Provider 插件。这种方式比较适合于调试本地 Provider 插件代码。

对于上述的几种插件安装方式，Terraform 会尝试通过 include 和 exclude 模式匹配 Provider，遍历匹配的安装方式，选择一个符合 Terraform 代码中对插件版本约束的最新版本。如果你拥有一个插件的特定版本的本地镜像，并且你希望 Terraform 只使用这个本地镜像，那么你需要移除 direct 安装方式，或是在 direct 中通过exclude 参数排除特定的 Provider。

1.7.1.1.5. 隐式的本地镜像目录

如果命令行配置文件中没有包含 provider_installation 块，那么 Terraform 会生成一个隐式的配置。该隐式配置包含了一个 filesystem_mirror 方法以及一个 direct 方法。

在不同的操作系统上，Terraform 会选择不同的路径作为隐式 filesystem_mirror 路径：

  • Windows：%APPDATA%/terraform.d/plugins 以及 %APPDATA%/HashiCorp/Terraform/plugins
  • Mac OS X：$HOME/.terraform.d/plugins/，~/Library/Application Support/io.terraform/plugins 以及 /Library/Application Support/io.terraform/plugins
  • Linux 以及其他 Unix 风格系统：$HOME/.terraform.d/plugins/，以及配置的 XDG 基础目录后接 terraform/plugins。如果没有设置 XDG 环境变量，Terraform 会使用 ~/.local/share/terraform/plugins，/usr/local/share/terraform/plugins，以及 /usr/share/terraform/plugins

Terraform 会在启动时为上述路径的每一个目录创建一个隐式 filesystem_mirror 块。另外如果当前工作目录下包含有 terraform.d/plugins 目录，那么也会为它创建一个隐式 filesystem_mirror 块。

相对于任意多个隐式 filesystem_mirror 块，Terraform 同时也会创建一个隐式 direct 块。Terraform 会扫描所有文件系统镜像目录，对找到的 Provider 自动从 direct 块中排除出去（这种自动的 exclude 行为只对隐式 direct 块有效。如果你在 provider_installation 块中显式指定了 direct 块，那么你需要自己显式定义 exclude 规则）。

TODO:https://developer.hashicorp.com/terraform/cli/config/config-file#provider-plugin-cache

1.7.1.1.6. Provider 插件缓存

1.7.1.1.7. 允许 Provider 缓存跳过依赖锁文件检查

1.7.2.1. 环境变量

Terraform使用一系列的环境变量来定制化各方面的行为。如果只是想简单使用Terraform，我们并不需要设置这些环境变量；但他们可以在一些不常见的场景下帮助我们改变Terraform的默认行为，或者是出于调试目的修改输出日志的级别。

1.7.2.1.1. TF_LOG

该环境变量可以设定 Terraform 内部日志的输出级别，例如：

1
$ export TF_LOG=TRACE

Terraform 日志级别有 TRACE、DEBUG、INFO、WARN 和 ERROR。TRACE 包含的信息最多也最冗长，如果 TF_LOG 被设定为这五级以外的值时 Terraform 会默认使用 TRACE。

如果在使用 Terraform 的过程中遇到未知的错误并怀疑是 Terraform 或相关插件的 bug，请设置 TF_LOG 级别后收集输出的日志并提交给相关人员。

有志于获取 Terraform 认证的读者请注意，该知识点近乎属于必考。

1.7.2.1.2. TF_LOG_PATH

该环境变量可以设定日志文件保存的位置。注意，如果TF_LOG_PATH被设置了，那么 TF_LOG 也必须被设置。举例来说，想要始终把日志输出到当前工作目录，我们可以这样：

1
$ export TF_LOG_PATH=./terraform.log

1.7.2.1.3. TF_INPUT

该环境变量设置为 "false" 或 "0" 时，等同于运行 Terraform 相关命令行命令时添加了参数 -input=false。如果你想在自动化环境下避免 Terraform 通过命令行的交互式提示要求给定输入变量的值而是直接报错时(无 default 值的输入变量，无法通过任何途径获得值)可以设置该环境变量：

1
$ export TF_INPUT=0

1.7.2.1.4. TF_VAR_name

我们在介绍输入变量赋值时介绍过，可以通过设置名为 TF_VAR_name 的环境变量来为名为 "name" 的输入变量赋值：

1
2
3
4
$ export TF_VAR_region=us-west-1
$ export TF_VAR_ami=ami-049d8641
$ export TF_VAR_alist='[1,2,3]'
$ export TF_VAR_amap='{ foo = "bar", baz = "qux" }'

1.7.2.1.5. TF_CLI_ARGS 以及 TF_CLI_ARGS_name

TF_CLI_ARGS 的值指定了附加给命令行的额外参数，这使得在自动化 CI 环境下可以轻松定制 Terraform 的默认行为。

该参数的值会被直接插入在子命令后(例如 plan)以及通过命令行指定的参数之前。这种做法确保了环境变量参数优先于通过命令行传递的参数。

例如，执行这样的命令：TF_CLI_ARGS="-input=false" terraform apply -force，它等价于手工执行 terraform apply -input=false -force。

TF_CLI_ARGS 变量影响所有的 Terraform 命令。如果你只想影响某个特定的子命令，可以使用 TF_CLI_ARGS_name 变量。例如：TF_CLI_ARGS_plan="-refresh=false"，就只会针对 plan 子命令起作用。

该环境变量的值会与通过命令行传入的参数一样被解析，你可以在值里使用单引号和双引号来定义字符串，多个参数之间以空格分隔。

1.7.2.1.6. TF_DATA_DIR

TF_DATA_DIR 可以修改 Terraform 保存在每个工作目录下的数据的位置。一般来说，Terraform 会把这些数据写入当前工作目录下的 .terraform 文件夹内，但这一位置可以通过设置 TF_DATA_DIR 来修改。

大部分情况下我们不应该设置该变量，但有时我们不得不这样做，比如默认路径下我们无权写入数据时。

该数据目录被用来保存下一次执行任意命令时需要读取的数据，所以必须被妥善保存，并确保所有的 Terraform 命令都可以一致地读写它，否则 Terraform 会找不到 Provider 插件、模块代码以及其他文件。

1.7.2.1.7. TF_WORKSPACE

多环境部署时，可以使用此环境变量而非 terraform workspace select your_workspace 来切换 workspace。使用 TF_WORKSPACE 允许设置使用的工作区。

比如：

1
export TF_WORKSPACE=your_workspace

建议仅在非交互式使用中使用此环境变量，因为在本地 shell 环境中，很容易忘记设置了该变量并将变更执行到错误的环境中。

可以在这里阅读工作区的更多信息。

1.7.2.1.8. TF_IN_AUTOMATION

如果该变量被设置为非空值，Terraform 会意识到自己运行在一个自动化环境下，从而调整自己的输出以避免给出关于该执行什么子命令的建议。这可以使得输出更加一致且减少非必要的信息量。

1.7.2.1.9. TF_REGISTRY_DISCOVERY_RETRY

该变量定义了尝试从 registry 拉取插件或模块代码遇到错误时的重试次数。

1.7.2.1.10. TF_REGISTRY_CLIENT_TIMEOUT

该变量定义了发送到 registry 连接请求的超时时间，默认值为 10 秒。可以这样设置超时：

1
$ export TF_REGISTRY_CLIENT_TIMEOUT=15

1.7.2.1.11. TF_CLI_CONFIG_FILE

该变量设定了 Terraform 命令行配置文件的位置：

1
$ export TF_CLI_CONFIG_FILE="$HOME/.terraformrc-custom"

1.7.2.1.12. TF_PLUGIN_CACHE_DIR

TF_PLUGIN_CACHE_DIR 环境变量是配置插件缓存目录的另一种方法。你也可以使用 TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE 环境变量设置 plugin_cache_may_break_dependency_lock_file 配置项

1.7.2.1.13. TF_IGNORE

如果 TF_IGNORE 设置为 "trace"，Terraform 会在调试信息中输出被忽略的文件和目录。该配置与 .terraformignore 文件搭配时对调试大型代码仓库相当有用：

1
export TF_IGNORE=trace

1.7.3.1. 资源地址

在编码时我们有时会需要引用一些资源的输出属性或是一些模块的输出值，这都涉及到如何在代码中引用特定模块或是资源。另外在执行某些命令行操作时也需要我们显式指定一些目标资源，这时我们要掌握Terraform的资源路径规则。

一个资源地址是用以在一个庞大的基础设施中精确引用一个特定资源对象的字符串。一个地址由两部分组成：[module path][resource spec]。

1.7.3.1.1. 模块路径

一个模块路径在模块树上定位了一个特定模块。它的形式是这样的：module.module_name[module index]

  • module：module 关键字标记了这时一个子模块而非根模块。在路径中可以包含多个 module 关键字
  • module_name：用户定义的模块名
  • [module index]：(可选)访问多个子模块中特定实例的索引，由方括号包围

一个不包含具体资源的地址，例如 module.foo 代表了模块内所有的资源(如果只是单个模块而不是多实例模块)，或者是多实例模块的所有实例。要指代特定模块实例的所有资源，需要在地址中附带下标，例如 module.foo[0]。

如果地址中模块部分被省略，那么地址就指代根模块资源。

这里有一个包含多个 module 关键字应用于多实例模块的例子：module.foo[0].module.bar["a"]。

要注意的是，由于模块的 count 和 for_each 元参数是 Terraform 0.13 开始引进的，所以多实例模块地址也只能在 0.13 及之后的版本使用。

1.7.3.1.2. 资源地址形式

一个资源地址定位了代码中特定资源对象，它的形式是这样的：resource_type.resource_name[resource index]

  • resource_type：资源类型
  • resource_name：用户定义的资源名称
  • [resource index]：(可选)访问多实例资源中特定资源实例的索引，由方括号包围

1.7.3.1.3. 多实例模块与资源的访问索引

以下规约适用于访问多实例模块及资源时使用的索引值：

  • [N]：当使用 count 元参数时N是一个自然数。如果省略，并且 count > 1，那么指代所有的实例
  • ["INDEX"]：当使用 for_each 元参数时 INDEX 是一个字母数字混合的字符串

1.7.3.1.4. 例子

1.7.3.1.4.1. count 的例子

给定一个代码定义：

1
2
3
4
resource "aws_instance" "web" {
  # ...
  count = 4
}

给定一个地址：aws_instance.web[3]，它指代的是最后一个名为 web 的 aws_instance 实例；给定地址 aws_instance.web，指代的是所有名为 web 的 aws_instance 实例。

1.7.3.1.4.2. for_each 的例子

给定如下代码：

1
2
3
4
5
6
7
8
9
resource "aws_instance" "web" {
  # ...
  for_each = {
    "terraform": "value1",
    "resource":  "value2",
    "indexing":  "value3",
    "example":   "value4",
  }
}

地址 aws_instance.web["example"] 引用的是 aws_instance.web 中键为 "example" 的实例。

1.7.4.1. apply

Terraform 最重要的命令就是 apply。apply 命令可以生成执行计划(可选)并执行之，使得基础设施资源状态符合代码的描述。

1.7.4.1.1. 用法

terraform apply [options] [plan file]

Terraform 的 Apply 有两种模式：自动 Plan 模式以及既有 Plan 模式。

1.7.4.1.2. 自动 Plan 模式

当我们运行 terraform apply 而不指定计划文件时，Terraform 会自动创建一个新的执行计划，就像我们已运行 terraform plan 一样，提示我们批准该计划，并采取指示的操作。我们可以使用所有 plan 模式和 plan 选项来自定义 Terraform 创建计划的方式。

我们可以设置 -auto-approve 选项来要求 Terraform 跳过确认直接执行计划。

警告：如果使用 -auto-approve，建议确保没有人可以在 Terraform 工作流程之外更改我们的基础设施。这可以最大限度地降低不可预测的变更和配置漂移的风险。

1.7.4.1.3. 既有 Plan 模式

当您将既有的计划文件传递给 terraform apply 时，Terraform 会执行既有的计划中的操作，而不提示确认。在自动化运行 Terraform 时，可能需要使用由这样的两个步骤组成的工作流。

我们在应用计划之前可以使用 terraform show 检查既有的计划文件。

使用既有的计划时，我们无法指定任何其他计划模式或选项。这些选项只会影响 Terraform 关于采取哪些操作的决策，而这些决策的最终结果已经在计划文件中包含了。

1.7.4.1.4. Plan 参数

在未提供既有计划文件时，terraform apply 命令支持 terraform plan 命令所支持的所有 Plan 模式参数以及 Plan 选项参数。

  • Plan 模式参数：包括 -destroy（创建销毁所有远程对象的计划）和 -refresh-only（创建更新 Terraform 状态和根模块输出值的计划）。
  • Plan 选项参数：包括指定 Terraform 应替换哪些资源实例、设置 Terraform 输入变量等的参数。

1.7.4.1.5. Apply 参数

下面的参数可以更改 apply 命令的执行方式和 apply 操作生成的报告格式。

  • -auto-approve：跳过交互确认步骤，直接执行变更。此选项将被忽略，因为 Terraform 认为我们指定了计划文件即已批准执行，因此在这种情况下永远不会提示。
  • -compact-warnings：以紧凑的形式显示所有警告消息，其中仅包含摘要消息，除非输出信息中存在至少一个错误，因此警告文本中可能包含有错误的上下文信息。
  • -input=true：禁用 Terraform 的所有交互式提示。请注意，这也会阻止 Terraform 提示交互式批准计划，这时 Terraform 将保守地假设您不希望应用该计划，从而导致操作失败。如果您希望在非交互式上下文中运行 Terraform，请参阅 Terraform 与自动化 了解一些不同的方法。
  • -json：启用机器可读的 JSON UI 输出。这意味着 -input=false，因此配置 variable 值都已赋值才能继续。要启用此参数，您还必须启用 -auto-approve 标志或指定既有的计划文件。
  • -lock=false：执行时是否先锁定状态文件。如果其他人可能同时对同一工作区运行命令，则这是危险的。
  • -lock-timeout=DURATION：除非使用 -lock=false 禁用锁定，否则命令 Terraform 为上锁操作设置一个超时时长。持续时间语法是一个数字后跟一个时间单位字母，例如“3s”表示三秒。
  • -no-color：关闭彩色输出。在无法解释输出色彩的终端中运行 Terraform 时请使用此参数。
  • -parallelism=n：限制 Terraform 遍历图时的最大并行度，默认值为 10(考试高频考点)

当配置中只使用了 local Backend 时，terraform apply 还支持以下三个遗留参数：

  • -backup-path：保存备份文件的路径。默认等于 -state-out 参数后加上 ".backup" 后缀。设置为 "-" 可关闭
  • -state=path：保存状态文件的路径，默认值是 "terraform.tfstate"。如果使用了远程 Backend 该参数设置无效。该参数不影响其他命令，比如执行 init 时会找不到它设置的状态文件。如果要使得所有命令都可以使用同一个特定位置的状态文件，请使用 Local Backend
  • -state-out=path：写入更新的状态文件的路径，默认情况使用 -state 的值。该参数在使用远程 Backend 时设置无效

1.7.4.1.6. 指定其他配置文件目录

Terraform v0.13 及更早版本接受提供目录路径的附加位置参数，在这种情况下，Terraform 将使用该目录作为根模块而不是当前工作目录。

该用法在 Terraform v0.14 中已弃用，并在 Terraform v0.15 中删除。如果您的工作流程需要修改根模块目录，请改用 -chdir 全局选项，该选项适用于所有命令，并使 Terraform 始终在给定目录中查找它通常在当前工作目录中读取或写入的所有文件。

如果我们之前使用此遗留模式时同时需要 Terraform 将 .terraform 子目录写入当前工作目录，即使根模块目录已被覆盖，请使用 TF_DATA_DIR 环境变量命令 Terraform 将 .terraform 目录写入其他位置，而不是当前工作目录。

1.7.5.1. console

有时我们想要一个安全的调试工具来帮助我们确认某个表达式是否合法，或者表达式的值是否符合预期，这时我们可以使用 terraform console 启动一个交互式控制台。

1.7.5.1.1. 用法

terraform console [options] [options]

console 命令提供了一个用以执行和测试各种表达式的命令行控制台。在编码时如果我们不确定某个表达式的最终结果时(例如使用字符串模版)，我们可以在这个控制台中搭配当前状态文件中的数据进行各种测试。

如果当前状态是空的或还没有创建状态文件，那么控制台可以用来测试各种表达式语法以及内建函数。假如当前根模块有状态，console 命令将会对状态加锁，这使得我们无法在运行其他可能会修改状态的操作时使用 console 命令。

在控制台中可以使用 exit 命令或是 Ctrl-C 或是 Ctrl-D 退出。

当使用的是 local Backend 时，terraform console 可以使用 -state 遗留参数：

  • -state=path：指向本机状态文件的路径。表达式计算会使用该状态文件中记录的值。如果没有指定，则会使用当前工作区(Workspace)关联的状态文件

1.7.5.1.2. 脚本化

terraform console 命令可以搭配非交互式脚本使用，可以使用管道符将其他命令输出接入控制台执行。如果没有发生错误，只有最终结果会被打印。

样例：

1
2
3
4
5
6
echo 'split(",", "foo,bar,baz")' | terraform console
tolist([
  "foo",
  "bar",
  "baz",
])

1.7.5.1.3. 远程状态

如果使用了远程 Backend 存储状态，Terraform 会从远程 Backend 读取当前工作区的状态数据来计算表达式。

1.7.5.1.4. 搭配既有计划文件运行

默认情况下，terraform console 根据当前 Terraform 状态计算表达式，因此对于尚未通过 Apply 创建的资源实例，结果通常非常有限。

您可以使用 -plan 选项首先生成执行计划，就像运行 terraform plan 一样，然后根据计划的状态进行计算，以描述 Terraform 期望在应用计划后应得的值。这通常会在控制台提示出现之前引发更长的延迟，但作为回报，可知的表达式范围中将有一组更完整的可用值。

一个好的 Terraform 配置代码，在 Plan 阶段不应对实际远程对象进行任何修改，但我们可以编写一个在 Plan 时可以执行重要操作的配置。例如，使用 hashcorp/external Provider 程序的 external 数据源的配置可能会在 Plan 阶段运行设置的的外部命令，这意味着该外部命令也会被 terraform console -plan 运行。

我们不建议编写在 Plan 阶段进行更改的配置。如果您不顾该建议而编写了此类配置，则在 Plan 模式下针对该配置使用控制台时请务必小心。

1.7.5.1.5. 例子

terraform console 命令将从配置的 Backend 读取当前工作目录中的 Terraform 配置和 Terraform 状态文件，以便可以根据配置和状态文件中的值计算表达式。

假设我们有如下的 main.tf：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
variable "apps" {
  type = map(any)
  default = {
    "foo" = {
      "region" = "us-east-1",
    },
    "bar" = {
      "region" = "eu-west-1",
    },
    "baz" = {
      "region" = "ap-south-1",
    },
  }
}

resource "random_pet" "example" {
  for_each = var.apps
}

执行 terraform console 会进入交互式 shell，我们可以在其中计算表达式：

打印一个 map：

1
2
3
4
> var.apps.foo
{
  "region" = "us-east-1"
}

根据给定值过滤 map：

1
2
3
4
5
6
> { for key, value in var.apps : key => value if value.region == "us-east-1" }
{
  "foo" = {
    "region" = "us-east-1"
  }
}

确认特定值是否为尚不知晓（Known after apply）值：

1
2
> random_pet.example
(known after apply)

测试各种函数：

1
2
> cidrnetmask("172.16.0.0/12")
"255.240.0.0"

destroy

1.7.6.1. destroy

terraform destroy 命令可以用来销毁并回收所有由 Terraform 配置所管理的基础设施资源。

虽然我们一般不会删除长期存在于生产环境中的对象，但有时我们会用 Terraform 管理用于开发目的的临时基础设施，在这种情况下，您可以在完成后使用 terraform destroy 来方便地清理所有这些临时资源。

1.7.6.1.1. 用法

terraform destroy [options]

该命令是以下命令的快捷方式：

1
terraform apply -destroy

因此，此命令接受 terraform apply 所支持的大部分选项，但是它不支持 -destroy 模式搭配指定计划文件的用法。

我们还可以通过运行以下命令创建推测性销毁计划，以查看销毁的效果：

1
terraform plan -destroy

该命令会以 destroy 模式运行 terraform plan 命令，显示准备要销毁的变更，但不予执行。

注意：terraform apply 的 -destroy 选项仅存在于 Terraform v0.15.2 及更高版本中。对于早期版本，必须使用 terraform destroy 才能获得 terraform apply -destroy 的效果。

1.7.7.1. fmt

terraform fmt 命令被用来格式化 Terraform 代码文件的格式和规范。该命令会对代码文件应用我们之前介绍过的代码风格规范中的一些规定，另外会针对可读性对代码做些微调整。

其他具有生成Terraform代码文件功能的命令会按照terraform fmt的标准来生成代码，所以请在项目中遵循fmt的代码风格以保持代码风格的统一。

其他那些会生成 Terraform 代码的 Terraform 命令，生成的代码都会符合 terraform fmt 所强制推行的格式，因此对我们自己编写的文件使用该命令可以保持所有代码风格的一致。

Terraform 不同版本的代码风格规范会有些微不同，所以在升级 Terraform 后我们建议要对代码执行一次 terraform fmt。

我们不会将修改 terraform fmt 执行的格式规则视作是 Terraform 新版本的破坏性变更（意为，不同版本的 terraform fmt 可能会对代码做不同的格式化），但我们的目标是最大限度地减少对那些已符合 Terraform 文档中显示的样式示例的代码的更改。添加新的格式规则时，他们通常会按照文档中代码示例中展示的新规则来制定，因此我们建议遵循文档中的样式，即使这些文档中的样式尚未被 terraform fmt 强制执行。

格式化决定始终是主观的，因此您可能不同意 terraform fmt 做出的决定。该命令是被设计成固执己见的，并且没有自定义选项，因为它的主要目标是鼓励不同 Terraform 代码库之间风格的一致性，即使所选的风格永远不可能是每个人都喜欢的。

我们建议代码作者在编写 Terraform 模块时遵循 terraform fmt 应用的样式约定，但如果您发现结果特别令人反感，那么您可以选择不使用此命令，并可能选择使用第三方格式化工具。如果您选择使用第三方工具，那么您还应该在 Terraform 自动生成的文件上运行它，以获得手写文件和生成文件之间的一致性。

1.7.7.1.1. 用法

terraform fmt [options] [target...]

默认情况下，fmt 会扫描当前文件夹以寻找代码文件。如果 [target...] 参数指向一个目录，那么 fmt 会扫描该目录。如果 [target...] 参数是一个文件，那么 fmt 只会处理那个文件。如果 [target...] 参数是一个减号(-)，那么 fmt 命令会从标准输入中读取(STDIN)。

该命令支持以下参数：

  • -list=false：不列出包含不一致风格的文件

  • -write=false：不要重写输入文件(通过 -check 参数实现，或是使用标准输入流时)

  • -diff：展示格式差异

  • -check：检查输入是否合规。返回状态码 0 则代表所有输入的代码风格都是合规，反之则不是 0，并且会打印一份包含了文件内容不合规的文件名清单。

  • -recursive：是否递归处理所有子文件夹。默认情况下为 false(只有当前文件夹会被处理，不涉及内嵌子模块)

  • 1.7.8.1. force-unlock

  • 1.7.8.1.1. 用法

1.7.8.1. force-unlock

手动解除状态锁。

这个命令不会修改你的基础设施，它只会删除当前工作区对应的状态锁。具体操作步骤取决于使用的 Backend。本地状态文件无法被其他进程解锁。

1.7.8.1.1. 用法

terraform force-unlock [options] LOCK_ID

参数：

  • -force=true：解锁时不提示确认

需要注意的是，就像我们在状态管理篇当中介绍过的那样，每一个状态锁都有一个锁 ID。Terraform 为了确保我们解除正确的状态锁，所以会要求我们显式输入锁 ID。

一般情况下我们不需要强制解锁，只有在 Terraform 异常终止，来不及解除锁时需要我们手动强制解除锁。错误地解除状态锁可能会导致状态混乱，所以请小心使用。

1.7.9.1. get

terraform get 命令可以用来下载以及更新根模块中使用的模块。

1.7.9.1.1. 用法

terraform get [options]

模块被下载并安装在当前工作目录下 .terraform 子目录中。这个子目录不应该被提交至版本控制系统。

get 命令支持以下参数：

  • -update：如果指定，已经被下载的模块会被检查是否有新版本，如果存在新版本则会更新
  • -no-color：禁用输出中的文字颜色

graph

1.7.10.1. graph

terraform graph 命令可以用来生成代码描述的基础设施或是执行计划的可视化图形。它的输出是 DOT 格式)，可以使用 GraphViz 来生成图片，也有许多网络服务可以读取这种格式。

1.7.10.1.1. 用法

terraform graph [options]

默认情况下，该命令输出一个简化图，仅描述配置中资源（resource 和 data 块）的依赖顺序。

-type=... 参数可以在一组具有更多细节的其他图类型中进行选择，但作为代价，它也暴露了 Terraform 语言运行时的一些实现细节。

参数：

  • -plan=tfplan：针对指定计划文件生成图。使用该参数暗示着 -type=apply。
  • -draw-cycles：用彩色的边高亮图中的环，这可以帮助我们分析代码中的环错误(Terraform 禁止环状依赖)。该参数只有在通过 -type=... 参数指定了操作类型时有效。
  • -type=...：生成图表的类型，默认生成只包含 resource 的简化图。可以是：plan、plan-destroy 或是 apply。

1.7.10.1.2. 创建图片文件

terraform graph 命令输出的是 DOT 格式)的数据，可以轻松地使用 GraphViz 转换为图形文件：

1
$ terraform graph -type=plan | dot -Tpng >graph.png

输出的图片大概是这样的：

生成的依赖图

图 1.7.10/1 - 生成的依赖图

1.7.10.1.3. 如何安装GraphViz

安装GraphViz也很简单，对于Ubuntu：

1
$ sudo apt install graphviz

对于CentOS：

1
$ sudo dnf install graphviz

对于Windows，也可以使用choco：

1
> choco install graphviz

对于Mac用户：

1
$ brew install graphviz

1.7.11.1. import

terraform import 命令用来将已经存在的资源对象导入 Terraform。

我们并不总是那么幸运，能够在项目一开始就使用 Terraform 来构建和管理我们的基础设施；有时我们有一组已经运行着的基础设施资源，然后我们为它们编写了相应的 Terraform 代码，我们进行了测试，确认了这组代码描述的基础设施与当前正在使用的基础设施是等价的；但是我们仍然无法直接使用这套代码来管理现有的基础设施，因为我们缺乏了相应的状态文件。这时我们需要使用 terraform import 将资源对象“导入”到 Terraform 状态文件中去。

1.7.11.1.1. 用法

terraform import [options] ADDRESS ID

terraform import 会根据资源 ID 找到相应资源，并将其信息导入到状态文件中 ADDRESS 对应的资源上。ADDRESS 必须符合我们在资源地址中描述的合法资源地址格式，这样 terraform import 不但可以把资源导入到根模块中，也可以导入到子模块中。

ID 取决于被导入的资源对象的类型。举例来说，AWS 主机的 ID 格式类似于 i-abcd1234，而 AWS Route53 Zone 的 ID 类似于 Z12ABC4UGMOZ2N，请参考相关 Provider 文档来获取有关 ID 的详细信息。如果不确信的话，可以随便尝试任意 ID。如果 ID 不合法，你会看到一个错误信息。

警告，Terraform设想的是每一个资源对象都仅对应一个独一无二的实际基础设施对象，通常来说如果我们完全使用 Terraform 创建并管理基础设施时这一点不是问题；但如果你是通过导入的方式把基础设施对象导入到 Terraform 里，要绝对避免将同一个对象导入到两个以及更多不同的地址上，这会导致 Terraform 产生不可预测的行为。

该命令有以下参数可以使用：

  • -config=path：包含含有导入目标的Terraform代码的文件夹路径。默认为当前工作目录。如果当前目录不包含 Terraform 代码文件，则必须通过手动输入或环境变量来配置 Provider。
  • -input=true：是否允许提示输入 Provider 配置信息
  • -lock=false：如果 Backend 支持，是否锁定状态文件。在其他人可能会同时修改同一工作区的配置时关闭锁是危险的。
  • -lock-timeout=0s：重试尝试获取状态锁的间隔
  • -no-color：如果设定该参数，则不会输出彩色信息
  • -parallelism=n：限制 Terraform 遍历图的最大并行度，默认值为 10(又是考点)
  • -var 'foo=bar'：通过命令行设置输入变量值，类似 plan 命令中的介绍
  • -var-file=foo：类似 plan 命令中的介绍

当代码只使用了 local 类型的 Backend 时，terraform import 同时接受以下遗留参数：

  • -state=FILENAME：要读取的状态文件的地址
  • -state-out=FILENAME：指定修改后的状态文件的保存路径，如果我们设置了 -state 而没同时设置 -state-out，则 Terraform -state 的值写给 -state-out，这意味着 Terraform 如果创建新的状态快照，将直接写入源状态文件。
  • -backup=FILENAME：生成状态备份文件的地址，默认情况下是 -state-out 路径加上 .backup 后缀名。设置为 - 可以关闭备份(不推荐)

1.7.11.1.2. Provider配置

Terraform 会尝试读取要导入的资源对应的 Provider 的配置信息。如果找不到相关 Provider 的配置，那么 Terraform 会提示你输入相关的访问凭据。你也可以通过环境变量来配置访问凭据。

Terraform 在读取 Provider 配置时唯一的限制是不能依赖于"非输入变量"的输入。举例来说，Provider 配置不能依赖于数据源的输出。

举一个例子，如果你想要导入 AWS 资源而你有这样的一份代码文件，那么 Terraform 会使用这两个输入变量来配置 AWS Provider：

1
2
3
4
5
6
7
variable "access_key" {}
variable "secret_key" {}

provider "aws" {
  access_key = var.access_key
  secret_key = var.secret_key
}

1.7.11.1.3. 例子

1
$ terraform import aws_instance.foo i-abcd1234
1
$ terraform import module.foo.aws_instance.bar i-abcd1234
1
$ terraform import 'aws_instance.baz[0]' i-abcd1234
1
$ terraform import 'aws_instance.baz["example"]' i-abcd1234

上面这条命令如果是在PowerShell下：

1
$ terraform import 'aws_instance.baz[\"example\"]' i-abcd1234

如果是cmd：

1
$ terraform import aws_instance.baz[\"example\"] i-abcd1234

1.7.12.1. init

terraform init 命令被用来初始化一个包含 Terraform 代码的工作目录。在编写了一些 Terraform 代码或是克隆了一个 Terraform 项目后应首先执行该命令。反复执行该命令是安全的(考点)。

1.7.12.1.1. 用法

terraform init [options]

该命令为初始化工作目录执行了多个不同的步骤。详细说明可以见下文，总体来说用户不需要担心这些步骤。即使某些步骤可能会遭遇错误，但是该命令绝对不会删除你的基础设施资源或是状态文件。

1.7.12.1.2. 常用参数

  • -input=true：是否在取不到输入变量值时提示用户输入
  • -lock=false：是否在运行时锁定状态文件
  • -lock-timeout=<duration>：尝试获取状态文件锁时的超时时间，默认为 0s（0 秒），意为一旦发现锁已被其他进程获取立即报错
  • -no-color：禁止输出中包含颜色
  • -upgrade：是否升级模块代码以及插件

1.7.12.1.3. 从模块源拷贝模块

默认情况下，terraform init 会假设工作目录下已经包含了 Terraform 代码文件。

我们也可以在空文件夹内搭配 -from-module=MODULE-SOURCE 参数运行该命令，这样在运行任何其他初始化步骤之前，指定的模块将被复制到目标目录中。

这种特殊的使用方式有两种场景：

  • 我们可以用这种方法从模块源对应的版本控制系统当中签出指定版本代码并为它初始化工作目录
  • 如果模块源指向的是一个样例项目，那么这种方式可以把样例代码拷贝到本地目录以便我们后续基于样例编写新的代码

如果是常规使用时，建议使用版本控制系统自己的命令单独检查版本控制的配置。这样，可以在必要时将额外的标志传递给版本控制系统，并在运行 terraform init 之前执行其他准备步骤（例如代码生成或激活凭据）。

1.7.12.1.4. Backend 初始化

在执行 init 时，会分析根模块代码以寻找 Backend 配置，然后使用给定的配置设定初始化 Backend 存储。

在已经初始化 Backend 后重复执行 init 命令会更新工作目录以使用新的 Backend 设置。这时我们必须设置 -reconfigure 或是 -migrate-state 来升级 Backend 配置。

-migrate-state 选项会尝试将现有状态复制到新 Backend，并且根据更改的内容，可能会导致交互式提示以确认工作区状态的迁移。 设置 -force-copy 选项可以阻止这些提示并对迁移问题回答 yes。启用 -force-copy 还会自动启用 -migrate-state 选项。

-reconfigure 选项会忽略任何现有配置，从而防止迁移任何现有状态。

要跳过后端配置，请使用 -backend=false。请注意，其他一些初始化步骤需要初始化后端，因此建议仅当先前已为特定后端初始化工作目录时才使用此标志。

要跳过 Backend 配置，可以设置 -backend=false。注意某些其他 init 步骤需要已经被初始化的 Backend，所以推荐只在已经初始化过 Backend 后使用该参数。

-backend-config=... 参数可以用来动态指定 Backend 配置，我们在状态管理章节中介绍“部分配置”时已经提过，在此不再赘述。

1.7.12.1.5. 初始化子模块

init 会搜索代码中的 module 块，然后通过 source 参数取回引用的模块代码。

模块安装之后重新运行 init 命令会继续安装那些自从上次 init 之后新增的模块，但不会修改已被安装的模块。设置 -upgrade 可以改变这种行为，将所有模块升级到最新版本的代码。

要跳过子模块安装步骤，可以设置 -get=false 参数。要注意其他一些init步骤需要模块树完整，所以建议只在成功安装过模块以后使用该参数。

1.7.12.1.6. 插件安装

我们在 Provider 章节中介绍了插件安装，所以在此不再赘述，我们值介绍一下参数：

  • -upgrade：将之前所有已安装的插件升级到符合 version 约束的最新版本。
  • -plugin-dir=PATH：跳过插件安装，只从命令行配置文件的 filesystem_mirror 指定的目录加载插件。该参数会跳过用户插件目录以及所有当前工作目录下的插件。我们推荐使用命令行参数文件来全局设置 Terraform 安装方法，-plugin-dir 可以作为一次性的临时方法，例如测试当前本地正在开发的 Provider 插件。
  • -lockfile=MODE 设置依赖锁文件的模式 该参数的可选值有：
  • readonly：禁用锁定文件更改，但根据已记录的信息验证校验和。该参数与 -upgrade 参数冲突。如果我们使用第三方依赖项管理工具更新锁定文件，那么控制它何时显式更改将很有用。

1.7.12.1.7. 在自动化环境下运行 terraform init 命令

如果在团队的变更管理和部署流水线中 Terraform 扮演了关键角色，那么我们可能需要以某种自动化方式编排 Terraform 运行，以确保运行之间的一致性，并提供其他有趣的功能，例如与版本控制系统的钩子进行集成。

在此类环境中运行 init 时需要注意一些特殊问题，包括可选择在本地提供插件以避免重复重新安装。有关更多信息，请参阅 Terraform 与自动化。

1.7.12.1.8. 设置其他代码文件夹

Terraform v0.13 及更早版本还可以设置目录路径来代替 terraform apply 的计划文件参数，在这种情况下，Terraform 将使用该目录作为根模块而不是当前工作目录。

Terraform v0.14 中仍支持该用法，但现已在 Terraform v0.15 中弃用并删除。如果我们的工作流程依赖于覆盖根模块目录，请改用 -chdir 全局选项，该选项适用于所有命令，并使 Terraform 始终在给定目录中查找它通常在当前工作目录中读取或写入的所有文件。

如果您之前的工作流同时要求 Terraform 即使根模块目录已被修改也要将 .terraform 子目录写入当前工作目录，请使用 TF_DATA_DIR 环境变量命令 Terraform 将 .terraform 目录写入当前工作目录之外的其他位置。

1.7.13.1. output

terraform output 命令被用来提取状态文件中输出值的值。

1.7.13.1.1. 用法

terraform output [options] [NAME]

如果不添加参数，output 命令会展示根模块内定义的所有输出值。如果指定了 NAME，只会输出相关输出值。

可以使用以下参数：

  • -json：设置该参数后 Terraform 会使用 JSON 格式输出。如果指定了 NAME，只会输出相关输出值。该参数搭配 jq 使用可以构建复杂的流水线
  • -raw：设置该参数后 Terraform 会将指定的输出值转换为字符串，并将该字符串直接打印到输出中，不带任何特殊格式。这在使用 shell 脚本时很方便，但它仅支持字符串、数字和布尔值。处理复杂的数据类型时还请使用 -json。
  • -no-color：不输出颜色
  • -state=path：状态文件的路径，默认为 terraform.tfstate。启用远程 Backend 时该参数无效

注意：设置 -json 或 -raw 参数时，Terraform 状态中的任何敏感值都将以纯文本显示。有关详细信息，请参阅状态中的敏感数据。

1.7.13.1.2. 样例

假设有如下输出值代码：

1
2
3
4
5
6
7
8
9
10
11
12
output "instance_ips" {
  value = aws_instance.web.*.public_ip
}

output "lb_address" {
  value = aws_alb.web.public_dns
}

output "password" {
  sensitive = true
  value = var.secret_password
}

列出所有输出值：

1
2
3
4
5
6
7
8
$ terraform output
instance_ips = [
  "54.43.114.12",
  "52.122.13.4",
  "52.4.116.53"
]
lb_address = "my-app-alb-1657023003.us-east-1.elb.amazonaws.com"
password = <sensitive>

注意password输出值定义了sensitive = true，所以它的值在输出时会被隐藏：

1
2
$ terraform output password
password = <sensitive>

要查询负载均衡的DNS地址：

1
2
$ terraform output lb_address
my-app-alb-1657023003.us-east-1.elb.amazonaws.com

查询所有主机的IP：

1
2
3
4
5
6
$ terraform output instance_ips
test = [
    54.43.114.12,
    52.122.13.4,
    52.4.116.53
]

使用-json和jq查询指定主机的ip：

1
$ terraform output -json instance_ips | jq '.value[0]'

1.7.13.1.3. 在自动化环境下运行 terraform output 命令

terraform output 命令默认以便于人类阅读的格式显示，该格式可以随着时间的推移而改变以提高易读性。

对于脚本编写和自动化，请使用 -json 生成稳定的 JSON 格式。您可以使用 JSON 命令行解析器（例如 jq）解析输出：

1
2
$ terraform output -json instance_ips | jq -r '.[0]'
54.43.114.12

如果要在 shell 脚本中直接使用字符串值，可以转而使用 -raw 参数，它将直接打印字符串，没有额外的转义或空格。

1
2
$ terraform output -raw lb_address
my-app-alb-1657023003.us-east-1.elb.amazonaws.com

-raw 选项仅适用于 Terraform 可以自动转换为字符串的值。处理复杂类型的值（例如对象）时还请改用 -json（可以与 jq 结合使用）。

Terraform 字符串是 Unicode 字符序列而不是原始字节，因此 -raw 输出在包含非 ASCII 字符时将采用 UTF-8 编码。如果您需要不同的字符编码，请使用单独的命令（例如 iconv）对 Terraform 的输出进行转码。

1.7.14.1. plan

terraform plan 命令被用来创建变更计划。Terraform 会先运行一次 refresh(我们后面的章节会介绍，该行为也可以被显式关闭)，然后决定要执行哪些变更使得现有状态迁移到代码描述的期待状态。

该命令可以方便地审查状态迁移的所有细节而不会实际更改现有资源以及状态文件。例如，在将代码提交到版本控制系统前可以先执行 terraform plan，确认变更行为如同预期一般。

如果您直接在交互式终端中使用 Terraform 并且希望执行 Terraform 所提示的变更，您也可以直接运行 terraform apply。默认情况下，apply 命令会自动生成新计划并提示您批准它。

可选参数 -out 可以将变更计划保存在一个文件中，以便日后使用 terraform apply 命令来执行该计划。

在使用版本控制和代码审查工作流程对实际基础架构进行更改的团队中，开发人员可以使用保存下来的的计划文件来验证更改的效果，然后再对提交的变更进行代码审查。但是，要慎重考虑考虑对目标系统同时进行的其他更改可能会导致配置更改的最终效果与早期保存的计划所指示的不同，因此您应该始终重新检查最终的实际执行的计划，在执行之前确保它仍然符合您的意图。

如果 Terraform 检测不到任何变更，那么 terraform plan 会提示没有任何需要执行的变更。

1.7.14.1.1. 用法

terraform plan [options]

plan 命令在当前工作目录中查找根模块配置。

由于 plan 命令是 Terraform 的主要命令之一，因此它有多种不同的选项，如下部分所述。但是，大多数时候我们不需要设置这些选项，因为 Terraform 配置通常应设计为无需特殊的附加选项即可进行日常工作。

plan 命令的参数选项可以分为以下三大类

  • Plan 模式：当我们的目标不仅仅是更改远程系统以匹配代码配置时，我们可以在某些特殊情况下使用一些特殊的替代规划模式。
  • Plan 选项：除了特殊的 Plan 模式之外，我们还可以设置一些选项，以便根据特殊的需求来定制计划流程。
  • 其他选项：这些选项改变了规划命令本身的行为，而不是定制生成的计划的内容。

1.7.14.1.2. Plan 模式

上一节描述了 Terraform 的默认规划变更计划行为，该行为会变更远程系统以匹配我们对配置代码所做的更改。 Terraform 还有两种不同的规划模式，每种模式都会创建具有不同预期结果的计划。这些选项可用于 terraform plan 和 terraform apply。

  • Destroy 模式：创建一个计划，其目的是销毁当前存在的所有远程对象，留下空的 Terraform 状态。这与运行 terraform destroy 相同。销毁模式对于临时的开发环境等情况非常有用，在这种情况下，一旦开发任务完成，托管对象就不再需要保留。

    通过 -destroy 命令行选项启用销毁模式。

  • Refresh-Only 模式：创建一个计划，其目标仅是更新 Terraform 状态和所有根模块的输出值，以匹配对 Terraform 外部远程对象所做的更改。如果您使用 Terraform 之外的工具更改了一个或多个远程对象（例如，在响应事件时），并且您现在需要使 Terraform 的记录与这些更改保持一致，那么该命令会很有帮助。

    使用 -refresh-only 命令行选项启用 Refresh-Only 模式。

相对而言，我们把 Terraform 在未选择任何替代模式时使用的默认规划模式的情况下的行为称为“正常模式”。由于上述的替代模式仅适用于特殊情况，因此其他一些 Terraform 文档仅讨论正常规划模式。

Plan 模式都是互斥的，因此启用任何非默认 Plan 模式时都会禁用“正常”计划模式，并且我们不能同时使用多种替代模式。

注意：在 Terraform v0.15 及更早版本中，只有 terraform plan 命令支持 -destroy 选项，terraform apply 命令是不支持的。要在早期版本中以 Destroy 模式创建并应用计划，我们必须运行 terraform destroy。另外，-refresh-only 选项仅在 Terraform v0.15.4 及之后的版本中可用。

1.7.14.1.3. Plan 选项

相较于 Plan 模式，还有一些可以用来更改规划行为的参数选项。

  • -refresh=false：在检查配置更改之前跳过同步 Terraform 状态与远程对象的默认行为。这可以减少远程 API 请求的数量，加快规划操作的速度。但是，设置 refresh=false 会导致 Terraform 忽略外部更改，这可能会导致计划不完整或不正确。您不能在 Refresh Only 计划模式中使用 refresh=false，因为这将导致什么都不做。
  • -replace=ADDRESS - 命令 Terraform 在计划中替换给定地址的资源实例。当一个或多个远程对象降级时，这非常有用，并且我们可以替换成具有相同配置的对象来与不可变的基础架构模式保持一致。如果指定的资源在计划中存在“更新”操作或没有变化，则 Terraform 将使用“替换”操作。多次包含此选项可一次替换多个对象。您不能将 -replace 与 -destroy 选项一起使用，并且该功能仅从 Terraform v0.15.2 开始可用。对于早期版本，使用 terraform taint 来实现类似的结果。
  • -target=ADDRESS - 命令 Terraform 只计算给定地址匹配的资源实例以及这些实例所依赖的任何对象的变更。 注意：应该仅在特殊情况下使用 -target=ADDRESS，例如从错误中恢复或绕过 Terraform 限制。有关更多详细信息，请参阅资源定位。
  • -var 'NAME=VALUE' - 设置在配置的根模块中声明的单个输入变量的值。多次设置该选项可设置多个变量。有关详细信息，请参阅在命令行中输入变量。
  • -var-file=FILENAME - 使用 tfvars 文件中的定义为配置的根模块中声明的潜在多个输入变量设置值。多次设置该选项可包含多个文件中的值。

除了 -var 和 -var-file 选项之外，还有其他几种方法可以在根模块中设置输入变量的值。有关详细信息，请参阅为根模块输入变量赋值。

1.7.14.1.4. 在命令行中输入变量

我们可以使用 -var 命令行选项来指定根模块中声明的输入变量的值。

然而，要做到这一点，需要编写一个可由您选择的 shell 和 Terraform 解析的命令，对于涉及大量引号和转义序列的表达式来说这可能会很复杂。在大多数情况下，我们建议改用 -var-file 选项，并将实际值写入单独的文件中，以便 Terraform 可以直接解析它们，而不是解释 shell 解析后的结果。

警告：如果在等号之前或之后包含空格（例如 -var “length = 2”），Terraform 将报错。

要在 Linux 或 macOS 等系统上的 Unix 风格 shell 上使用 -var，我们建议将选项参数写在单引号 ' 中，以确保 shell 按字面解释该值：

1
terraform plan -var 'name=value'

如果我们的预期值还包含单引号，那么我们仍然需要对其进行转义，以便 shell 进行正确解释，这还需要暂时终止引号序列，以便反斜杠转义字符合法：

1
terraform plan -var 'name=va'\''lue'

在 Windows 上使用 Terraform 时，我们建议使用 Windows 命令提示符 (cmd.exe)。当您从 Windows 命令提示符将变量值传递给 Terraform 时，请在参数周围使用双引号 "：

1
terraform plan -var "name=value"

如果我们的预期值还包含双引号，那么您需要用反斜杠转义它们：

1
terraform plan -var "name=va\"lue"

Windows 上的 PowerShell 无法正确地将文字引号传递给外部程序，因此我们不建议您在 Windows 上时将 Terraform 与 PowerShell 结合使用。请改用 Windows 命令提示符。

根据变量的类型约束，声明变量值的语法有所不同。原始类型 string、number 和 bool 对应一个直接的字符串值，除非您的 shell 如上面的示例所示需要，否则不需要添加特殊的标点符号。对于所有其他类型约束，包括 list、map 和 set 类型以及特殊的 any 关键字，您必须编写一个表示该值的有效 Terraform 语言表达式，并附带必要的引用或转义字符以确保它将通过您的 shell 逐字传递到 Terraform。例如，对于 list(string) 类型约束：

1
2
3
4
5
# Unix-style shell
terraform plan -var 'name=["a", "b", "c"]'

# Windows Command Prompt (do not use PowerShell on Windows)
terraform plan -var "name=[\"a\", \"b\", \"c\"]"

使用环境变量设置输入变量时也适用类似的约束。有关设置根模块输入变量的各种方法的更多信息，请参阅为根模块变量赋值。

1.7.14.1.5. 资源定位

我们可以使用 -target 选项将 Terraform 的计算范围仅集中在少数资源上。我们可以使用资源地址语法来指定约束。Terraform 对代码中的资源地址的解释行为如下：

  • 如果给定地址定位了一个特定资源实例，Terraform 将单独选择该实例。对于设置了 count 或 for_each 的资源，资源实例地址必须包含实例索引部分，例如 azurerm_resource_group.example[0]。
  • 如果给定的地址对应到一个资源整体（即表达式中不含索引部分），Terraform 将选择该资源的所有实例。对于设置了 count 或 for_each 的资源，这意味着选择当前与该资源关联的所有实例索引。对于单实例资源（没有 count 或 for_each），资源地址和资源实例地址相同，因此这种可能性不适用。
  • 如果给定的地址标识整个 Module 实例，Terraform 将选择属于该 Module 实例及其所有子 Module 实例的所有资源的所有实例。

一旦 Terraform 选择了我们直接定位的一个或多个资源实例，它还会扩展选择范围以包括这些选择直接或间接依赖的所有其他对象。

这种资源定位功能是为某些特殊情况设计的，例如从故障中恢复或绕过 Terraform 的某些限制。不建议将 -target 用于常规操作，因为这可能会导致未检测到的配置漂移以及对资源真实状态与配置的关系的混淆。

与其使用 -target 作为对非常庞大的配置的一小部分子集进行操作的方法，不如将大型配置分解为多个较小的配置，每个配置都可以独立应用。数据源可用于访问有关在其他配置中创建的资源的信息，从而允许将复杂的系统架构分解为更易于管理且可以独立更新的部分。

1.7.14.1.6. 其他选项

terraform plan 命令还有一些与规划命令的输入和输出相关的其他选项，这些配置不会影响 Terraform 将创建哪种类型的计划。这些命令不一定在 terraform apply 上也可用，除非该命令的文档中另有说明。

  • -compact-warnings：如果 Terraform 生成了一些告警信息而没有伴随的错误信息，那么以只显示消息总结的精简形式展示告警

  • -detailed-exitcode：当命令退出时返回一个详细的返回码。如果有该参数，那么返回码将会包含更详细的含义：

  • 0 = 成功的空计划(没有变更)

  • 1 = 错误

  • 2 = 成功的非空计划(有变更)

  • -generate-config-out=PATH -（实验功能）如果配置中存在 import 块，则命令 Terraform 为尚未存在的任何导入资源生成 HCL。配置将写入 PATH 位置的新文件，该文件不可以存在，否则 Terraform 将报错。如果 plan 命令因为其他原因失败，Terraform 仍可能尝试写入配置。

  • -input=false：在取不到值的情况下是否提示用户给定输入变量值。此参数在非交互式自动化系统中运行 Terraform 时特别有用。

  • -lock=false：操作过程中不对状态文件上锁。如果其他人可能同一时间对同一工作区运行命令可能引发事故。

  • -lock-timeout=DURATION：除非使用 -lock=false 禁用锁定，否则指示 Terraform 在返回错误之前重试获取锁定一段时间。持续时间语法是一个数字后跟一个时间单位字母，例如 "3s" 表示三秒。

  • -no-color：关闭彩色输出。在无法解释输出色彩的终端中运行 Terraform 时请使用此参数。

  • -out=FILENAME：将变更计划保存到指定路径下的文件中，随后我们可以使用terraform apply执行该计划

    Terraform 将允许计划文件使用任何文件名，但典型的约定是将其命名为 tfplan。请不要使用 Terraform 支持的后缀名来命名文件；如果您使用 .tf 后缀，那么 Terraform 将尝试将该文件解释为配置源文件，这将导致后续命令出现语法错误。

  • -parallelism-n：限制Terraform遍历图的最大并行度，默认值为 10。

1.7.14.1.7. 指定其他配置文件目录

Terraform v0.13 及更早版本接受提供目录路径的附加位置参数，在这种情况下，Terraform 将使用该目录作为根模块而不是当前工作目录。

该用法在 Terraform v0.14 中已弃用，并在 Terraform v0.15 中删除。如果您的工作流程需要修改根模块目录，请改用 -chdir 全局选项，该选项适用于所有命令，并使 Terraform 始终在给定目录中查找它通常在当前工作目录中读取或写入的所有文件。

如果我们之前使用此遗留模式时同时需要 Terraform 将 .terraform 子目录写入当前工作目录，即使根模块目录已被覆盖，请使用 TF_DATA_DIR 环境变量命令 Terraform 将 .terraform 目录写入其他位置，而不是当前工作目录。

1.7.14.1.8. 安全警告

被保存的变更计划文件(使用 -out 参数)内部可能含有敏感信息，Terraform 本身并不会加密计划文件。如果你要移动或是保存该文件一段时间，强烈建议你自行加密该文件。

Terraform 未来打算增强计划文件的安全性。

1.7.15.1. providers

terraform providers 命令显示有关当前工作目录中代码的 Provider 声明的信息，以帮助我们了解每个被需要的 Provider 是从何而来。

该命令是含有内嵌子命令，这些子命令我们会逐个解释。

1.7.15.1.1. 用法

1
terraform providers

mirror

1.7.15.1.1. terraform providers mirror

该子命令从 Terraform 0.13 开始引入。

terraform providers mirror 命令下载当前代码所需要的 Provider 并且将其拷贝到本地文件系统的一个目录下。

一般情况下，terraform init 会在初始化当前工作目录时自动从 registry 下载所需的 Provider。有时 Terraform 工作在无法执行该操作的环境下，例如一个无法访问 registry 的局域网内。这时可以通过显式配置 Provider 安装方式来使得在这样的环境下 Terraform 可以从本地插件镜像存储中获取插件。

terraform providers mirror 命令可以自动填充准备用以作为本地插件镜像存储的目录。

1.7.15.1.1.1. 用法

terraform providers mirror [options] <target-dir>

target-dir 参数是必填的。Terraform 会自动在目标目录下建立起插件镜像存储所需的文件结构，填充包含插件文件的 .zip 文件。

Terraform同时会生成一些包含了合法的网络镜像协议响应的 .json 索引文件，如果我们把填充好的文件夹上传到一个静态站点，那就能够得到一个静态的网络插件镜像存储服务。Terraform 在使用本地文件镜像存储时会忽略这些镜像文件，因为使用本地文件镜像时文件夹本身的信息更加权威。

该命令支持如下可选参数：

  • -platform=OS_ARCH：选择构建镜像的目标平台。默认情况下，Terraform 会使用当前运行 Terraform 的平台。可以多次设置该参数以构建多目标平台插件镜像

    目标平台必须包含操作系统以及 CPU 架构。例如：linux_amd64 代表运行在 AMD64 或是 X86_64 CPU 之上的 Linux 操作系统。

我们可以针对已构建的镜像文件夹重新运行 terraform providers mirror 来添加新插件。例如，可以通过设置 -platform 参数来添加新目标平台的插件，Terraform 会下载新平台插件同时保留原先的插件，将二者合并存储，并更新索引文件。

schema

1.7.15.2.1. terraform providers schema

terraform providers schema 命令被用来打印当前代码使用的 Provider 的架构。Provider 架构包含了使用的所有 Provider 本身的参数信息，以及所提供的 resource、data 的架构信息。

1.7.15.2.1.1. 用法

terraform providers schema [options]

可选参数为：

  • -json：用机器可读的 JSON 格式打印架构

请注意，目前 -json 参数是必填的，未来该命令将允许使用其他参数。

输出包含一个 format_version 键，就拿 Terraform 1.1.0 来说，其值为 "1.0"。该版本的语义是：

  • 对于向后兼容的变更或新增字段，我们将增加 minor 版本号，例如 "1.1"。这种变更会忽略所有不认识的对象属性，以保持与未来其他 minor 版本的前向兼容。
  • 对于不向后兼容的变更，我们将增加 major 版本，例如 "2.0"。不同的 major 版本之间的数据无法直接传递。

我们只会在 Terraform 1.0 兼容性承诺的范围内更新 major 版本。

1.7.15.3.1. terraform providers lock

terraform providers lock 会查询上游 registry（默认情况下），以便将 Provider 的依赖项信息写入依赖项锁文件。

更新依赖项锁定文件的常见方法是由 terraform init 命令安装 Provider 时生成，但在某些情况下，这种自动生成的方法可能不够：

  • 如果您在使用其他 Provider 程序安装方法（例如文件系统或网络镜像）的环境中运行 Terraform，则常规的 Provider 安装程序将不会访问 Provider 程序在 Registry 上的源，因此 Terraform 将无法填充所有可能的包校验和选定的 Provider 版本。

    如果您使用 terraform lock 将 Provider 程序的官方版本校验和写入依赖项锁定文件中，则将来的 terraform init 运行将根据之前记录的官方校验和验证所选镜像中可用的软件包，从而进一步确保镜像返回的 Provider 程序的确是官方版本。

  • 如果您的团队在多个不同平台上运行 Terraform（例如在 Windows 和 Linux 上），并且 Provider 的上游 Registry 无法使用最新的哈希方案提供签名的校验和，则后续在其他平台上运行 Terraform 可能会添加额外的校验和锁定文件。您可以通过使用 terraform providers lock 命令为您打算使用的所有平台预先填充哈希值来避免这种情况。

terraform providers lock 仅在 Terraform v0.14 或更高版本中可用。

1.7.15.3.1.1. 用法

terraform providers lock [options] [providers...]

在没有额外的命令行参数的情况下，terraform providers lock 将分析当前工作目录中的代码，以查找它所依赖的所有 Provider 程序，并且将从其源 Registry 中获取有关这些 Provider 程序的关键数据，然后更新依赖项锁文件，写入所有选定的 Provider 程序版本以及 Provider 程序开发人员的私钥签名的包校验和。

警告：terraform providers lock 命令会打印有关其获取的内容以及每个包是否使用加密签名进行签名的信息，但它无法自动验证 Provider 提供者是否值得信赖以及它们是否符合您的本地系统策略或相关法规。在将更新的锁定文件提交到版本控制系统之前，请检查输出中的签名密钥信息，以确认您信任所有签名者。

如果您在命令行上列出一个或多个 Provider 程序源地址，则 terraform providers lock 将其工作仅限于这些提供程序，而其他提供程序（如果有的话）的锁定条目保持不变。

我们可以使用以下附加选项定制该命令的行为：

  • -fs-mirror=PATH - 命令 Terraform 在给定的本地文件系统镜像目录中查找提供程序包，而不是在上游注册表中。给定目录必须使用通常的文件系统镜像目录布局。

  • -net-mirror=URL - 命令 Terraform 在给定的网络镜像服务中查找提供程序包，而不是在上游注册表中。给定的 URL 必须实现 Terraform Provider 网络镜像协议。

  • -platform=OS_ARCH - 设置打算用于处理此 Terraform 配置的平台。Terraform 将确保 Provider 程序均可用于指定的平台，并将在锁文件中保存足够的包校验和以至少支持指定的平台。

    可以多次设置此选项以包含多个目标系统的校验和。

    目标平台名称由操作系统和 CPU 架构组成。例如，linux_amd64 选择在 AMD64 或 x86_64 CPU 上运行的 Linux 操作系统。

    我们将在后续节中讲述有关于此参数的更多详细信息。

  • -enable-plugin-cache - 启用全局配置的插件缓存的使用。这将加快锁定过程。默认情况下不启用此功能，因为插件缓存不是权威来源。由于 terraform providers lock 命令用于确保使用受信任的 Provider 程序版本，因此从缓存安装插件被认为是有风险的。

1.7.15.3.1.2. 指定目标平台

例如，在我们的团队中可能既有在 Windows 或 macOS 工作站上使用 Terraform 配置的开发人员，也有在 Linux 上运行 Terraform 配置的自动化系统。

在这种情况下，我们可以选择验证所有 Provider 程序是否支持所有这些平台，并通过运行 terraform providers lock 并指定这三个平台来预先填充锁文件所需的校验和：

1
2
3
4
terraform providers lock \
  -platform=windows_amd64 \ # 64-bit Windows
  -platform=darwin_amd64 \  # 64-bit macOS
  -platform=linux_amd64     # 64-bit Linux

（上面的示例使用 Unix 风格的 shell 包装语法来提高可读性。如果您在 Windows 上运行该命令，则需要将所有参数放在一行上，并删除反斜杠和注释。）

1.7.15.3.1.3. 内部 Providers 的锁条目

所谓内部 Provider 程序是还没有在真正的 Terraform Provider 注册表上发布的 Provider 程序，因为它仅在特定组织内开发和使用，并通过文件系统镜像或网络镜像进行分发。

默认情况下，terraform providers lock 命令假定所有 Provider 程序都是在 Terraform Provider 程序注册表中可用，并尝试联系源注册表以访问有关提供程序包的所有细节信息。

要为仅在本地镜像中可用的特定 Provider 程序创建锁定条目，可以使用 -fs-mirror 或 -net-mirror 命令行选项来覆盖查询 Provider 程序的原始注册表的默认行为：

1
2
3
4
5
6
terraform providers lock \
  -fs-mirror=/usr/local/terraform/providers
  -platform=windows_amd64 \
  -platform=darwin_amd64 \
  -platform=linux_amd64 \
  tf.example.com/ourcompany/ourplatform

（上面的示例使用 Unix 风格的 shell 包装语法来提高可读性。如果您在 Windows 上运行该命令，则需要将所有参数放在一行上，并删除反斜杠和注释。）

由于上面的命令包含 Provider 程序源地址 tf.example.com/ourcompany/ourplatform，因此 terraform providers lock 将仅尝试访问该特定 Provider 程序，并将保留所有其他 Provider 程序的锁条目不变。如果我们有来自不同来源的各种不同的 Provider 程序，可以多次运行 terraform providers lock 并每次指定不同的 Provider 程序子集。

-fs-mirror 和 -net-mirror 选项与 Provider 程序安装方法配置中的 filesystem_mirror 和 network_mirror 块具有相同的含义，但仅配置其中之一，以便明确您打算从何处派生包校验和信息。

请注意，只有原始注册表可以提供开发人员的原始加密签名所签署的官方校验和。因此，从文件系统或网络镜像创建的锁条目将仅覆盖您请求的确切平台，并且记录的校验和将是镜像报告的校验和，而不是原始注册表的官方校验和。如果要确保记录的校验和是由原始 Provider 发布者签名的校验和，请运行不带 -fs-mirror 或 -net-mirror 选项的此命令，以从原始注册表中获取所有信息。

如果您愿意，您可以通过内部 Provider 程序注册表发布您的内部 Provider 程序，然后该注册表将允许锁定和安装这些 Provider 程序，而无需任何特殊选项或额外的 CLI 配置。有关详细信息，请参阅 Provider 注册协议。