锁定和升级提供程序版本

11 分钟
|
Terraform

Terraform 提供程序通过与目标 API 通信来管理资源。每当目标 API 发生更改或添加功能时，提供程序维护者可能会更新和版本化提供程序。

当多个用户或自动化工具运行相同的 Terraform 配置时，它们应该都使用所需的相同版本的提供程序。您可以通过以下两种方式在配置中管理提供程序版本：

在配置的 terraform 块中指定提供程序版本约束。
使用依赖锁文件

如果您没有适当地限定提供程序版本，Terraform 将下载满足版本约束的最新提供程序版本。这可能会导致意外的基础设施更改。通过指定精细限定的提供程序版本并使用依赖锁文件，您可以确保 Terraform 正在使用正确的提供程序版本，以便您的配置得到一致的应用。

在本教程中，您将从已初始化的 Terraform 配置创建一个 S3 存储桶。然后，您将更新 Terraform 依赖锁文件以使用最新版本的 AWS 提供程序，并编辑 Terraform 配置以符合新提供程序版本的要求。

先决条件

您可以使用 Terraform Community Edition 或 HCP Terraform 以相同的流程完成本教程。HCP Terraform 是一个平台，可用于管理和执行您的 Terraform 项目。它包含远程状态和执行、结构化计划输出、工作区资源摘要等功能。

选择 HCP Terraform 标签页以使用 HCP Terraform 完成本教程。

本教程假设您熟悉 Terraform 工作流程。如果您是 Terraform 新手，请先完成入门教程。

为了完成本教程，您需要以下条件

本地安装的 Terraform v1.2+ 。
一个配置了本地凭证的AWS 账户，这些凭证已配置为与 Terraform 一起使用。

本教程假设您熟悉 Terraform 和 HCP Terraform 工作流。如果您是 Terraform 新手，请先完成入门教程。如果您是 HCP Terraform 新手，请先完成HCP Terraform 入门教程。

为了完成本教程，您需要以下条件

本地安装的 Terraform v1.2+ 。
一个AWS 账户。
一个HCP Terraform 账户，并已本地配置 HCP Terraform 身份验证。
一个已使用您的 AWS 凭证配置的 HCP Terraform 变量集。

克隆示例仓库

克隆 Learn Terraform Provider Versioning 仓库。

$ git clone https://github.com/hashicorp-education/learn-terraform-provider-versioning

在终端中导航到存储库目录。

$ cd learn-terraform-provider-versioning

检查配置

此目录是一个预先初始化的 Terraform 项目，包含三个文件：main.tf、terraform.tf 和 .terraform.lock.hcl。自此工作区首次初始化以来，HashiCorp 发布了较新版本的 AWS 提供程序。

探索 `main.tf`

打开 main.tf 文件。此文件使用 AWS 和 random 提供程序在 us-west-2 区域部署一个随机命名的 S3 存储桶。

main.tf

provider "aws" {
  region = "us-west-2"
}

resource "random_pet" "petname" {
  length    = 5
  separator = "-"
}

resource "aws_s3_bucket" "sample" {
  bucket = random_pet.petname.id

  tags = {
    public_bucket = false
  }
}

探索 `terraform.tf`

打开 terraform.tf 文件。您将在此处找到 terraform 块，它指定此配置所需的提供程序版本和所需的 Terraform 版本。

terraform.tf

terraform {
  /* Uncomment this block to use Terraform Cloud for this tutorial
  cloud {
    organization = "organization-name"
    workspaces {
      name = "learn-terraform-provider-versioning"
    }
  }
  */

  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "3.1.0"
    }

    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.5.0"
    }
  }

  required_version = "~> 1.2"
}

该 terraform 块包含 required_providers 块，它指定提供程序本地名称、源地址和版本。

初始化此配置时，Terraform 将下载

随机提供程序的版本 3.1.0。
AWS 提供程序的最新版本大于 4.5.0。 >= 版本约束运算符指定与配置兼容的最低提供程序版本。

Terraform 块还指定，只有 Terraform 二进制文件 v1.x（但高于 v1.2）才能使用 ~> 运算符运行此配置。

探索 `terraform.lock.hcl`

当您第一次使用 Terraform 1.1 或更高版本初始化 Terraform 配置时，Terraform 将在当前工作目录中生成一个新的 .terraform.lock.hcl 文件。您应该将锁定文件包含在您的版本控制存储库中，以确保 Terraform 在您的团队中以及在临时远程执行环境中，使用相同的提供程序版本。

打开 .terraform.lock.hcl 文件。

.terraform.lock.hcl

# This file is maintained automatically by "terraform init".
# Manual edits may be lost in future updates.

provider "registry.terraform.io/hashicorp/aws" {
  version     = "4.5.0"
  constraints = ">= 4.5.0"
  hashes = [
    "h1:PR5m6lcJZzSIYqfhnMd0YWTN+On2XGgfYV5AKIvOvBo=",
    "zh:0573de96ba316d808be9f8d6fc8e8e68e0e6b614ed4d707bd236c4f7b46ac8b1",
## ...
    "zh:f4722596e8b5f012013f87bf4d2b7d302c248a04a144de4563b3e3f754a30c51",
  ]
}

provider "registry.terraform.io/hashicorp/random" {
  version     = "3.1.0"
  constraints = "3.1.0"
  hashes = [
    "h1:9cCiLO/Cqr6IUvMDSApCkQItooiYNatZpEXmcu0nnng=",
    "zh:2bbb3339f0643b5daa07480ef4397bd23a79963cc364cdfbb4e86354cb7725bc",
## ...
    "zh:d9e13427a7d011dbd654e591b0337e6074eef8c3b9bb11b2e39eaaf257044fd7",
    "zh:f7605bd1437752114baf601bdf6931debe6dc6bfe3006eb7e9bb9080931dca8a",
  ]
}

请注意，在您的 terraform.tf 文件中指定了两个提供程序。AWS 提供程序版本是 v4.5.0。这满足了 >=4.5.0 约束，但不再是 AWS 提供程序的最新版本。随机提供程序设置为 v3.1.0 并满足其版本约束。

初始化并应用配置

初始化此配置。

$ terraform init

Initializing the backend...

Initializing provider plugins...
- Reusing previous version of hashicorp/aws from the dependency lock file
- Reusing previous version of hashicorp/random from the dependency lock file
- Installing hashicorp/aws v4.5.0...
- Installed hashicorp/aws v4.5.0 (signed by HashiCorp)
- Installing hashicorp/random v3.1.0...
- Installed hashicorp/random v3.1.0 (signed by HashiCorp)

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

打开您的 terraform.tf 文件并取消注释 cloud 块。将 organization 名称替换为您自己的 HCP Terraform 组织。

terraform.tf

terraform {
  cloud {
    organization = "organization-name"
    workspaces {
      name = "learn-terraform-provider-versioning"
    }
  }

  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "3.1.0"
    }

    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.5.0"
    }
  }

  required_version = "~> 1.2"
}

初始化您的配置。Terraform 将自动在您的 HCP Terraform 组织中创建 learn-terraform-provider-versioning 工作区。

$ terraform init

Initializing HCP Terraform...

Initializing provider plugins...
- Reusing previous version of hashicorp/aws from the dependency lock file
- Reusing previous version of hashicorp/random from the dependency lock file
- Installing hashicorp/aws v4.5.0...
- Installed hashicorp/aws v4.5.0 (signed by HashiCorp)
- Installing hashicorp/random v3.1.0...
- Installed hashicorp/random v3.1.0 (signed by HashiCorp)

HCP Terraform has been successfully initialized!

You may now begin working with HCP Terraform. Try running "terraform plan" to
see any changes that are required for your infrastructure.

If you ever set or change modules or Terraform Settings, run "terraform init"
again to reinitialize your working directory.

注意

本教程假定您使用的是特定于教程的 HCP Terraform 组织，并已设置您的 AWS 凭据的全局变量。请参阅创建凭据变量集以获取详细指南。如果您使用的是作用域变量集，请立即将其分配给您的新工作区。

请注意，Terraform 没有安装符合配置版本约束的最新版本的 AWS 提供程序，而是安装了锁定文件中指定的版本。在初始化您的工作区时，Terraform 读取了依赖项锁定文件，并下载了 AWS 和随机提供程序的指定版本。

如果 Terraform 没有找到锁定文件，它将下载满足您在 required_providers 块中定义的版本约束的最新版本的提供程序。下表显示了在这种情况下 Terraform 将根据版本约束和锁定文件的存在情况下载哪个提供程序。

提供商	版本约束	`terraform init`（没有锁定文件）	`terraform init`（锁定文件）
aws	>= 4.5.0	最新版本（例如 5.55.0）	锁定文件版本（4.5.0）
random	3.1.0	3.1.0	锁定文件版本（3.1.0）

锁定文件指示 Terraform 始终安装相同的提供程序版本，从而确保在您的团队或远程会话中进行一致的运行。

应用您的配置。使用 yes 回应确认提示，以创建示例基础设施。

$ terraform apply

Terraform used the selected providers to generate the following execution plan.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # aws_s3_bucket.sample will be created
  + resource "aws_s3_bucket" "sample" {
      + acceleration_status                  = (known after apply)

## ...

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

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

## ...

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

升级 AWS 提供程序版本

-upgrade 标志将升级所有提供程序到与配置中指定的版本约束一致的最新版本。

升级 AWS 提供程序。

注意

你不应该直接修改锁定文件。

$ terraform init -upgrade

Initializing HCP Terraform...

Initializing provider plugins...
- Finding hashicorp/aws versions matching ">= 4.5.0"...
- Finding hashicorp/random versions matching "3.1.0"...
- Installing hashicorp/aws v5.56.1...
- Installed hashicorp/aws v5.56.1 (signed by HashiCorp)
- Using previously-installed hashicorp/random v3.1.0

Terraform has made some changes to the provider dependency selections recorded
in the .terraform.lock.hcl file. Review those changes and commit them to your
version control system if they represent changes you intended to make.

Terraform has been successfully initialized!

## ...

请注意，Terraform 会安装 AWS 提供程序的最新版本。

打开 .terraform.lock.hcl 文件，并注意 AWS 提供程序的版本现在是最新版本。

.terraform.lock.hcl

provider "registry.terraform.io/hashicorp/aws" {
  version     = "5.56.1"
  constraints = ">= 4.5.0"
  ## ...
}

提示

您也可以使用 -upgrade 标志来降级提供程序版本，如果版本约束被修改为指定低于锁定文件中指定版本的提供程序版本。

规划您的配置，以确保其与升级后的提供程序兼容。

$ terraform plan
random_pet.petname: Refreshing state... [id=gratefully-radically-quickly-fitting-troll]
aws_s3_bucket.sample: Refreshing state... [id=gratefully-radically-quickly-fitting-troll]

No changes. Your infrastructure matches the configuration.

Terraform has compared your real infrastructure against your configuration and
found no differences, so no changes are needed.

提示

有时，提供程序升级需要您修改配置才能使其与新的提供程序版本一起工作。例如，属性名称或要求可能会从一个主要的提供程序版本更改到另一个主要版本。在更改提供程序版本后，始终运行 Terraform plan。

如果计划步骤成功完成，则可以安全地将包含更新后的锁定文件的配置提交到版本控制。如果计划或应用步骤失败，请不要在解决错误之前将锁定文件提交到版本控制。

清理基础设施

在验证资源已成功部署后，请销毁它们。请使用 yes 回复确认提示。

$ terraform destroy
## ...
Terraform used the selected providers to generate the following execution plan.
Resource actions are indicated with the following symbols:
  - destroy

Terraform will perform the following actions:

  # aws_s3_bucket.sample will be destroyed
  - resource "aws_s3_bucket" "sample" {

## ...

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

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes

## ...

Destroy complete! Resources: 2 destroyed.

如果您在此教程中使用 HCP Terraform，则在销毁资源后，请从您的 HCP Terraform 组织中删除 learn-terraform-provider-versioning 工作区。

下一步

在本教程中，您使用了依赖锁文件来管理提供程序版本，并升级了锁文件。

要了解有关提供程序的更多信息，请访问以下资源。

依赖锁文件文档
提供程序版本约束文档
使用 Terraform 提供程序调用 API教程将指导您了解提供程序如何作为 Terraform 和目标 API 之间的桥梁，并展示如何构建自定义 Terraform 提供程序。

Terraform 版本

目标资源

本教程还出现在

21 个教程

编写 Terraform 配置
通过示例学习 Terraform 配置语言。编写配置以管理多个基础设施组件，并迭代结构化数据。通过引用其他配置中的资源来部署和管理相关的基础设施。
- Terraform
6 个教程

HashiConf Announcements - Terraform 1.0
尝试在 HashiConf 上听到的功能，包括 CDKTF Golang 支持以及 HCP Terraform 私有注册表。版本 Terraform、状态、提供程序和 HCP Terraform。
- Terraform
2 个教程

Terraform 0.14 教程
试用 Terraform 0.14 中的新功能。将变量标记为敏感信息，以保护您的敏感数据免受意外暴露。使用依赖锁定文件来管理您的提供程序版本。
- Terraform