使用 Go 官方 SDK（armprivatedns）管理 Azure Private DNS：从客户端工厂到虚拟网络链接的完整指南-平芜编程栈

测试
云原生
质量保障

【免费下载链接】origin

Conformance test suite for OpenShift

项目地址：https://gitcode.com/gh_mirrors/or/origin

导读

本文以 OpenShift 项目中 vendored 的 Azure Go SDK 模块armprivatedns（位于仓库vendor/github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/privatedns/armprivatedns/，对应 go.mod 中github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/privatedns/armprivatedns v1.2.0）为对象，系统讲解如何通过新一代 Azure SDK for Go 的 ARM 资源管理客户端来操作 Azure Private DNS——即私有 DNS 区域（Private Zone）、记录集（Record Set）与虚拟网络链接（Virtual Network Link）的创建、查询、更新与删除。读完本文，你将掌握该模块的安装方式、azidentity认证接入、ClientFactory工厂模式的使用、三大客户端（PrivateZonesClient、RecordSetsClient、VirtualNetworkLinksClient）的 API 组织方式，以及基于内存 Fake Server 编写单元测试的思路。

一、模块概览：armprivatedns 是什么

armprivatedns是 Azure SDK for Go 中负责Azure Private DNS 资源管理（ARM 平面）的模块，它基于 AutoRest 代码生成器自动生成，对应的 ARM API 版本为2020-06-01（可在 privatezones_client.go 等请求构造代码中看到api-version=2020-06-01的固定写入）。

从仓库内的文件布局可以确认该模块的核心组成：

文件	职责
client_factory.go	`ClientFactory`客户端工厂，统一创建本模块所有客户端
privatezones_client.go	`PrivateZonesClient`：私有 DNS 区域的生命周期管理
recordsets_client.go	`RecordSetsClient`：区域内 A/AAAA/CNAME/MX/PTR/SOA/SRV/TXT 记录集管理
virtualnetworklinks_client.go	`VirtualNetworkLinksClient`：区域与虚拟网络的链接管理
models.go	全部请求/响应模型（`PrivateZone`、`RecordSet`、`VirtualNetworkLink`等）
constants.go	枚举常量（`ProvisioningState`、`RecordType`、`VirtualNetworkLinkState`）与模块版本号
options.go	各方法的可选参数（ETag 条件头、`Top`分页上限、`ResumeToken`等）
CHANGELOG.md	版本演进记录（v1.2.0 起支持 test fakes 与 OpenTelemetry trace spans）

根据 CHANGELOG.md，该模块自v1.0.0（2022-05-18）起切换到下一代设计原则，包含破坏性变更；v1.1.0引入ClientFactory；v1.2.0（2023-11-24）增加 test fakes 与 OpenTelemetry trace spans 支持。仓库当前锁定版本正是 v1.2.0。

二、快速开始：环境与安装

2.1 前置条件

使用该模块前需要满足：

一个有效的Azure 订阅（Subscription），订阅 ID 会在每个服务调用的 URI 中体现；
Go 1.18 或更高版本。这一点在源码中得到印证：所有客户端源文件头部都有//go:build go1.18构建标签（如 client_factory.go），低于 1.18 的 Go 版本无法编译该模块。

2.2 安装模块

本项目采用 Go Modules 进行版本化与依赖管理，安装命令为：

go get github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/privatedns/armprivatedns

在 OpenShift 仓库中，该依赖以间接依赖（// indirect）形式记录于根目录 go.mod 第 151 行，并被 vendored 进vendor/目录。如果你的项目也使用 vendor 模式，go get之后需要同步 vendor 目录。

三、认证：用 azidentity 提供 TokenCredential

创建任意客户端时都需要传入一个azcore.TokenCredential凭据，用于向 Azure 服务发起带令牌的请求。官方推荐的获取方式是使用azidentity模块的默认凭据链，它依次尝试环境变量（client/secret）、证书、托管身份等常见认证方式：

cred, err := azidentity.NewDefaultAzureCredential(nil)

该凭据对象随后被传入客户端构造函数。从 client_factory.go 的注释可见，credential参数的定位是“用于对请求授权的凭据，通常是来自 azidentity 的凭据”。

四、Client Factory：创建任意客户端

armprivatedns模块由多个客户端组成，官方为此提供了ClientFactory工厂，用于统一创建模块内的任意客户端，避免为每个客户端重复传入订阅 ID、凭据和选项：

clientFactory, err := armprivatedns.NewClientFactory(<subscription ID>, cred, nil)

从源码看，NewClientFactory 会先通过arm.NewClient(moduleName, moduleVersion, credential, options)校验并初始化底层 ARM 客户端，然后将subscriptionID、credential与克隆后的options保存在工厂内。工厂内部为每个子客户端提供便捷构造方法：

func (c *ClientFactory) NewPrivateZonesClient() *PrivateZonesClient func (c *ClientFactory) NewRecordSetsClient() *RecordSetsClient func (c *ClientFactory) NewVirtualNetworkLinksClient() *VirtualNetworkLinksClient

这些方法会把工厂持有的订阅 ID、凭据与选项传播给新建的客户端（见 client_factory.go）。用法示例：

client := clientFactory.NewPrivateZonesClient()

注意：各客户端的NewXxxClient构造函数的注释均明确“不要直接使用类型，请通过构造函数或工厂创建”（如 privatezones_client.go）。

4.1 ClientOptions：切换公有云、主权云与 Azure Stack

ClientOptions（位于github.com/Azure/azure-sdk-for-go/sdk/azcore/arm包）用于设置端点，以连接公有云、主权云以及 Azure Stack。以下示例将客户端指向Azure China云：

options := arm.ClientOptions { ClientOptions: azcore.ClientOptions { Cloud: cloud.AzureChina, }, } clientFactory, err := armprivatedns.NewClientFactory(<subscription ID>, cred, &options)

传入nil则使用默认值（Azure 公有云）。

五、三大客户端与核心 API

“客户端”将一组相关 API 聚合在一起，提供对某一资源维度的访问能力。本模块包含三个客户端，覆盖 Azure Private DNS 的全部资源类型。

5.1 PrivateZonesClient：私有 DNS 区域

负责私有 DNS 区域的增删改查，方法包括：

BeginCreateOrUpdate(ctx, resourceGroupName, privateZoneName, parameters, options)：创建或更新区域。源码注释强调它不会修改区域内的虚拟网络链接或 DNS 记录（privatezones_client.go）；
Get(ctx, resourceGroupName, privateZoneName, options)：获取区域属性，但不包含虚拟网络链接与记录集；
BeginUpdate(...)：更新区域（仅更新PrivateZone的可写字段，不改链接与记录）；
BeginDelete(...)：删除区域。警告：区域内的所有 DNS 记录将一并删除且不可恢复；必须先移除所有指向该区域的虚拟网络链接才能删除区域（privatezones_client.go）；
NewListPager(options)：分页列出订阅内全部资源组中的私有区域；
NewListByResourceGroupPager(resourceGroupName, options)：分页列出某资源组内的私有区域。

从请求构造代码可以看到 REST 资源路径模式（privatezones_client.go）：

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/privateDnsZones/{privateZoneName}

创建、更新属于长时运行操作（LRO）：BeginXxx返回*runtime.Poller[T]轮询器，可通过PollUntilDone等待完成；同时支持通过options.ResumeToken从断点恢复轮询（runtime.NewPollerFromResumeToken）。列表类方法返回*runtime.Pager[T]分页器，内部依据响应中的NextLink自动翻页（privatezones_client.go）。

5.2 RecordSetsClient：记录集

负责区域内记录集（同一名称与类型的 DNS 记录集合）的管理：

CreateOrUpdate(ctx, resourceGroupName, privateZoneName, recordType, relativeRecordSetName, parameters, options)：创建或更新记录集。注意：SOA 类型的记录集只能更新不能创建——它在区域创建时自动生成（recordsets_client.go）；
Get(...)、Update(...)、Delete(...)：对应的查、改、删；
NewListPager(...)、NewListByTypePager(...)：分页枚举记录集，两者都支持Recordsetnamesuffix（按后缀过滤）与Top参数。

RecordType枚举定义了 8 种支持的类型（constants.go）：

常量	值	说明
`RecordTypeA`	`A`	IPv4 地址记录
`RecordTypeAAAA`	`AAAA`	IPv6 地址记录
`RecordTypeCNAME`	`CNAME`	别名记录
`RecordTypeMX`	`MX`	邮件交换记录
`RecordTypePTR`	`PTR`	反向解析记录
`RecordTypeSOA`	`SOA`	起始授权记录
`RecordTypeSRV`	`SRV`	服务定位记录
`RecordTypeTXT`	`TXT`	文本记录

对应的记录模型定义在 models.go 中：ARecord（IPv4Address）、AaaaRecord（IPv6Address）、CnameRecord（Cname）、MxRecord（Exchange+Preference）、PtrRecord（Ptrdname）、SrvRecord（Port/Priority/Target/Weight）、TxtRecord（Value []*string）与SoaRecord（Host/Email/SerialNumber/RefreshTime/RetryTime/ExpireTime/MinimumTTL）。

RecordSetProperties还包含TTL（记录 TTL，秒）、Metadata（附加元数据）、只读的Fqdn（记录集全限定域名）与IsAutoRegistered（是否通过虚拟网络链接自动注册）等字段（models.go）。

5.3 VirtualNetworkLinksClient：虚拟网络链接

将私有区域与 Azure 虚拟网络绑定，使该网络内的资源能够解析区域内的私有域名：

BeginCreateOrUpdate(ctx, resourceGroupName, privateZoneName, virtualNetworkLinkName, parameters, options)：创建或更新链接；
BeginUpdate(...)、BeginDelete(...)：更新与删除链接。警告：若删除的是注册型（registration）虚拟网络的链接，该网络在区域内所有自动注册的 DNS 记录也会一并删除且无法撤销（virtualnetworklinks_client.go）；
Get(...)、NewListPager(...)：查询与分页枚举。

VirtualNetworkLinkProperties的关键可写字段是RegistrationEnabled *bool（是否启用虚拟网络内虚拟机记录的自动注册）与VirtualNetwork *SubResource（被链接虚拟网络的引用）；只读字段包括ProvisioningState与VirtualNetworkLinkState（InProgress/Completed，见 models.go 与 constants.go）。

5.4 可选参数（options.go）速查

各方法通过*Options结构体接收可选参数，核心字段如下（完整定义见 options.go）：

字段	适用方法	语义
`IfMatch *string`	各 Create/Update/Delete	携带资源的 ETag：省略则无条件覆盖；指定上次见到的 ETag 可防止覆盖并发变更
`IfNoneMatch *string`	CreateOrUpdate 系列	设为`"*"`允许新建但不允许更新已有资源；其他值被忽略
`ResumeToken string`	Begin* 系列	从提供的令牌恢复长时操作轮询
`Top *int32`	List 系列	返回条数上限，未指定时默认最多返回100条
`Recordsetnamesuffix *string`	RecordSets List 系列	按名称后缀过滤枚举结果

六、模型与枚举：理解数据平面

6.1 核心模型

PrivateZone（models.go）：私有区域资源，可写字段为Location、Tags、Etag与Properties；ID/Name/Type为只读。
PrivateZoneProperties（models.go）：全部为只读，包括ProvisioningState、MaxNumberOfRecordSets、MaxNumberOfVirtualNetworkLinks、MaxNumberOfVirtualNetworkLinksWithRegistration以及当前计数NumberOfRecordSets等。
RecordSet/RecordSetProperties：见 5.2 节。
VirtualNetworkLink/VirtualNetworkLinkProperties：见 5.3 节。

6.2 关键枚举

ProvisioningState（constants.go）：Canceled、Creating、Deleting、Failed、Succeeded、Updating，为只读属性，尝试设置会被忽略。
RecordType：见 5.2 节表格。
VirtualNetworkLinkState：InProgress与Completed。

每个枚举类型都配套提供PossibleXxxValues()函数（如PossibleRecordTypeValues()），返回全部合法取值，可用于校验输入。

七、Fakes：离线单元测试

从 v1.2.0 起，本模块支持test fakes——fake 包提供了构建内存假服务器的类型，用于单元测试中模拟服务端各种成功/失败场景，无需连接真实 Azure 服务即可覆盖业务逻辑的边界条件。

典型的应用方式是：在测试中构造对应的 fake server 类型，将其作为 HTTP 传输层注入客户端（azcore的ClientOptions.Transport指向 fake 服务器），随后正常调用客户端方法断言返回结果与错误分支。这与官方sdk/samples/fakes中给出的模式一致，也呼应了 CHANGELOG 中“Support for test fakes and OpenTelemetry trace spans”的版本特性。

八、在 OpenShift 仓库中的定位与集成注意点

armprivatedns在当前 OpenShift conformance 测试仓库中是以vendored 间接依赖的形式存在的（见根目录 go.mod），源码目录为vendor/github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/privatedns/armprivatedns/。这意味着：

它随 Azure SDK for Go 的管理平面依赖链被拉入，供集群相关测试或基础设施工具在需要操作 Azure 私有 DNS 资源时直接 import；
使用时应遵循 Go Modules + vendor 的依赖管理约束：升级模块版本需同步更新go.mod/go.sum并重新 vendor；
若在仓库外独立项目中使用，直接执行go get github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/privatedns/armprivatedns即可获取最新稳定版（当前仓库锁定的 v1.2.0 对应 ARM API 2020-06-01）。

九、最小可运行骨架

综合上述内容，一个最小化的端到端使用骨架如下：

package main import ( "context" "fmt" "github.com/Azure/azure-sdk-for-go/sdk/azidentity" "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/privatedns/armprivatedns" ) func main() { subscriptionID := "<subscription ID>" resourceGroupName := "<resource group name>" privateZoneName := "example.internal" // 不带结尾点号 // 1. 认证 cred, err := azidentity.NewDefaultAzureCredential(nil) if err != nil { panic(err) } // 2. 通过工厂创建客户端（nil 选项 = Azure 公有云默认端点） clientFactory, err := armprivatedns.NewClientFactory(subscriptionID, cred, nil) if err != nil { panic(err) } zonesClient := clientFactory.NewPrivateZonesClient() recordsClient := clientFactory.NewRecordSetsClient() ctx := context.Background() // 3. 创建私有 DNS 区域（长时操作） poller, err := zonesClient.BeginCreateOrUpdate(ctx, resourceGroupName, privateZoneName, armprivatedns.PrivateZone{Location: tostring}, nil) if err != nil { panic(err) } resp, err := poller.PollUntilDone(ctx, nil) if err != nil { panic(err) } fmt.Println("zone created:", *resp.PrivateZone.Name) // 4. 创建 A 记录集 _, err = recordsClient.CreateOrUpdate(ctx, resourceGroupName, privateZoneName, armprivatedns.RecordTypeA, "db", armprivatedns.RecordSet{ Properties: &armprivatedns.RecordSetProperties{ TTL: toint64, ARecords: []*armprivatedns.ARecord{ {IPv4Address: tostring}, }, }, }, nil) if err != nil { panic(err) } }

说明：示例中的toT是常见的指针辅助函数；实际工程中可使用azcore/to包提供的指针工具，或自行定义。区域名、记录名均“不带结尾点号”（不含 terminating dot）。

十、进一步学习与反馈

模块内更多细节可直接阅读仓库内 README.md 及其同目录源码（client、models、options、constants），以及 CHANGELOG.md 了解版本演进；
官方针对 Private Zone、Record Sets、Virtual Network Link 分别提供了可运行示例，可作为代码参考；
若遇到 bug 或有改进建议，可按 Azure SDK 的 issue 流程提交，并附带Private DNS标签，便于维护团队定位。

适用前提与限制：本文所有 API 形态、参数与枚举均以仓库内锁定版本v1.2.0（对应 ARM API 版本 2020-06-01）为准；不同版本的 SDK 可能在方法签名或字段上存在差异，升级前请参考对应版本的 CHANGELOG 与迁移指南。