VM Guest Management Skill

Agent Summary

Use this skill for guest-level Azure VM or Arc machine actions such as Run Command execution, Bastion SSH or tunnel setup, and SSH key rotation. Most operations require an ARM auth context from ./skills/azure/Connect-AzureApi.ps1, while Bastion connectivity also depends on Azure CLI.

When to Use

• Execute an inline or file-based script on an Azure VM or Arc machine.
• Open a Bastion tunnel for SSH, SCP, SFTP, or IDE workflows.
• Rotate or replace SSH keys across one or more Linux VMs.

Required Parameters

Invoke-VmRunCommand.ps1

Connect-VmBastionSsh.ps1

Example Agent Prompts

• "Run a bootstrap script on an Azure VM and return the guest output."
• "Start an Azure Bastion tunnel for this VM so I can SSH locally."
• "Rotate SSH public keys across these Linux VMs."

Example Agent Workflow

$ctx = ./skills/azure/Connect-AzureApi.ps1 -AuthenticationType ManagedIdentity -Environment AzureCloud -SubscriptionId $subscriptionId

$result = ./skills/vm-guest-management/Invoke-VmRunCommand.ps1 -ResourceGroupName "rg-app" -VmName "vm01" -ScriptString "echo hello" -AuthContext $ctx

Security Caveats

• Do not treat ARM provisioning success as guest execution success; always inspect execution state and exit code.
• Prefer managed identity or federated credentials over client secrets for ARM access.
• Protect SAS URIs, SSH private keys, and break-glass accounts as sensitive credentials.

Overview

Provides reusable PowerShell wrappers for executing guest scripts on Azure VMs/Arc-enabled machines (Run Command) and for managing SSH access via Bastion and SSH key rotation.

Authentication

• ARM token for Run Command and SSH key management
• Entra ID + Virtual Machine Administrator Login role for Bastion

Endpoints

Uses ARM endpoint from environment.

Skills

Toolchain

Patterns & Caveats

Action Run Command Limits

Managed Run Command (Production)

• Up to 25 per VM
• Supports timeoutInSeconds, runAsUser, outputBlobUri, errorBlobUri
• treatFailureAsDeploymentFailure

Critical: Success Is Misleading

Provisioning success != guest script success. Always inspect instanceView.

Multi-VM Execution

• Anti-pattern: unthrottled backgrounding
• Recommended: ForEach-Object -Parallel with bounded throttle

Bastion Modes

• ssh/rdp: human sessions
• tunnel: automation, SCP, IDE

Arc Run Command Caveats

• Preview status
• Agent 1.33+ required
• No portal UI
• SAS URIs for blob auth (no MI)

SSH Key Lifecycle

• az vm user update APPENDS keys
• Full replacement requires VMAccess extension

Examples

1. Run Command with output validation (managed execution):

   $result = ./skills/vm-guest-management/Invoke-VmRunCommand.ps1 \
     -ResourceGroupName 'rg-app' \
     -VmName 'vm01' \
     -RunCommandName 'run-bootstrap' \
     -ScriptString 'echo hello && uname -a' \
     -TimeoutInSeconds 600 \
     -TreatFailureAsDeploymentFailure \
     -OutputBlobUri $env:RUNCOMMAND_OUTPUT_SAS \
     -ErrorBlobUri  $env:RUNCOMMAND_ERROR_SAS \
     -AuthContext $context
   
   if ($result.ExecutionState -ne 'Succeeded' -or $result.ExitCode -ne 0) {
     throw "Guest execution failed: State=$($result.ExecutionState) ExitCode=$($result.ExitCode) Error=$($result.Error)"
   }
   Write-Host $result.Output

2. Bastion tunnel for local automation:

   $tunnel = ./skills/vm-guest-management/Connect-VmBastionSsh.ps1 \
     -BastionName 'hub-bastion' \
     -ResourceGroupName 'rg-hub' \
     -TargetResourceId $vmId \
     -Mode tunnel \
     -LocalPort 50022 \
     -ResourcePort 22 \
     -AuthType ssh-key \
     -Username 'azureuser' \
     -SshKeyPath '~/.ssh/id_rsa'
   
   Write-Host $tunnel.RecommendedCommand
   # e.g., ssh -p 50022 azureuser@127.0.0.1

3. SSH key rotation (replace prior keys):

   ./skills/vm-guest-management/Invoke-VmSshKeyRotation.ps1 \
     -ResourceGroupName 'rg-app' \
     -VmNames 'vm01','vm02' \
     -PublicKeyPath '~/.ssh/id_ed25519.pub' \
     -RemovePriorKeys \
     -AuthContext $context

Prerequisites

Required modules

• PowerShell 7.2+
• Az.Accounts and Az.Resources (used by the shared Azure auth/REST patterns)
• Azure CLI az (required for Bastion connection setup)

Required roles

• For Bastion (AAD path): Virtual Machine Administrator Login on the target VM
• For Run Command and SSH key management (ARM): permissions to write/execute VM Run Command and manage VMAccessForLinux extension (e.g., Microsoft.Compute/virtualMachines/runCommand/action and VM extension write permissions)

Related Docs

• Auth Patterns
• Patterns and Caveats
• Environment Endpoints