In this chapter, you will learn to:
vCloud Director allows users to build multitenant private clouds on top of VMware infrastructure by creating virtual datacenters with server resources and providing it to their customers via a web-based portal. Although it is no longer available to new users, there are automation advantages for existing users and service providers.
This chapter takes you through some common tasks that can be automated within vCloud Director. Since vCloud Director is now only sold to service providers, the main focus of this chapter will be administration of the vCloud Director infrastructure. Administration and automation of tenants can be found in Chapter 20, “vCloud Air.” This chapter assumes that you have already deployed the vCloud Director product, that it has been configured at least to the point that the administrator can log into the vCloud Director homepage, and that vCloud Director is attached to a vCenter. From here, you will learn to automate tasks like creating provider virtual datacenters (vDCs), external networks, network pools, and organizations; allocating resources; and managing users.
To be able to connect to and administer in vCloud Director, you must ensure that the vCloud Air/vCD PowerCLI feature is installed. You select this feature during the installation of PowerCLI, and it provides cmdlets for automating vCloud Air and vCloud Director features. If PowerCLI was installed without the vCloud Air/vCD feature, you can rerun the PowerCLI installer and add this feature to continue (see Figure 19-1).
Use the code in Listing 19-1 to see a list of commands that can be run in vCloud Director. This will return all the cmdlets available for use within vCloud Director. Notice that a majority of these command names contain the characters CI
(for Cloud Infrastructure).
Listing 19-1: Obtaining a list of vCloud Director cmdlets
# Return any module ending in .Cloud and save it to a variable
$mod = Get-Module *.Cloud -ListAvailable
# Use the Get-Command cmdlet searching for the target module and filter on Cmdlet
Get-Command -Module $mod -Type Cmdlet | Select Name, ModuleName
Before you can work within the vCloud Director environment, you must log on to the target private cloud to authorize the PowerCLI session. You then can connect to vCloud Director using the Connect-CIServer
command:
Connect-CIServer -Server vCD.vmwarelab.com -User Administrator -Password VMware1!
At times, it is beneficial to run multiple PowerCLI sessions against vCloud Director at the same time. This may be through the use of PowerShell jobs, scripts invoking other scripts, and so on. You can leverage a single vCD logon across multiple sessions by grabbing the SessionSecret
from your main PowerCLI session when logging into vCloud Director:
$connection = Connect-CIServer -Server vCD.vmwarelab.com -User Administrator `
-Password VMware1!
You can also run this command without placing your credentials in your code by using the Get-Credential
cmdlet:
$connection = Connect-CIServer -Server vCD.vmwarelab.com -Credential `
(Get-Credential)
When prompted, enter your username and password without revealing it within your script. Once you’ve used that line of code to connect to vCloud Director, you can see your SessionSecret
:
$connection.SessionSecret
526da858-9d41-2760-7d90-4d30fc4635aa
You can then use the SessionSecret
to log into vCloud Director in your other PowerCLI sessions by using the -SessionID
parameter:
Connect-CIServer -Server vCD.vmwarelab.com -SessionID $connection.SessionSecret
This allows you to log on to other sessions without entering a username and password as long as the main connection stays active.
vCloud Director Organizations (also known as orgs) are the topmost containers whereon the rest of the private cloud is created. Within these organizations, administrators can create org vDCs (virtual datacenters), add local users, create vApps, manage catalog items, and allocate virtual resources. Service providers may find it necessary to create new orgs from time to time, as well as disable or remove orgs. This section will cover the administration and management of orgs.
Organizations are one of the objects that can be created using PowerCLI. The cmdlet New-Org
requires two parameters: Name
and FullName
.
New-Org -Name Customer1 -FullName Customer_X_Seattle `
-Description "This is Customer X in Seattle"
Org names and descriptions can easily be updated using the Set-Org
cmdlet as well:
Get-Org -Name Customer1 | Set-Org -FullName Customer_Y_Orlando `
-Description
"This customer is based out of Orlando
"
Once a new org is created, it is enabled by default. Generally this is fine, but sometimes administrators need to disable an organization. When this happens, it is easy to use PowerCLI to disable the target organizations:
Get-Org -Name Customer1 | Set-Org -Enabled:$false
When an org is disabled, it cannot deploy or power on any additional vApps until it has been re-enabled. An org must be disabled before it can be removed.
Each org requires its own org vDC network. More org vDC networks can be associated to each org. These networks fulfill different purposes within the org. There are three network types that can be used within the org:
You will most likely encounter each type of network throughout various org vDCs in your environment. You can use the following code to report on the networks that currently exist:
Get-OrgNetwork | Select Name, NetworkType, Gateway, `
PrimaryDns, SecondaryDns, Netmask
You may be asked from time to time to review the organizations in your environment. From a purely mathematical and operations point of view, simply running the Get-Org
cmdlet and filtering out unwanted information to leave you with the name of the org, settings, and statistics will return the necessary information:
Get-Org | Select Name, FullName,Description, Enabled, `
CanPublish,DeployedVMQuota, StoredVMQuota, VdcCount, `
CatalogCount, VAppCount | Export-Csv `
-Path C:TempOrgSummary.CSV -NoTypeInformation -NoClobber
vCloud Director cmdlets do not allow for adding or modifying users, but they are available for reporting and auditing. These cmdlets allow administrators to quickly and easily create these reports to validate the settings, roles, and properties of users in each org. The Get-CIUser
and Get-CIRole
cmdlets can be used together for more in-depth views of the users configuration.
Get-Org | Foreach { `
Write-Host " Org: $($_.Name) " -ForegroundColor Green; `
Get-CIUser -Org $_ | Foreach { `
Write-Host $_.Name -ForegroundColor yellow; `
Get-CIRole -user $_.Name}}
It is critical to create rules and roles for objects within your private cloud environment. As in vCenter, you can define roles and rights for different users and groups within vCloud Director. It is wise to review each access control rule periodically. In addition to the roles and rights given to users and groups, you can set access control levels on objects within your vCloud Director environment.
To create new access control rules, use the New-CIAccessControlRule
cmdlet. This requires several parameters to succeed: -AccessLevel
, -User
or -EveryoneInOrg
, and -Entity
. The access level allows you to specify Read
, ReadWrite
, or FullControl
permissions for the selected object. You can choose specific users for a given access level, or you can set it for everyone in the organization of the selected object. Entity refers to the object that will receive the access control rules; this may be either a catalog or a vApp object.
Let’s say that you do not want others to be able to change the configuration of a specific vApp. You could create a new access control rule that gives all users read-only access to that vApp:
New-CIAccessControlRule -Entity 'SecuredVApp' -EveryoneInOrg `
-AccessLevel "Read" -Confirm:$false
Once you are connected to a vCloud Director server, you can retrieve a listing of all access control rules using a simple Get-CIAccessControlRule
cmdlet, which will return all the rules that have been created for the entire vCloud Director environment. (It is wise to review this list periodically.)
Get-CIAcessControlRule
You can specify the scope of this cmdlet and return rules that have been created based on the catalog or vApp object, user, or access level. Use the Sort-Object
cmdlet to organize the results:
Get-CIAccessControlRule | Sort-Object AccessLevel | `
Select Entity, AccessLevel, User
Note that if an access level has been set for EveryoneInOrg
, the user that is returned is the name of the organization rather than a specific user or a list of all the users included in the organization.
Once access control rules have been created, there may come a time that a specific rule needs to be modified. There are two different ways of changing a rule that has already been created. The best way to do it is to use the Set-CIAccessControlRule
cmdlet, which allows you to update the properties of an existing rule. The second way is to use the New-CIAccessControlRule
cmdlet and add the -Force
parameter, overwriting the settings of the previous rule.
Using the Set-CIAccessControlRule
, you can update the settings of a rule as follows:
$rule = Get-CIAccessControlRule -Entity 'SecuredVApp' `
-User OrgVDC
$rule | Set-CIAccessControlRule -AccessLevel "FullControl"
or:
Get-CIAccessControlRule -Entity 'SecuredVApp'
-User OrgVDC| `
Set-CIAccessControlRule -AccessLevel "FullControl"
Both of these options achieve the same results.
Removing an access control rule is a simple task similar to that of modifying a rule. The one note of caution here is to make sure that you only delete the specific rule intended. To delete a rule, use the Get-CIAccessControlRule
cmdlet to specify the entity on which the rule resides:
Get-CIAccessControlRule -Entity 'SecuredVApp'
Once you verify that the command returns only the intended rule(s), you can press the up arrow in your PowerCLI session and pipe the results of the previous command to the Remove-CIAccessControlRule
cmdlet:
Get-CIAccessControlRule -Entity 'SecuredVApp'| Remove-CIAccessControlRule
There are two types of virtual datacenter constructs within vCloud Director:
vCloud Director does not have any native cmdlets for creating a provider vDC. Since the provider vDC must be set up and configured to build the rest of your private cloud, PowerCLI offers a single cmdlet to view the properties of a provider vDC: Get-ProviderVdc
. The Get-ProviderVdc
cmdlet returns a summary of all the provider vDCs and includes the status, resources used, and whether the vDC is enabled or disabled.
Get-ProviderVdc
More information can be pulled from this cmdlet by piping the results to a formatted list (fl
):
Get-ProviderVdc | fl *
Href : https://vcd-l-01a/api/admin/extension/provid
ervdc/a1891824-e45f-43b6-acab-a9492c8aead9
StorageUsedGB :
StorageOverheadGB :
StorageTotalGB : 0
StorageAllocatedGB:
Status : Ready
MemoryUsedGB : 2.34765625
MemoryOverheadGB : 0
MemoryTotalGB : 2.60546875
MemoryAllocatedGB : 0
Enabled : True
CpuUsedGHz : 0
CpuOverheadGHz : 0
CpuTotalGHz : 7.614
CpuAllocatedGHz : 0
ExtensionData : VMware.VimAutomation.Cloud.Views.VMWProvider
Vdc
Description : example pVDC
Id : urn:vcloud:providervdc:a1891824-e45f-43b6-ac
ab-a9492c8aead9
Name : MainpVDC
Client : /CIServer=administrator:system@vcd-l-01a:443
Uid : /CIServer=administrator:system@vcd-l-01a:443
/ProviderVdc=urn:vcloud:providervdc:a1891824-e
45f-43b6-acab-a9492c8aead9/
As you can see, a bit more data is returned when you use the Format-List
cmdlet. You can create a report of provider vDCs that returns key information for the providers in your vCloud Director environment, as shown in Listing 19-2.
Listing 19-2: Provider vDC reporting
function Get-ProviderVdcReport {
<#
.SYNOPSIS
Report of all Provider vDCs in the environment
.DESCRIPTION
This function will write a report to CSV with key information
About each Provider vDC including resource information and
Other metrics.
.NOTES
Source: Automating vSphere Administration
.PARAMETER Path
Path is the destination and CSV name for where the report
will be exported to.
.PARAMETER Memory
Reports Memory metrics on each Provider vDC. Can be used
with -CPU and -Storage parameters
.PARAMETER CPU
Reports CPU metrics on each Provider vDC. Can be used
with -Memory and -Storage parameters
.PARAMETER Storage
Reports Storage metrics on each Provider vDC. Can be used
with -Memory and -CPU parameters
.PARAMETER All
Reports on all three parameters (Memory, CPU, Storage) and
must be called by itself.
.EXAMPLE
Get-ProviderVdcReport -Path c:TempProvidervDCReport.csv -All
Show all metric information for each pVDC
.EXAMPLE
Get-ProviderVdcReport -Path c:TempProvidervDCReport.csv `
-Storage -CPU
Show Storage and CPU metric information for each pVDC
#>
[CmdletBinding(DefaultParameterSetName = "All")]
param (
[Parameter(Mandatory = $True)]
[string]$Path,
# Set parameters into a ParameterSetName for grouping
[Parameter(ParameterSetName = 'Resources')]
[switch]$Memory,
[Parameter(ParameterSetName = 'Resources')]
[switch]$CPU,
[Parameter(ParameterSetName = 'Resources')]
[switch]$Storage,
# Set All in different ParameterSetName to not be used with Resources
[Parameter(ParameterSetName = 'All')]
[switch]$All = $true
)
process {
#Create empty array
$PvDCs = @()
foreach ($PvDC in (Get-ProviderVdc)) {
#Default pVDC information
$pVDCProperties = @{
Name = $PvDC.Name
Description = $PvDC.Description
Enabled = $PvDC.Enabled
Status = $PvDC.Status
}
#Storage
if (($Storage) -or ($All)) {
$pVDCProperties$pVDCProperties["StorageUsedGB"] = $PvDC.StorageUsedGB
$hshPropertiesForNewObj["StorageOverheadGB"] = $PvDC.StorageOverheadGB
$pVDCProperties["StorageTotalGB"] = $PvDC.StorageTotalGB
$pVDCProperties["StorageUsedPcnt"] = $(if ($PvDC.StorageTotalGB -gt 0) `
{($PvDC.StorageUsedGB / $PvDC.StorageTotalGB) * 100})
}
#Memory
if (($Memory) -or ($All)) {
$pVDCProperties["MemoryUsedGB"] = $PvDC.MemoryUsedGB
$pVDCProperties["MemoryOverheadGB"] = $PvDC.MemoryOverheadGB
$pVDCProperties["MemoryTotalGB"] = $PvDC.MemoryTotalGB
$pVDCProperties["MemoryAllocatedGB"] = $PvDC.MemoryAllocatedGB
$pVDCProperties["MemoryOverAllocatedPcnt"] = $(if ($PvDC.MemoryTotalGB `
-gt 0) {($PvDC.MemoryAllocatedGB / $PvDC.MemoryTotalGB) * 100})
}
#CPU
if (($CPU) -or ($All)) {
$pVDCProperties["CPUUsedGHz"] = $PvDC.CpuUsedGHz
$pVDCProperties["CpuOverheadGHz"] = $PvDC.CpuOverheadGHz
$pVDCProperties["CpuTotalGHz"] = $PvDC.CpuTotalGhz
$pVDCProperties["CpuAllocatedGHz"] = $PvDC.CpuAllocatedGHz
$pVDCProperties["CpuOverAllocatedPcnt"] = ($PvDC.CpuAllocatedGHz / `
$PvDC.CpuTotalGhz) * 100
}
$vDC = New-Object -TypeName PSObject -Property $pVDCProperties
}
#Set -NoClobber to not overwrite existing files
$PvDCs | Export-Csv "$Path" -NoTypeInformation -NoClobber
#Verify the file was created
if(!(Test-Path $Path)){Write-Warning "It appears that the CSV `
file was not created. Please try again."} else `
{Write-Verbose "File Saved Successfully to '$Path'"}
}
}
Within your organization, you can split up the resource allocation and configurations by using org vDCs. Org vDCs are partitioned from the resources of a provider vDC.
You can get a list of org vDCs by using the Get-OrgVdc
cmdlet. This cmdlet will return the same type of information that was returned in the previous section with Get-ProviderVdc
, only for the org subset:
Get-OrgVdc
You can narrow the results by provider vDC using the -ProviderVdc
parameter:
Get-OrgVdc -ProviderVdc MainpVDC
Listing 19-3 shows you how to export a report to CSV on all of your org vDCs along with critical information about CPU, storage, memory, and overall summary.
Listing 19-3: Org vDC report by org
function Get-OrgVdcSummary {
<#
.SYNOPSIS
Retrieve a summary of all Organization vDCs by Organization
.DESCRIPTION
Retrieves critical information about each Org vDC in the
environment
.NOTES
Source: Automating vSphere Administration
.PARAMETER Path
Specify the file path for the CSV output
.EXAMPLE
Get-OrgVdcSummary -Path C:TempOrgSummary.csv
#>
param(
[Parameter(Mandatory=$true)]
[ValidateNotNull()]
[String]$Path
)
process{
foreach ($Org in (Get-Org)){
foreach ($orgVDC in (Get-OrgvDC -Org $Org.Name)) {
$CurrentOrg = New-Object -TypeName PSObject -Property @{
Org = $Org.Name
OrgVDC = $orgVDC.Name
Description = $orgVDC.Description
Enabled = $orgVDC.Enabled
Status = $orgVDC.Status
ProviderVdc = $orgVDC.ProviderVdc
AllocationModel = $orgVDC.AllocationModel
VMMaxCount = $orgVDC.VMMaxCount
ThinProvisioning = $orgVDC.ThinProvisioning
FastProvisioning = $orgVDC.FastProvisioning
# Network Info
NetworkPool = $orgVDC.NetworkPool
NetworkMaxCount = $orgVDC.NetworkMaxCount
NicMaxCount = $orgVDC.NicMaxCount
# Storage Info
StorageUsedGB = $orgVDC.StorageUsedGB
StorageLimitGB = $orgVDC.StorageLimitGB
StorageAllocationGB = $orgVDC.StorageAllocationGB
StorageOverheadGB = $orgVDC.StorageOverheadGB
StorageUsedPcnt = ($orgVDC.StorageUsedGB / `
$orgVDC.StorageAllocationGB)*100
# Memory Info
MemoryGuaranteedPercent = $orgVDC.MemoryGuaranteedPercent
MemoryUsedGB = $orgVDC.MemoryUsedGB
MemoryLimitGB = $orgVDC.MemoryLimitGB
MemoryAllocationGB = $orgVDC.MemoryAllocationGB
MemoryOverheadGB = $orgVDC.MemoryOverheadGB
MemoryOverAllocatedPcnt = $(if ($orgVDC.MemoryAllocationGB -gt 0) `
{($orgVDC.MemoryAllocatedGB / $orgVDC.MemoryAllocationGB)*100})
# CPU Info
CPUGuaranteedPercent = $orgVDC.CPUGuaranteedPercent
VMCpuCoreMHz = $orgVDC.VMCpuCoreMHz
CPUUsedGhz = $orgVDC.CpuUsedGhz
CpuLimitGhz = $orgVDC.CpuLimitGhz
CPuOverheadGhz = $orgVDC.CpuOverheadGhz
CpuOverAllocatedPcnt = ($orgVDC.CpuUsedGHz / $orgVDC.CpuLimitGhz)*100
}
$CurrentOrg | Export-CSV $Path -Append -NoClobber `
-NoTypeInformation
}
}
}
}
vCloud Director uses a different method of organizing virtualizing workloads. All workloads are deployed as vApps, which are an organizational container for one or more virtual machines, their networking, and any policies associated with the VMs. The vApps can be set to boot the encapsulated virtual machines in a specific order as well as set shares and priorities for those machines.
We can use PowerCLI to either import vApps or create new vApp containers that we can populate with virtual machines afterward. If we create a new vApp, we are essentially only creating the container and will need to populate it with virtual machines. In Listing 19-4, we create a new vApp and then import several virtual machines from the underlying vSphere environment, placing them within the new vApp.
Listing 19-4: Creating vApp containers
# Create vApp Container
$NewVApp = New-CIVApp -Name TestvApp `
-Description "Newly Created vApp" -OrgVdc "OrgVdc1"
# Import each Apache VM into newly created vApp
Get-VM -Name Apache* | Foreach {
Import-CIVApp -VM $_ -VApp $NewVApp.Name
}
The code in Listing 19-4 creates a vApp, TestvApp
, and imports three virtual machines from vSphere (see Figure 19-2). Note that if we had added the -NoCopy
parameter to the Import-CIVApp
command, it would have moved the virtual machines out of vSphere and into vCD, rather than creating a copy.
PowerCLI gives you the ability to start, stop, restart, or suspend the vApps using the Start-CIVApp
, Stop-CIVApp
, Restart-CIVApp
, and Suspend-CIVApp
cmdlets, respectively. Running any of these four commands invokes the action specified on every virtual machine found within the vApp container. We recommend that all the virtual machines within the vApps be powered off when using these cmdlets, rather than performing the action against specific virtual machines inside the vApp. This ensures that the vApp will start up or shut down properly using the configuration that it has been given.
The Stop-CIVApp
and Restart-CIVApp
cmdlets do not perform their actions gracefully. By that, we mean that using those commands is the equivalent to hitting the power button or restart button on your computer chassis; it does not actually initiate a shutdown or restart at the guest operating system level. To be able to shut down or restart your vApps gracefully, you can use the Stop-CIVAppGuest
and Restart-CIVAppGuest
cmdlets, respectively. To execute properly, these cmdlets require that VMware Tools be installed and running within the virtual machines. These commands will perform the given action on each virtual machine within the vApp.
If it is determined that a vApp needs to be restarted (we recommend that you apply a power setting to the entire vApp rather than specific virtual machines), it is best to restart it gracefully:
Get-CIVApp -Name TestvApp | Restart-CIVAppGuest -Confirm:$false
You can replace Restart-CIVAppGuest
with Stop-CIVappGuest
in this code if you decide to shut the vApp down rather than restart it.
Set-CIVApp
allows you to modify the configuration of a given vApp. Using this cmdlet, you can change settings such as Description, Name, Owner, RenewLease, RuntimeLease, and StorageLease.
In the next example, we take the TestvApp
that runs three Apache virtual machines (created earlier in this chapter), rename it to something that more accurately reflects its purpose (ApachevApp
), add a description stating what the vApp used to be called, and set both a 10-day storage and runtime lease:
$lease = New-TimeSpan -Days 10
$vApp = Get-CIVapp -Name "TestvApp"
$vApp | Set-CIVApp -Name "ApachevApp" -Description "Renamed from TestvApp" | `
Set-CIVApp -StorageLease $Lease -RuntimeLease $Lease -RenewLease
vApp networks are the networks defined within the vApp container that allow communication between the virtual machines within the vApp. These networks have the ability to connect to an organization network to extend communication for the virtual machines in the vApp out past the container level to either an organization-wide network or an external network.
Get-CIVAppNetwork
retrieves all vApp networks found in your vCloud Director environment. You can use this cmdlet to retrieve specific types of vApp networks by using the -ConnectionType
parameter, which accepts the following values: Direct
, Fenced
, Isolated
, and Routed
. You can use the -ParentOrgNetwork
parameter to retrieve a list of all vApp networks connected there:
Get-CIVappNetwork -ConnectionType Routed
Get-CIVAppNetwork -ParentOrgNetwork 'Site A Intranet'
Creating new vApp networks is a little more complex in that the cmdlet, New-CIVAppNetwork
, has a number of required parameters. This cmdlet can be especially helpful in automating the bulk creation of vApp networks when pulling the needed information from a CSV file (Listing 19-5).
Listing 19-5: Bulk import of vApp networks from CSV
function Add-CIVAppNetwork {
<#
.SYNOPSIS
Bulk-import vAppNetworks from CSV
.DESCRIPTION
This function will allow you to bulk-import vAppNetworks from CSV
.NOTES
Headers Used in CSV: vApp,ParentOrgNetwork,NetType,Name,Description,`
DNSSuffix,Gateway,Netmask,PrimaryDNS,SecondaryDNS,StaticIPPool
Source: Automating vSphere Administration
ARAMETER CSV
Parameter used by the function to locate the import file
.EXAMPLE
Add-CIVappNetwork -CSV c: empvAppNetworks.csv
#>
param(
[Parameter(Mandatory=$True,Position=1)]
[ValidateNotNullOrEmpty()]
[String]$CSV
)
process{
$Source = Import-Csv -Path "$CSV"
foreach ($line in $Source) {
$hshParamForNewCIVAppNetwk = @{
VApp = $line.vApp
Routed = $true
Name = $line.Name
Description = $line.Description
DnsSuffix = $line.DNSSuffix
Gateway = $line.Gateway
Netmask = $line.Netmask
PrimaryDns = $line.PrimaryDNS
SecondaryDNS = $line.SecondaryDNS
StaticIPPool = $line.StaticIPPool
}
Switch ($line.NetType) {
{"Routed", "Direct" -contains $_} `
{$hshParamForNewCIVAppNetwk["ParentOrgNetwork"] `
= $line.ParentOrgNetwork}
"Isolated" {$hshParamForNewCIVAppNetwk["ParentOrgNetwork"] `
= $null}
}
Write-Verbose "Importing vApp Network: $($line.Name) for `
$($line.vApp)"
New-CIVAppNetwork @hshParamForNewCIVAppNetwk
}
}
}
$hshParamForNewCIVAppNetwk = @{
VApp = $line.vApp
Routed = $true
Name = $line.Name
Description = $line.Description
DnsSuffix = $line.DNSSuffix
Gateway = $line.Gateway
Netmask = $line.Netmask
PrimaryDns = $line.PrimaryDNS
SecondaryDNS = $line.SecondaryDNS
StaticIPPool = $line.StaticIPPool
}
Switch ($line.NetType) {
{"Routed", "Direct" -contains $_} `
{$hshParamForNewCIVAppNetwk["ParentOrgNetwork"] = $line.ParentOrgNetwork}
"Isolated" {$hshParamForNewCIVAppNetwk["ParentOrgNetwork"] = $null}
} New-CIVAppNetwork @hshParamForNewCIVAppNetwk
Modifying the vApp network allows you to update properties such as the description, DNS information, firewall, NAT, and parent organization network. It does not allow you to change the IP, gateway, or subnet mask of the network. Making changes to a vApp network involves specifying the target vApp and piping it to the Set-CIVAppNetwork
cmdlet:
$vAppNetwork = Get-CIVApp -Name vApp_system_3 | Get-CIVappNetwork Internal
$vAppNetwork | Set-CIVAppNetwork -PrimaryDns '10.144.99.16' -SecondaryDns `
'10.144.99.17' | Set-CIVAppNetwork -FirewallEnabled:$true
vApp networks are easily removed from a vApp. Use extreme caution in running this cmdlet, especially if you have set the -Confirm
parameter set to false
:
$vAppNetwork = Get-CIVApp -Name vApp_system_3 | Get-CIVappNetwork Internal
$vAppNetwork | Remove-CIVAppNetwork -Confirm:$false
vApp templates are the vApps that are found in your catalogs. In large vCloud Director environments, there may be dozens of catalogs with hundreds of templates. You can use the Get-CIVAppTemplate
cmdlet to retrieve a report of all the templates that exist at several different levels within your environment. You can retrieve all vApp templates that are visible to your account by entering the cmdlet by itself:
Get-CIVAppTemplate
You can also use the function presented in Listing 19-6 to retrieve a report of all vApp templates by catalog.
Listing 19-6: vApp
function Get-vAppTemplateReport {
<#
.SYNOPSIS
Retrieve a summary of all vApps in all catalogs
.DESCRIPTION
Retrieves information about each vApp of every catalog in the
environment
.NOTES
Source: Automating vSphere Administration
.PARAMETER Path
Specify the file path for the CSV output
.EXAMPLE
Get-vAppTemplateReport -Path C:TempTemplateReport.csv
#>
param(
[Parameter(Mandatory=$true)]
[ValidateNotNull()]
[String]$Path
)
process{
$Results = @()
foreach ($Catalog in (Get-Catalog)){
foreach ($vAppTemplate in (Get-CIVappTemplate `
-Catalog $Catalog.Name)) {
$Results += $vAppTemplate | Select-Object -Property `
Catalog, Name, Description, OrgVDC, Published, IsGoldMaster, `
StorageUsedGB, Owner, CustomizeOnInstantiate, StorageLease
}
}
$Results | Export-CSV $Path -Append `
-NotypeInformation -NoClobber
}
}
Additional vApp templates can be created or imported into vCloud Director. The New-CIVappTemplate
cmdlet allows you to create a template from an existing vApp in vCloud Director:
Get-CIVApp 'vApp_system_3' | New-CIVAppTemplate `
-Name 'Default Gold Linux Build' `
-OrgVdc 'OrgVDC1' `
-Catalog 'Full-Catalog' `
-Description 'Suse Gold Build'
You can import virtual machines as vApps from vSphere or OVF packages from your local machine:
Import-CIVAppTemplate -SourcePath C:TempovfLogInsight.ovf `
-Name 'Log Insight' `
-OrgVdc 'OrgVDC1' `
-Catalog 'Full-Catalog'
To import virtual machines as vApps from vSphere, you must first ensure that you are connected to both vCloud Director and vSphere. You can import any virtual machine from vSphere as long as you have your target information (org vDC and catalog):
$vmname = Get-VM -Name 'MGMT-LogInsight'
Import-CIVAppTemplate -VM $vmname `
-Name 'Log Insight Management vApp' `
-OrgVdc 'OrgVDC1' `
-Catalog 'Full-Catalog'
Listing 19-7 shows a function that allows you to bulk-import virtual machines from vSphere into vCloud Director catalogs. To use this function, you will need to do a little preparation within your vCenter server.
Listing 19-7 leverages tags, tag descriptions, and tag categories to correctly identify and place virtual machines from your vSphere environment into vCloud Director. You will need to create a new tag category, assigned only to virtual machines, which will be used to identify the virtual machines you want to import. You then need to create at least one tag. The tag name needs to match the target org vDC; the tag description needs to be the name of the catalog where the virtual machine will be placed. Once you’ve created the tag, use it to tag all relevant virtual machines that you wish to import into vCloud Director. You can then proceed to use the function. If you need to refresh your skills on using tags, refer to the “Tags” section found in Chapter 12, “Organize Your Disaster Recovery.”
Listing 19-7: Bulk-importing VMs from vSphere
function Import-VMtoVCD {
<#
.SYNOPSIS
Import Tagged Virtual Machines into vCD
.DESCRIPTION
This is designed to allow users to create a Tag Category
designated for mass importation of Virtual Machines from
vSphere into a vCD Catalog. This requires a designated
Tag Category along with the Tag Name being the destination
Org name and the description being the catalog name.
.NOTES
Source: Automating vSphere Administration
.PARAMETER TagCategory
This parameter specifies the virtual machine Tag Category
that is used to determine which VMs to mass import. Any
virtual machine tagged with a Tag from this category will
be imported into a vCD catalog
.EXAMPLE
Import-VMtoVCD -TagCategory vCD_Import
#>
param(
[Parameter(Mandatory=$True,Position=1,ValueFromPipeline=$True)]
[ValidateNotNullOrEmpty()]
[String]$TagCategory
)
process{
# Specify the virtual machine entity
$VMs = Get-VM
# Find all virtual machines with specified Tag Assignment
$Tagged = Get-TagAssignment -Entity (Get-VM) -Category $TagCategory
# Cycle through each tagged virtual machine
foreach ($tag in $Tagged) {
$Org = Get-OrgVDC $tag.Tag.Name
$Cat = $tag.Tag.Category
$Desc = Get-Catalog $tag.Tag.Description
$VM = $VMs | ?{$_.name -eq $tag.Entity.Name}
Write-Verbose "Importing VM: [$VM] into Catalog: [$Cat] in Org [$Org]"
# Invoke the importation cmdlet
Import-CIVappTemplate `
-VM $VM `
-Name $tag.entity Entity `
-OrgVdc $Org `
-Catalog $Desc
}
}
}
To update the name, description, or lease time of a vApp template, you can select a specific template and pipe it to the Set-CIVAppTemplate
cmdlet:
$lease = New-Timespan -Days 14
Get-CIVAppTemplate -Name 'Default Gold Linux Build' | `
Set-CIVAppTemplate -StorageLease $lease | `
Set-CIVAppTemplate -Name 'Suse Gold Current' `
-Description 'Most Current Suse Build for Engineering'
In vCloud Director, virtual machines are managed differently within a vApp compared to running solely within a vSphere environment. Virtual machines are found within the vApp containers. Unlike the -CIVApp
cmdlets, the CIVM
cmdlets affect only the VM specified, rather than each VM within the vApp.
New-CIVM
allows you to create additional virtual machines inside an existing vApp. Start-CIVM
, Stop-CIVM
, Restart-CIVM
, and Suspend-CIVM
are all used for the power management of individual virtual machines inside a vApp. Suspend-CIVM
works just like suspending a virtual machine within vSphere. If you want to freeze the state of a virtual machine to work with it later, the Suspend-CIVM
cmdlet will save the entire state of the given virtual machine in a VMSS file for later use.
Powering on specific virtual machines within a vApp rather than powering on the entire vApp is not recommended—but sometimes it’s necessary. In those situations, you can run the following:
Get-CIVApp TestvApp | Get-CIVM -Name Apache03 | Start-CIVM
To gracefully power off or restart specific virtual machines in a vApp, you can use the Stop-CIVMGuest
and Restart-CIVMGuest
cmdlets, which will communicate with the guest operating system to ensure the virtual machine is powered down or restarted safely and gracefully. For example, if one of the CIVMs created earlier in this chapter, Apache03
, were exhibiting issues or presenting irregular performance data and the administrators determined that it should be restarted, you would want to restart just the affected virtual machine, rather than the entire vApp and all virtual machines within it:
Get-CIVApp TestvApp | Get-CIVM -Name Apache03 | `
Restart-CIVMGuest -Confirm:$false
Once the vApp has been created or imported into vCloud Director, you can set start rules for the virtual machines in that vApp. Each virtual machine within a vApp has a default Start Rule of PowerOn
with no start delay. If, for example, a vApp contained an Active Directory server, a database server, and an application server, you could consider setting start rules that start up the AD server at the same time as the database server, but delay the application server a given number of seconds to allow the database server to be up and running before the application tries to connect.
Although changing the start rules for our example of the three Apache virtual machines will not be beneficial at this moment, we will still use that vApp to demonstrate how these rules can be set:
$TargetvApp = Get-CIVapp TestvApp
Get-CIVAppStartRule -VApp $TargetvApp
When you run that code, you will see that this vApp has the default start rules. Using the next example code, we will set Apache04
and Apache 05
each for a delay of 20 seconds but allow Apache03
to start immediately:
$vm = Get-CIVM -Name Apache04,Apache05 -VApp $TargetvApp
$startrule = Get-CIVAppStartRule -VApp $TargetvApp -VM $vm
Set-CIVappStartRule -StartRule $startrule -StartDelaySeconds 20
When working in vCloud Director, you’ll deal with three types of networks:
Since both organization and vApp networks have been discussed in previous sections of this chapter, we will only discuss external networks here. You can retrieve a list of all the external networks of your vCloud Director environment using the Get-ExternalNetwork
cmdlet:
Get-ExternalNetwork
You can also retrieve more specific results by specifying a Provider vDC:
Get-ProviderVDC 'MainpVDC' | Get-ExternalNetwork
Search-Cloud
is a powerful cmdlet that allows users to search their vCloud Director environment for specific object types. You may find this cmdlet will return results faster than other Get-
cmdlets in vCD.
When using this cmdlet, you may find that there isn’t a whole lot of information on what object query types can be searched for. There are several ways to get this information. The first is to try an invalid search term on the -QueryType
parameter like ESX
. An error message will display and ask you to “Specify one of the following enumerator names and try again.” It will then proceed to list all available enumerator names for the -QueryType
parameter. Table 19-1 lists the available enumerator names.
You will notice that there are a number of objects in Table 19-1 that do not have an equivalent Get-
command. Search-Cloud
is especially useful with these objects, because it gives you a way to quickly view information about the object and allows you to use the vCloud API to invoke actions when needed.
Table 19-1: Available -QueryType
enumerator names
ESX enumerator | ESX enumerator | ESX enumerator | ESX enumerator |
AclRule | AdminVAppTemplate | Host | ServiceLink |
AdminAllocatedExternalAddress | AdminVM | Media | ServiceResource |
AdminApiDefinition | AdminVMDiskRelation | NetworkPool | StrandedItem |
AdminCatalog | AllocatedExternalAddress | Organization | StrandedUser |
AdminCatalogItem | ApiDefinition | OrgNetwork | Task |
AdminDisk | ApiFilter | OrgVdc | VApp |
AdminEvent | BlockingTask | OrgVdcNetwork | VAppNetwork |
AdminEventCBM | Catalog | OrgVdcResourcePoolRelation | VAppOrgNetworkRelation |
AdminFileDescriptor | CatalogItem | OrgVdcStorageProfile | VAppOrgVdcNetworkRelation |
AdminGroup | Cell | Portgroup | VAppTemplate |
AdminMedia | Condition | ProviderVdc | VirtualCenter |
AdminOrgNetwork | DatastoreProviderVdcRelation | ProviderVdcResourcePoolRelation | Vm |
AdminOrgVdc | Disk | ProviderVdcStorageProfile | VmDiskRelation |
AdminOrgVdcStorageProfile | DvSwitch | ResourceClass | Datastore |
AdminService | EdgeGateway | ResourceClassAction | User |
AdminShadowVM | Event | ResourcePool | |
AdminTask | ExternalLocalization | ResourcePoolVmList | |
AdminUser | ExternalNetwork | Right | |
AdminVApp | FileDescriptor | Role | |
AdminVAppNetwork | Group | Service |
For example, you might want to get additional information on the vCenter(s) attached to vCloud Director. In this situation, you would run this:
$Vc = Search-Cloud -QueryType VirtualCenter | Get-CIView
You can then perform a Get-Member
to see the methods available against the object. You’ll notice that there are a number of Import and Refresh commands, as well as a number of other options. This may be useful if you want to perform actions available through the API that do not have a cmdlet available.
$vc | gm | Select Name, MemberType
Name MemberType
---- ----------
Delete_Task Method
Equals Method
Forcevimserverreconnect Method
Forcevimserverreconnect_Task Method
GetHashCode Method
GetHostReferences Method
GetNetworks Method
GetResourcePoolList Method
GetStorageProfiles Method
GetType Method
GetVIView Method
GetVmsList Method
ImportMedia Method
ImportVmAsVApp Method
ImportVmAsVAppTemplate Method
ImportVmIntoExistingVApp Method
ImportVmIntoExistingVApp_Task Method
Refresh Method
RefreshStorageProfiles Method
RefreshStorageProfiles_Task Method
Refresh_Task Method
ToString Method
Unregister Method
Unregister_Task Method
UpdateServerData Method
UpdateServerData_Task Method
UpdateViewData Method
When using the Search-Cloud
cmdlet, if you do not specify which properties you want retrieved using the -Property
parameter, the result will display all properties of the objects returned. The -Filter
parameter can be used to narrow the search results. Note that you can add multiple filter criteria on each search. The criteria must be separated by a semicolon (;). For more information on the filter syntax, refer to the vCloud API Programming Guide.
You also can search for a particular org vDC. In our next example, we’ll search for an org vDC named OrgVDC1
:
Search-Cloud -QueryType OrgVdcNetwork -Filter 'VdcName==OrgVDC1'
That code returns all properties of OrgVDC1
. You can simplify the results by using the -Property
parameter mentioned earlier:
Search-Cloud -QueryType OrgVdcNetwork -Filter 'VdcName==OrgVDC1' `
-Property 'Name', 'DnsSuffix', 'DefaultGateway', 'Dns1'
The return now presents only the data specified.