VMware Cloud Foundation 4.5

5.2 5.1 5.0 4.5
Deutsch Français Italiano 日本語 English

ESXi Certificate Management for
VMware Cloud Foundation

If your organization has a policy to use certificates signed by an external certificate authority (CA), you must replace the default ESXi SSL certificates that are signed by the VMware Certificate Authority (VMCA).
SDDC Manager does not manage certificates for ESXi hosts. Instead, VMCA on vCenter Server provisions each new ESXi host with a signed certificate where VMCA is the root certificate authority by default. To comply with the policy of your organization, you manually replace the host’s certificate.
You can replace host certificates step-by-step by using product user interface or in an automated way, as code-based alternatives to certain UI-based procedures, by calling the cmdlets in the VMware.CloudFoundation.CertificateManagement module in PowerShell Gallery.
If you want to read the documentation, provide feedback, report an issue with automation, or contribute to the
VMware.CloudFoundation.CertificateManagement
 module, go to the VMware.CloudFoundation.CertificateManagement open-source project in Github.

Content Scope

The ESXi certificate management guidance in this section covers following scenarios:
  • Replacing an ESXi host certificate signed by VMCA with a certificate signed by an external certificate authority in an already deployed SDDC workload domain.
  • Replacing an ESXi host certificate signed by an external certificate authority with another certificate signed by an external certificate authority in an already deployed SDDC workload domain.

Prerequisites

To perform the configuration associated with ESXi certificate management, verify that your system fulfills the following prerequisites.
Category
Prerequisite
Environment
Verify that your
VMware Cloud Foundation
 instance is healthy and fully operational.
Infrastructure-as-code
To use the infrastructure-as-code method for managing ESXi host certificates, verify that your system fulfills the prerequisites, described in the documentation of the VMware.CloudFoundation.CertificateManagement open-source project in Github.

Change the Certificate Mode to Custom for the ESXi Hosts in a Workload Domain

You change certificate mode for the hosts in a workload domain in
VMware Cloud Foundation
 to custom so that VMCA no longer automatically provisions the ESXi hosts with VMCA certificates.

Prerequisites

  • The workload domain vCenter Server must be in a scheduled maintenance window. You must restart vCenter Server service to finish the process.

UI Procedure

  1. Log in to the workload domain vCenter Server that manages the target hosts at
    https://<vcenter-server_fqdn>/ui
     as
    administrator@vsphere.local
    .
  2. Change the certificate mode for the managed ESXi hosts.
    • In the
      Hosts and Clusters
       inventory, select the vCenter Server instance.
    • On the
      Configure
       tab, under
      Settings
      , click
      Advanced Settings
       and click
      Edit Settings
      .
    • In the
      Name
       filter text box, enter
      vpxd.certmgmt.mode
      .
    • Change the value of
      vpxd.certmgmt.mode
       to
      custom
      , and click
      Save
      .
  3. Restart the vCenter Server instance for apply the changes.
    1. From the vSphere Client Menu, select
      Administration
      .
    2. In the
      Deployment
       section, select
      System configuration
      .
    3. Select the vCenter Server instance from the list and click
      Reboot node
      .
    4. Enter
      Change ESXi certificate mode to custom CA mode.
       as a reason for the restart and click
      Reboot
      .
  4. Verify that the vCenter Server instance has successfully restarted and that you are able to log in to the vSphere Client.
  5. Acknowledge the
    vSphere vCenter Host Certificate Management Mode
     alarm.
  6. In the vSphere Client, verify that for the workload domain vCenter Server the value of the
    vpxd.certmgmt.mode
     property is
    custom
    .

PowerShell Procedure

  1. Start Windows PowerShell.
  2. Replace the values in the sample code and run the commands in the PowerShell console.
    $sddcManagerFqdn = "sfo-vcf01.sfo.rainpole.io" 
$sddcManagerUser = "administrator@vsphere.local" 
$sddcManagerPass = "VMw@re1!"
$workloadDomain = "sfo-m01"
$mode = "custom"
  3. Set the ESXi certificate mode to
    custom
     by running the following command in the PowerShell console.
    Set-EsxiCertificateMode -server $sddcManagerFqdn -user $sddcManagerUser -pass $sddcManagerPass -domain $workloadDomain -mode $mode
  4. Restart the vCenter Server instance manually to apply the changes as described in the UI-assisted procedure.
  5. Retrieve and verify the ESXi certificate mode has been set to
    custom
     by entering the following command.
    Get-EsxiCertificateMode -server $sddcManagerFqdn -user $sddcManagerUser -pass $sddcManagerPass -domain $workloadDomain

Generate a Certificate Signing Request for the ESXi Hosts in a Workload Domain

By using the ESXi Shell, you generate Certificate Signing Request (CSR) files for each ESXi host in the workload domain. You can send the CSR files to a third-party certificate authority and receive CA-signed certificates for the hosts.
The certificate chain of the third-party certificate authority must be present in the trust store of SDDC Manager and the workload domain vCenter Server.

UI Procedure

  1. Log in to the ESXi Shell by using the DCUI or an SSH client as a user with administrator privileges.
  2. In the
    /etc/vmware/ssl
     directory, create a file by running the following command.
    vi ESXi.cfg
  3. Place the following content in the
    ESXi.cfg
     file
    [ req ]
days = 
    certificate-expiration-period (730)
    
default_md = sha512
default_bits = 2048
distinguished_name = req_distinguished_name
prompt = no
[ req_distinguished_name ]
commonName = 
    esxi-fqdn
    
countryName = 
    your-country
    
stateOrProvinceName = 
    your-state
    
localityName = 
    your-locality
    
0.organizationName = 
    your-organization
    
organizationalUnitName = 
    your-unit
  4. Run the following command to generate a private key and a CSR file, replacing the values in the example command.
    openssl req -new -nodes -out 
    esxi-fqdn
    .csr -keyout 
    esxi-fqdn
    .key -config ESXi.cfg
  5. Export the
    esxi-hostname
    .csr
     file and optionally
    esxi-hostname
    .key
     from the ESXi host, for example, by using an SCP utility, such as WinSCP.
  6. Repeat the steps for the remaining ESXi hosts in the workload domain.

PowerShell Procedure

  1. Start Windows PowerShell.
  2. Replace the values in the sample code and run the commands in the PowerShell console.
    $sddcManagerFqdn = "sfo-vcf01.sfo.rainpole.io" 
$sddcManagerUser = "administrator@vsphere.local" 
$sddcManagerPass = "VMw@re1!"
$workloadDomain = "sfo-m01"
$cluster = "sfo-m01-cl01"
$country = "US"
$locality = "San Francisco"
$organization = "Rainpole"
$organizationUnit = "IT"
$stateOrProvince = "California"
$outputDirectory = "F:\CSR\"
  3. Perform the configuration by entering the following command in the PowerShell console.
    Request-VCFCsr -esxi -server $sddcManagerFqdn -user $sddcManagerUser -pass $sddcManagerPass -domain $workloadDomain -cluster $cluster -Country $country -Locality $locality -Organization $organization -OrganizationUnit $organizationUnit -StateOrProvince $stateOrProvince -outputDirectory $outputDirectory
  4. Repeat the steps for each cluster in the workload domain.

What to do next

Send the CSR files to the third-party certificate authority to receive the CA-signed host certificates.

Verify That the Certificate Authority Is Trusted by vCenter Server and SDDC Manager

For a trusted communication, the certificate authority that signed the certificates of the ESXi hosts must be in the trust store of by both the workload domain vCenter Server and SDDC Manager.

UI Procedure

  1. Verify that the certificate of the CA is in the trust store of SDDC Manager.
    1. Log in to SDDC Manager at
      https://<sddc_manager_fqdn>
       with a user assigned the
      Admin
       role.
    2. In the navigation pane, click
      Inventory
      Workload Domains
      .
    3. On the
      Workload Domains
       page, click the target workload domain.
    4. On the workload domain summary page, click the
      Certificates
       tab.
    5. Verify the certificate issuer for the
      vcenter
       resource type is the same as the issuer of the CA-signed host certificates.
  2. Verify that the certificate of the CA is in the trust store of the workload domain vCenter Server.
    1. Log in to vCenter Server at
      https://<vcenter_server_fqdn>/ui
       as
      administrator@vsphere.local
      .
    2. From the vSphere Client Menu, select
      Administration
      .
    3. Under
      Certificates
      , select
      Certificate Management
      .
    4. On the upper right hand corner, select the vCenter Server instance from the drop-down menu.
    5. Verify that the
      Trusted Root Certificates
       store contains the certificate of the certificate authority with the same issuer name as the host certificates.
    6. Verify that the subject and serial number are the same as in the issuer part of the signed host certificates.

PowerShell Procedure

  1. Start Windows PowerShell.
  2. Replace the values in the sample code and run the commands in the PowerShell console.
    $sddcManagerFqdn = "sfo-vcf01.sfo.rainpole.io"
$sddcManagerUser = "administrator@vsphere.local"
$sddcManagerPass = "VMw@re1!"
$workloadDomain = "sfo-m01"
$rootCertificate = "F:\Certificate\rainpoleRoot64.cer"
$issuer = "rainpole"
  3. Verify if the CA's certificate is trusted by running the following command.
    Confirm-CAInvCenterServer -server $sddcManagerFqdn -user $sddcManagerUser -pass $sddcManagerPass -domain $workloadDomain -issuer $issuer -signedCertificate $rootCertificate
  4. Verify that the command output returns
    true
    .

Replace the ESXi Host Certificates with CA-Signed Certificate in a Workload Domain

Replace each ESXi host certificate with a CA-signed certificate obtained from a certificate authority to meet the security requirements of your organization.
Perform the replacement of the host certificates in the workload domain in a scheduled maintenance window. This operation requires more time to complete than is usually allocated in a regular operational mode.

UI Procedures

  1. Log in to the workload domain vCenter Server that manages the target hosts at
    https://<vcenter-server_fqdn>/ui
     as
    administrator@vsphere.local
    .
  2. If you are using vSAN as principal storage, verify the vSAN health.
    1. In the
      Hosts and Clusters
       inventory, select the cluster that contains the ESXi hosts and click the
      Monitor
       tab.
    2. In the left pane, under
      vSAN
      Skyline health
      , click
      Retest
       and confirm the operation.
    3. Verify no red alerts appear in the
      Overview
       pane.
    4. In the left pane, under
      vSAN
      Resyncing objects
      , verify that all synchronization tasks are complete.
  3. Place the ESXi host in maintenance mode.
    1. In the
      Hosts and Clusters
       inventory, expand the workload domain vCenter Server and navigate to the first ESXi host in the first cluster.
    2. Right click on the ESXi host and select
      Maintenance Mode
      Enter Maintenance mode
      .
    3. In the
      Enter maintenance mode
       dialog box, from the
      vSAN data migration
       drop-down menu, select
      Full data migration
      , and click
      OK
      .
  4. Deactivate ESXi lockdown mode.
    1. Click the
      Configure
       tab for the ESXI host.
    2. Under
      System
      , select
      Security Profile
      .
    3. In the
      Lockdown Mode
       pane, click
      Edit
      .
    4. In the
      Lockdown Mode
       dialog box, on the
      Lockdown Mode
       page, select
      Disabled
      .
    5. Click
      OK
      .
  5. Disconnect the ESXi host from vCenter Server.
    1. In the
      Hosts and Clusters
       inventory, right-click the ESXi host and select
      Connection
      Disconnect
      .
    2. In confirmation dialog box, click
      OK
      .
  6. Back up the current ESXi host certificate.
    1. Log in to the ESXi Shell by using the DCUI or an SSH client as a user with
      administrator
       privileges.
    2. In the
      /etc/vmware/ssl
       directory, rename the existing certificates by running the following commands. 
      cp rui.crt 
      esxi-hostname
      -orig.rui.crt
cp rui.key 
      esxi-hostname
      -orig.rui.key
    3. Export the
      esxi-hostname
      -orig.rui.crt
       and
      esxi-hostname
      -orig.rui.key
       files from the ESXi host, for example, by using an SCP utility, such as WinSCP.
  7. Replace the ESXi host certificate.
    1. Copy the
      esxi-hostname
      .cer
       and
      esxi-hostname
      .key
       certificate files, received from the certificate authority, to the
      /etc/vmware/ssl
       directory on the hosts, for example, by using an SCP utility, such as WinSCP.
    2. In the ESXi Shell, in the
      /etc/vmware/ssl
       folder, rename both
      esxi-hostname
      .cer
       and
      esxi-hostname
      .key
       to
      rui.crt
       and
      rui.key
      , respectively, by running the following commands.
      Confirm any file replacement.
      mv /etc/vmware/ssl/
      esxi-hostname
      .cer rui.crt
mv /etc/vmware/ssl/
      esxi-hostname
      .key rui.key
    3. Restart the ESXi host by running the following command.
      reboot
  8. In the vSphere Client, in the
    Hosts and Clusters
     inventory, right-click the ESXi host and select
    Connection
    Connect
    .
  9. Verify the ESXi host certificate has been replaced successfully after the restart.
    1. Click the
      Configure
       tab for the ESXI host.
    2. Under
      System
      , select
      Certificate
      .
    3. Verify the issuer and valid dates of the certificate match to CA-signed certificate.
    4. Verify that the
      Status
       is
      Good
      .
  10. If you are using vSAN as principal storage, verify the vSAN health.
  11. Verify ESXi host connectivity to SDDC Manager.
    1. Log in to SDDC Manager at
      https://<sddc_manager_fqdn>
       with a user assigned the
      Admin
       role.
    2. In the navigation pane, select
      Inventory
      Hosts
      .
    3. Verify the
      Configuration Status
       of the host is
      Active
      .
  12. Verify ESXi host connectivity to the NSX Manager instance for the workload domain.
    1. In the NSX Manager UI at
      https://<nsx_manager_fqdn>
      , click the
      System
       tab.
    2. Navigate to the host transport node.
      VMware Cloud Foundation Version
      Steps
      VMware Cloud Foundation 4.5
      1. In the navigation pane, select
        Fabric
        Nodes
        .
      2. Click the
        Host Transport Nodes
         tab.
      3. From
        Managed by
         drop-down menu, select the workload domain vCenter Server and expand the list.
      VMware Cloud Foundation 4.5.1 or later
      1. In the navigation pane, select
        Fabric
        Hosts
        .
      2. Click the
        Clusters
         tab.
    3. Verify that
      NSX configuration
       is
      Success
       and
      Node Status
       is
      Up
       for the ESXi host.
  13. In the vSphere Client, reactivate the lockdown mode of the ESXi host.
  14. Exit the maintenance mode of the ESXi host.
    1. In the vSphere Client, expand the workload domain vCenter Server and navigate to the ESXi host.
    2. Right-click the ESXi host and select
      Maintenance Mode
      Exit Maintenance mode
      .
  15. Repeat the procedure for the remaining ESXi hosts in the cluster.
  16. Repeat the procedure for the hosts in the remaining clusters in the workload domain.

PowerShell Procedure

  1. Start Windows PowerShell.
  2. Replace the values in the sample code and run the commands in the PowerShell console.
    $sddcManagerFqdn = "sfo-vcf01.sfo.rainpole.io" 
$sddcManagerUser = "administrator@vsphere.local" 
$sddcManagerPass = "VMw@re1!" 
$cluster = "sfo-m01-cl01" 
$workloadDomain = "sfo-m01"
$certificateDirectory = "F:\Certificate"
$certificateFileExt = ".cer"
  3. If you are using vSAN as principal storage, to verify the vSAN health status, run the following command and verify that the output contains no red alerts.
    Get-vSANHealthSummary -server $sddcManagerFqdn -user $sddcManagerUser -pass $sddcManagerPass -domain $workloadDomain -cluster $cluster
  4. The
    Install-VCFCertificate
     command that you run to replace the host certificates does not back up the original ESXi certificate and private key.
  5. Replace the ESXi host certificate by running the following command.
    Install-VCFCertificate -esxi -server $sddcManagerFqdn -user $sddcManagerUser -pass $sddcManagerPass -domain $workloadDomain -cluster $cluster -certificateDirectory $certificateDirectory  -certificateFileExt $certificateFileExt
    The command output shows
    successfully completed certificate replacement
    .
  6. If you are using vSAN as principal storage, verify the vSAN health status again.
  7. Repeat the procedure for the remaining clusters in the workload domain.

What to do next

Because the ESXi certificate mode is set to custom, before adding ESXi hosts to the workload domain, replace their certificates with CA-signed ones.

Restore the Certificate of an ESXi Host in a Workload Domain from a Backup

If you run into issues during ESXi certificate replacement, you can restore the original certificate setup of a host from the backup you took before the replacement operation.

Procedure

  1. Log in to the workload domain vCenter Server that manages the target host at
    https://<vcenter-server_fqdn>/ui
     as
    administrator@vsphere.local
    .
  2. Place the ESXi host in maintenance mode.
    1. In the
      Hosts and Clusters
       inventory, expand the workload domain vCenter Server and navigate to the first ESXi host in the first cluster.
    2. Right click on the ESXi host and select
      Maintenance mode
      Enter maintenance mode
      .
    3. For a vSAN cluster, in the
      Enter maintenance mode
       dialog box, from the
      vSAN data migration
       drop-down menu, select
      Full data migration
      , and click
      OK
      .
  3. Deactivate ESXi Lockdown mode.
    1. Click the
      Configure
       tab for the ESXI host.
    2. Under
      System
      , select
      Security Profile
      .
    3. In the
      Lockdown Mode
       pane, click
      Edit
      .
    4. In the
      Lockdown Mode
       dialog box, on the
      Lockdown Mode
       page, select
      Disabled
      .
    5. Click
      OK
      .
  4. Deactivate ESXi lockdown mode by using the VMware Host Client.
    The ESXi host might be disconnected from the workload domain vCenter Server because of authentication issues caused by the unsuccessful certificate replacement on the host.
    1. Log in to the ESXi host at
      https://
      <esxi_host_fqdn>
      /ui
       as
      root
      .
    2. In the navigation pane, select
      Manage
      Security & users
      .
    3. Select
      Lockdown Mode
       and click
      Edit settings
      .
    4. Select
      Disabled
       and click
      Change
      .
  5. Disconnect the ESXi host from vCenter Server.
    1. In the vSphere Client, in the
      Hosts and Clusters
       inventory, right-click the ESXi host and select
      Connection
      Disconnect
      .
    2. In confirmation dialog box, click
      OK
      .
  6. Restore the original ESXi host certificate.
    1. Copy the original certificate files
      esxi-hostname
      -orig.rui.crt
       and
      esxi-hostname
      -orig.rui.key
       to the
      /etc/vmware/ssl
       directory on the host, for example, by using an SCP utility, such as WinSCP..
    2. Log in to the ESXi Shell, using either the DCUI or an SSH client, as a user with
      administrator
       privileges.
    3. In the
      /etc/vmware/ssl
       directory, rename
      esxi-hostname
      -orig.rui.crt
       and
      esxi-hostname
      -orig.rui.key
       to
      rui.crt
       and
      rui.key
      , respectively, by running the following commands.
      mv /etc/vmware/ssl/
      esxi-hostname
      -orig.rui.crt rui.crt
mv /etc/vmware/ssl/
      esxi-hostname
      -orig.rui.key rui.key
    4. Restart the ESXi host by running the following command.
      reboot
  7. In the vSphere Client, in the
    Hosts and Clusters
     inventory, right-click the ESXi host and select
    Connection
    Connect
    .
  8. Verify the ESXi host certificate has been replaced successfully after the restart.
    1. Click the
      Configure
       tab for the ESXI host.
    2. Under
      System
      , select
      Certificate
      .
    3. Verify the issuer and valid dates of the certificate match to CA-signed certificate.
    4. Verify that the
      Status
       is
      Good
      .
  9. If you are using vSAN as principal storage, verify the vSAN health.
    1. In the
      Hosts and Clusters
       inventory, select the cluster that contains the ESXi hosts and click the
      Monitor
       tab.
    2. In the left pane, under
      vSAN
      Skyline health
      , click
      Retest
       and confirm the operation.
    3. Verify no red alerts appear in the
      Overview
       pane.
    4. In the left pane, under
      vSAN
      Resyncing objects
      , verify that all synchronization tasks are complete.
  10. Verify ESXi host connectivity to SDDC Manager.
    1. Log in to SDDC Manager at
      https://<sddc_manager_fqdn>
       with a user assigned the
      Admin
       role.
    2. In the navigation pane, select
      Inventory
      Hosts
      .
    3. Verify the
      Configuration Status
       of the host is
      Active
      .
  11. Verify ESXi host connectivity to the NSX Manager instance for the workload domain.
    1. In the NSX Manager UI at
      https://<nsx_manager_fqdn>
      , click the
      System
       tab.
    2. Navigate to the host transport node.
      VMware Cloud Foundation Version
      Steps
      VMware Cloud Foundation 4.5
      1. In the navigation pane, select
        Fabric
        Nodes
        .
      2. Click the
        Host Transport Nodes
         tab.
      3. From
        Managed by
         drop-down menu, select the workload domain vCenter Server and expand the list.
      VMware Cloud Foundation 4.5.1 or later
      1. In the navigation pane, select
        Fabric
        Hosts
        .
      2. Click the
        Clusters
         tab.
    3. Verify that
      NSX configuration
       is
      Success
       and
      Node Status
       is
      Up
       for the ESXi host.
  12. Exit the maintenance mode of the ESXi host.
    1. In the vSphere Client, expand the workload domain vCenter Server and navigate to the ESXi host.
    2. Right-click the ESXi host and select
      Maintenance mode
      Exit maintenance mode
      .

Content feedback and comments