Desinstalación del agente de Azure Connected Machine desde servidores habilitados para Arc

Si ya no desea administrar una máquina a través de servidores habilitados para Azure Arc, debe quitar las extensiones de máquina virtual del servidor, desconectar el agente y desinstalar el software del servidor. Es importante completar todos estos pasos para quitar completamente todos los componentes de software relacionados del sistema.

Quitar extensiones de máquina virtual

Si ha implementado Azure extensiones de máquina virtual en un servidor habilitado para Azure Arc, debe desinstalar todas las extensiones antes de desconectar el agente o desinstalar el software. La desinstalación del agente de Azure Connected Machine no quita automáticamente las extensiones y estas extensiones no se reconocen si vuelve a conectar el servidor a Azure Arc.

Para obtener instrucciones sobre cómo enumerar y quitar las extensiones en el servidor habilitado para Azure Arc, consulte los siguientes recursos:

• Administrar extensiones de máquina virtual con el portal de Azure
• Administración de extensiones de máquina virtual con Azure PowerShell
• Administración de extensiones de máquina virtual con la CLI de Azure

Desconecte el servidor de Azure Arc

Después de quitar todas las extensiones del servidor habilitado para Arc, el siguiente paso es desconectar el agente. Esta acción elimina el recurso de Azure correspondiente para el servidor y borra el estado local del agente.

Para desconectar el agente, ejecute el azcmagent disconnect comando como administrador en el servidor. Se le pedirá que inicie sesión con una cuenta de Azure que tenga permiso para eliminar el recurso de la suscripción. Si el recurso ya se eliminó en Azure, pase una marca adicional para limpiar el estado local: azcmagent disconnect --force-local-only.

Si sus cuentas de administrador y de Azure son diferentes, es posible que surjan problemas porque el mensaje de inicio de sesión se establece de forma predeterminada en la cuenta de administrador. Para resolver estos problemas, ejecute el azcmagent disconnect --use-device-code comando . Se le pedirá que inicie sesión con una cuenta de Azure que tenga permiso para eliminar el recurso.

Desinstalación del agente

Después de desconectar el agente de Azure Arc, quite el agente de Connected Machine del servidor.

sudo apt purge azcmagent

sudo yum remove azcmagent

sudo zypper remove azcmagent

Eliminación de recursos obsoletos del servidor

Si retira o desconecta un servidor sin quitar limpiamente el agente, el recurso normalmente permanece en el portal de Azure con un estado Disconnected. Con el tiempo, estos recursos obsoletos pueden desordenar su entorno.

El siguiente script de PowerShell le ayuda a identificar y eliminar servidores habilitados para Azure Arc que se han desconectado durante un número especificado de días.

Prerequisites

• Azure PowerShell: Az módulo instalado.
• Permisos: Acceso de lector para realizar consultas a través de Azure Resource Graph, y de colaborador o propietario (o Microsoft.HybridCompute/machines/delete) para eliminar los recursos.

Script de limpieza

Este script usa Azure Resource Graph para consultar Microsoft.HybridCompute/machines recursos en los que el estado es Disconnected y la marca de tiempo lastStatusChange es anterior al umbral configurado.

Guarde el código siguiente como Cleanup-StaleArcServers.ps1.

<#
.SYNOPSIS
    Identifies and removes stale Azure Arc-enabled servers that have been disconnected for a specified number of days.

.DESCRIPTION
    This script queries Azure Resource Graph to find Azure Arc-enabled servers (Microsoft.HybridCompute/machines)
    that have a status of 'Disconnected' and have not updated their status for more than the specified number of days.
    Supports -WhatIf and -Confirm via SupportsShouldProcess.

.PARAMETER DaysDisconnected
    The number of days a server must be disconnected to be considered stale. Default is 60.

.PARAMETER Subscription
    Optional. One or more Subscription IDs to scope the query to.
    If not specified, queries all subscriptions the current context has access to.

.PARAMETER ManagementGroup
    Optional. A Management Group name to scope the query to.
    Cannot be used together with -Subscription.

.EXAMPLE
    .\Cleanup-StaleArcServers.ps1 -DaysDisconnected 60 -WhatIf
    Lists Arc servers disconnected for more than 60 days across all subscriptions.

.EXAMPLE
    .\Cleanup-StaleArcServers.ps1 -DaysDisconnected 90 -Subscription 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
    Permanently deletes Arc servers disconnected for more than 90 days in the specified subscription.

.NOTES
    Author: Microsoft
    Date: 2026-01-12
    Requires: Az.ResourceGraph, Az.Resources
#>

[CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')]
param (
    [int]$DaysDisconnected = 60,
    
    [ValidateNotNullOrEmpty()]
    [string[]]$Subscription,

    [ValidateNotNullOrEmpty()]
    [string]$ManagementGroup
)

# Check required modules
foreach ($mod in @('Az.ResourceGraph', 'Az.Resources')) {
    if (-not (Get-Module -Name $mod -ListAvailable -ErrorAction SilentlyContinue)) {
        Write-Error "Required module '$mod' is not installed. Run: Install-Module $mod -Scope CurrentUser"
        return
    }
}

# Check for Azure connection
try {
    $context = Get-AzContext -ErrorAction Stop
    Write-Host "Connected to Azure context: $($context.Name)" -ForegroundColor Cyan
}
catch {
    Write-Error "Not connected to Azure. Please run 'Connect-AzAccount' first."
    return
}

# Construct the KQL query
# We look for resources of type hybridcompute/machines
# Status must be Disconnected
# lastStatusChange must be older than $DaysDisconnected
$kqlQuery = @"
Resources
| where type == 'microsoft.hybridcompute/machines'
| where properties.status == 'Disconnected'
| where properties.lastStatusChange < ago($($DaysDisconnected)d)
| project id, name, resourceGroup, subscriptionId, location, status = properties.status, lastStatusChange = properties.lastStatusChange
"@

Write-Host "Searching for Arc servers disconnected for more than $DaysDisconnected days..." -ForegroundColor Yellow

# Execute Search with pagination (Search-AzGraph returns max 1000 results per call)
$staleServers = [System.Collections.Generic.List[object]]::new()
$skipToken = $null

try {
    do {
        $params = @{
            Query = $kqlQuery
            First = 1000
        }
        if ($skipToken) {
            $params['SkipToken'] = $skipToken
        }
        if ($Subscription) {
            $params['Subscription'] = $Subscription
        }
        if ($ManagementGroup) {
            $params['ManagementGroup'] = $ManagementGroup
        }

        $result = Search-AzGraph @params -ErrorAction Stop
        if ($result) {
            $staleServers.AddRange([object[]]$result)
            $skipToken = $result.SkipToken
        }
    } while ($skipToken)
}
catch {
    Write-Error "Failed to query Azure Resource Graph. Ensure resource graph module is installed and you have read permissions.`nError: $_"
    return
}

if ($staleServers.Count -eq 0) {
    Write-Host "No stale Arc servers found matching the criteria." -ForegroundColor Green
    return
}

Write-Host "Found $($staleServers.Count) stale servers." -ForegroundColor Yellow

# Process results
$successCount = 0
$failCount = 0

foreach ($server in $staleServers) {
    if ($PSCmdlet.ShouldProcess($server.id, "Delete stale Arc server '$($server.name)' (Disconnected since: $($server.lastStatusChange))")) {
        try {
            Remove-AzResource -ResourceId $server.id -Force -ErrorAction Stop
            Write-Host "Successfully deleted '$($server.name)'." -ForegroundColor Green
            $successCount++
        }
        catch {
            Write-Error "Failed to delete '$($server.name)'. Error: $_"
            $failCount++
        }
    }
}

Write-Host "`nCleanup completed. Deleted: $successCount, Failed: $failCount, Total: $($staleServers.Count)" -ForegroundColor Green

Uso del script

Prerequisites

El script requiere los siguientes módulos de PowerShell:

• Az.ResourceGraph
• Az.Resources

Si no están instalados, ejecute:

Install-Module Az.ResourceGraph, Az.Resources -Scope CurrentUser

Steps

1. Iniciar sesión en Azure

   Abra el terminal de PowerShell e inicie sesión.

   Connect-AzAccount
   

2. Ejecución de un análisis de What-If

   En primer lugar, ejecute el script con la opción -WhatIf. En este paso se enumeran los servidores que cumplen los criterios sin eliminarlos realmente. Este comando comprueba los servidores que se han desconectado durante 60 días o más.

   .\Cleanup-StaleArcServers.ps1 -DaysDisconnected 60 -WhatIf
   

   Para limitar el ámbito de la consulta a una suscripción específica, use el -Subscription parámetro :

   .\Cleanup-StaleArcServers.ps1 -DaysDisconnected 60 -Subscription 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' -WhatIf
   

   Para limitar el ámbito de la consulta a un grupo de administración en su lugar, use el -ManagementGroup parámetro :

   .\Cleanup-StaleArcServers.ps1 -DaysDisconnected 60 -ManagementGroup 'MyManagementGroup' -WhatIf
   

   Revise la salida para asegurarse de que solo enumera los servidores previstos.

3. Realizar la limpieza

   Cuando esté seguro de la lista de servidores que se van a quitar, ejecute el script sin el -WhatIf conmutador.

   .\Cleanup-StaleArcServers.ps1 -DaysDisconnected 60
   

   Para limpiar los servidores desconectados durante un período más largo (por ejemplo, seis meses), aumente el número de días:

   .\Cleanup-StaleArcServers.ps1 -DaysDisconnected 180
   

   El script solicita confirmación antes de cada eliminación. Para omitir mensajes, agregue -Confirm:$false.

Contenido relacionado

• Obtenga información sobre cómo administrar las versiones del agente de Connected Machine en servidores habilitados para Arc.
• Aprenda a configurar los ajustes del proxy del agente de Azure Connected Machine.
• Obtenga información sobre cómo cambiar el nombre de un servidor habilitado para Arc o moverlo a otra región de Azure.