「Provider 开发实战」

# Provider 是独立进程，Core 通过 go-plugin 启动它并建立 gRPC 通道
ps aux | grep terraform-provider

// 协议 6 使用 proto3，通过 tfprotov6 接口暴露
// Core 与 Provider 之间不共享内存，只有 RPC

# 从官方模板生成脚手架
git clone https://github.com/hashicorp/terraform-provider-scaffolding-framework
cd terraform-provider-scaffolding-framework
make build    # 生成 terraform-provider-<name> 二进制
make install  # 安装到 ~/.terraform.d/plugins

func main() {
	var debug bool
	flag.BoolVar(&debug, "debug", false, "set to true to run with delve")
	flag.Parse()

	opts := providerserver.ServeOpts{
		Address: "registry.terraform.io/example/example",
		Debug:   debug,
	}

	err := providerserver.Serve(context.Background(), New, opts)
	if err != nil {
		log.Fatal(err.Error())
	}
}

# ~/.terraformrc
provider_installation {
  dev_overrides {
    "example/example" = "/Users/me/go/bin"
  }
  direct {}
}

# 覆盖生效后无需 terraform init，直接 plan
terraform plan
# 会打印警告：跳过 init，使用开发版本

func (r *WidgetResource) Schema(
	ctx context.Context,
	req resource.SchemaRequest,
	resp *resource.SchemaResponse,
) {
	resp.Schema = schema.Schema{
		MarkdownDescription: "管理一个示例 Widget 资源",
		Attributes: map[string]schema.Attribute{
			"id": schema.StringAttribute{
				Computed:            true,
				MarkdownDescription: "资源唯一标识",
			},
			"name": schema.StringAttribute{
				Required:            true,
				MarkdownDescription: "Widget 名称",
			},
			"size": schema.Int64Attribute{
				Optional:            true,
				Computed:            true,
				Default:             int64default.StaticInt64(1),
				MarkdownDescription: "规格大小",
			},
			"api_token": schema.StringAttribute{
				Optional:  true,
				Sensitive: true,
			},
		},
	}
}

type WidgetResource struct {
	client *client.Client
}

type WidgetResourceModel struct {
	ID       types.String `tfsdk:"id"`
	Name     types.String `tfsdk:"name"`
	Size     types.Int64  `tfsdk:"size"`
	APIToken types.String `tfsdk:"api_token"`
}

func (r *WidgetResource) Create(
	ctx context.Context,
	req resource.CreateRequest,
	resp *resource.CreateResponse,
) {
	var plan WidgetResourceModel
	resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
	if resp.Diagnostics.HasError() {
		return
	}

	w, err := r.client.CreateWidget(plan.Name.ValueString(), plan.Size.ValueInt64())
	if err != nil {
		resp.Diagnostics.AddError("创建 Widget 失败", err.Error())
		return
	}

	plan.ID = types.StringValue(w.ID)
	resp.Diagnostics.Append(resp.State.Set(ctx, &plan)...)
}

// Read：从 API 读回真实属性，写回 state
w, err := r.client.GetWidget(state.ID.ValueString())
if errors.Is(err, client.ErrNotFound) {
	// 资源已被外部删除：从 state 移除，下次 plan 会重新创建
	resp.State.RemoveResource(ctx)
	return
}
// 属性映射与 Create 类似，此处省略

func (d *WidgetDataSource) Read(
	ctx context.Context, req datasource.ReadRequest, resp *datasource.ReadResponse,
) {
	var config WidgetDataSourceModel
	resp.Diagnostics.Append(req.Config.Get(ctx, &config)...)

	w, err := d.client.GetWidgetByName(config.Name.ValueString())
	if err != nil {
		resp.Diagnostics.AddError("查询 Widget 失败", err.Error())
		return
	}

	config.ID = types.StringValue(w.ID)
	resp.Diagnostics.Append(resp.State.Set(ctx, &config)...)
}

func (r *WidgetResource) ImportState(
	ctx context.Context,
	req resource.ImportStateRequest,
	resp *resource.ImportStateResponse,
) {
	resource.ImportStatePassthroughID(ctx, path.Root("id"), req, resp)
}

# 用户侧使用
import {
  to = example_widget.legacy
  id = "widget-12345"
}

func (r *WidgetResource) UpgradeState(
	ctx context.Context,
) map[int64]resource.StateUpgrader {
	return map[int64]resource.StateUpgrader{
		0: { // 从 schema 版本 0 升级到 1
			PriorSchema: &schema.Schema{ /* 旧 schema */ },
			StateUpgrader: func(
				ctx context.Context,
				req resource.UpgradeStateRequest,
				resp *resource.UpgradeStateResponse,
			) {
				// 把旧字段 disk_size 迁移到新字段 size
				var prior struct {
					DiskSize types.Int64 `tfsdk:"disk_size"`
				}
				resp.Diagnostics.Append(req.State.Get(ctx, &prior)...)
				resp.Diagnostics.Append(resp.State.SetAttribute(
					ctx, path.Root("size"), prior.DiskSize)...)
			},
		},
	}
}

func TestAccWidgetResource_basic(t *testing.T) {
	resource.Test(t, resource.TestCase{
		PreCheck:                 func() { testAccPreCheck(t) },
		ProtoV6ProviderFactories: testAccProtoV6ProviderFactories,
		CheckDestroy:             testAccCheckWidgetDestroy,
		Steps: []resource.TestStep{
			{
				Config: testAccWidgetConfig("demo"),
				Check: resource.ComposeAggregateTestCheckFunc(
					resource.TestCheckResourceAttrSet("example_widget.test", "id"),
					resource.TestCheckResourceAttr("example_widget.test", "name", "demo"),
					resource.TestCheckResourceAttr("example_widget.test", "size", "1"),
				),
			},
			{
				// 验证导入：导入后配置与状态一致
				ResourceName:      "example_widget.test",
				ImportState:       true,
				ImportStateVerify: true,
			},
		},
	})
}

# 必须显式开启，否则测试被跳过（避免误建真实资源）
export TF_ACC=1
export EXAMPLE_API_TOKEN=xxx
go test ./internal/provider/ -run TestAcc -v -timeout 30m

# 生成文档，确保 schema 与文档同步
go generate ./...
tfplugindocs generate

# .goreleaser.yml 片段：交叉编译多平台二进制
builds:
  - env: [CGO_ENABLED=0]
    goos: [windows, linux, darwin]
    goarch: [amd64, arm64]

git tag v0.3.0 && git push origin v0.3.0   # 触发发布流水线
goreleaser release --clean                 # 产出签名清单，Registry 据此分发

# 用户侧用约束表达可接受的升级范围
terraform {
  required_providers {
    example = {
      source  = "example/example"
      version = "~> 1.3"
    }
  }
}