provider-configuration

用途

本技能面向 Terraform Provider 开发者，讲解如何实现 Provider 的配置与认证逻辑，即 Provider 如何接收连接设置并解析凭据。资料指出，认证体验是每个 Provider 用户最先接触的部分，设计良好的凭据提供者链是生产级 Provider 与演示级 Provider 的分水岭。示例使用虚构的 examplecloud provider 和 Plugin Framework。

认证属性的 Schema 设计

每个认证属性都必须是 Optional，绝不能是 Required——Required 会迫使用户把凭据写进配置，使环境变量和凭据文件解析无法实现。密钥字段要标记 Sensitive，以便 Terraform 在 plan 输出中脱敏。每个属性的描述中要写明环境变量回退方式，让 tfplugindocs 发布解析规则。

示例 Schema 包含 endpoint、api_key、api_secret（Sensitive）、profile、skip_credentials_validation 等属性，均为 Optional。资料强调：绝不要给凭据属性添加 Default，也绝不要在 Provider 中硬编码凭据；默认值应放在解析逻辑中，而非 Schema 中。

凭据提供者链

凭据解析按有序来源列表进行，取第一个能产生完整凭据集的来源。规范优先级从高到低为：

静态配置——Provider 块中直接设置的值，显式设置总是优先。
环境变量——如 EXAMPLECLOUD_API_KEY，适合 CI。
共享凭据文件——~/.examplecloud/credentials 中的命名 profile，适合多账号用户。
平台身份——实例元数据、工作负载身份或 OIDC 令牌交换，无需存储凭据。

两条规则保证链的可预测性：密钥作为整体解析，而非逐字段解析（若环境变量只提供 key 而无 secret，则该来源不提供任何内容，整体落到下一来源）；非密钥连接设置则逐字段解析（endpoint、profile、insecure 可各自独立遵循 config > env > file > default）。

核心抽象是单方法接口加哨兵错误：ErrNoCredentials 表示“该来源无内容可提供”（继续下落），其他错误表示“该来源已配置但不可用”（保留并最终呈现）。Credentials 结构体含 APIKey、APISecret、Source 字段及 Complete() 方法。Chain 本身也是 Provider，可组合，按顺序遍历并返回第一个完整凭据集，同时把跳过的来源记录进聚合的 ChainError。完整实现见 references/credential-chain.md。

将链接入 Configure

Configure 每次 Terraform 操作运行一次，在任何资源 CRUD 之前。步骤包括：

未知值守卫——planning 阶段，引用其他资源输出的属性是 unknown 而非 null，若不守卫，Provider 会静默当作空值、穿过链、以错误身份认证或报出误导性的“缺少凭据”错误。守卫消息中要给出环境变量变通方案。
通过链解析凭据——用哨兵检查区分“你什么都没给”（列出可操作选项）与“你给的东西坏了”（显示解析错误）。
构建客户端一次，与所有资源与数据源共享。

资料强调：记录来源，绝不记录密钥。

面向用户的诊断

认证错误消息是 Provider 被阅读最多的文档。每个凭据失败诊断都应写明：按顺序尝试的每个来源及跳过原因（ChainError 提供）；查询过的确切环境变量名、凭据文件路径与 profile；Provider 认证指南的文档 URL。对可疑但非致命的情况使用警告而非错误，并说明什么优先。

密钥卫生

为 Credentials 类型提供 String() 和 GoString() 方法以脱敏密钥字段，防止 %v、%+v 或错误包装泄露密钥。绝不在诊断、日志行或包装错误中包含凭据值。当凭据文件可被其他用户读取时发出警告（Windows 上跳过此检查）。

配置期校验

在 Configure 中及早解析链，绝不要延迟到首次资源使用，这样凭据问题只在 plan 时失败一次并给出好消息。若 API 有廉价的身份端点，在解析凭据后调用它，使无效凭据也在配置期失败；用 skip_credentials_validation 属性为隔离或打桩环境提供开关。

单元测试

链是纯逻辑，用单元测试（Test 前缀，无 TF_ACC）而非验收测试。让环境可注入，把文件提供者指向 t.TempDir() 夹具。关键测试包括：每个来源的行为、优先级、失败聚合、硬错误、脱敏。完整测试示例见 references/credential-chain.md。

检查清单

资料提供了一份检查清单，涵盖：所有认证属性 Optional、密钥标记 Sensitive；属性描述写明环境变量回退；Configure 中每个认证属性有未知值守卫；链优先级；密钥整体解析、非密钥逐字段解析；哨兵错误区分下落与硬失败；缺少凭据诊断列出所有来源与文档 URL；Credentials 类型脱敏；凭据文件权限警告；及早解析与可选身份检查；单元测试覆盖；绝不记录凭据值。

限制

资料未提供该技能的具体安装命令、收费信息、支持平台或实际运行效果，这些内容暂未提供。

技能介绍

用途