Saltar al contenido principal

Agente SaaS non-root

El connector se instala con un usuario Linux normal en el host que tiene conectividad RFC hacia SAP y salida hacia el origen exacto que muestra Tenant Console. En producción ese origen usa HTTPS. El entorno de desarrollo puede mostrar HTTP con una excepción explícita y un warning visible. No escribe en /opt, /etc ni /var: sus generaciones, estado y logs quedan bajo $HOME.

Antes de instalar​

  1. Entra como admin en Tenant console > Connectors.
  2. Crea el connector y conserva el código de instalación de un solo uso. Caduca a los 30 minutos y sólo se muestra una vez.
  3. Abre Add agent guide y genera la URL temporal del bootstrap.
  4. Ejecuta la guía en el host final y con el usuario Linux que mantendrá el servicio.

Connectors en Tenant console

Elegir el paquete y el entorno​

La guía y Download verified bootstrap muestran Development candidate cuando el entorno de desarrollo tiene un candidato confiable y vigente para pruebas. Seleccionan la generación válida más reciente, con bootstrap y runtime firmado compatibles para Linux amd64 del mismo release. En producción muestran Stable package y sólo permiten paquetes estables confiables.

Si falta la identidad válida, el bootstrap o su runtime compatible verificado, la instalación queda bloqueada y Generate permanece desactivado. No cambies de entorno ni omitas la verificación para habilitarlo.

Prueba el candidato en desarrollo antes de solicitar una promoción manual a producción. Generar una URL o descargar el bootstrap no actualiza ni reenrola un connector existente. Request upgrade conserva el canal estable; mostrar un candidato de desarrollo no lo habilita como upgrade automático.

Descargar el bootstrap​

Descarga el binario pequeño indicado por la consola y comprueba su SHA-256 antes de ejecutarlo:

wget -O spot-connector-bootstrap_<version>_linux_amd64 \
  "<temporary-bootstrap-url>"
echo '<bootstrap-sha256>  spot-connector-bootstrap_<version>_linux_amd64' | sha256sum -c -
chmod 0755 spot-connector-bootstrap_<version>_linux_amd64

No descargues ni extraigas manualmente el runtime y no uses curl | sh. El bootstrap lleva embebida la raíz pública TUF de su entorno, valida metadata vigente y el digest del runtime antes de extraer o ejecutar nada. Cada entorno usa una raíz y un repositorio de confianza independientes; una instalación de producción nunca acepta una raíz no productiva.

Si la consola indica que no existe un bootstrap confiable sincronizado desde Platform, detente: no hay fallback a un tarball antiguo ni a una descarga sin verificar.

Instalar y enrolar​

Para mantener el servicio después de cerrar SSH, habilita una vez linger:

sudo loginctl enable-linger "$USER"
loginctl show-user "$USER" -p Linger --value

Ejecuta el comando exacto mostrado por Add agent guide:

./spot-connector-bootstrap_<version>_linux_amd64 \
  --control-plane '<tenant-control-plane-url>' \
  --target '<trusted-runtime-target>' \
  --version '<connector-version>' \
  --start-mode systemd-user

No sustituyas el origen mostrado por otro host. --control-plane siempre debe usar el origen SaaS canónico del tenant. La URL temporal sólo descarga el bootstrap y puede usar un endpoint de descarga distinto; nunca se convierte en el control plane. Si la consola muestra HTTP, el comando generado añade --development-http: es una excepción visible limitada al host SaaS canónico o loopback y se conserva en el launcher del servicio. HTTP no valida la identidad del servidor; elimina la excepción cuando SaaS use HTTPS. La verificación TUF y de digest permanece obligatoria en ambos casos.

Introduce el código sólo cuando aparezca el prompt oculto. No lo añadas a la URL, argumentos, historial, logs o stdout. Como alternativa automatizada, usa --install-code-file con un fichero temporal 0600 y bórralo al terminar.

El connector genera localmente su credencial persistente de 256 bits y registra sólo su hash en SPOT. La guarda de forma atómica en $HOME/.config/spot/connector.json con permisos 0600; nunca compartas ese fichero.

stat -c '%a %n' "$HOME/.config/spot/connector.json"

Verificar el servicio​

systemctl --user status spot-agent-saas.service --no-pager
journalctl --user -u spot-agent-saas.service -n 80 --no-pager
readlink "$HOME/spot-agent-saas/current"

La tarjeta pasa de Pending a OK después de autenticarse, aplicar configuración, enviar heartbeat saludable y reanudar telemetría.

Una instalación canónica mantiene current -> generations/<version>. El runtime también reconoce el current/ plano dejado por un updater afectado y lo normaliza atómicamente en el siguiente upgrade, conservando estado y generación anterior. No crees el enlace a mano ni muevas esos directorios: podrías separar el binario de su SDK, estado o configuración.

Si el journal muestra current/scripts/env.sh: No such file or directory, detén el servicio y comprueba su unidad:

systemctl --user cat spot-agent-saas.service
test -x "$HOME/spot-agent-saas/bin/spot-agent-saas"
test -x "$HOME/spot-agent-saas/scripts/env.sh"

Si el connector heredado ni siquiera puede consumir el upgrade, conserva $HOME/.config/spot/connector.json y usa el bootstrap verificado más reciente como puente de recuperación; no reenroles ni borres la credencial. Este puente es excepcional. systemctl --user enable --now no reinicia una unidad que ya estaba activa: si la tarjeta sigue mostrando la versión anterior, ejecuta una vez systemctl --user restart spot-agent-saas.service. El upgrade siguiente debe autoactivarse sin intervención.

Si systemd --user no está disponible, ejecuta un bootstrap nuevo con un código nuevo y --start-mode nohup. Consulta el estado con $HOME/spot-agent-saas/scripts/saas-status.sh.

Perfil de recursos y verificación​

La unidad firmada systemd --user aplica CPUQuota=200%, MemoryHigh=1G y MemoryMax=1280M al proceso completo. El runtime mantiene GOMAXPROCS=2 y GOMEMLIMIT=320MiB; este último es un objetivo blando de memoria administrada por Go, no un techo duro ni toda la memoria nativa que puede usar el SDK RFC. MemoryHigh activa presión antes del máximo y MemoryMax establece la cota del cgroup.

Después de instalar o actualizar, comprueba las propiedades efectivas del servicio y el PID que las usa. SPOT conserva el perfil confirmado anterior mientras valida la salud de la generación nueva y aplica la unidad firmada nueva sólo después. Un override temporal puede cambiar el servicio en ejecución, pero no demuestra que ese perfil esté instalado para el siguiente arranque.

Mide RSS/PSS, eventos memory.high, PSI y progreso de las colecciones bajo una carga SAP representativa, dejando headroom para el resto del host. Un margen mayor para memoria nativa no demuestra una fuga resuelta, estabilidad indefinida ni compatibilidad con cualquier sistema SAP. No omitas las comprobaciones de salud o rollback para forzar una actualización.

Actualizaciones y rollback​

SPOT solicita automáticamente las versiones stable según la oleada asignada. Connectors > Actions > Request upgrade queda como acción administrativa puntual cuando está disponible; nunca propone bajar desde una candidate más nueva a la última stable. El supervisor:

  • verifica TUF, metadata no expirada y digest;
  • instala una generación nueva sin sobrescribir la activa;
  • cambia el puntero current atómicamente;
  • confirma arranque, configuración, autenticación, heartbeat y telemetría;
  • recupera la generación anterior si no alcanza salud.

No reenroles para actualizar, no reemplaces manualmente el tar y no reinicies el servicio como parte de un upgrade normal: la generación nueva se autoactiva. SPOT distribuye stable por oleadas y puede pausarlas si empeoran heartbeats, telemetría o rollback.

Re-enrollment y revocación​

Generar un código de re-enrollment no revoca la credencial que está funcionando. La sustitución se confirma sólo cuando el nuevo enrollment termina correctamente. Detén el servicio, genera el código y ejecuta:

"$HOME/spot-agent-saas/bin/spot-agent-saas" saas-enroll \
  --control-plane '<tenant-control-plane-url>' \
  --save \
  --start

Introduce el código por el prompt oculto. Disable connector o Revoke sí invalidan inmediatamente la credencial activa, los códigos pendientes, las sesiones y los upgrades solicitados.

Diagnóstico seguro​

"$HOME/spot-agent-saas/bin/spot-agent-saas" saas-pull-config
tail -n 80 "$HOME/spot-agent-saas/log/spot-agent-sap.log"

Revisa también Tenant console > Agent logs. No compartas connector.json, códigos, secretos SAP, claves Elastic ni configuración sin sanear. Un error de firma, metadata TUF expirada o digest inesperado detiene la instalación o el upgrade; no existe una opción productiva para omitir la verificación.

Las colecciones de cinco minutos están ancladas al reloj y repartidas durante el primer minuto del bloque. Observed es la hora devuelta por SAP; el inicio del bucket del gráfico no indica cuándo terminó la ingesta. Si parece faltar un punto, compara scheduled_at, start_delay_ms, @timestamp e ingested_at en Agent logs antes de aumentar la ventana de frescura.

El agente limita la concurrencia y consolida ciclos atrasados. El heartbeat incluye sólo contadores agregados de CPU, RSS/PSS, heap/GC/cgo, threads, cola, RFC y exportación. CPU debe calcularse entre dos muestras; el valor acumulado no es un porcentaje instantáneo.

Entorno y alcance de la comprobación​

Comprueba que el origen de la guía pertenece al entorno en el que trabajas. Desarrollo y producción mantienen instalaciones y confianza independientes; un bootstrap de un entorno no valida paquetes del otro. Si cambia el origen SaaS canónico, usa la guía actualizada y conserva las credenciales y el estado de la instalación existente según las instrucciones de soporte. No copies una instalación o datos de desarrollo para crear una instalación de producción.

Una prueba con configuración de demostración puede comprobar instalación, enrollment, heartbeat y recepción de configuración. No demuestra conectividad RFC, extracción SAP real ni una actualización desde una versión anterior. Para considerar una conexión SAP operativa, revisa además un resultado de colección reciente y datos nuevos de esa conexión. No confundas un heartbeat saludable con telemetría nueva.

Si sólo preparas una prueba temporal, conserva las instalaciones previas y, al terminar, revoca exclusivamente el connector de prueba y elimina su servicio, directorio y fichero temporal de código. Comprueba que el connector anterior sigue funcionando.