はじめに
ONTAPのAPIの利用において、過去の記事では、ONTAP PowerShell Toolkitの導入＋基本的な使用方法を中心に紹介しました。
今回の記事では、実際にONTAP PowerShell Toolkitを利用ている運用現場において困った際に利用できるであろうTipsをいくつか選んで記載致します。
記事における環境情報
本記事では、以下の環境で実施した内容となります。
分かり易くするために、構成図は単純化しています。
NetApp.ONTAP PowerShell Toolkit 9.17.1
Windows Server 2022
ONTAPへの接続例
ONTAP PowerShell Toolkitを使ってONTAPに接続する際には、Cluster全体管理もしくは個々のSVMに作成した管理LIFを指定します。
# ModuleのImpoer
> Import-Module .\NetApp.ONTAP.psd1
> get-module
ModuleType Version PreRelease Name ExportedCommands
---------- ------- ---------- ---- ----------------
Manifest 7.0.0.0 Microsoft.PowerShell.Management {Add-Content, Clear-Content, Clear-Item, Clear-ItemProperty…}
Manifest 7.0.0.0 Microsoft.PowerShell.Utility {Add-Member, Add-Type, Clear-Variable, Compare-Object…}
Manifest 9.17.1.25… NetApp.ONTAP {Add-NaCredential, Add-NaHostIscsiConnection, Add-NcAggr, Add-NcAggrObjectStore…}
Script 2.3.6 PSReadLine {Get-PSReadLineKeyHandler, Get-PSReadLineOption, Remove-PSReadLineKeyHandler, Set-PSReadLineKeyHandler…}
# Cluster管理SVMへの接続
> Connect-NcController -Name 192.168.123.100
Windows PowerShell Credential Request
Enter your credentials.
User: admin
Password for user admin: ***********
Name Address Vserver Version
---- ------- ------- -------
192.168.123.100 192.168.123.100 NetApp Release 9.14.1P12: Tue Mar 25 23:16:26 UTC 2025
#コマンドレットの実行
> Get-NcVol
Name State TotalSize Used Available Dedupe Aggregate Vserver
---- ----- --------- ---- --------- ------ --------- -------
bkup_root online 1.0 GB 970.6 MB aggr1_node2 bkup
nfs01_root online 1.0 GB 970.7 MB aggr1_node1 nfs01
nfs01_vol online 5.0 GB 4.7 GB aggr1_node1 nfs01
nfs01_vol_bk online 5.0 GB 5.0 GB aggr1_node1 bkup
1. ONTAPI(ZAPI)形式でコマンドレットを実行
PowerShell Toolkitは REST APIとONTAPIの両方をサポートしています。NetAppのKB に記載のとおり、当面は ONTAPI のサポートも延長されています（2025年10月時点、サポート終了時期は未定）。
一方で、以下の状況下では明示的に ONTAPIを指定して実行する必要があります。
- ONTAP をUpgradeしたら、コマンドレットの出力が変わった
- ONTAP 9.14.1 にUpgradeしたら、コマンドレットが通らなくなった
- コマンドレット実行時に、引数不足のエラーが出る
コマンドレットに-ONTAPIを付ける事で明示的にONTAPIを使用できます
1-1. SnapMirrorのStatusがidelから変わる例
ONTAP9.8利用時に、SnapMirrorのStausはidleと表示されるのに、ONTAPを9.11.1にUpgrade後はsnapmirroredに変わっている事が確認できます。
こちらは-ONTAPIをつけてコマンドレット実行で今までと同じ表示を返す事ができます。
# ONTAP 9.8へ接続して確認
> Connect-NcController -Name 192.168.123.100
Windows PowerShell Credential Request
Enter your credentials.
User: admin
Password for user admin: ***********
Name Address Vserver Version
---- ------- ------- -------
192.168.123.100 192.168.123.100 NetApp Release 9.8P21: Thu Nov 16 22:06:00 UTC 2023
# SnapMirrorの状態確認
> Get-NcSnapmirror | Where-Object MirrorState
SourceLocation DestinationLocation Status MirrorState
-------------- ------------------- ------ -----------
nfs01:vol100 mirror_svm:vol100_bk idle snapmirrored
# ONTAP 9.11.1へ接続して確認
> Connect-NcController -Name 192.168.123.100
Windows PowerShell Credential Request
Enter your credentials.
User: admin
Password for user admin: ***********
Name Address Vserver Version
---- ------- ------- -------
192.168.123.100 192.168.123.100 NetApp Release 9.11.1P18: Mon Nov 11 16:29:27 UTC 2024
# -ONTAPIを付けない場合のコマンドレット結果
> Get-NcSnapmirror | Where-Object MirrorState
SourceLocation DestinationLocation Status MirrorState
-------------- ------------------- ------ -----------
nfs01:vol100 mirror_svm:vol100_bk snapmirrored snapmirrored
#-ONTAPIを付けた場合のコマンドレット結果
> Get-NcSnapmirror -ONTAPI | Where-Object MirrorState
SourceLocation DestinationLocation Status MirrorState
-------------- ------------------- ------ -----------
nfs01:vol100 mirror_svm:vol100_bk idle snapmirrored
1-2. ONATP9.14.1で個別SVM操作でエラーが出る
端的に言うと不具合に該当し、ONTAP9.15.1では解消していますが、-ONTAPIをつけてコマンドレット実行で今までと同じ表示を返す事ができます。
# ONTAP 9.14.1のデータSVMに接続して確認
> Connect-NcController -Name 172.16.22.42 -vserver nfs01
Windows PowerShell Credential Request
Enter your credentials.
User: vsadmin
Password for user vsadmin: ********
Name Address Vserver Version
---- ------- ------- -------
172.16.22.42 172.16.22.42 nfs01 NetApp Release 9.14.1P12: Tue Mar 25 23:16:26 UTC 2025
# -ONTAPI無い場合はエラー発生
> Get-NcVol
Get-NcVol: [400]: Cannot set the svm context from HTTP header using: "X-Dot-SVM-Name" or "X-Dot-SVM-UUID" while in an existing svm context.
# -ONTAPIを付けるとコマンドレットが成功する
> Get-NcVol -ONTAPI
Name State TotalSize Used Available Dedupe Aggregate Vserver
---- ----- --------- ---- --------- ------ --------- -------
nfs01_root online 1.0 GB 0% 972.1 MB False aggr1_node1 nfs01
nfs01_vol online 5.0 GB 0% 4.7 GB False aggr1_node1 nfs01
1-3. コマンドレット実行時に必須の引数が変わる
ONTAPのUPgrade後に引数に関するエラーが出るような場合は、-ONTAPIをつけてコマンドレット実行で成功します。
# REST APIの利用だと失敗
> $attributes = Get-NcNfsService -Template
> $attributes.IsNfsv3Enabled = $true
> Add-NcNfsService -Attributes $attributes -VserverContext test100
Add-NcNfsService: [400]: "0" is an invalid value for field "credential_cache.negative_ttl" (<60000..604800000>)
# ONTAPI指定の場合は成功
> $attributes = Get-NcNfsService -Template
> $attributes.IsNfsv3Enabled = $true
> Add-NcNfsService -ONTAPI -Attributes $attributes -VserverContext test100
Vserver GeneralAccess IsNfsv3 IsNfsv4 IsNfsv41 DefaultWindowsUser
------- ------------- ------- ------- -------- ------------------
test100 True True True True
2. Invoke-NcSshを使いSSH利用でCLIを直接投げる
PowerShell Toolkitには、Invoke-NcSshコマンドレットの引数として、ONTAPのCLIを入力し実行させる事ができます。
以下のような場合に実行する事が考えられます。
- コマンドレットで用意されていないOptionを指定したい
- コマンドレットの不具合で指定した引数が設定されない場合の回避策
実行するとONTAP間との通信としてSSH通信が発生しますので、古いWindows OS上から操作の際には別途OpenSSHが必要となる場合があります。
# OSの確認
> systeminfo |Select-String "OS 名:"
OS 名: Microsoft Windows Server 2025 Datacenter
# Invoke-NcSshの実行
> Invoke-NcSsh -Command "net int show"
NcController : 172.16.22.42
Value :
Last login time: 10/13/2025 07:13:32
(network interface show)
Logical Status Network Current Current Is
Vserver Interface Admin/Oper Address/Mask Node Port Home
----------- ---------- ---------- ------------------ ------------- ------- ----
nfs01
data up/up 172.16.22.40/24 PS-8200cl02-01 a0a-22 true
mgm up/up 172.16.22.42/24 PS-8200cl02-01 a0a-22 true
2 entries were displayed.
上記のコマンド実行時パケットを採取するとSSH通信が発生している事が確認できます。
3. REST APIを使ってCLIを直接投げる方法
運用環境によっては、Windows Serverが古いのでOpenSSHがネイティブで入っていない環境であったり、ONTAPとWindows間にFWが入っていて直ぐにSSH疎通が許可できないので、httpsのみでどうにかCLI操作を実行したいといった事があるかと思います。
ONTAPのREST APIではapi/private/cliを利用して実現する事ができます。
# Base64で"ユーザ名:パスワード"をエンコード
$auth = "admin:NT@pTast10st2025"
$byte = ([System.Text.Encoding]::Default).GetBytes($auth)
$b64enc = [Convert]::ToBase64String($byte)
# 実行したCLIの内容を定義(以下の例はNFS modifyの為のオプション指定部分)
$uri = "https://192.168.123.100/api/private/cli/nfs?vserver=nfs01"
$headers = @{
"accept" = "application/json"
"authorization" = "Basic $b64enc"
}
$body = @{
allow_idle_connection_timeout = "disabled"
} | ConvertTo-Json
# Invoke-RestMethodの実行(Modifyを実施したいので、MethodはPatchを指定)
> Invoke-RestMethod -Uri $uri -Method Patch -Headers $headers -Body $body
num_records
-----------
1
上記の実行例は検証環境の為、以下のように証明書検証を強制的に無効化してから実行しています。
> add-type @"
using System.Net;
using System.Security.Cryptography.X509Certificates;
public class TrustAllCertsPolicy : ICertificatePolicy {
public bool CheckValidationResult(
ServicePoint srvPoint, X509Certificate certificate,
WebRequest request, int certificateProblem) {
return true;
}
}
"@
> [System.Net.ServicePointManager]::CertificatePolicy = New-Object TrustAllCertsPolicy
api/private/cliの詳細な説明については、REST APIの Online Referenceで確認できます。
(Cluster管理LIF/docs/apiにブラウザからアクセスして確認できるページ)
参考及びリンク
NetApp.ONTAP PowerShell Toolkit
PowerShell Toolkitのヘルプへのアクセス方法
Data ONTAP PowerShell Toolkitのデバッグログの収集方法
Powershell Toolkit 9.14.1 Snapmirror Relationship does not work