自定义Terraform-Providers(使用提供程序执行CRUD操作)-01

一 前言

在本教程中，您将使用Terraform提供程序与一个名为HashiCups的虚构咖啡店应用程序进行交互。在这个过程中，您将了解提供程序如何将目标API映射到Terraform，以便创建、读取、更新和删除资源。
稍后，您将基于Terraform Plugin SDK V2重新创建本教程中讨论的HashiCups提供程序。

二 Terraform Plugins

Terraform由Terraform核心和Terraform插件组成。

• Terraform核心读取配置并构建资源依赖关系图。
• Terraform插件（提供者和提供者）连接Terraform核心和它们各自的目标API。Terraform提供程序插件通过基本的CRUD（创建、读取、更新和删除）API实现资源，以与第三方服务通信。

注意：我们建议Terraform插件使用外部API客户机库，如上图所示。如果一个不存在，你应该创建一个。这与保持软件项目模块化的现代编码实践相一致。

在terraform计划或terraform应用时，terraform核心要求terraform提供者通过RPC接口执行操作。提供者试图通过对目标API的客户端库调用CRUD操作来实现请求。这一进程强制明确分离关注事项。提供程序可以作为客户端库的抽象。

虽然大多数Terraform提供商管理云基础设施（例如AWS、Azure和GCP提供商），但提供商可以作为任何API的接口，并允许Terraform潜在地管理任何资源。

三 HashiCups项目简介

HashiCups是一个演示应用程序，允许您查看和订购定制的HashiCorp品牌咖啡。
该API有许多未受保护的端点和受保护的端点。您可以列出特定咖啡的所有咖啡和成分，而无需验证。经过身份验证后，您可以创建、读取、更新和删除(CRUD)订单。
Terraform HashiCups提供程序通过GoLang客户机库与产品的REST API接口。这允许您通过Terraform管理HashiCups订单。

四 项目启动

4.1 预置条件

• 本地安装的Terraform 0.14+CLI。
• Docker和Docker组合在本地运行HashiCups实例。

它还假设您熟悉通常的Terraform计划/应用工作流。如果您是Terraform本身的新手，请先参考入门部分。

4.2 启动项目

它还假设您熟悉通常的Terraform计划/应用工作流。如果您是Terraform本身的新手，请先参考入门部分。

git clone https://github.com/hashicorp/learn-terraform-hashicups-provider && cd learn-terraform-hashicups-provider

导航到docker_compose目录并运行docker compose up以在端口19090上旋转HashiCups的本地实例。

cd docker_compose && docker compose up

让此进程在终端窗口中运行。这将包含HashiCups的日志消息。
在另一个终端窗口中，通过向HashiCups的健康检查端点发送请求来验证HashiCups是否正在运行。

curl localhost:19090/health

五 安装HashiCups provider

对于Terraform 0.13+，必须在Terraform配置中指定所有必需的提供程序及其各自的源。提供程序源字符串由[hostname]/[namespace]/[name]组成。

• 对于Terraform注册表中hashicorp命名空间中的提供程序来说，主机名和命名空间都是可选的。
• 如果省略主机名，Terraform将使用Terraform注册表主机名作为默认主机名。
• 在设置主机名时，总是需要命名空间。

对于第三方Terraform提供程序，可以为主机名和命名空间选择任意标识符（由字母和连字符组成）。

运行terraform init时，terraform将尝试从terraform注册表下载提供程序。

如果Terraform无法从Terraform注册表下载提供程序（例如，如果提供程序是本地的，或者由于防火墙限制），您可以显式指定安装方法配置。否则，Terraform将隐式地尝试在用户插件目录中的适当子目录中本地查找提供程序，~/.Terraform.d/plugins/${host_name}/${namespace}/${type}/​${version}/​${target}或%appdata%\Terraform.d\plugins${host_name}/​${namespace}/​${type}/​${version}/${target}。

为了使用未发布到注册表的任何第三方提供程序，您必须下载二进制文件，然后将其移动到用户插件目录中的适当子目录中。因为HashiCups是一个主要用于演示和教育的第三方提供商，所以您可以这样做。HashiCups提供程序的提供程序源字符串将是hashiCorp.com/edu/HashiCups。

首先，下载HashiCups提供程序二进制文件。因为提供程序是Go二进制文件，所以您可以下载预编译的二进制文件或直接从源代码构建它。从源头构建需要一些Go经验。

由于测试本地为Mac系统，使用Mac 二进制版本下载

下载与您的系统相匹配的HashiCups provider V0.3.1二进制文件。可以在Terraform HashiCups Provider发布页面上找到完整的二进制文件列表。将文件重命名为terraform-provider-hashicups。

# 下载macOS的HashiCups提供程序。
curl -LO https://github.com/hashicorp/terraform-provider-hashicups/releases/download/v0.3.1/terraform-provider-hashicups_0.3.1_darwin_amd64.zip
 
# 在用户插件目录中为HashiCups提供程序创建适当的子目录。
mkdir -p ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.3.1/darwin_amd64

# 然后，将下载的二进制文件解压缩到适当的用户插件目录中。
unzip terraform-provider-hashicups_0.3.1_darwin_amd64.zip -d ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.3.1/darwin_amd64

# 最后，使二进制文件可执行。
chmod +x ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.3.1/darwin_amd64/terraform-provider-hashicups_v0.3.1

现在提供程序位于用户插件目录中，您可以在Terraform配置中使用提供程序。

六 创建一个HashiCups user

HashiCups需要用户名和密码来生成JSON web令牌(JWT)，该令牌用于根据受保护的端点进行身份验证。您将使用此用户向HashiCups提供程序进行身份验证，以管理您的订单。
在HashiCups上创建一个名为education的用户，密码为test123。

$ curl -X POST localhost:19090/signup -d '{"username":"education", "password":"test123"}'
{"UserID":1,"Username":"education","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NTQ3NDE1NzYsInVzZXJfaWQiOjEsInVzZXJuYW1lIjoiZWR1Y2F0aW9uIn0.Z2IevoCXshPoDr5sgBWpuxJC8ISCSNNVWN8z9D5unVE"}

然后，对HashiCups进行身份验证。这将返回用户ID、用户名和一个JSON Web令牌(JWT)授权令牌。稍后将使用JWT授权令牌检索订单。

curl -X POST localhost:19090/signin -d '{"username":"education", "password":"test123"}'
{"UserID":1,"Username":"education","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NTQ3NDE2NDgsInVzZXJfaWQiOjEsInVzZXJuYW1lIjoiZWR1Y2F0aW9uIn0.occs9DyYZalDM39llYLzV1pyVKFl1R6FUwRlAv3mMhc"}

将HASHICUPS_TOKEN环境变量设置为从调用/signin端点中检索的令牌。您将在本教程的后面使用该命令来验证您的HashiCups订单是否已创建、更新和删除。

export HASHICUPS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NTQ3NDE2NDgsInVzZXJfaWQiOjEsInVzZXJuYW1lIjoiZWR1Y2F0aW9uIn0.occs9DyYZalDM39llYLzV1pyVKFl1R6FUwRlAv3mMhc

包含HashiCups日志的终端将记录这两个操作。

既然HashiCups应用程序已经运行，您就可以使用Terraform提供程序与它进行交互了。

七 初始化工作区

将以下内容添加到main.tf文件中。这是Terraform 0.13+所必需的。

terraform {
  required_providers {
    hashicups = {
      version = "~> 0.3.1"
      source  = "hashicorp.com/edu/hashicups"
    }
  }
}

由于HashiCups是第三方提供程序，所以源字符串中的主机名和命名空间值是任意的。有关提供程序源的详细信息，请参阅提供程序源文档。

然后，初始化您的Terraform工作区。如果您的Hashicups提供程序位于正确的目录中，它应该会成功初始化。否则，请将HashiCups提供程序移动到正确的目录:~/.terraform.d/plugins/${name}/${version}/${os}_​${arch}。

terraform init

八 创建订单

8.1 执行创建订单

将以下内容添加到main.tf文件中。
这将对HashiCups提供程序进行身份验证，创建订单并将订单详细信息作为Terraform输出值返回。该订单总共包含4个咖啡：每个coffee_id2个，3个和2个。

provider "hashicups" {
  username = "education"
  password = "test123"
}

resource "hashicups_order" "edu" {
  items {
    coffee {
      id = 3
    }
    quantity = 2
  }
  items {
    coffee {
      id = 2
    }
    quantity = 2
  }
}

output "edu_order" {
  value = hashicups_order.edu
}

运行terraform apply创建订单。请注意执行计划如何显示建议的订单，以及关于该订单的附加信息。用是确认应用步骤。

一旦apply完成，提供程序将保存资源的状态。如果在本地运行Terraform，则Terraform.tfstate文件包含此状态。还可以通过运行terraform state show<resource_name>查看状态。

在terraform apply步骤期间，执行计划中的（apply后已知的）值都已填充，因为订单已成功创建。

8.2 校验订单

当您使用Terraform在HashiCups中创建订单时，包含HashiCups日志的终端将记录由HashiCups提供程序调用的操作。

docker-compose logs

提供程序总共调用了4个操作。

1. 当您运行terraform apply以检索资源的当前状态时，提供程序调用了第一个signin操作。因为没有资源，它只对用户进行了身份验证。
2. 在您确认apply运行之后，提供程序调用了第二个signin操作。提供程序使用提供的凭据进行身份验证，以检索和保存JWT令牌。
3. 提供程序调用CreateOrder操作来创建由Terraform配置定义的订单。因为这是一个受保护的端点，所以它使用signin操作中保存的JWT令牌。
4. 创建订单后，提供程序调用GetUserOrder操作来检索订单详细信息。因为这是一个受保护的端点，所以它使用signin操作中保存的JWT令牌。

通过API检索订单详细信息来验证订单是否已创建。

curl -X GET  -H "Authorization: ${HASHICUPS_TOKEN}" localhost:19090/orders/1
{"id":1,"items":[{"coffee":{"id":3,"name":"Nomadicano","teaser":"Drink one today and you will want to schedule another","description":"","price":150,"image":"/nomad.png","ingredients":null},"quantity":2},{"coffee":{"id":2,"name":"Vaulatte","teaser":"Nothing gives you a safe and secure feeling like a Vaulatte","description":"","price":200,"image":"/vault.png","ingredients":null},"quantity":2}]}

九 查询信息

向main.tf文件添加一个数据块和一个输出块。这将从您的订单中检索第一杯咖啡的配料。数据块检索有关资源的附加信息，这使另一个Terraform资源可以引用该资源。在本例中，输出块使用它来显示咖啡成分。

data "hashicups_ingredients" "first_coffee" {
  coffee_id = hashicups_order.edu.items[0].coffee[0].id
}

output "first_coffee_ingredients" {
  value = data.hashicups_ingredients.first_coffee
}

在提供者协调状态（前三个操作）之后，它销毁订单。
通过API检索订单详细信息，验证订单已删除。

参考链接

• https://learn.hashicorp.com/collections/terraform/providers