Saltar a contenido

Worker

El Clarive Worker es uno de los métodos de comunicación disponibles utilizados para enviar/recuperar archivos y ejecutar comandos en servidores remotos.

El Worker es un archivo ejecutable que necesita ser instalado en cada servidor de su red donde desee ejecutar ciertas operaciones DevOps, que típicamente son ejecutar comandos shell locales, enviar archivos (ship) y recuperar archivos (fetch).

El Worker es un agente pull, lo que significa que inicia la conexión al servidor pubsub de Clarive y espera instrucciones. Es ideal para casos donde el servidor que aloja el worker se ejecuta detrás de un firewall y no es directamente accesible por el servidor Clarive a través de SSH o un agente push como ClaX.

SO/Plataformas Soportadas

El Worker soporta 3 plataformas principales:

  • Versiones de Linux 2.6 o superiores, incluyendo CentOS 5.x o superior
  • Windows 7.x, 8.x, 10.x y Windows Server 2003 o superior
  • MacOS 10.12 o superior

Instalar el Worker

El Clarive Worker es un binario único y no tiene prerequisitos específicos. El único requisito es que el servidor donde se está instalando el worker pueda alcanzar el servidor Clarive directamente.

Típicamente el proceso para conectar su Servidor Clarive al resto de su infraestructura para construcción, despliegue y otras actividades relacionadas con DevOps es este:

  • Descargar el binario del Clarive Worker cla-worker al servidor
  • Registrar el worker con el servidor usando un passkey de proyecto
  • Iniciar el worker en línea o como demonio
  • Ejecutar sus reglas y pipeline de Clarive contra el worker

Requisitos del servidor Clarive

Para que el worker pueda conectarse, el servidor web de Clarive debe estar ejecutándose con el módulo pubsub activo.

Por defecto el módulo pubsub está activo y se inicia con el resto de los servicios web de cla web-start.

Capacidades del Worker

Una instancia de worker puede ejecutar las siguientes acciones en su servidor anfitrión:

  • recibir un archivo remoto del servidor Clarive y escribirlo localmente
  • enviar un archivo local al servidor Clarive
  • ejecutar cualquier comando arbitrario localmente en el servidor según lo solicitado por el servidor Clarive
  • evaluar instrucciones JavaScript arbitrarias en el servidor, usando bibliotecas NodeJS expuestas o importadas

Seguridad del Worker

El Worker solo se ejecuta como el usuario del SO actual con el que ha sido lanzado. Pero los comandos enviados por el servidor podrían escalar permisos si el usuario o ejecutable tienen algún tipo de permisos sudo, sticky bit o mecanismo similar.

Descargar el Worker

El Clarive Worker es de código abierto y puede descargarse desde la cuenta Github de Clarive:

 https://github.com/clarive/cla-worker/releases

El worker es un binario autocontenido disponible para Linux, MacOS y Windows y no tiene prerequisitos.

El binario del worker viene empaquetado en un binario auto-ejecutable. No se necesita instalación especial. Una vez que el archivo .zip o .tgz está descomprimido, use el ejecutable que coincida con su plataforma:

  • cla-worker/cla-worker-win.exe (Windows)
  • cla-worker/cla-worker-macos (MacOS)
  • cla-worker/cla-worker-linux (Linux)

Una vez descomprimido, renombre el archivo correcto:

MacOS:

cd cla-worker
mv cla-worker-macos cla-worker
rm cla-worker-*

Linux:

cd cla-worker
mv cla-worker-linux cla-worker
rm cla-worker-*

Windows:

cd cla-worker
ren cla-worker-win.exe cla-worker.exe
del cla-worker-*

Registrar el Worker

Para que un worker se conecte a un servidor Clarive necesita un passkey. Los passkeys están disponibles en base proyecto por proyecto. Cada proyecto Clarive puede o no tener un passkey, si el propietario del proyecto o administrador genera uno.

Para obtener el passkey, vaya a un proyecto dado (menú desplegable de proyecto), seleccione la opción de menú Deploy > Worker del menú izquierdo y presione el botón Register Worker en la parte superior. Se generará un nuevo comando de registro como tal:

cla-worker register --passkey (your project passkey) --url (url to your server) --save

Copie el comando de registro y péguelo en una terminal donde descomprimió el binario cla-worker para registrar su worker.

Important

Una vez generado, el passkey debe mantenerse en secreto, ya que podría permitir a un intruso registrar un worker como, por ejemplo, un worker de PRODUCCIÓN y secuestrar las tareas de despliegue de producción de un proyecto dado. Puede invalidar un passkey de registro abriendo la sección Register Worker y presionando el botón Invalidate si sospecha que el passkey está o podría estar comprometido.

El proceso de registro devolverá un par ID-token que es único para esta instancia de worker.

ℹ Registration token:  97d317df5ad3fbb68334657ec94aefe6
ℹ Projects registered:  ["CLARIVE"]
ℹ Start the worker with the following command:

            cla-worker run --id RKmp3hSwb --token 97d317df5ad3fbb68334657ec94aefe6

El token de registro devuelto es la "contraseña" del worker para acceder al servidor bajo un ID dado.

Si usó la opción --save durante el registro, los datos de registro también se guardarán en un archivo cla-worker.yml en el mismo directorio que el binario cla-worker.

Cuando existe un archivo cla-worker.yml correctamente registrado, simplemente puede iniciarlo con:

 cla-worker run

Si su archivo de configuración está en otra ruta, debe poner la ruta al archivo cla-worker.yml con la opción --config o -c:

 cla-worker run -c /path/to/cla-worker.yml

La URL del servidor también está en el archivo de configuración, en caso de que necesite modificarla. Mantenga los permisos del archivo cla-worker.yml seguros de ojos curiosos, ya que contiene su token de registro.

Important

El par ID-worker es análogo a un nombre de usuario/contraseña para su instancia de worker. Guárdelo en un lugar seguro. Si está comprometido un atacante podría hacerse pasar por el worker haciendo que el Servidor Clarive crea que está conectado al servidor correcto cuando de hecho está conectado a la infraestructura del atacante. Eso podría terminar con información o archivos sensibles siendo enviados por el Servidor Clarive al worker comprometido.

cla-worker.yml

Para mantener sus registros seguros, use el archivo cla-worker.yml.

Por defecto el archivo cla-worker.yml se carga desde una de las siguientes 4 posibilidades, en orden de precedencia:

  1. desde el parámetro --config filepath o -c /path/to/cla-worker.yml está presente
  2. desde la variable de entorno CLA_WORKER_CONFIG=/path/to/cla-worker.yml
  3. desde el directorio de trabajo actual, desde donde se inicia el binario
  4. desde el directorio home del usuario (variable de entorno HOME)
  5. desde /etc/cla-worker.yml

Para guardar su registro directamente en el archivo cla-worker.yml, use --save o --save /path/to/cla-worker.yml:

 cla-worker register --save --passkey 123428198291ad98d98c89b8

Estructura del archivo cla-worker.yml

Estos son los parámetros de configuración permitidos en el archivo de configuración:

id - el identificador único del worker token - el token devuelto por el proceso de registro passkey - la clave de acceso del proyecto para registrar workers verbose - para ejecutar el worker en modo verbose, establézcalo en verbose: true tags - una lista separada por comas de etiquetas envs - una lista separada por comas de entornos

Asignar un ID al Worker

Cada worker, una vez registrado, tendrá un ID único aleatorio correspondiente asignado a él.

Para facilitar la identificación de su worker, opcionalmente puede asignarle un ID único.

cla-worker register --id myworker --passkey 2323928198291ad98d98c89b8

Puede registrar un worker con el mismo ID contra muchos proyectos, pero nunca el mismo ID de worker dos veces para un proyecto dado.

Dar de baja el worker

Para dar de baja un Worker dado del servidor, haciéndolo disponible para re-registrarse con el mismo ID o simplemente para descatalogarlo de la lista de workers disponibles, ejecute el siguiente comando:

cla-worker unregister --id myworker --token [token]

Debe conocer el token correspondiente al id para poder dar de baja un worker.

Ejecutar el worker

Una vez registrado, inicie el worker con el siguiente comando usando el ID y token usados en el registro:

cla-worker run --id myworker --token 97d317df5ad3fbb68334657ec94aefe6

O simplemente, si tiene un archivo cla-worker.yml en su PATH con solo un registro (par ID-token):

cla-worker run

Opcionalmente, si tiene múltiples registros de ID en su archivo cla-worker.yml:

cla-worker run --id myworker

IU de gestión de Workers

Disponible en el área de proyecto, Deploy -> Workers.

Desde allí puede:

  • Obtener el passkey para registrar workers para un proyecto dado.

  • Monitorear el uso del worker.

  • Dar de baja workers, lo que elimina el worker de este proyecto.

  • Apagar workers, lo que mata el proceso en los servidores.

  • Deshabilitar workers, lo que no mata el proceso en el servidor pero previene que nuevos trabajos lo usen.

Warning

Apagar workers matará el proceso del servidor. Después de un apagado, reiniciar el worker requiere iniciar sesión manualmente en el servidor e iniciar el proceso.

Limitar Workers por entorno

Para limitar qué entornos están disponibles para un worker dado, limitando su uso a digamos QA o PROD, use las siguientes flags en la línea de comandos de cla-worker:

$ cla-worker run --id myworkerid --envs QA,PROD

# O separando cada entrada:

$ cla-worker run --id myworkerid --env QA --env PROD

Note

Los entornos necesitan existir en Clarive para que el worker se inicie exitosamente. Los nombres de entorno distinguen entre mayúsculas y minúsculas.

Establecer etiquetas de worker

Las etiquetas de worker son útiles para identificar las capacidades de un worker. Luego, al escribir rulebooks que hacen uso de un worker, puede solicitar cualquier worker disponible con una capacidad dada.

Ejemplos de etiquetas útiles podrían ser java (puede construir proyectos java), gcc (compilador C), nodejs, etc.

$ cla-worker run --id myworkerid --tags java,nodejs

# O separando cada entrada:

$ cla-worker run --id myworkerid --tag java --tag nodejs

Luego invoque su worker dentro de un rulebook con las siguientes opciones:

do:
    shell:
       worker: { tags: ['java'] }
       cmd: javac MyClass.java

Esto ejecutará su comando en el primer worker que soporte la etiqueta java (lo que significa que tiene un compilador Java disponible):

Uno podría tener varios workers dentro de un servidor dado, con diferentes ids y conjuntos de tag para diferentes capacidades.

Registrar worker en más de un proyecto

Esto no se recomienda debido al hecho de que crea una posible brecha de información del proyecto entre proyectos.

Si desea tener 2 o más proyectos ejecutándose en el mismo par user@hostname, recomendamos tener un workerid en base por proyecto, en lugar de compartir el mismo worker para más de un proyecto.

Aún así, si en cambio prefiere compartir el mismo workerid con diferentes proyectos, puede registrar su worker en más de un proyecto re-registrando un worker ya registrado con el passkey del nuevo proyecto.

Tenga en cuenta que los workers registrados en más de un proyecto llevan las siguientes advertencias:

  • los usuarios pueden ver qué proyectos comparten un worker a través de la IU de gestión de Workers.

  • si un usuario en un proyecto apaga o deshabilita un worker compartido, el worker quedará no disponible para todos los proyectos registrados.

  • dar de baja un worker, sin embargo, de un proyecto NO lo dará de baja de todos los proyectos.

Iniciar como demonio

Para ejecutar el Clarive Worker como demonio, es decir, para iniciar el proceso en segundo plano y recuperar el control en el shell, ejecute el siguiente comando:

cla-worker start --id myworker --token 97d317df5ad3fbb68334657ec94aefe6
ℹ spawning cla-worker in the background...
ℹ logfile=/opt/cla-worker/cla-worker.log
ℹ pidfile=/opt/cla-worker/cla-worker-myworker.pid
ℹ forked child with pid 16412

El id del proceso se almacena en el pidfile mientras que un registro de ejecución detallado se almacena en logfile. Estos pueden controlarse enviando la opción --logfile y --pidfile con la ruta completa a los archivos.

Para verificar el estado del demonio, el comando cla-worker status puede ser útil:

$ cla-worker status --id myworker
ℹ checking status for workerid=myworker and pidfile=/opt/cla-worker/cla-worker-myworker.pid
ℹ logfile=/opt/cla-worker/cla-worker.log
ℹ workerid=myworker is assigned pid=27532...
✔ worker is running with pid=27532

Para detener el demonio del worker, use lo siguiente:

cla-worker stop --id myworker
ℹ stopping daemon with pid=16412, from pidfile=/opt/cla-worker/cla-worker-myworker.pid
ℹ killed daemon with pid=16412
ℹ deleted '/opt/cla-worker/cla-worker-myworker.pid'

El comando stop buscará un pidfile en la ubicación predeterminada para un id dado . Si el pidfile se encuentra en otro lugar, pase al comando stop la ruta al pidfile con cla-worker stop --pidfile [pidfile].