Agentes de Windows autohospedados

Azure DevOps Services

Para compilar e implementar Windows, Azure y otras soluciones de Visual Studio, necesitará al menos un agente de Windows. Los agentes de Windows también pueden compilar aplicaciones de Java y Android.

Más información acerca de los agentes

Si ya sabe qué es un agente y cómo funciona, vaya directamente a las secciones siguientes. Pero si desea más información sobre lo que hacen y cómo funcionan, consulte Agentes de Azure Pipelines.

Comprobación de los requisitos previos

Asegúrese de que la máquina cumple estos requisitos previos:

• Versión del sistema operativo
  • Sistema operativo de cliente
    • Windows 7 SP1 ESU
    • Windows 8.1
    • Windows 10
    • Windows 11
  • Sistema operativo de servidor
    • Windows Server 2012 o posterior
• El software del agente instala su propia versión de .NET, por lo que no hay requisito previo de .NET.
• PowerShell 3.0 o posterior
• Subversion: si va a compilar desde un repositorio de Subversion, debe instalar el cliente de Subversion en la máquina.
• Recomendado: herramientas de compilación de Visual Studio (2015 o superior)

La primera vez, debe ejecutar la instalación del agente manualmente. Después de hacerse una idea de cómo funcionan los agentes o si desea automatizar la configuración de muchos agentes, considere la posibilidad de usar la configuración desatendida.

Especificaciones de hardware

Las especificaciones de hardware de los agentes variarán según sus necesidades, el tamaño del equipo, etc. No es posible hacer una recomendación general que se aplicará a todos. Como punto de referencia, el equipo de Azure DevOps compila el código de agentes hospedados mediante canalizaciones que usan agentes hospedados. Por otro lado, la mayor parte del código de Azure DevOps se crea mediante máquinas de clase de servidor de 24 núcleos que ejecutan cuatro agentes autohospedados cada una.

Preparación de los permisos

Seguridad de la información para agentes autohospedados

Para configurar el agente, el usuario necesita permisos de administrador del grupo, pero no para ejecutarlo.

Las carpetas controladas por el agente deben restringirse al menor número posible de usuarios, ya que contienen secretos que podrían descifrarse o filtrarse.

El agente de Azure Pipelines es un producto de software diseñado para ejecutar código que descarga de orígenes externos. De forma inherente, podría recibir ataques de ejecución remota de código (RCE).

Por lo tanto, es importante tener en cuenta el modelo de amenazas que rodea a cada uso individual de los agentes de canalización para realizar el trabajo y decidir cuáles son los permisos mínimos que se pueden conceder al usuario que ejecuta el agente, a la máquina donde se ejecuta el agente, a los usuarios que tienen acceso de escritura a la definición de canalización, los repositorios de Git donde se almacena yaml o el grupo de usuarios que controlan el acceso al grupo para nuevas canalizaciones.

Es un procedimiento recomendado hacer que la identidad que ejecute el agente sea diferente de la identidad con permisos para conectar el agente al grupo. El usuario que genera las credenciales (y otros archivos relacionados con el agente) es diferente del usuario que necesita leerlas. Por lo tanto, es más seguro considerar cuidadosamente el acceso concedido a la propia máquina del agente y las carpetas del agente que contienen archivos confidenciales, como los registros y los artefactos.

Tiene sentido conceder acceso a la carpeta del agente solo a los administradores de DevOps y la identidad de usuario que ejecuta el proceso del agente. Es posible que los administradores necesiten investigar el sistema de archivos para comprender errores de compilación u obtener archivos de registro para poder notificar errores de Azure DevOps.

Decida el usuario que va a usar

Debe registrar el agente una vez. Alguien con permiso para administrar la cola del agente debe completar estos pasos. El agente no usará las credenciales de esta persona en las operaciones diarias, pero es necesario para completar el registro. Más información sobre cómo se comunican los agentes.

Confirmación de que el usuario tiene permiso

Asegúrese de que la cuenta de usuario que va a usar tiene permiso para registrar el agente.

¿Es el usuario propietario de una organización de Azure DevOps o TFS, o administrador de Azure DevOps Server? Deténgase aquí, tiene permiso.

De lo contrario:

1. Abra un explorador y vaya a la pestaña Grupos de agentes de la organización de Azure Pipelines, Azure DevOps Server o el servidor TFS:

   1. Inicie sesión en su organización (https://dev.azure.com/{yourorganization}).

   2. Elija Azure DevOps, Configuración de la organización.

      

   3. Seleccione Grupos de agentes.

      

   1. Inicie sesión en la colección de proyectos (http://your-server/DefaultCollection).

   2. Seleccione Azure DevOps, Configuración de colección.

      

   3. Seleccione Grupos de agentes.

      

   1. Seleccione Azure DevOps, Configuración de colección.

      

   2. Seleccione Grupos de agentes.

      

2. Seleccione el grupo en el lado derecho de la página y haga clic en Seguridad.

3. Si no se muestra la cuenta de usuario que va a usar, que un administrador la agregue. El administrador puede ser administrador del grupo de agentes, propietario de la organización de Azure DevOps o administrador de TFS o Azure DevOps Server.

   Si se trata de un agente de grupo de implementación, el administrador puede ser administrador del grupo de implementación, propietario de la organización de Azure DevOps o administrador de TFS o Azure DevOps Server.

   Puede agregar un usuario al rol de administrador del grupo de implementación en la pestaña Seguridad de la página Grupos de implementación de Azure Pipelines.

Descarga y configuración del agente

Azure Pipelines

1. Inicie sesión en la máquina con la cuenta para la que ha preparado los permisos, como se explicó anteriormente.

2. En el explorador web, inicie sesión en Azure Pipelines y vaya a la pestaña Grupos de agentes:

   1. Inicie sesión en su organización (https://dev.azure.com/{yourorganization}).

   2. Elija Azure DevOps, Configuración de la organización.

      

   3. Seleccione Grupos de agentes.

      

   1. Inicie sesión en la colección de proyectos (http://your-server/DefaultCollection).

   2. Seleccione Azure DevOps, Configuración de colección.

      

   3. Seleccione Grupos de agentes.

      

   1. Seleccione Azure DevOps, Configuración de colección.

      

   2. Seleccione Grupos de agentes.

      

3. Seleccione el grupo Predeterminado y la pestaña Agentes, y elija Nuevo agente.

4. En el cuadro de diálogo Obtener el agente, elija Windows.

5. En el panel izquierdo, seleccione la arquitectura del procesador de la versión instalada del sistema operativo Windows en el equipo. La versión del agente x64 está pensada para Windows de 64 bits, mientras que la versión x86 está pensada para Windows de 32 bits. Si no está seguro de qué versión de Windows está instalada, siga estas instrucciones para averiguarlo.

6. En el panel derecho, haga clic en el botón Descargar.

7. Siga las instrucciones de la página para descargar el agente.

8. Desempaquete el agente en el directorio que prefiera. Asegúrese de que la ruta de acceso al directorio no contiene espacios, porque las herramientas y los scripts no siempre escapan correctamente a los espacios. Una carpeta recomendada es C:\agents. La extracción en la carpeta de descarga u otras carpetas de usuario puede causar problemas de permisos.

Instalación del agente

1. Inicie una ventana con privilegios elevados (PowerShell) y establezca la ubicación en la que desempaquetó el agente.

   cd C:\agents 
   
   

2. Ejecute config.cmd. Se le hará una serie de preguntas para configurar el agente.

   .\config.cmd
   
   

Dirección URL del servidor

Tipo de autenticación de configuración del agente

Cuando registre un agente, elija entre los siguientes tipos de autenticación y el programa de instalación le solicitará la información adicional específica requerida para cada tipo de autenticación. Para obtener más información, consulte Opciones de autenticación del agente autohospedado.

El método de autenticación para el registro del agente se usa solo durante dicho registro. Para más información sobre la forma en que los agentes se comunican con Azure Pipelines después del registro, consulte Comunicación con Azure Pipelines o TFS.

Elección del modo interactivo o de servicio

Para instrucciones sobre la ejecución del agente en modo interactivo o como servicio, consulte Agentes: interactivos o como servicio.

Si decide ejecutarse como servicio (lo que se recomienda), el nombre de usuario que ejecute como debe tener 20 caracteres o menos.

Ejecución del agente

Ejecución de forma interactiva

Si configuró el agente para que se ejecute de forma interactiva, ejecute el siguiente comando para iniciar el agente.

.\run.cmd

Para reiniciar el agente, pulse Ctrl+C para parar al agente y ejecute run.cmd para reiniciarlo.

variables:
 AZP_AGENT_CLEANUP_PSMODULES_IN_POWERSHELL: "true"

Una ejecución

También puede elegir que el agente acepte solo un trabajo y luego salga. Para ejecutar esta configuración, utilice el siguiente comando.

.\run.cmd --once

Los agentes de este modo solo aceptarán un trabajo y se retirarán fácilmente (útiles para la ejecución de un Docker en servicios como Azure Container Instances).

Ejecución como un servicio

Si ha configurado el agente para que se ejecute como un servicio, se inicia automáticamente. Puede ver y controlar el estado de ejecución del agente desde el complemento de servicios. Ejecute services.msc y busque una de las siguientes:

• “Agente de Azure Pipelines (nombre del agente)”.
• “Agente de VSTS (nombre del agente)”.
• “vstsagent.(nombre de la organización).(nombre del agente)”.

Para reiniciar el agente, haga clic con el botón derecho en la entrada y elija Reiniciar.

Para usar el agente, ejecute un trabajo mediante el grupo del agente. Si no ha elegido un grupo diferente, el agente estará en Predeterminado.

Reemplazar un agente

Para reemplazar un agente, siga los pasos de Descarga y configuración del agente de nuevo.

Al configurar un agente con el mismo nombre que un agente que ya existe, se le pregunta si desea reemplazar el agente existente. Si responde Y, asegúrese de quitar el agente (consulte a continuación) que va a reemplazar. De lo contrario, después de unos minutos de conflictos, uno de los agentes se apagará.

Eliminación de un agente y reconfiguración

Para eliminar el agente:

.\config remove

Después de quitar el agente, puede volver a configurarlo.

Configuración desatendida

El agente se puede configurar desde un script sin intervención humana. Debe pasar --unattended y las respuestas a todas las preguntas.

Para configurar un agente, debe conocer la dirección URL de la organización o la colección, y las credenciales de alguien autorizado para configurar agentes. Todas las demás respuestas son opcionales. En su lugar, se puede especificar cualquier parámetro de línea de comandos mediante una variable de entorno: coloque su nombre en mayúsculas y anteponga VSTS_AGENT_INPUT_. Por ejemplo, VSTS_AGENT_INPUT_PASSWORD en lugar de especificar --password.

Opciones necesarias

• --unattended: el programa de instalación del agente no solicitará información y todas las configuraciones se deben proporcionar en la línea de comandos.
• --url <url>: dirección URL del servidor. Por ejemplo, https://dev.azure.com/myorganization o http://my-azure-devops-server:8080/tfs.
• --auth <type>: tipo de autenticación. Los valores válidos son:
  • pat (Token de acceso personal)
  • SP (Entidad de servicio) (Requiere la versión del agente 3.227.1 o posterior)
  • negotiate (Kerberos o NTLM)
  • alt (Autenticación básica)
  • integrated (Credenciales predeterminadas de Windows)

Opciones de autenticación

• Si ha elegido --auth pat:
  • --token <token>: especifica su token de acceso personal.
  • También puede pasar un token de OAuth 2.0 como parámetro --token.
• Si ha elegido --auth negotiate o --auth alt:
  • --userName <userName>: especifica un nombre de usuario de Windows en formato domain\userName o userName@domain.com.
  • --password <password>: especifica una contraseña.
• Si ha elegido --auth SP:
  • --clientID <clientID>: especifica el identificador de cliente de la entidad de servicio con acceso a los agentes de registro.
  • --tenantId <tenantID>: especifica el identificador de inquilino en el que se registra la entidad de servicio.
  • --clientSecret <clientSecret>: especifica el secreto de cliente de la entidad de servicio
  • Para obtener más información, consulte Registro de un agente con una entidad de servicio.

Nombres de grupo y agente

• --pool <pool>: nombre del grupo al que se unirá el agente.
• --agent <agent>: nombre del agente.
• --replace: reemplaza el agente en un grupo. Si otro agente está escuchando por el mismo nombre, comenzará a generar un error de conflicto.

Instalación del agente

• --work <workDirectory>: directorio de trabajo donde se almacenan los datos del trabajo. El valor predeterminado es _work en la raíz del directorio del agente. El directorio de trabajo es propiedad de un agente determinado y no debe compartirse entre varios agentes.
• --acceptTeeEula: acepta el contrato de licencia de usuario final Team Explorer Everywhere (solo macOS y Linux).
• --disableloguploads: no transmite ni envía la salida del registro de consola al servidor. En su lugar, puede recuperarlos del sistema de archivos del host del agente una vez completado el trabajo.

Inicio solo de Windows

• --runAsService: configura el agente para que se ejecute como un servicio de Windows (requiere permiso de administrador).
• --runAsAutoLogon: configura el inicio de sesión automático y ejecuta el agente al iniciarse (requiere permiso de administrador).
• --windowsLogonAccount <account>: se usa con --runAsService o --runAsAutoLogon para especificar el nombre de usuario de Windows en formato domain\userName o userName@domain.com.
• --windowsLogonPassword <password>: se usa con --runAsService o --runAsAutoLogon para especificar la contraseña de inicio de sesión de Windows (no es necesario para las cuentas de servicio administradas del grupo y las cuentas integradas de Windows, como "NT AUTHORITY\NETWORK SERVICE").
• --enableservicesidtypeunrestricted : se usa con --runAsService para configurar el agente con el tipo de SID de servicio como SERVICE_SID_TYPE_UNRESTRICTED (requiere permiso de administrador)
• --overwriteAutoLogon: se usa con --runAsAutoLogon para sobrescribir el inicio de sesión automático existente en la máquina.
• --noRestart: se usa con --runAsAutoLogon para impedir que el host se reinicie una vez completada la configuración del agente.

Solución de problemas de configuración del agente con la opción runAsAutoLogon

La configuración del agente con la opción runAsAutoLogon ejecuta el agente siempre después del reinicio de la máquina. Realice los pasos siguientes si el agente no se ejecuta después de reiniciar la máquina.

Si el agente ya estaba configurado en la máquina

Antes de volver a configurar el agente, es necesario quitar la configuración del agente anterior. Intente ejecutar este comando desde la carpeta del agente:

.\config.cmd remove --auth 'PAT' --token '<token>'

Compruebe si el agente se quitó del grupo de agentes después de ejecutar el comando:

<Azure DevOps organization> / <Project> / Settings / Agent pools / <Agent Pool> / Agents

Quite el agente del grupo de agentes manualmente si no se quitó con el comando.

A continuación, intente volver a configurarlo mediante la ejecución de este comando desde la carpeta del agente:

.\config.cmd --unattended --agent '<agent-name>' --pool '<agent-pool-name>' --url '<azure-dev-ops-organization-url>' --auth 'PAT' --token '<token>' --runAsAutoLogon --windowsLogonAccount '<domain\user-name>' --windowsLogonPassword '<windows-password>'

Especifique el nombre del agente (cualquier nombre único específico) y compruebe si este agente apareció en el grupo de agentes después de volver a configurarlo.

Será mucho mejor desempaquetar un archivo de agente (que se puede descargar aquí) y ejecutar este comando desde la nueva carpeta del agente desempaquetado.

Compruebe si la clave del Registro de Windows se registra y se guarda correctamente.

Ejecute el comando whoami /user para obtener <sid>. Abra Registry Editor y siga la ruta de acceso:

Computer\HKEY_USERS\<sid>\SOFTWARE\Microsoft\Windows\CurrentVersion\Run

Compruebe si está la clave VSTSAgent. Elimine esta clave si existe, cierre Registry Editor y configure el agente ejecutando el comando .\config.cmd (sin argumentos) desde la carpeta del agente. Antes de responder a la pregunta Enter Restart the machine at a later time?, vuelva a abrir Registry Editor y compruebe si ha aparecido la clave VSTSAgent. Presione Enter para responder a la pregunta y compruebe si la clave VSTSAgent permanece en su lugar después de reiniciar la máquina.

Compruebe si las claves del Registro de Windows funcionan correctamente en la máquina.

Cree un archivo autorun.cmd que contenga la línea siguiente: echo "Hello from AutoRun!". Abra Registry Editor y cree en la ruta de acceso anterior un nuevo par clave-valor con la clave AutoRun y el valor.

C:\windows\system32\cmd.exe /D /S /C start "AutoRun" "D:\path\to\autorun.cmd"

Reinicie el equipo. Si no ve una ventana de la consola con el mensaje Hello from AutoRun!, tiene un problema con las claves del Registro de Windows.

Solo el grupo de implementación

• --deploymentGroup: configura el agente como agente del grupo de implementación.
• --deploymentGroupName <name>: se usa con --deploymentGroup para especificar el grupo de implementación para que el agente se una.
• --projectName <name>: se usa con --deploymentGroup para establecer el nombre del proyecto.
• --addDeploymentGroupTags: se usa con --deploymentGroup para indicar que se deben agregar etiquetas de grupo de implementación.
• --deploymentGroupTags <tags>: se usa con --addDeploymentGroupTags para especificar la lista de etiquetas separadas por comas para el agente del grupo de implementación; por ejemplo, "web, db".

Solo entornos

• --addvirtualmachineresourcetags: se usa para indicar que se deben agregar etiquetas de recurso del entorno.
• --virtualmachineresourcetags <tags>: se usa con --addvirtualmachineresourcetags para especificar la lista de etiquetas separadas por comas para el agente del recurso de entorno; por ejemplo, "web, db".

.\config --help siempre enumera las respuestas obligatorias y opcionales más recientes.

Diagnóstico

Si tiene problemas con el agente autohospedado, puede intentar ejecutar diagnósticos. Después de configurar el agente:

.\run --diagnostics

Esto se ejecutará a través de un conjunto de diagnósticos que puede ayudarle a solucionar el problema. La característica de diagnóstico está disponible a partir de la versión 2.165.0 del agente.

Ayuda sobre otras opciones

Para información sobre otras opciones:

.\config --help

La ayuda proporciona información sobre las alternativas de autenticación y la configuración desatendida.

Funcionalidades

Las funcionalidades del agente se catalogan y anuncian en el grupo para que solo se asignen las compilaciones y versiones que pueda controlar. Consulte Funcionalidades del agente de compilación y versión.

En muchos casos, después de implementar un agente, se debe instalar software o utilidades. Por lo general, se debe instalar en los agentes cualquier software y herramientas que se use en la máquina de desarrollo.

Por ejemplo, si la compilación incluye la tarea npm, la compilación no se ejecutará a menos que haya un agente de compilación en el grupo que tenga npm instalado.

Preguntas más frecuentes

¿Qué versión de Git ejecuta mi agente?

De forma predeterminada, el agente de Windows usa la versión de Git que se incluye con el software del agente. Microsoft recomienda usar la versión de Git que se incluye con el agente, pero tiene varias opciones para invalidar este comportamiento predeterminado y usar la versión de Git que la máquina del agente haya instalado en la ruta de acceso.

• Establezca una variable de canalización denominada System.PreferGitFromPath en true en las canalizaciones.
• En los agentes autohospedados, puede crear un archivo denominado .env en el directorio raíz del agente y agregar una línea System.PreferGitFromPath=true al archivo. Para más información, consulte ¿Cómo se establecen diferentes variables de entorno para cada agente?

Para ver la versión de Git que usa una canalización, puede examinar los registros de un paso checkout de la canalización, como se muestra en el ejemplo siguiente.

Syncing repository: PathFilter (Git)
Prepending Path environment variable with directory containing 'git.exe'.
git version
git version 2.26.2.windows.1

¿Cómo se garantiza la versión más reciente del agente?

1. Vaya a la pestaña Grupos de agentes:

   1. Inicie sesión en su organización (https://dev.azure.com/{yourorganization}).

   2. Elija Azure DevOps, Configuración de la organización.

      

   3. Seleccione Grupos de agentes.

      

   1. Inicie sesión en la colección de proyectos (http://your-server/DefaultCollection).

   2. Seleccione Azure DevOps, Configuración de colección.

      

   3. Seleccione Grupos de agentes.

      

   1. Seleccione Azure DevOps, Configuración de colección.

      

   2. Seleccione Grupos de agentes.

      

2. Haga clic en el grupo que contiene el agente.

3. Asegúrese de que el agente está habilitado.

4. Vaya a la pestaña Funcionalidades:

   1. En la pestaña Grupos de agentes, seleccione el grupo de agentes deseado.

      

   2. Seleccione Agentes y elija el agente deseado.

      

   3. Selecciona la pestaña Funcionalidades.

      

      Nota:

      Los agentes hospedados por Microsoft no muestran las funcionalidades del sistema. Para una lista de software instalado en agentes hospedados por Microsoft, consulte Uso de un agente hospedado por Microsoft.

   1. En la pestaña Grupos de agentes, seleccione el grupo deseado.

      

   2. Seleccione Agentes y elija el agente deseado.

      

   3. Selecciona la pestaña Funcionalidades.

      

   1. En la pestaña Grupos de agentes, seleccione el grupo deseado.

      

   2. Seleccione Agentes y elija el agente deseado.

      

   3. Selecciona la pestaña Funcionalidades.

      

5. Busque la funcionalidad Agent.Version. Puede comprobar este valor en la versión más reciente del agente publicado. Consulte Agente de Azure Pipelines y compruebe en la página el máximo número de versión enumerado.

6. Los agentes se actualizan automáticamente cuando ejecutan una tarea que requiere una versión más reciente. Si desea actualizar manualmente algunos agentes, haga clic con el botón derecho en el grupo y seleccione Actualizar todos los agentes.

¿Cómo se ejecuta el agente con certificado autofirmado?

Ejecución del agente con certificado autofirmado

¿Cómo se ejecuta el agente detrás de un proxy web?

Ejecución del agente detrás de un proxy web

¿Cómo se reinicia el agente?

Si ejecuta el agente de forma interactiva, consulte las instrucciones de reinicio en Ejecución interactiva. Si ejecuta el agente como servicio, reinicie el agente siguiendo los pasos que se indican en Ejecución como servicio.

MyEnv0=MyEnvValue0
MyEnv1=MyEnvValue1
MyEnv2=MyEnvValue2
MyEnv3=MyEnvValue3
MyEnv4=MyEnvValue4

https://login.microsoftonline.com
https://app.vssps.visualstudio.com 
https://{organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com
https://{organization_name}.vstmr.visualstudio.com
https://{organization_name}.pkgs.visualstudio.com
https://{organization_name}.vssps.visualstudio.com

https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net
https://vstsagentpackage.azureedge.net
https://vssps.dev.azure.com

¿Qué es habilitar SERVICE_SID_TYPE_UNRESTRICTED para el servicio del agente?

Al configurar el software del agente en Windows Server, puede especificar el identificador de seguridad del servicio desde el siguiente símbolo del sistema.

Enter enable SERVICE_SID_TYPE_UNRESTRICTED for agent service (Y/N) (press enter for N)

Las versiones anteriores del software del agente establecen el tipo de identificador de seguridad de servicio en SERVICE_SID_TYPE_NONE, que es el valor predeterminado para las versiones actuales del agente. Para configurar el tipo de identificador de servicio de seguridad en SERVICE_SID_TYPE_UNRESTRICTED, presione Y.

Para obtener más información, consulte Estructura SERVICE_SID_INFO e identificadores de seguridad.