About VMware PowerCLI?
VMware PowerCLI is an extremely powerful automation tool to script and automate almost every function in vSphere and beyond.
Get started at https://developer.broadcom.com/powercli to learn more about installing and using PowerCLI or the documentation at https://docs.vmware.com/en/VMware-PowerCLI/index.html
It’s always a good idea to use the latest version of PowerCLI, which at the time of writing this article is version 13.3.0 (see release notes)
Use PowerCLI to update an existing vSphere Configuration Profiles enabled cluster
Let’s take a look at how we can use PowerCLI to perform the following workflow:
- Create a vSphere Configuration Profiles draft from a reference host
- Export the draft to a json file and make edits
- Import the edited draft
- Pre-check, apply the updated configurations to the cluster, and check compliance
In this example, we’re going to target a host called ‘esx-01.vmw.lab’ located in a cluster called ‘cluster-01’ using their managed object IDs (moIDs). We will re-used these references so we will define variables for each.
|
1 2 3 4 |
# Set cluster ID and reference host ID variables $clusterid=(Get-Cluster -Name cluster-01).Id.Replace("ClusterComputeResource-","") $hostMoid = (Get-VMHost -Name "esx-01.vmw.lab").Id.Replace("HostSystem-","") |
Using the chosen reference host moID and cluster ID we use the following commands to create a new vSphere Configuration Profile draft. Confirm that the draft is created in the vSphere Client, by navigating to the Cluster > Configure tab > Desired State > Configuration > Draft tab.
|
1 2 3 4 5 6 7 |
# Create a draft from a reference host $reqbody = Initialize-SettingsClustersConfigurationDraftsImportFromHostTaskRequestBody -VarHost $hostMoid $taskid = Invoke-ImportFromHostClusterDraftAsync -Cluster $clusterid -Draft latest -SettingsClustersConfigurationDraftsImportFromHostTaskRequestBody $reqbody # Check the status of the draft creation task Invoke-GetTask -Task $taskid |
The draft is created, and we can edit it directly in the vSphere Client if we choose, but in this example we are exporting the draft to a JSON format file.
|
1 2 3 4 |
# Export the Draft and output to File $config = Invoke-ExportConfigClusterDraft -Cluster $clusterid -Draft latest $config.config | Out-File 'C:\Users\Administrator\Downloads\cluster-01-config.json' |
You can use your preferred text editor to make configuration changes to the JSON file directly. For example, update the NTP settings for all hosts in the cluster.
Next, import the updated JSON file back into the cluster draft. Refresh the vSphere Configuration Profile draft tab and you will see the updated draft is imported. The draft is not applied to the cluster yet.
|
1 2 3 4 5 6 7 8 |
# Import the edited Draft file $config = Get-Content 'C:\Users\Administrator\Downloads\cluster-01-config.json' | Out-String Get-Content 'C:\Users\Administrator\Downloads\cluster-01-config.json' | Out-String $updateSpec=Initialize-SettingsClustersConfigurationDraftsUpdateSpec -Config $config Invoke-UpdateClusterDraft -Cluster $clusterid -Draft latest -SettingsClustersConfigurationDraftsUpdateSpec $updateSpec |
Check the current draft against the cluster to ensure no issues are foreseen ahead of remediation. Depending on the configuration being applied, the hosts may need to enter maintenance mode and be rebooted. The pre-check will note this. In this example, the configuration change does not require maintenance mode or a reboot.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
# Precheck the draft $prechecktask = Invoke-PrecheckClusterDraftAsync -Cluster $clusterid -Draft latest # Check the status of the precheck task Invoke-GetTask -Task $prechecktask # Print the remediation summary (Invoke-GetTask -Task $prechecktask).result.remediation_summary # Example # PS > (Invoke-GetTask -Task $prechecktask).result.remediation_summary # args default_message # ---- --------------- # {0} 0 hosts will be put into maintenance mode and then rebooted. # {0} 0 hosts will be put into maintenance mode. |
Remediate the cluster and apply the updated settings to the cluster. For auditing you can denote a remediation reason for the operation, denoted by the -Message flag.
|
1 2 3 4 5 6 7 |
# Apply the draft to the Cluster $applySpec=Initialize-SettingsClustersConfigurationDraftsApplySpec -Message "Update cluster NTP settings" $applyResult=Invoke-ApplyClusterDraft -Cluster $clusterid -Draft latest -SettingsClustersConfigurationDraftsApplySpec $applySpec # Check the status of the apply task Invoke-GetTask -Task $applyResult.apply_task |
The remediation task will automatically check for compliance against the applied configuration. You can also manually invoke a compliance check against the current vSphere Configuration Profile.
|
1 2 3 4 5 |
# Check Compliance $complianceTask = Invoke-CheckComplianceClusterConfigurationAsync -Cluster $clusterid # Check the status of the compliance check task Invoke-GetTask -Task $complianceTask |
Use PowerCLI to transition a cluster to use vSphere Configuration Profiles
Transitioning a cluster to use vSphere Configuration Profiles is a very quick task in the vSphere Client but, like anything, can be automated and orchestrated using PowerCLI.
Let’s take a look at how we can use PowerCLI to transition a cluster to use vSphere Configuration Profiles:
- Check the eligibility of the cluster
- Create the cluster configuration from a reference host
- Validate and Pre-check the configuration profile
- Apply the configuration profile to the cluster, and check compliance
In this example, we’re going to target a host called ‘esx-09.vmw.lab’ located in a cluster called ‘cluster-03’ using their managed object IDs (moIDs). We will re-used these references so we will define variables for each.
|
1 2 3 4 |
# Set cluster ID and reference host ID variables $clusterid=(Get-Cluster -Name cluster-03).Id.Replace("ClusterComputeResource-","") $hostMoid = (Get-VMHost -Name "esx-09.vmw.lab").Id.Replace("HostSystem-","") |
We will use PowerCLI to invoke vSphere REST APIs. The following commands initiate the required authentication for the REST API calls.
|
1 2 3 4 5 6 |
# Deal with login & create header to be used in future requests $base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $username,$password))) $session = Invoke-RestMethod -uri "https://$vc/rest/com/vmware/cis/session" -Method:Post -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)} $headers = @{'vmware-api-session-id'=$session.value} |
Check the eligibility of the cluster to transition to use vSphere Configuration Profiles. All hosts in the cluster must be version 8.0.0 or later to transition the cluster.
|
1 2 3 4 5 6 |
$action = 'checkEligibility' $taskId = Invoke-RestMethod -uri "https://$vc/api/esx/settings/clusters/$clusterid/enablement/configuration/transition?action=$action&vmw-task=true" -Method:Post -Headers $headers # Monitor the status of the eligibility check task Invoke-RestMethod -uri "https://$vc/api/cis/tasks/$taskId" -Headers $headers |
Using the reference host, esx-09.vmw.lab, defined above, import a configuration profile to be assigned to the cluster.
|
1 2 3 |
$action = 'importFromHost' Invoke-RestMethod -uri "https://$vc/api/esx/settings/clusters/$clusterid/enablement/configuration/transition?action=$action&vmw-task=true" -Body "`"$hostMoid`"" -ContentType:'application/json' -Method:Post -Headers $headers |
Validate the configuration profile against the hosts in the cluster.
|
1 2 3 |
$action = 'validateConfig' Invoke-RestMethod -uri "https://$vc/api/esx/settings/clusters/$clusterid/enablement/configuration/transition?action=$action&vmw-task=true" -Method:Post -Headers $headers |
Pre-check that the configuration profile can be applied to the cluster
|
1 2 3 |
$action = 'precheck' Invoke-RestMethod -uri "https://$vc/api/esx/settings/clusters/$clusterid/enablement/configuration/transition?action=$action&vmw-task=true" -Method:Post -Headers $headers |
Enable and apply the configuration profile to the cluster. The cluster will automatically invoke a compliance check after the configuration profile has been applied.
|
1 2 3 4 5 6 |
$action = 'enable' $taskid = Invoke-RestMethod -uri "https://$vc/api/esx/settings/clusters/$clusterid/enablement/configuration/transition?action=$action&vmw-task=true" -Method:Post -Headers $headers # Monitor the status of the enable task Invoke-RestMethod -uri "https://$vc/api/cis/tasks/$taskid" -Headers $headers |
