How to Export and Import vCenter Custom Roles with PowerCLI (JSON)

Short answer: the vSphere Client has no export button for vCenter custom roles, but PowerCLI does the job in a few lines. Read the non-system roles with Get-VIRole, save each role’s name and PrivilegeList (privilege IDs) to JSON, then on the target vCenter resolve those IDs with Get-VIPrivilege -Id and recreate the role with New-VIRole. Privileges that don’t exist on the target version are reported and skipped.

When you need to copy roles between vCenters

Custom roles for backup software, monitoring, CSI drivers or automation accounts take time to get right. You usually want the same role on every vCenter. If the vCenters are in the same SSO domain with Enhanced Linked Mode, you don’t need a script, because Enhanced Linked Mode replicates roles, permissions, licenses, policies and tags. The script is useful for:

• standalone vCenters in separate SSO domains (lab, DMZ, customer sites),
• rebuilding a vCenter from scratch instead of restoring it,
• keeping role definitions in Git so you can see who changed a privilege, and when.

PowerCLI objects you work with

The cmdlets are documented in the PowerCLI User’s Guide and the PowerCLI cmdlet reference.

Export vCenter custom roles to JSON

Connect-VIServer -Server vcsa-src.lab.local

$roles = Get-VIRole | Where-Object { -not $_.IsSystem }

$export = foreach ($r in $roles) {
    [pscustomobject]@{
        Name        = $r.Name
        Description = $r.Description
        Privileges  = @($r.PrivilegeList)
    }
}

$export | ConvertTo-Json -Depth 3 | Set-Content -Path .\vcenter-roles.json -Encoding UTF8

IsSystem filters out the built-in roles like Administrator, Read-only and No access. The sample roles that ship with vCenter, and roles created by solutions, are not system roles, so they will be exported too. Add a name filter (for example Where-Object Name -like 'CUST-*') if you only want your own roles.

Import roles on the target vCenter

Connect-VIServer -Server vcsa-dst.lab.local

$roles = Get-Content -Path .\vcenter-roles.json -Raw | ConvertFrom-Json

foreach ($r in $roles) {
    if (Get-VIRole -Name $r.Name -ErrorAction SilentlyContinue) {
        Write-Warning "Role '$($r.Name)' already exists - skipped"
        continue
    }
    $privs   = Get-VIPrivilege -Id $r.Privileges -ErrorAction SilentlyContinue
    $missing = $r.Privileges | Where-Object { $_ -notin $privs.Id }
    if ($missing) {
        Write-Warning "Role '$($r.Name)': not on target: $($missing -join ', ')"
    }
    New-VIRole -Name $r.Name -Privilege $privs | Out-Null
    Write-Host "Created role $($r.Name) with $($privs.Count) privileges"
}

To update an existing role instead of skipping it, compare the lists and call Set-VIRole -Role $role -AddPrivilege $privs. If you run the import more than once, keep it idempotent: never delete and recreate a role that is already in use, because the permissions assigned to it would go with it.

Things that trip people up

1. Version differences. Each vSphere release adds and removes privileges. When you export from a newer vCenter and import into an older one, expect IDs that can’t be resolved. The warning shows you which ones.
2. Roles are not permissions. The JSON only defines roles. The assignments of user or group plus role on an object (Get-VIPermission/New-VIPermission) depend on the inventory and identity source on the target and have to be handled separately.
3. Solution-created roles. Some products create or update their roles when they register with vCenter. Leave those to the product installer.
4. Service accounts. If an account with a copied role still can’t log in, the role is often fine and the password is the problem. See fixing vCenter password expiration errors.

Further reading

• Paul van Dieën: Export and Import vCenter Custom Roles with PowerShell (a complete script with metadata and reporting)
• Broadcom TechDocs: Create a vSphere Role and Assign Permissions to a User (PowerCLI)
• Broadcom Developer: New-VIRole cmdlet reference