「Azure Storage documentation update: [Refresh sdk-resourcemanager/storagesync/armstoragesync]-generated-from-SDK Generation – Go-6325947」は、Azure Storage全体の仕様変更ではなく、Azure Storage Sync、つまりAzure File Syncを管理するGo向けAzure Resource Manager SDKの更新です。結論から言うと、GoでStorage Sync Service、Sync Group、Server Endpoint、Registered Serverなどを自動管理している開発者は、armstoragesync/v2への移行、BeginUpdate系メソッドの引数変更、beta版SDKの採用可否を確認する必要があります。一方、AzureポータルだけでAzure File Syncを運用している管理者への直接影響は限定的ですが、RBAC、同期トポロジ、Managed Identity関連の設定確認にはつなげておくべき更新です。
今回のPRは2026年5月20日にAzure SDK for Goのリポジトリへマージされ、対象はgithub.com/Azure/azure-sdk-for-go/sdk/resourcemanager/storagesync/armstoragesyncです。PRコメントでは、設定ファイルがspecification/storagesync/resource-manager/Microsoft.StorageSync/StorageSync/tspconfig.yaml、API Versionが2022-09-01、SDK Release Typeがbeta、SpecRepoのCommitSHAがd58b2d8e241284207c7cee7f86eb07343195015dであることが示されています。(GitHub)
今回の更新は「Storage SyncのGo管理SDK更新」と理解する
この更新は、Blob Storage、Queue Storage、Table Storage、Azure Filesそのものの利用方法が変わるという話ではありません。主な対象は、Azure File Syncの管理プレーンをGo SDKから操作しているアプリケーション、運用ツール、社内CLI、CI/CDパイプラインです。
Azure File Syncでは、Storage Sync ServiceがAzure Resource Manager上のルートリソースとして機能し、Windows ServerとAzure file shareの同期関係を管理します。1つのStorage Sync Serviceには複数のSync GroupとRegistered Serverを含められますが、1台のWindows Serverは1つのStorage Sync Serviceにのみ登録できます。(Microsoft Learn)
つまり今回の更新で見るべきポイントは、Azure Storageの保存データそのものではなく、次のような管理操作をGoで実装している箇所です。
| 確認対象 | 影響の可能性 | まず確認すること |
|---|---|---|
| Go製のAzure File Sync管理ツール | 高い | armstoragesyncのimport path、go.mod、更新系メソッド |
| Storage Sync Serviceを作成・更新する自動化コード | 高い | ServicesClient.BeginUpdateの呼び出し |
| Server Endpointを更新するコード | 高い | ServerEndpointsClient.BeginUpdateの呼び出し |
| Registered Serverを扱う運用コード | 中〜高 | 追加されたBeginUpdateや認証関連の型 |
| Azureポータル中心の運用 | 低い | IAM、同期トポロジ、Agent更新方針 |
| Bicep、ARM、Terraform AzAPI | 中 | API Version 2022-09-01のプロパティ差分 |
変更点の全体像
今回のPRでは、TypeSpecベースのGo Code Generatorを使ってarmstoragesync Resource Manager SDKが再生成され、v2.0.0-beta.1としてクライアント、Pager、LRO、Fake、サンプルが更新されています。PR上のレビュー概要では、モジュールがarmstoragesync/v2へ上がり、API Version 2022-09-01向けにサービスクライアントが再生成されたことが説明されています。(GitHub)
Go Packages上でも、github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/storagesync/armstoragesync/v2のv2.0.0-beta.1が2026年5月20日に公開されたことを確認できます。(Go Packages)
モジュールパスが/v2になる
READMEでは、インストール対象が次のモジュールパスになっています。(GitHub)
go get github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/storagesync/armstoragesync/v2既存コードで次のようにimportしている場合は、
import "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/storagesync/armstoragesync"新しいbeta版を使うコードでは、次のように/v2付きのimportへ変更します。
import "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/storagesync/armstoragesync/v2"Goではメジャーバージョン2以上のモジュールでimport pathに/v2のようなサフィックスが入るため、単純にバージョン番号だけを上げても既存コードがそのまま動くとは限りません。CIでgo test ./...を回す前に、import pathとgo.modを同時に確認してください。
SDK Release Typeはbeta
今回のSDK Release Typeはbetaです。PRコメントにもbetaとして示され、Changelogにも2.0.0-beta.1としてBreaking ChangesとFeatures Addedが記載されています。(GitHub)
beta版は、新機能や新しいAPIサーフェスを先行して試せる一方で、今後のリリースでシグネチャや型が変わる可能性があります。商用本番環境で採用する場合は、少なくとも次の条件を満たしてからにしましょう。
| 採用してよいケース | 見送るべきケース |
|---|---|
API Version 2022-09-01の機能をGoから使いたい | 既存の本番自動化が安定稼働している |
| Managed Identity関連の型やRegistered Server更新を検証したい | beta版を自動更新する運用になっている |
| ステージング環境でStorage Sync操作を十分に再現できる | go get -uで依存関係を一括更新している |
| Fakeを使った単体テストを強化したい | LROやPagerの挙動をテストしていない |
本番環境では、@v2.0.0-beta.1のようにバージョンを明示して依存関係を固定し、意図しない更新を避けるのが安全です。
go get github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/storagesync/armstoragesync/[email protected]
go mod tidy
go test ./...API Versionは2022-09-01
今回のSDK生成対象は、Storage SyncのResource Manager API Version 2022-09-01です。Azure REST API Specs側でもStorageSyncの設定にpackage-2022-09があり、stable/2022-09-01/storagesync.jsonが入力ファイルとして示されています。(GitHub)
Microsoft LearnのARM/Bicepリファレンスでも、Microsoft.StorageSync/storageSyncServices/registeredServersのリソース形式にapiVersion: "2022-09-01"が掲載されています。(Microsoft Learn)
API Versionがそろうことで、Go SDK、ARMテンプレート、Bicep、Terraform AzAPIなどの管理操作で扱うプロパティの見通しがよくなります。ただし、SDKの型が増えたからといって、すべての設定をすぐ本番で有効化すべきという意味ではありません。特に認証方式やManaged Identity関連は、権限、既存Agent、運用手順とセットで検証してください。
破壊的変更で最も注意すべきメソッド
Changelogで明示されている大きなBreaking Changesは、ServerEndpointsClient.BeginUpdateとServicesClient.BeginUpdateの引数変更です。これまでOptions側に入れていたParametersが削除され、更新パラメーターをメソッドの通常引数として渡す形に変わっています。(GitHub)
ServerEndpointsClient.BeginUpdateの変更
旧形式では、更新パラメーターをOptions内のParametersフィールドに入れる形でした。
// 旧形式のイメージ
options := &armstoragesync.ServerEndpointsClientBeginUpdateOptions{
Parameters: &armstoragesync.ServerEndpointUpdateParameters{
// 更新内容
},
}
poller, err := client.BeginUpdate(
ctx,
resourceGroupName,
storageSyncServiceName,
syncGroupName,
serverEndpointName,
options,
)新形式では、ServerEndpointUpdateParametersをメソッド引数として渡します。
// 新形式
parameters := armstoragesync.ServerEndpointUpdateParameters{
// 更新内容
}
poller, err := client.BeginUpdate(
ctx,
resourceGroupName,
storageSyncServiceName,
syncGroupName,
serverEndpointName,
parameters,
nil,
)この変更はコンパイル時に検出しやすいものの、複数の社内ツールやバッチ処理で同じSDKを使っている場合は見落としがちです。BeginUpdate(でgrepし、Storage Sync関連の呼び出しをまとめて確認してください。
ServicesClient.BeginUpdateの変更
Storage Sync Service自体を更新するServicesClient.BeginUpdateも同様です。旧形式ではOptions内にParametersを持っていましたが、新形式ではServiceUpdateParametersを直接渡します。(GitHub)
parameters := armstoragesync.ServiceUpdateParameters{
// 更新内容
}
poller, err := servicesClient.BeginUpdate(
ctx,
resourceGroupName,
storageSyncServiceName,
parameters,
nil,
)Storage Sync Serviceは同期構成の上位リソースです。タグ更新やIdentity関連の設定変更を自動化している場合、単にコンパイルを通すだけでなく、実際にステージング環境で更新、ポーリング完了、取得、再更新まで試してください。
追加された主な型・機能
Changelogでは、ManagedServiceIdentityType、ServerAuthType、ServerProvisioningStatus、CloudTieringLowDiskModeStateなどのenum、ManagedServiceIdentity、RegisteredServerUpdateParameters、ServerEndpointProvisioningStatus、UserAssignedIdentityなどのstructが追加されています。また、RegisteredServersClient.BeginUpdateやCloudEndpointsClient.AfsShareMetadataCertificatePublicKeysも追加されています。(GitHub)
実務上は、次のように捉えると分かりやすいです。
| 追加・更新された要素 | 実務での見方 |
|---|---|
ManagedServiceIdentity関連 | Storage Sync Serviceや登録サーバーの認証・ID管理をコード上で扱いやすくなる可能性がある |
ServerAuthType | 証明書認証とManaged Identity認証の状態確認・分岐に使える可能性がある |
RegisteredServersClient.BeginUpdate | Registered Serverの更新操作をLROとして扱うコードが必要になる |
ServerEndpointProvisioningStatus | Server Endpoint作成・更新時の状態監視を細かく実装しやすくなる |
NextLink追加 | 一覧取得で複数ページを前提にした実装が重要になる |
| Fake再生成 | ライブAzure環境に接続しない単体テストの整備に使える |
ここで重要なのは、「型が追加された」ことと「本番で即有効化する」ことを分けて考えることです。たとえばManaged Identityを使う場合、SDK側の型だけでなく、Azure側のID割り当て、RBAC、既存運用フロー、障害時の切り戻し手順まで確認する必要があります。
削除された型にも注意する
Changelogでは、ProgressType、Reason、Error、OperationDisplayResource、ProxyResource、Resource、ResourcesMoveInfo、SubscriptionState、TrackedResourceなどが削除されています。(GitHub)
これらを直接参照していない場合でも、社内ライブラリでラップしている可能性があります。特に次のようなコードは確認してください。
- 独自のエラー変換処理
- Azureリソースの共通型として
ResourceやTrackedResourceを受け取る処理 - SDKのレスポンス型をJSONに変換して保存している処理
- Storage Sync操作結果を監査ログへ出力している処理
- APIレスポンスをそのまま社内APIのレスポンスに流用している処理
削除された型がある場合、単純な置換ではなく「その型を使って何を判断していたか」まで戻って見直すのが安全です。
LROとPagerの確認は必須
今回のPR概要では、Pager、LRO、リクエスト構築の更新が含まれると説明されています。具体的には、サービスクライアントがAPI Version 2022-09-01向けに再生成され、Pager/LROの挙動やリクエスト構築が更新されています。(GitHub)
Azure Resource ManagerのBeginCreate、BeginUpdate、BeginDelete系は、処理がすぐ完了しないLong Running Operationになることがあります。実装では、Begin...を呼んだだけで成功とみなさず、Pollerで完了まで待つ処理を入れてください。
poller, err := client.BeginUpdate(ctx, resourceGroupName, storageSyncServiceName, syncGroupName, serverEndpointName, parameters, nil)
if err != nil {
return err
}
resp, err := poller.PollUntilDone(ctx, nil)
if err != nil {
return err
}
// respを使って更新後の状態を確認
_ = resp一覧取得も同様です。NextLinkが追加された型が複数あるため、1回のAPI呼び出しで全件取れる前提の実装は避けます。Pagerを最後まで回し、途中ページの失敗、空ページ、削除済みリソース混在もテストしましょう。
管理者が確認すべきAzure File Syncの設定
今回の更新はGo SDK中心ですが、管理者はこのタイミングでStorage Sync Serviceまわりの設定を棚卸しする価値があります。特に自動化コードがStorage Sync ServiceやServer Endpointを作成・更新する環境では、SDK更新と運用設定のズレが障害につながります。
RBACと最小権限
Microsoft Learnでは、Storage Sync Serviceは配置先のサブスクリプションとリソースグループからアクセス許可を継承するため、誰がアクセスできるかを慎重に確認するよう推奨しています。書き込み権限を持つ主体は、Storage Sync Serviceに登録されたサーバーから新しいファイルセットを同期させ、Azure Storageへデータを流せる可能性があります。(Microsoft Learn)
確認すべき項目は次の通りです。
| 確認項目 | 判断基準 |
|---|---|
| Storage Sync ServiceのIAM | Owner、Contributor、Azure File Sync Administratorが過剰に付与されていないか |
| 自動化用サービスプリンシパル | 作成、更新、削除のどこまで必要かを分けているか |
| Storage Account側の権限 | Cloud Endpoint作成に必要な権限だけを付与しているか |
| Managed Identity利用予定 | Identityに必要なロールを明示し、不要な広範権限を避けているか |
| CI/CDの権限 | 本番と検証で同じ資格情報を使っていないか |
サーバー登録やCloud Endpoint作成に関しては、Azure File Sync Administrator、Owner、Contributorなどのロール要件がMicrosoft Learnに記載されています。Cloud Endpoint作成者は、対象Azure file shareを含むStorage Account側の権限も確認する必要があります。(Microsoft Learn)
Cloud Endpointの一対一関係
Azure File Syncでは、Azure file shareとCloud Endpointの一対一関係が重要です。Microsoft Learnでは、Azure file shareが複数のCloud Endpointに関連付けられている構成はサポートされない不健全なトポロジであり、修正されるまでServer Endpoint作成がブロックされると説明されています。(Microsoft Learn)
自動化コードでCloud Endpointを作る場合は、作成前に次を確認してください。
| 作成前チェック | 理由 |
|---|---|
| 対象Azure file shareが既存Cloud Endpointで使われていないか | 二重同期や不健全なトポロジを避ける |
| Sync Group名とStorage Account名をログに残す | 障害時に対応範囲を特定しやすくする |
| 既存メタデータ削除を安易に自動化しない | 誤削除は同期障害やデータ損失につながる |
| 削除・再作成の手順を手動承認にする | 本番ファイル共有への影響を抑える |
特に危険なのは、「Cloud Endpoint作成に失敗したからメタデータを削除して再作成する」という自動処理です。Microsoft Learnでも、使用中のAzure file share上のメタデータ削除はAzure File Sync操作を失敗させ、別のSync Groupで使うとデータ損失がほぼ確実になると警告されています。(Microsoft Learn)
Server Endpointの作成条件
Server Endpoint作成時の失敗は、SDK更新後の検証でよく見つかります。Microsoft Learnでは、Server Endpointのパスはローカル接続されたNTFSボリュームである必要があり、マップドライブはサポートされないと説明されています。また、システムボリューム上でCloud Tieringを有効にしたServer Endpoint作成はサポートされません。(Microsoft Learn)
確認項目を運用チェックリストにすると、次のようになります。
| チェック項目 | NG例 | 対応 |
|---|---|---|
| パスの種類 | Z:\shareのようなマップドライブ | ローカル接続されたNTFSパスを使う |
| Cloud Tiering | システムボリュームで有効化 | システムボリュームでは無効化する |
| 重複パス | 同じディレクトリを複数Endpointで同期 | 既存Endpointを確認してから作成する |
| Endpoint数 | 1サーバーあたり上限を超過 | 不要なEndpointを整理する |
| オフラインサーバー | 削除処理が期限切れになる | サーバー接続性を確認し、必要なら登録解除手順を使う |
Microsoft Learnでは、Azure File Syncが現在1サーバーあたり最大30個のServer Endpointをサポートすることも示されています。(Microsoft Learn)
開発者向けの移行手順
Go SDKを使ってAzure Storage Syncを管理している場合は、次の順序で移行すると失敗を減らせます。
| 手順 | 作業 | 目的 |
| -: | ———————— | ——————— |
| 1 | armstoragesyncの利用箇所を検索 | 影響範囲を把握する |
| 2 | go.modとgo.sumをバックアップ | すぐ戻せる状態にする |
| 3 | /[email protected]へ更新 | 対象バージョンを固定する |
| 4 | import pathを/v2へ変更 | Goのv2モジュールに対応する |
| 5 | BeginUpdate系の引数を修正 | Breaking Changesに対応する |
| 6 | PagerとPollerの処理を見直す | 一覧取得とLROの失敗を防ぐ |
| 7 | Fakeを使うテストを更新 | ライブAzure依存を減らす |
| 8 | ステージングでStorage Sync操作を実行 | 実リソースで挙動を確認する |
| 9 | 本番は小さな対象から展開 | 影響を限定する |
| 10 | ログと監査証跡を確認 | 障害時の追跡性を確保する |
移行時に最初に実行するコマンド例は次の通りです。
go get github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/storagesync/armstoragesync/[email protected]
go mod tidy
go test ./...現在のgo.modでは、モジュールパスがgithub.com/Azure/azure-sdk-for-go/sdk/resourcemanager/storagesync/armstoragesync/v2になっており、依存関係としてazcoreやazidentityも記載されています。(GitHub)
自動化コードで失敗しやすいポイント
今回のようなSDK再生成では、コードのコンパイルエラーだけを直して終わらせると、実行時に問題が出ることがあります。特にAzure File SyncはオンプレミスのWindows Server、Azure file share、Storage Sync Service、認証、ネットワークが絡むため、管理APIの更新が運用影響に直結しやすい領域です。
go get -uでまとめて上げない
beta版を含む依存関係を一括更新すると、Storage Sync以外のAzure SDKまで同時に変わり、障害時に原因を切り分けにくくなります。まずは対象モジュールだけをバージョン固定で更新し、go.modの差分をレビューしてください。
Optionsに残ったParametersを見落とさない
今回のBreaking Changesでは、ServerEndpointsClientBeginUpdateOptions.ParametersとServicesClientBeginUpdateOptions.Parametersが削除されています。(GitHub)
単にコンパイルエラーを直すだけでなく、更新パラメーターの中身が以前と同じ意味で送られているかを確認しましょう。特にタグ、Identity、Cloud Tiering関連の設定は、空値やnilの扱いで意図しない更新になる可能性があります。
一覧取得を1ページ前提にしない
Changelogでは、複数の配列型にNextLinkが追加されています。たとえばCloudEndpointArray、RegisteredServerArray、ServerEndpointArray、ServiceArray、SyncGroupArray、WorkflowArrayなどです。(GitHub)
一覧取得後に「存在しない」と判断して新規作成する処理では、Pagerを最後まで読まないと重複作成や誤削除につながります。ページング処理のテストでは、1件だけの環境ではなく、複数ページになる可能性を想定したFakeやモックを使ってください。
Managed Identityを「型があるから使える」と判断しない
ManagedServiceIdentityやServerAuthTypeManagedIdentityのような型が追加されても、実際の環境で使えるかどうかは別問題です。必要なロール、既存サーバー登録状態、Agent、ネットワーク、組織のセキュリティポリシーを確認してから段階的に検証してください。
Portal運用とSDK運用の差分を残さない
Azureポータルで手動作成したStorage Sync ServiceやSync Groupを、Go SDKの自動化で更新する場合、タグ、Identity、認証方式、Private Endpoint関連設定などがコードに反映されていないことがあります。最初にGetで現状を取得し、更新前後の差分をログに出す仕組みを入れておくと、意図しない上書きを防ぎやすくなります。
管理者と開発者で分担すべき確認項目
今回の更新は開発者だけで完結しません。Go SDKの更新作業と、Azure File Syncの運用設定確認を分けて進めると安全です。
| 役割 | 確認項目 | 完了条件 |
|---|---|---|
| 開発者 | import path、go.mod、Breaking Changes | go test ./...が通り、ステージングで更新操作が成功 |
| Azure管理者 | Storage Sync ServiceのIAM | 不要なOwner/Contributorが削除または見直し済み |
| インフラ担当 | Sync GroupとEndpoint構成 | Cloud Endpointの一対一関係が確認済み |
| Windows Server管理者 | Agent、サーバー登録、Endpointパス | 対象パスがローカルNTFSで、重複Endpointがない |
| セキュリティ担当 | Managed Identity、サービスプリンシパル | 最小権限と監査ログが確認済み |
| 運用担当 | 障害時の切り戻し | 旧SDK、旧バイナリ、手動手順の戻し方が明確 |
Azure File Sync Agentについては、Microsoft LearnでMicrosoft Updateを有効にして最新状態を保つことが推奨されています。SDK更新そのものがAgent更新を意味するわけではありませんが、管理プレーンの更新を検証するタイミングでAgent更新方針も確認しておくと、原因切り分けがしやすくなります。(Microsoft Learn)
すぐ使える確認チェックリスト
本番展開前に、次のチェックリストを使ってください。
| チェック | 内容 |
|---|---|
| SDKバージョン | armstoragesync/[email protected]を明示している |
| import path | すべてarmstoragesync/v2へ変更済み |
| Goビルド | go test ./...が成功している |
| Breaking Changes | BeginUpdate系の引数変更に対応済み |
| LRO | PollUntilDoneなどで完了確認している |
| Pager | 一覧取得で全ページを処理している |
| IAM | Storage Sync ServiceとStorage Accountの権限を確認済み |
| Sync topology | Cloud Endpointの一対一関係を確認済み |
| Server Endpoint | ローカルNTFS、重複なし、上限未超過を確認済み |
| beta採用判断 | 本番適用の可否をチームで合意済み |
| ロールバック | 旧バージョンへ戻す手順がある |
| 監査ログ | 更新対象、実行者、結果を記録している |
今回の更新を採用すべきか
判断基準はシンプルです。GoでAzure File Syncの管理操作を実装しており、API Version 2022-09-01の型や機能、Managed Identity関連の扱い、Registered Server更新、最新のFakeを必要としているなら、検証環境で試す価値があります。
一方、既存のAzure File Sync運用が安定しており、Go SDKからStorage Syncを操作していない、または本番自動化でbeta版を受け入れにくい場合は、すぐに本番採用する必要はありません。今回の更新は「Azure Storageを使っているすべてのユーザーが即対応すべき変更」ではなく、「Storage SyncのGo管理SDKを使うチームが慎重に評価すべき変更」です。
まずは、自社コードでarmstoragesyncを使っているかを確認してください。使っている場合は、/v2移行、BeginUpdate修正、Pager/LROテスト、IAM確認の順に進めます。使っていない場合でも、Azure File Sync管理者はStorage Sync Serviceの権限、Cloud Endpointの一対一関係、Server Endpointの作成条件を棚卸ししておくと、今後のSDK更新や自動化導入に備えやすくなります。
コメント