Managing vSphere Certificates with PowerCLI

Managing vSphere certificates is a feature that many customers have been asking for on our feature request site. And when all the necessary APIs for it were added in vSphere 7 we were finally able to add it to PowerCLI 12.4.

This doesn’t mean however that all the cmdlets require vSphere 7. Some of them are supported in 6.7 or even 6.5. For example, you can check what are the trusted certificates on vSphere 6.7, but to add a certificate or certificate chain to the trusted certificate store you need vSphere 7. Also, you can check or change the machine certificate of an ESXi host for all supported ESXi versions, but to do that for vCenter Server you need vSphere 7.

So, let’s take a look at what cmdlets are available for certificate management. Here is the list:

• Add-VITrustedCertificate
• Get-VIMachineCertificate
• Get-VITrustedCertificate
• New-VIMachineCertificateSigningRequest
• Remove-VITrustedCertificate
• Set-VIMachineCertificate

Managing the Trusted Certificate Store

Let’s start with trusted certificate store management. We can use Get-VITrustedCertificate to check the details of the trusted root certificates on our vCenter Server and/or the connected ESXi hosts, such as issuer, expiration date, serial number, etc. Here is an example of how we can check the certificate stores of our servers for expired certificates.

If we want, for example, to add the certificate or certificate chain of the certificate authority that we use to the trusted certificate store we can use Add-VITrustedCertificate. Here is a sample script for this.

We also have the Remove-VITrustedCertificate cmdlet to remove trusted certificates that we no longer need. However, this is a command that you should be very careful with. Make sure that you don’t remove a certificate that is in use, or is a part of a trust chain that is in use. It’s not accidental that this operation is not available at all in the UI. Here is an example how to use Remove-VITrustedCertificate to remove the expired certificates from the trusted certificate store of the vCenter Server:

Managing the Machine SSL Certificate of vCenter Server

Now let’s move on to managing the Machine SSL certificate of a vCenter Server. If we have a lot of people accessing the vSphere client and we want it to present a certificate that is accepted by default by various browsers, we have to replace it with a certificate generated by a trusted certificate authority. First, let’s check the details of the current machine certificate:

Next, we have to create a certificate signing request (CSR) for the vCenter Server to give to our trusted certificate authority. We can use New-VIMachineCertificateSigningRequest as in the following example.

Then, when we receive our certificate file from the certificate authority, we can change the VC machine certificate by using Set-VIMachineCertificate like this.

Note: Before we try to set the Machine SSL certificate we have to make sure that the root certificate of our CA is added to the vCenter Server trusted root store. Also keep in mind that changing the certificate will cause the vCenter to reboot.

Managing Machine SSL Certificates of ESXi Servers

If we want to go to full custom mode and manage all the certificates on our own, we’ll have to change the certificates of the ESXi hosts as well. The workflow for changing the ESXi machine certificate is a bit more complex. First, we have to change the ESXi host certificate management mode setting on the vCenter to ‘custom’ and reboot the vCenter for the change to take effect.

Then, we must to generate the CSR for the ESXi server. This step is similar to the one for the vCenter Server with the only difference that for the ESXi server it’s important to specify the CommonName parameter. The CommonName must be either the ESXi host’s FQDN or IP address. And it must match the identifier that we use to add the host to the vCenter Server system.

Then, when we get the certificate from the certificate authority we have to follow the steps below to set it to the ESXi server.

1. 1. 1. Put the host in maintenance mode and remove it from vCenter
         
         $vmhost = Get-VMHost 'MyESXiHost' ` Set-VMHost -VMHost $vmhost -State Maintenance Remove-VMHost $vmhost

         1 2 3

         $vmhost = Get-VMHost 'MyESXiHost' ` Set-VMHost -VMHost $vmhost -State Maintenance Remove-VMHost $vmhost

      2. Connect directly to the ESXi host, set the new machine certificate and restart the host for the changes to take effect
         
         $esxConnection = Connect-VIServer $vmhost.Name ` -User 'My User' ` -Password 'My Password' ` -Force $esxCertificatePem = Get-Content "C:\Users\jdoe\downloads\myesxcert.pem" -Raw $targetEsxHost = Get-VMHost $vmhost.Name Set-VIMachineCertificate -PemCertificate $esxCertificatePem -VMHost $targetEsxHost | Out-Null Restart-VMHost $targetEsxHost Disconnect-VIServer $esxConnection

         1 2 3 4 5 6 7 8 9 10 11 12

         $esxConnection = Connect-VIServer $vmhost.Name `     -User 'My User' `     -Password 'My Password' `     -Force   $esxCertificatePem = Get-Content "C:\Users\jdoe\downloads\myesxcert.pem" -Raw $targetEsxHost = Get-VMHost $vmhost.Name Set-VIMachineCertificate -PemCertificate $esxCertificatePem -VMHost $targetEsxHost | Out-Null   Restart-VMHost $targetEsxHost   Disconnect-VIServer $esxConnection

         ---

         Note: Just like with the vCenter, before we try to set the machine certificate, we need to make sure that the root certificate of our CA is added to the trusted root stores of the ESXi server and all other servers that will communicate with it – vCenter Server and ESXi.

         ---

      3. Re-add the ESXi server to the vCenter.
         
         $vCenterConnection = Connect-VIServer vc1.example.com ` -User 'My User' ` -Password 'My Password' $vmhost = Add-VMHost -Name <ESXi host's FQDN> or <ESXi host's IP address> ` -Location (Get-Datacenter "My Datacenter")` -User "My User" ` -Password "My Password" $vmhost = Set-VMHost -VMHost $vmhost -State Connected

         1 2 3 4 5 6 7 8 9 10

         $vCenterConnection = Connect-VIServer vc1.example.com `     -User 'My User' `     -Password 'My Password'   $vmhost = Add-VMHost -Name <ESXi host's FQDN> or <ESXi host's IP address> `     -Location (Get-Datacenter "My Datacenter")`     -User "My User" `     -Password "My Password"   $vmhost = Set-VMHost -VMHost $vmhost -State Connected

Summary

With the new certificate management cmdlets it’s now much easier to automate vSphere certificate management with PowerCLI. There are some specifics in the process (especially for the ESXi hosts), so I hope this blog post will be useful in getting the entire process right. For step-by-step guidance on vSphere certificate management, visit the PowerCLI User’s Guide. Let us know in the comments if you want to see more technical blog posts like this and feel free to propose new topics.

Don’t miss the blog post for PowerCLI 12.5 here: PowerCLI 12.5 – What’s new?