Citrix.AppLayering

about_Citrix.AppLayering

Short description

Citrix App Layering PowerShell module providing cmdlets to manage App Layering appliances, connectors, credentials and image packaging workflows.

Long description

The Citrix.AppLayering module contains PowerShell cmdlets that enable automation of common App Layering operations against an App Layering appliance. The module supports connecting to an appliance, managing connector configuration and credentials, starting and monitoring IPS tasks (prepare, export, diagnostics), and interacting with task details.

Typical workflows supported by this module include:

• Establishing a management session to an App Layering appliance and storing credentials.
• Preparing images for export and running export pipelines to deliver images to target locations.
• Running diagnostics against images or appliances to gather logs and health information.
• Monitoring long-running tasks and retrieving detailed per-task output for troubleshooting or audit.

Examples

The examples below follow the exact canonical usage shown in the individual cmdlet help topics. Replace the sample connector IDs, task IDs and paths with values from your environment.

Example 1 — Change stored vSphere platform credentials

# Connect to appliance with admin credentials
PS C:\> $applianceCredential = Get-Credential -Message "Enter appliance admin credentials"
PS C:\> $connectionId = Connect-AlAppliance -Address '192.168.10.5' -Credential $applianceCredential

# Get existing credentials and find vSphere service account to update
PS C:\> $existingCredentials = Get-AlCredential
PS C:\> $vsphereCredential = $existingCredentials | Where-Object { $_.Name -eq "vSphere Connector" }

# Create new vSphere service account credential object
PS C:\> $newVsphereCred = Get-Credential -Message "Enter vSphere service account credentials"

# Update the vSphere service account stored credential
PS C:\> Set-AlCredential -Id $vsphereCredential.Id -Credential $newVsphereCred
<!--NeedCopy-->

This workflow shows a common credential management scenario: connect to the appliance with admin credentials, then manage vSphere platform service account credentials stored on the appliance. The example shows updating vSphere service account credentials, but the same pattern applies for any type of credentials.

Example 2 — Start an IPS export, wait for completion, and print results

# Establish an authenticated session to the appliance first
PS C:\> $credentials = Get-Credential
PS C:\> $connectionId = Connect-AlAppliance -Address '192.168.10.5' -Credential $credentials

# Get available connector configurations and find one that supports IPS export
PS C:\> $connectors = Get-AlConnectorConfig -Features IpsExport
PS C:\> $exportConnector = $connectors | Where-Object { $_.Name -eq "My Export Connector" }

# Start the export using the connector config ID from above
PS C:\> $exportTask = Start-AlIpsExport -ConnectorConfigId $exportConnector.Id -SourceDisk "[DatastoreName] VMFolder/disk.vmdk" -OutputDiskName "MyExportedDisk"

# Wait for the asynchronous export task to complete
PS C:\> $finalResult = $exportTask | Wait-AlTask

# Show the final result object
PS C:\> $finalResult | Format-List -Force

# Retrieve detailed per-work-item/subtask information for the export
PS C:\> $exportTask | Get-AlTaskItemDetail | Format-List -Force
<!--NeedCopy-->

This sequence uses Get-AlConnectorConfig to find a connector that supports IPS exports, then uses that connector’s ID with Start-AlIpsExport. Since only one authenticated session exists in this example, the -ConnectionId parameter is omitted (cmdlets will use the most recently used connection by default).

Example 3 — Troubleshoot an IPS-related task using diagnostics

# Establish an authenticated session to the appliance first
PS C:\> $credentials = Get-Credential
PS C:\> $connectionId = Connect-AlAppliance -Address '192.168.10.5' -Credential $credentials

# Get the connector named `My Azure Connector`
PS C:\> $azureConnector = Get-AlConnectorConfig -Name "My Azure Connector"
PS C:\> $sourceDisk = "/subscriptions/$ENV:AZURE_SUBSCRIPTION_ID/resourceGroups/my-resource-group/providers/Microsoft.Compute/disks/managed-disk"

PS C:\> $PrepareParams = @{
    ConnectorConfigId = $azureConnector.Id
    SourceDisk = $sourceDisk
    OutputDiskName = "managed-disk-prepared"
    ProvisioningType = "Pvs"
    PvsInstallVersion = "latest"
    DebugSettings = @{BreakOnError = $true; enableBootDiagnostics = $true; PreserveCeOnError = $true}
}

# Example: Running a prepare that preserves disks if it fails (for later diagnosis). Note that when waiting for the task to finish, `ActionRequired` is added, which will instruct `Wait-AlTask` to stop waiting when the task enters the `ActionRequired` state as well as any terminal state.
PS C:\> $result = Start-AlIpsPrepare @PrepareParams | Wait-AlTask -AdditionalStates 'ActionRequired'

# Assuming the prepare job failed, some information can be gathered from the failed job.
PS C:\> $ipsTaskContext = $result | Get-AlTaskItemDetail | Where-Object { $_.ItemType -Eq 'IpsTaskContext' }
PS C:\> $prepareTaskId = $result.Id
PS C:\> $outputData = $ipsTaskContext.ItemDetails.OutputData
PS C:\> $output = $outputData.CompositingMachine.VmInfo.output
PS C:\> $vmId = $output.machineId
PS C:\> $diskId = $output.diskId

# This uses the `Stop-AzVm` located within the Az Powershell module, to stop the VM before proceeding.
PS C:\> Stop-AzVM -Id $vmId -Force

# Collect diagnostics for a disk produced by a failed IPS task, wait for it to finish, retrieve the details, and print the results to the console
PS C:\> $details = Start-AlIpsDiagnostics -ConnectorConfigId $azureConnector.Id -SourceDisk $diskId | Wait-AlTask | Get-AlTaskItemDetail | Format-List -Force

# At this point, logs have been collected and stored on the appliance. Login to the appliance using the web interface and export the logs.
<!--NeedCopy-->

Note: The Start-AlIpsDiagnostics cmdlet is used to collect information about failed IPS tasks. When running the original export/prepare task that might need diagnostics, use debug settings like PreserveCeOnError or BreakOnError to ensure disks are preserved for analysis.

Note

• This module requires network access to an App Layering appliance and appropriate privileges on that appliance. Ensure firewall and network routing permit management connections.
• Credentials used by the cmdlets should have the minimum privileges required to perform the intended operations (connector management, image prepare/export, diagnostics).
• Some operations (prepare/export) are long-running and may take minutes to hours depending on image size and destination performance.
• If only one authenticated connection exists in the session, cmdlets will implicitly use that connection; when multiple authenticated connections exist, cmdlets will use the most recently used valid connection unless a specific -ConnectionId is provided to target a particular session.

Troubleshooting note

• Authentication failures: Verify the appliance hostname, credentials, and that the appliance is reachable from the host running these cmdlets. Use Test-NetConnection or Test-Connection to validate network connectivity.
• Permission denied or API errors: Confirm the account has sufficient rights on the appliance and that any connector targets (SMB/NFS locations, cloud endpoints) are reachable from the appliance and have proper permissions.
• Long-running tasks appear stuck: Use Get-AlTaskItemDetail to inspect current progress and identify any errors or bottlenecks. For large images, consider increasing the -Timeout parameter on Start-AlIpsPrepare or Start-AlIpsExport. If a task fails and you need to collect diagnostic information, use debug settings like PreserveCeOnError or BreakOnError when starting the task, then run Start-AlIpsDiagnostics against the preserved disk. See Example 3 for a complete diagnostic workflow.
• If a cmdlet reports unexpected output or failure, consult the appliance system logs and the individual cmdlet help topic for known issues and parameter requirements.