How vSphere Auto Deploy Works with PowerCLI

Managing vSphere Auto Deploy with PowerCLI Cmdlets

You can manage vSphere Auto Deploy with PowerCLI cmdlets to create rules that associate hosts with image profiles, host profiles, custom scripts and locations on the vCenter Server target. You can also update hosts by testing rule compliance and repairing compliance issues.

Overview of the vSphere Auto Deploy Process by Using PowerCLI

Getting started with vSphere Auto Deploy requires that you learn how vSphere Auto Deploy works, install the vSphere Auto Deploy server, install PowerCLI, write PowerCLI rules that provision hosts, and power on your hosts to be booted with the image profile you specify. You can customize of the image profile, host profile, and vCenter Server location.

See vSphere PowerCLI Scenario for vSphere Auto Deploy for a step-by-step exercise that helps you set up your first vSphere Auto Deploy environment.

To provision the hosts in your environment with vSphere Auto Deploy successfully, you can follow these steps.

Deploy vCenter Server.
The vSphere Auto Deploy server is included.
Configure the vSphere Auto Deploy service startup type.
See Prepare Your System for vSphere Auto Deploy.
Install PowerCLI, which includes vSphere Auto Deploy and vSphere ESXi Image Builder cmdlets.
See Configure vSphere ESXi Image Builder, Using vSphere Auto Deploy Cmdlets, and Using VMware.Image Builder Cmdlets.
Find the image profile that includes the VIBs that you want to deploy to your hosts.
- Usually, you add the depots containing the required software to your PowerCLI session, and then select an image profile from one of those depots.
- To create a custom image profile, use vSphere ESXi Image Builder cmdlets to clone an existing image profile and add the custom VIBs to the clone. Add the custom image profile to the PowerCLI session.
You must use vSphere ESXi Image Builder for customization only if you have to add or remove VIBs. In most cases, you can add the depot where VMware hosts the image profiles to your PowerCLI session as a URL.
Start a PowerCLI session and connect to the vCenter Server system that vSphere Auto Deploy is registered with.
Use the New-DeployRule PowerCLI cmdlet to write a rule that assigns the image profile to one host, to multiple hosts specified by a pattern, or to all hosts.
```
New-DeployRule -Name "testrule" -Item image-profile -AllHosts
```
See Assign an Image Profile to Hosts.

Note: vSphere Auto Deploy is optimized for provisioning hosts that have a fixed MAC address to IP address mapping in DHCP (sometimes called DHCP reservations). If you want to use static IP addresses, you must set up the host profile to prompt for host customization. For more information, see the vSphere Host Profiles documentation.
Power on the hosts that you want to provision.
Set up the host you provisioned as a reference host for your host profile.
You can specify the reference host syslog settings, firewall settings, storage, networking, and so on.
Set up the host you provisioned as a reference host for your host profile.
You can specify the reference host syslog settings, firewall settings, storage, networking, and so on. See Setting Up a vSphere Auto Deploy Reference Host.
Create and export a host profile for the reference host.
See the Host Profiles documentation.
To provision multiple hosts with the host profile, use the Copy-DeployRule cmdlet to edit the previously created rule.
You can revise the rule to assign not only an image profile but also a host profile, a vCenter Server location, and a custom script bundle.
```
Copy-DeployRule -DeployRule "testrule" -ReplaceItem my_host_profile_from_reference_host,my_target_cluster
               -ReplacePattern  "ipv4=192.XXX.1.10-192.XXX.1.20"
```
Where my_host_profile_from_reference_host is the name of the reference host profile, and my_target_cluster is the name of the target cluster.
Perform the test and repair compliance operations to remediate the hosts.
See Test and Repair Rule Compliance.
Verify that the hosts you provisioned meet the following requirements.
- Each host is connected to the vCenter Server system.
- The hosts are not in maintenance mode.
- The hosts have no compliance failures.
- Each host with a host profile that requires user input has up-to-date host customization information.
Remediate host associations and compliance problems and reboot hosts until all hosts meet the requirements.

Read for an introduction to the boot process, differences between first and subsequent boots, and an overview of using host customization.

Using vSphere Auto Deploy Cmdlets

vSphere Auto Deploy cmdlets are implemented as Microsoft PowerShell cmdlets and included in PowerCLI. Users of vSphere Auto Deploy cmdlets can take advantage of all PowerCLI features.

Experienced PowerShell users can use vSphere Auto Deploy cmdlets just like other PowerShell cmdlets. If you are new to PowerShell and PowerCLI, the following tips might be helpful.

You can type cmdlets, parameters, and parameter values in the PowerCLI shell.

Get help for any cmdlet by running Get-Helpcmdlet_name.
Remember that PowerShell is not case sensitive.
Use tab completion for cmdlet names and parameter names.
Format any variable and cmdlet output by using Format-List or Format-Table, or their short forms fl or ft. For more information, run the Get-Help Format-List cmdlet.

Passing Parameters by Name

You can pass in parameters by name in most cases and surround parameter values that contain spaces or special characters with double quotes.

 Copy-DeployRule -DeployRule testrule -ReplaceItem MyNewProfile

Most examples in the vCenter Server Installation and Setup documentation pass in parameters by name.

Passing Parameters as Objects

You can pass parameters as objects if you want to perform scripting and automation. Passing in parameters as objects is useful with cmdlets that return multiple objects and with cmdlets that return a single object. Consider the following example.

Bind the object that encapsulates rule set compliance information for a host to a variable.
```
$tr = Test-DeployRuleSetCompliance MyEsxi42
```
View the itemlist property of the object to see the difference between what is in the rule set and what the host is currently using.
```
$tr.itemlist
```
Remediate the host to use the revised rule set by using the Repair-DeployRuleSetCompliance cmdlet with the variable.
```
Repair-DeployRuleSetCompliance $tr
```

The example remediates the host the next time you boot the host.

vSphere Auto Deploy PowerCLI Cmdlet Overview

You specify the rules that assign image profiles and host profiles to hosts using a set of PowerCLI cmdlets that are included in PowerCLI.

If you are new to PowerCLI, read thePowerCLI documentation and review Using vSphere Auto Deploy Cmdlets. You can get help for any command at the PowerShell prompt.

Basic help: Get-Help cmdlet_name
Detailed help: Get-Help cmdlet_name -Detailed

Note: When you run vSphere Auto Deploy cmdlets, provide all parameters on the command line when you invoke the cmdlet. Supplying parameters in interactive mode is not recommended.

Table 1. Rule Engine PowerCLI Cmdlets
Command	Description
Get-DeployCommand	Returns a list of vSphere Auto Deploy cmdlets.
New-DeployRule	Creates a new rule with the specified items and patterns.
Set-DeployRule	Updates an existing rule with the specified items and patterns. You cannot update a rule that is part of a rule set.
Get-DeployRule	Retrieves the rules with the specified names.
Copy-DeployRule	Clones and updates an existing rule.
Add-DeployRule	Adds one or more rules to the working rule set and, by default, also to the active rule set. Use the NoActivate parameter to add a rule only to the working rule set.
Remove-DeployRule	Removes one or more rules from the working rule set and from the active rule set. Run this command with the -Delete parameter to completely delete the rule.
Set-DeployRuleset	Explicitly sets the list of rules in the working rule set.
Get-DeployRuleset	Retrieves the current working rule set or the current active rule set.
Switch-ActiveDeployRuleset	Activates a rule set so that any new requests are evaluated through the rule set.
Get-VMHostMatchingRules	Retrieves rules matching a pattern. For example, you can retrieve all rules that apply to a host or hosts. Use this cmdlet primarily for debugging.
Test-DeployRulesetCompliance	Checks whether the items associated with a specified host are in compliance with the active rule set.
Repair-DeployRulesetCompliance	Given the output of Test-DeployRulesetCompliance, this cmdlet updates the image profile, host profile, and location for each host in the vCenter Server inventory. The cmdlet might apply image profiles, apply host profiles, or move hosts to prespecified folders or clusters on the vCenter Server system.
Apply-EsxImageProfile	Associates the specified image profile with the specified host.
Get-VMHostImageProfile	Retrieves the image profile in use by a specified host. This cmdlet differs from the Get-EsxImageProfile cmdlet in vSphere ESXi Image Builder.
Repair-DeployImageCache	Use this cmdlet only if the vSphere Auto Deploy image cache is accidentally deleted.
Get-VMHostAttributes	Retrieves the attributes for a host that are used when the vSphere Auto Deploy server evaluates the rules.
Get-DeployMachineIdentity	Returns a string value that vSphere Auto Deploy uses to logically link an ESXi host in vCenter Server to a physical machine.
Set-DeployMachineIdentity	Logically links a host object in the vCenter Server database to a physical machine. Use this cmdlet to add hosts without specifying rules.
Get-DeployOption	Retrieves the vSphere Auto Deploy global configuration options. This cmdlet currently supports the vlan-id option, which specifies the default VLAN ID for the ESXi Management Network of a host provisioned with vSphere Auto Deploy. vSphere Auto Deploy uses the value only if the host boots without a host profile.
Set-DeployOption	Sets the value of a global configuration option. Currently supports the vlan-id option for setting the default VLAN ID for the ESXi Management Network.
Add-ProxyServer	Adds a proxy server to the vSphere Auto Deploy database. Run the command with the -Address parameter to specify the IPv4 or IPv6 address. The address can include a port number.
List-ProxyServer	Lists the proxy servers that are currently registered with vSphere Auto Deploy.
Delete-ProxyServer	Deletes one or more proxy servers from the list of proxy servers that are registered with vSphere Auto Deploy. You can run the command with the -id parameter from the list of proxy servers or with the-Address parameter by specifying the IPv4 or IPv6 address of the proxy server you want to delete.
Add-ScriptBundle	Adds one or more script bundles to the vSphere Auto Deploy server.
Get-ScriptBundle	Retrieves the list of script bundles available on the vSphere Auto Deploy server and the scripts they contain.
Remove-ScriptBundle	Removes a script bundle from vSphere Auto Deploy. Applicable for vSphere version 6.7 and later.
Get-CustomCertificate	Retrieves the custom host certificate uploaded into AutoDeploy. You must run the command with the -HostId [MAC_Address \| BIOS_UUID] parameter. The first time you add custom certificates, you don't see any certificates returned by this cmdlet.
List-CustomCertificates	Retrieves information about all custom host certificates used by Auto Deploy. The list provides details for the name of the certificate, Host ID, and Associated Host Name, which reflects the name of the vCenter Server for the Auto Deploy server.
Add-CustomCertificate	Adds a custom certificate to the VMware Endpoint Certificate Store and associates it with an ESXi host. The certificate becomes active upon host reboot. You can use the Get-CustomCertificate cmdlet to retrieve the custom host certificate key. You can run the command with the -HostId [MAC_Address \| BIOS_UUID] parameter to associate the certificate to the host, specifying a -Key [file:///path/to/key.key] and -Cert [file:///path/to/cert.crt]. Using this cmdlet requires the AutoDeploy.Rule.Create privilege on the root folder of vCenter Server.
Remove-CustomCertificate	Removes a set of custom host certificates from Auto Deploy. The certificate entries are deleted from the database and the certificate files are removed from the filestore. Hosts that have already booted with a custom certificate must be rebooted to receive a new certificate. You must provide at least one of -Cert or -HostId parameters. Using this cmdlet requires the AutoDeploy.Rule.Create privilege on the root folder of vCenter Server.

Assign an Image Profile to Hosts

Before you can provision a host, you must create rules that assign an image profile to each host that you want to provision by using vSphere Auto Deploy.

vSphere Auto Deploy extensibility rules enforce that VIBs at the CommunitySupported level can only contain files from certain predefined locations, such as the ESXCLI plug-in path, jumpstart plug-in path, and so on. If you add a VIB that is in a different location to an image profile, a warning results. You can override the warning by using the force option.

If you call the New-DeployRule cmdlet on an image profile that includes VIBs at the CommunitySupported level which violate the rule, set $DeployNoSignatureCheck = $true before adding the image profile. With that setting, the system ignores signature validation and does not perform the extensibility rules check.

Note: Image profiles that include VIBs at the CommunitySupported level are not supported on production systems.

Procedure

In a PowerCLI session, run the Connect-VIServer cmdlet to connect to the vCenter Server system that vSphere Auto Deploy is registered with.
```
Connect-VIServer ipv4_or_ipv6_address
```
The cmdlet might return a server certificate warning. In a production environment, make sure no server certificate warnings result. In a development environment, you can ignore the warning.
Determine the location of a public software depot, or define a custom image profile by using vSphere ESXi Image Builder.

Run Add-EsxSoftwareDepot to add the software depot that contains the image profile to the PowerCLI session.

Depot Type	Cmdlet
Remote depot	Run `Add-EsxSoftwareDepot depot_url`.
ZIP file	Download the ZIP file to a local file path. Run `Add-EsxSoftwareDepot C:\file_path\my_offline_depot.zip`.

In the depot, find the image profile that you want to use by running the Get-EsxImageProfile cmdlet.
By default, the ESXi depot includes one base image profile that includes VMware tools and has the string standard in its name, and one base image profile that does not include VMware tools.
Define a rule in which hosts with certain attributes, for example a range of IP addresses, are assigned to the image profile.
```
New-DeployRule -Name "testrule" -Item "My Profile25" -Pattern "vendor=Acme,Zven", "ipv4=192.XXX.1.10-192.XXX.1.20"
```
Double quotes are required if a name contains spaces, optional otherwise. Specify -AllHosts instead of a pattern to apply the item to all hosts.
The cmdlet creates a rule named testrule. The rule assigns the image profile named My Profile25 to all hosts with a vendor of Acme or Zven that also have an IP address in the specified range.
Add the rule to the rule set.
```
Add-DeployRule testrule
```
By default, the rule is added to both the working rule set and the active rule set. If you use the NoActivate parameter, the working rule set does not become the active rule set.

Results

When the host boots from iPXE, it reports attributes of the machine to the console. Use the same format of the attributes when writing deploy rules.

******************************************************************
* Booting through VMware AutoDeploy...
*
* Machine attributes:
* . asset=No Asset Tag
* . domain=vmware.com
* . hostname=myhost.mycompany.com
* . ipv4=XX.XX.XXX.XXX
* . mac=XX:Xa:Xb:Xc:Xx:XX
* . model=MyVendorModel
* . oemstring=Product ID: XXXXXX-XXX
* . serial=XX XX XX XX XX XX...
* . uuid=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX
* . vendor=MyVendor
******************************************************************

What to do next

For hosts already provisioned with vSphere Auto Deploy, perform the compliance testing and repair operations to provision them with the new image profile. See Test and Repair Rule Compliance.
Turn on unprovisioned hosts to provision them with the new image profile.

Write a Rule and Assign a Host Profile to Hosts

vSphere Auto Deploy can assign a host profile to one or more ESXi hosts.

In many cases, you assign a host to a cluster instead of specifying a host profile explicitly. The host uses the host profile of the cluster.

Prerequisites

The host profile might include information about storage configuration, network configuration, or other characteristics of the host. If you add a host to a cluster, that cluster's host profile is used.

Install PowerCLI and all prerequisite software. For information, see vCenter Server Installation and Setup.
Export the host profile that you want to use.

Procedure

In a PowerCLI session, run the Connect-VIServer cmdlet to connect to the vCenter Server system that vSphere Auto Deploy is registered with.
```
Connect-VIServer ipv4_or_ipv6_address
```
The cmdlet might return a server certificate warning. In a production environment, make sure no server certificate warnings result. In a development environment, you can ignore the warning.
Using the vSphere Client, set up a host with the settings you want to use and create a host profile from that host.
Find the name of the host profile by running Get-VMhostProfile PowerCLI cmdlet, passing in the ESXi host from which you create a host profile.
At the PowerCLI prompt, define a rule in which host profiles are assigned to hosts with certain attributes, for example a range of IP addresses.
```
New-DeployRule -Name "testrule2" -Item my_host_profile -Pattern "vendor=Acme,Zven", "ipv4=192.XXX.1.10-192.XXX.1.20"
```
The specified item is assigned to all hosts with the specified attributes. This example specifies a rule named testrule2. The rule assigns the specified host profile my_host_profile to all hosts with an IP address inside the specified range and with a manufacturer of Acme or Zven.
Add the rule to the rule set.
```
Add-DeployRule testrule2
```
By default, the working rule set becomes the active rule set, and any changes to the rule set become active when you add a rule. If you use the NoActivate parameter, the working rule set does not become the active rule set.

What to do next

Assign a host already provisioned with vSphere Auto Deploy to the new host profile by performing compliance test and repair operations on those hosts. For more information, see Test and Repair Rule Compliance.
Power on unprovisioned hosts to provision them with the host profile.

Write a Rule and Assign a Host to a Folder or Cluster

vSphere Auto Deploy can assign a host to a folder or cluster. When the host boots, vSphere Auto Deploy adds it to the specified location on the vCenter Server. Hosts assigned to a cluster inherit the cluster's host profile.

Prerequisites

Prepare your system and install the Auto Deploy Server. For more information, see Prepare Your System for vSphere Auto Deploy.
Verify that the folder you select is in a data center or in a cluster. You cannot assign the host to a standalone top-level folder.

Procedure

In a PowerCLI session, run the Connect-VIServer cmdlet to connect to the vCenter Server system that vSphere Auto Deploy is registered with.
```
Connect-VIServer ipv4_or_ipv6_address
```
The cmdlet might return a server certificate warning. In a production environment, make sure no server certificate warnings result. In a development environment, you can ignore the warning.
Define a rule in which hosts with certain attributes, for example a range of IP addresses, are assigned to a folder or a cluster.
```
New-DeployRule -Name testrule3 -Item "my folder"	-Pattern "vendor=Acme,Zven", "ipv4=192.XXX.1.10-192.XXX.1.20"
```
This example passes in the folder by name. You can instead pass in a folder, cluster, or data center object that you retrieve with the Get-Folder, Get-Cluster, or Get-Datacenter cmdlet.
Add the rule to the rule set.
```
Add-DeployRule testrule3
```
By default, the working rule set becomes the active rule set, and any changes to the rule set become active when you add a rule. If you use the NoActivate parameter, the working rule set does not become the active rule set.

What to do next

Assign a host already provisioned with vSphere Auto Deploy to the new folder or cluster location by performing test and repair compliance operation. See Test and Repair Rule Compliance.
Power on unprovisioned hosts to add them to the specified vCenter Server location.

Configure a Stateless System by Running a Custom Script

You can use vSphere Auto Deploy to configure one or more hosts by associating custom scripts with a vSphere Auto Deploy rule.

The scripts run in alphabetical order after the initial ESXi boot workflow of the host.

Prerequisites

Verify that the script bundle you want to associate with a vSphere Auto Deploy rule is in .tgz format, with a maximum size of 10 MB, and written in Python or BusyBox ash scripting language.

Procedure

In a PowerCLI session, run the Connect-VIServer cmdlet to connect to the vCenter Server system that vSphere Auto Deploy is registered with.
```
Connect-VIServer ipv4_or_ipv6_address
```
The cmdlet might return a server certificate warning. In a production environment, make sure no server certificate warnings result. In a development environment, you can ignore the warning.
Run the Add-ScriptBundle cmdlet to add the script bundle that contains the necessary scripts to the vSphere Auto Deploy inventory.
```
Add-ScriptBundle c:/temp/MyScriptBundle.tgz
```
The name of the script bundle without the .tgz extension is the name identifier or object of the script bundle item. You can update an existing script bundle by using the -Update parameter with the Add-ScriptBundle cmdlet.
(Optional) Run the Get-ScriptBundle cmdlet to verify that the script bundle is added to the vSphere Auto Deploy inventory.
Define a rule in which hosts with certain attributes, for example a range of IP addresses, are assigned to the script bundle.
```
New-DeployRule -Name "testrule4" -Item "MyScriptBundle" -Pattern "vendor=Acme,Zven", "ipv4=192.XXX.1.10-192.XXX.1.20"
```
Double quotes are required if a name contains spaces, optional otherwise. Specify -AllHosts instead of a pattern to apply the item to all hosts.
You create a rule named testrule4. The rule assigns the script bundle named My Script Bundle to all hosts with a vendor of Acme or Zven that also have an IP address in the specified range. You can use the name identifier of the script bundle or the object returned by the Get-ScriptBundle cmdlet to identify the script bundle you want to associate with the rule.
Add the rule to the rule set.
```
Add-DeployRule testrule4
```
By default, the rule is added to both the working rule set and the active rule set. If you use the NoActivate parameter, the working rule set does not become the active rule set.

What to do next

For hosts already provisioned with vSphere Auto Deploy, perform the compliance testing and repair operations to provision them with the new scripts. See Test and Repair Rule Compliance.
Turn on unprovisioned hosts to provision them with the new scripts.

Test and Repair Rule Compliance

Test new or modified rules for compliance and repair accordingly, as changes in the vSphere Auto Deploy rule set are not updated automatically.

Prerequisites

When you add a rule to the vSphere Auto Deploy rule set or modify one or more rules, hosts are not updated automatically. vSphere Auto Deploy applies the new rules only when you test their rule compliance and perform remediation.

Prepare your system and install the Auto Deploy Server. For more information, see Prepare Your System for vSphere Auto Deploy.
Verify that your infrastructure includes one or more ESXi hosts provisioned with vSphere Auto Deploy, and that the host on which you installed PowerCLI can access those ESXi hosts.

Procedure

In a PowerCLI session, run the Connect-VIServer cmdlet to connect to the vCenter Server system that vSphere Auto Deploy is registered with.
```
Connect-VIServer ipv4_or_ipv6_address
```
The cmdlet might return a server certificate warning. In a production environment, make sure no server certificate warnings result. In a development environment, you can ignore the warning.
Use PowerCLI to check which vSphere Auto Deploy rules are currently available.
```
Get-DeployRule
```
The system returns the rules and the associated items and patterns.
Modify one of the available rules.
For example, you can change the image profile and the name of the rule.
```
Copy-DeployRule -DeployRule testrule -ReplaceItem MyNewProfile 
			 
```
You cannot edit a rule already added to the active rule set. Instead, you can copy the rule and replace the item or pattern you want to change.
Verify that you can access the host for which you want to test rule set compliance.
```
Get-VMHost -Name MyEsxi42
```
Run the cmdlet that tests rule set compliance for the host, and bind the return value to a variable for later use.
```
$tr = Test-DeployRuleSetCompliance MyEsxi42
```
Examine the differences between the contents of the rule set and configuration of the host.
```
$tr.itemlist
```
If the host for which you want to test the new rule set compliance is compliant with the active rule set, the system returns a table of current and expected items.
```
CurrentItem                             ExpectedItem
-----------                             ------------   
My Profile 25                           MyNewProfile
```
Remediate the host to use the revised rule set the next time you boot the host.
```
Repair-DeployRuleSetCompliance $tr
```

What to do next

If the rule you changed specified the inventory location, the change takes effect when you repair compliance. For all other changes, reboot your host to have vSphere Auto Deploy apply the new rule and to achieve compliance between the rule set and the host.

Register a Caching Proxy Server Address with vSphere Auto Deploy

Simultaneously booting large number of stateless hosts places a significant load on the vSphere Auto Deploy server. You can load balance the requests between the vSphere Auto Deploy server and one or more proxy servers that you register with vSphere Auto Deploy.

Prerequisites

Procedure

In a PowerCLI session, run the Connect-VIServer cmdlet to connect to the vCenter Server system that vSphere Auto Deploy is registered with.
```
Connect-VIServer ipv4_or_ipv6_address
```
The cmdlet might return a server certificate warning. In a production environment, make sure no server certificate warnings result. In a development environment, you can ignore the warning.
Register a caching proxy server addresses with vSphere Auto Deploy by running the Add-ProxyServer cmdlet.
```
Add-ProxyServer -Address 'https://proxy_server_ip_address:port_number'
```
You can run the cmdlet multiple times to register multiple proxy servers. The address can contain a port number.
(Optional) Run the List-ProxyServer cmdlet to verify that the caching proxy server is registered with vSphere Auto Deploy.