La pantalla Scripts de Portail ZAPP (menú Administración › Conectores y automatización › Scripts) mantiene el registro de los scripts de administración que después pueden ejecutarse en el servidor o en máquinas equipadas con un agente Outpost. Está reservada a los Administradores.
La lista de scripts
Cada script muestra su Nombre, su Motor, su Alcance, su Autor y la fecha de Última modificación (la de su versión más reciente). Escribe parte del nombre en Buscar y pulsa Filtrar; Restablecer vuelve a la lista completa. Haz clic en una fila para abrir el script.
Crear un script
Crear un script pide:
- Nombre y Descripción. El nombre es único: dos scripts no pueden tener el mismo nombre, sin tener en cuenta mayúsculas, acentos ni espacios al principio y al final («Purge temp» y «purge TEMP» son el mismo nombre);
- Motor: Windows PowerShell 5.1, PowerShell 7 (pwsh), Bash, sh (POSIX) o Shebang (#!). Elige un motor disponible en las máquinas de destino;
- Alcance: Solo local (en el servidor), Solo Outposts (en agentes) o Local y Outposts. Un script no puede lanzarse en un destino que su alcance excluye;
- Timeout por defecto (segundos): superado este tiempo, la ejecución se detiene y pasa a Tiempo agotado. Si se deja vacío, vale 300 segundos; 24 horas (86 400 segundos) como máximo;
- Número de reintentos por defecto: el valor se guarda, pero hoy no provoca ningún reintento automático; 10 como máximo;
- Contenido: el texto del script, 2 MB como máximo (2 097 152 bytes codificado en UTF-8; una letra acentuada cuenta dos bytes). El mismo límite vale para cada nueva versión;
- Parámetros (opcional): Añadir un parámetro por cada valor que se pedirá al lanzarlo.
Para cada parámetro, indica su Nombre, su Tipo (String, Integer, Boolean o Enum), si es Obligatorio, su Orden de visualización y, según el tipo, una Regex de validación, un Mín y un Máx, o unos Valores permitidos separados por comas (obligatorios para un Enum). Los valores introducidos al lanzar el script se comprueban con estas reglas.
Crear guarda el script y su versión 1. Después de la creación, el nombre, la descripción, el motor, el alcance, el timeout y el umbral de confirmación no se modifican ni desde la pantalla ni por la API: una nueva versión solo cambia el contenido y los parámetros. En cambio, una puesta en servicio (GOLIVE) los copia desde la instancia de origen. El umbral de confirmación de un lanzamiento en un grupo de máquinas es de 25 máquinas; solo la creación por la API (POST /api/v1/scripts, campo groupConfirmationThreshold) permite fijar otro.
Usar un secreto
No pegues nunca una contraseña en un script: haz referencia a un secreto del módulo Secretos con la sintaxis {{secret:nombre-del-secreto}}. El valor se inserta en el momento de la ejecución; no se guarda en el script ni se conserva en el historial. Para una ejecución en una máquina remota, el comando en espera de envío se cifra en la base de datos y se borra en cuanto termina la ejecución. Atención: si el propio script muestra el secreto (por ejemplo, al escribir sus variables), el valor aparece en la salida de la ejecución. Una referencia mal escrita se rechaza al guardar. Si el secreto no existe o el módulo Secretos no está activado, la ejecución se rechaza.
Versiones
La ficha de un script lista sus Versiones (número, autor, fecha). Haz clic en una versión para ver su Contenido y sus Parámetros.
Nueva versión parte del contenido y los parámetros de la última versión; modifícalos y pulsa Crear. Una versión guardada ya no puede modificarse: cada cambio crea una nueva versión, lo que conserva el rastro de lo que se ha ejecutado. Una nueva versión puede usarse de inmediato, sin paso de aprobación.
Desde la versión mostrada, Ejecutar lanza el script e Historial muestra sus ejecuciones (ver «Ejecutar un script»). Así puedes volver a lanzar una versión anterior.
Autorización por destino
La sección Autorización por destino decide quién puede lanzar este script en qué agentes Outpost. Cada regla asocia un Rol (un grupo de usuarios) con un Grupo de máquinas (definido en el módulo Agentes Outpost). Elige ambos y pulsa Añadir; Eliminar quita una regla.
- Sin ninguna regla, el script no puede lanzarse en ningún agente remoto.
- Para lanzar el script en un agente, hay que pertenecer al grupo de una regla cuyo grupo de máquinas contenga ese agente. Un agente que no pertenece a ningún grupo de máquinas no puede recibir ningún script.
- Estas reglas no afectan a la ejecución local en el servidor.
Cuando el módulo Agentes Outpost no está activado, la sección lo indica y no puede añadirse ninguna regla.
Resolución de problemas: creación rechazada
Cuando Crear rechaza un script o una nueva versión, la pantalla explica el motivo en tu idioma encima del formulario y conserva todo lo que has escrito: corrígelo y vuelve a guardar. La API (POST /api/v1/scripts, POST /api/v1/scripts/{id}/versions) responde 400 (404 para un script eliminado, ScriptNotFound) con el código estable (error), una frase en inglés (message), la clave de traducción (messageKey) y sus valores (parameters). El mensaje técnico queda en el registro del servidor. Por la API, un campo obligatorio ausente o vacío (nombre, contenido, nombre de un parámetro) o un valor de enumeración desconocido en forma de texto se rechaza antes, por la validación estándar de la API (400 en formato ProblemDetails).
| Código | Causa | Qué hacer |
|---|---|---|
ScriptNameRequired |
El nombre está vacío | Dar un nombre al script |
ScriptContentRequired |
El contenido está vacío | Escribir el script |
UnknownScriptEngine |
El motor enviado a la API no existe | Elegir un motor de la lista (GET /api/v1/scripts/engines) |
UnknownTargetScope |
El alcance enviado a la API no existe | LocalOnly, AgentsOnly o Both |
InvalidDefaultTimeout |
El timeout predeterminado es inferior a 1 segundo | Indicar 1 segundo o más, o dejarlo vacío |
DefaultTimeoutAboveMaximum |
El timeout predeterminado supera 24 horas (86 400 segundos) | Indicar 86 400 segundos o menos |
InvalidDefaultRetryCount |
El número de reintentos es negativo | Indicar 0 o más |
DefaultRetryCountAboveMaximum |
El número de reintentos supera 10 | Indicar 10 o menos |
InvalidGroupConfirmationThreshold |
El umbral de confirmación (API) es negativo | Indicar 0 o más |
DuplicateScriptName |
Otro script ya tiene este nombre (sin tener en cuenta mayúsculas, acentos ni espacios en los extremos); dos creaciones simultáneas del mismo nombre: la segunda recibe este rechazo | Elegir otro nombre |
ScriptContentTooLarge |
El contenido supera 2 MB (se muestran el tamaño y el máximo, en bytes) | Aligerar el script, o pasar los datos voluminosos a un archivo que el script lea |
MalformedSecretReference |
Una referencia de secreto está mal escrita | Escribir {{secret:nombre-del-secreto}} |
ParameterNameRequired |
Una fila de parámetro no tiene nombre | Poner nombre al parámetro o eliminar la fila |
DuplicateParameterName |
Dos parámetros tienen el mismo nombre (se muestra el nombre); en PowerShell, mayúsculas y minúsculas cuentan como iguales | Dejar una sola fila por nombre |
InvalidParameterRegex |
La regex de validación del parámetro (se muestra el nombre) no es válida | Corregir la expresión regular |
InvalidParameterBounds |
El Mín del parámetro (se muestra el nombre) supera su Máx | Invertir o corregir los límites |
EnumParameterWithoutValues |
Un parámetro Enum (se muestra el nombre) no tiene ningún valor permitido |
Indicar los valores separados por comas |
ScriptNotFound |
El script se eliminó mientras se escribía una nueva versión: la pantalla lo explica sin volver a mostrar el formulario, la API responde 404 |
Volver a la lista de scripts |
VersionConflict |
Se estaban guardando otras versiones del mismo script al mismo tiempo, varias veces seguidas; la API responde 409 |
Vuelve a guardar |
Un contenido demasiado grande siempre se rechaza con este código, nunca con un error del servidor sobre el tamaño de la petición.
Cualquier otro error no es un rechazo: la pantalla muestra la página de error y la API responde 500, sin el mensaje técnico.
GOLIVE: scripts descartados
Durante una puesta en servicio (GOLIVE), cada script promovido pasa los mismos controles que la pantalla Crear: nombre, límites del timeout y del número de reintentos, tamaño y referencias de secreto del contenido, parámetros de las versiones que se añadirán, y un nombre libre en la instancia de destino. Un script que no los pasa aparece ya en la vista previa con un aviso «Script descartado» y el motivo (por ejemplo «otro script de esta instancia ya tiene este nombre»), seguido del valor en cuestión y, para una versión, de su número (v3). Ese script no se aplica, ni un proceso que lo use; el resto del GOLIVE sí. Corrígelo en la instancia de origen (o cambia el nombre del script de la instancia de destino) y vuelve a promoverlo.
Un script se empareja de una instancia a otra por su identificador, el mismo en todas: se actualiza, nunca se vuelve a crear. Un script creado a mano en cada instancia se encuentra por su nombre.
Ver también
- «Ejecutar un script»: lanzar un script y seguir su resultado.
- «Seguir los agentes Outpost»: los agentes y los grupos de máquinas.