Required ESXi permissions for UNMAP through PowerCLI

I received a question recently on another UNMAP post what are the minimum permissions required to run UNMAP with PowerCLI and finally got around to looking into it. Turns out it is very straight forward. If you run it with a read-only account–it will fail. Since it is creating a file and making changes some configuration authority is required. Running as read only will look like this:

failedunmap

So as it says, you need a Host.Config.Storage permission to run this. There are a variety of roles that provide for this that are built in to vCenter (administrator for instance), but if you want to get granular you can create your own user role to do just this.

newrole

The permission that is required as seen in the vSphere Web Client is Host -> Configuration -> Storage partition configuration.

permission

Assign this permission and only this permission to a new custom role for the bare minimum.

Now you have to assign this to an object and there are a few ways to handle this. Unlike some other PowerCLI commands that are run against the vCenter, UNMAP is run directly to a host (after a vCenter connection) because it is a esxcli command, which requires a host object from get-vmhost. Therefore, the user needs a role with the Host.Config.Storage permission assigned to whichever host you will be running UNMAP from. So, the options are:

  1. Pick the host you want to run UNMAP for and assign the user this role (for the greatest security granularity) or…
  2. Choose a cluster object or vCenter object (or any higher-level object in the inventory in which the desired host(s) are subservient to) and assign it to that object and let the children inherit the permission. This option will grant UNMAP access to your user for all of the hosts below that object in your vCenter inventory.

Below I am assigning the user with my custom role to the vCenter object and propagating it down.

assignrole

One thing to note is that you do not need any actual permissions on the datastore, or really any child-object of the ESXi host. UNMAP will work with simply a Host.Config.Storage permission on the top level of the ESXi host with zero propagation. So basically it looks like if a user has this permission on a host, it can UNMAP any volume (that is of course actually presented to that host) even if they explicitly are given the “no access” permission on the datastore.

8 thoughts on “Required ESXi permissions for UNMAP through PowerCLI”

  1. Thanks a lot for this Cody. I think this should set us just right. After 1 last question of course :). I planned on running this weekly. Would you recommend a shorter/longer gap between runs, or does it vary?

    1. Sure thing! Sorry took so long. Weekly is fine. Id say most run it closer to monthly but it really depends on how dynamic your environment is. If you are deleting and recreating VMs quite often you probably want to run it more often. Same goes for if you are running your array on the fuller side (70%+)

  2. Hey Cody,

    Thanks for the role. We went ahead and tried it, looks good. However, we are coming across something else. Any idea what we’re missing?

    Iterating through VMFS volumes and running a reclamation on Pure Storage volumes only

    UNMAP will use a block count iteration of 60000

    Please be patient, this process can take a long time depending on how many volumes and their capacity
    ——————————————————————————————————

    PS C:\WINDOWS\system32> $volinfo = Invoke-RestMethod -Method Get -Uri “https://${purevip}/api/1.2/volume/${purevolname}?space=true” -WebSession $Session

    Invoke-RestMethod : {“msg”: “page not found”}
    At line:1 char:24
    + … $volinfo = Invoke-RestMethod -Method Get -Uri “https://${purevip}/ap …
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], WebException
    + FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand

    PS C:\WINDOWS\system32> $volinfo = Invoke-RestMethod -Method Get -Uri “https://${purevip}/api/1.2/volume/${purevolname}?space=true” -WebSession $Session

    Invoke-RestMethod : {“msg”: “page not found”}
    At line:1 char:24
    + … $volinfo = Invoke-RestMethod -Method Get -Uri “https://${purevip}/ap …
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], WebException
    + FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand

  3. Man we are really struggling. When we run the script against our test VCenter, it sees the volumes, it does its thing. When we run it against prod, literally ONLY changing the $vcenter line, it finds 0 VMFS volumes. The role was created and given rights to the specific cluster. If we login to the VCenter GUI as that user, he sees his hosts, but, on the config tab? no datastores. Baffled.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.