Comandos de crew

Un crew consiste en varias máquinas que ejecutan Collie bajo un lead, y el teléfono accede al herd de cada máquina a través de la URL única del lead. El lead es la máquina a la que accede el teléfono, las demás máquinas son miembros y el deputy es el único miembro autorizado para asumir el control.

collie join y collie leave siguen funcionando. Son alias de collie crew join y collie crew leave, utilizando los mismos argumentos y códigos de salida.

collie pack también sigue funcionando para cada verbo de esta tabla. Es un alias de collie crew con los mismos argumentos y códigos de salida. collie docs pack imprime esta página y la dirección /pack de la aplicación web redirige a /crew. Los tres desaparecen en 2.0.0 (ADR 0038).

Los comandos deputy, approve-promote y promote gestionan la conmutación por error. Para obtener instrucciones de configuración y recuperación, consulte docs/deployment.md → la puerta de espera y el día fatídico.

Dos máquinas, un crew

Dos comandos añaden una máquina, uno para Herdr y otro para Collie, y existe una ruta manual para un host al que crew add no puede conectarse por ssh y para un lead que sirve HTTP sin cifrar.

herdr machine add --label <name> <ssh-target>   # prepare the remote host
collie crew add <ssh-host>                      # install Collie there and enroll it

herdr machine add se ejecuta en la máquina frente a la que está sentado. Instala Herdr en el host remoto y lo guarda en la propia lista de Herdr, pero no añade la máquina a la crew. collie crew add se ejecuta en el lead. <ssh-target> y <ssh-host> son el mismo host, escrito como user@host o como un alias de Host de su ~/.ssh/config, y <name> solo etiqueta la lista de Herdr.

collie crew add <ssh-host> instala Collie en el host remoto a través de su propio SSH y lo registra. Genera el token localmente, aprovisiona Collie en la máquina remota y ejecuta collie crew join allí. Requiere Herdr preinstalado en el host remoto, que herdr machine add coloca allí, por lo que los dos comandos van juntos. Un lead que sirve HTTP sin cifrar necesita un paso manual adicional, porque crew add no admite --insecure: ejecute collie crew join --insecure en la máquina que se une. Utilice crew add o la vía manual para un host determinado, nunca ambos. collie crew add sin destino lista los hosts que su configuración de SSH y Herdr ya conocen, combinados según el host al que resuelve cada nombre; elija de esa lista en lugar de escribir el host de una segunda forma (abajo).

crew add toma la ruta indicada por su propio tipo de instalación. Un lead que se ejecuta desde un checkout de git, como ocurre con la instalación del plugin de Herdr, envía su propio commit al miembro y lo compila allí, por lo que dicho miembro requiere git y Bun. Un lead instalado desde instalación independiente o mediante un paquete no tiene commit; por tanto, instala el miembro a partir del release que ejecuta él mismo, enviando el instalador propio de Collie a través del mismo ssh, requiriendo en su lugar curl, tar y sha256sum o shasum. --path define el checkout remoto en la primera ruta y la raíz de instalación en la segunda. Si un miembro ya ejecuta el otro tipo de instalación, la operación se rechaza en lugar de sobreescribirse, indicando el comando exacto para resolverlo. En esa segunda ruta, el miembro descarga el release directamente desde github.com; un miembro sin conexión hacia github.com requiere entonces un lead ejecutado desde un checkout.

El comando de terminal collie crew update sigue las mismas dos rutas y evalúa la misma condición para elegir una: un lead ejecutado desde un checkout envía su propio commit a cada miembro, mientras que un lead basado en instalación independiente o en paquete actualiza cada miembro a la versión de release que él mismo ejecuta. En un lead de tipo release, si un miembro se ejecuta desde un checkout de git se omite, indicando en su fila el comando único para actualizarlo: collie update --to-tag v<version> en esa máquina. En un lead basado en checkout, si un miembro fue instalado mediante install.sh se omite a la inversa: este recibe releases, por lo que la página Updates del teléfono se encarga de nivelarlo. Un miembro omitido nunca detiene la ejecución, y la confirmación lo contabiliza por separado.

La ruta manual consta de cuatro comandos. Utilícela para un host no accesible mediante ssh, o para un lead que sirve HTTP plano, y no por el tipo de instalación del lead: cualquier tipo de lead añade un miembro mediante crew add. El lead es la instancia a la que el teléfono ya tiene acceso, y la máquina que se une debe tener Collie instalado y en ejecución.

1. 01
   En el lead, genere el token.

   collie crew invite        # prints the token, then the join command to run

   El token es de una sola línea: <token>.<lead-fingerprint>.

1. 01
   En la máquina que se une, únase a la crew y pegue el token cuando se le solicite.

   collie crew join https://lead.tail1234.ts.net

   Copie la dirección de la salida de invite. Es la de su propio lead, no la de este ejemplo.

1. 01
   En el lead, reinícielo para que el proceso en ejecución detecte al nuevo miembro.

   collie restart

1. 01
   En el lead, compruebe que el enlace ha respondido.

   collie crew status        # the new member, its address, and whether the link answered

Los tokens son de un solo uso, válidos durante diez minutos y se muestran una sola vez. El lead solo almacena el hash. Ejecutar invite reinicia el proceso del lead para que pueda aceptar el registro entrante e imprime la línea de unión incluyendo el nombre del lead.

El paso 3 es un segundo reinicio, y join lo indica al finalizar. invite reinició el lead para que pudiera aceptar el registro. Después, join escribió el nuevo miembro en el disco, y el proceso en ejecución no redirige tráfico a ese miembro hasta que se reinicie de nuevo.

En un terminal interactivo, join solicita el token. En un script, pase - y proporcione el token por stdin:

collie crew join https://lead.tail1234.ts.net -   # paste the token on stdin

Pase @<file> en su lugar para leer el token desde el disco. Pasar tokens en texto plano directamente como argumentos muestra una advertencia, ya que las listas de procesos exponen los argumentos a todos los usuarios locales (CREW_PROTOCOL.md §8.3).

Establezca la dirección del lead en cualquier nombre de host o host:port accesible desde este nodo. Una dirección sin esquema ni puerto se resuelve en https://<host>:8787, el puerto al que se vincula el propio listener de Collie.

Lo que imprime crew invite depende de cómo se publique el lead. En el modo HTTPS predeterminado, el lead escucha en loopback y tailscale serve lo publica en el puerto 443. Por lo tanto, invite imprime https://<full-tailnet-name>, que se conecta al puerto 443. Si se cambió la puerta de entrada con COLLIE_SERVE_PORT, imprime <name>:<port>. Con COLLIE_SERVE_MODE=http, el propio listener del lead responde en el puerto 8787 mediante HTTP sin cifrar, y invite imprime el nombre corto, incluyendo el puerto solo si se modificó. join solicita confirmación una vez antes de enviar el token a través de HTTP sin cifrar, y --insecure lo confirma automáticamente. Una dirección http:// explícita aún requiere --insecure y no solicita ninguna confirmación.

crew add entrega al miembro la misma puerta de entrada, por lo que el miembro también se conecta al puerto 443. Un nombre simple implicaría el puerto 8787, el cual un lead detrás de tailscale serve no expone a la tailnet.

--address en crew join es la dirección a la que el lead llama a esta máquina, y necesita un puerto: --address <host>:8787. join rechaza una dirección sin puerto, porque el lead intentaría llamar al puerto 443. Una dirección https://host:8787 sigue siendo aceptada y se almacena como host:8787.

La selección del multiplexor es local para cada nodo. Configure COLLIE_MUX en el .env propio de ese nodo, en ~/.config/collie/.env en una instalación binaria o en el directorio de configuración de plugins de Herdr en una instalación de Herdr. El protocolo de crew, que es la conexión directa entre las máquinas, no contiene campos específicos del multiplexor. Tenga en cuenta que los pares solo se han probado con Herdr en v1 (CREW_PROTOCOL.md §16).

crew add define ese valor para un nuevo miembro, ya que este no siempre puede determinarlo por sí mismo. Si el miembro ejecuta exactamente un multiplexor, se deja intacto y seleccionará ese durante su primer inicio. Si ejecuta varios, el lead solicitará una decisión, registrándose la respuesta como COLLIE_MUX en el .env de dicho miembro. Si el miembro ya tiene uno asignado, tampoco se modifica. Indique --mux <name> para responder por anticipado o para sustituir un valor preexistente. Un miembro sin ningún multiplexor en ejecución recibirá una advertencia y no se registrará nada, impidiendo su primer inicio hasta que se ejecute uno.

Máquinas de Herdr y el crew

Las máquinas guardadas de Herdr y un crew de Collie son dos listas separadas, y ninguna alimenta a la otra.

Para añadir una máquina, consulte Dos máquinas, un crew más arriba.

La lista de máquinas de Herdr pertenece a su ventana de Herdr. Herdr 0.9.0 conserva los destinos SSH guardados en su cliente y abre cada uno mediante SSH cada vez que se utiliza. Se obtienen terminales en esas máquinas, en esa ventana, en la máquina donde se está trabajando.

Una crew es Collie en cada máquina, y el lead se comunica con cada miembro mediante el enlace cifrado propio de Collie, configurado una sola vez mediante una instalación que utiliza su SSH. Una crew también muestra terminales y transmite más que terminales. Transfiere subidas de archivos. Mantiene el journal y el registro de auditoría de cada máquina en la máquina que ejecutó el panel. Actualiza toda la crew a partir de una única confirmación en el teléfono. Puede transferir la puerta de acceso a un deputy cuando el lead deja de responder. Funciona igual bajo tmux y zellij, que no disponen de ninguna lista de máquinas.

Tres hechos mantienen separadas las dos listas, y cada uno constituye un motivo por sí solo.

El teléfono nunca almacena una clave SSH. Una clave SSH da acceso a una shell completa en la máquina, y un teléfono se puede perder. En su lugar, el teléfono almacena un código de emparejamiento emitido por el lead, que abre la aplicación y nada más, y collie devices revoke <label> revoca ese código en caliente, sin necesidad de reiniciar (emparejar un dispositivo).

Las subidas de archivos, el journal y el registro de auditoría residen en la máquina que ejecuta el panel. Y el enlace de la crew, que es como Collie denomina a la línea cifrada entre dos máquinas, no necesita SSH una vez que el miembro se ha registrado.

De este modo no se configura lo mismo dos veces. Se configura SSH una vez y ambas herramientas lo utilizan. Herdr mantiene su lista para su propia ventana y Collie mantiene el crew para el teléfono. Agregar una máquina a Herdr no la agrega al crew. Eliminarla de Herdr no la elimina del crew. Un miembro del crew que ejecuta tmux o zellij nunca aparece en la lista de Herdr.

collie crew add sin destino ofrece candidatos de ambas listas, para no escribir un host dos veces. Lee entradas Host en ~/.ssh/config y ejecuta herdr machine list --json. Combina las dos listas según el destino ssh al que resuelve cada nombre. El comando sigue un Include en esa configuración con un nivel de profundidad, y solo para rutas bajo ~/.ssh/. No ofrece un alias en un archivo incluido desde otro archivo incluido. Cada fila muestra de dónde proviene el nombre: ssh config, herdr o ambos. Una fila para una máquina que ya está en este crew lleva el id de ese miembro en lugar de un número.

Cómo se conecta una crew

Solo el lead expone una puerta de acceso, y ninguna otra máquina de la crew expone ninguna.

El lead es la puerta de acceso administrada y sirve la PWA. El teléfono accede a él mediante HTTPS en /api/* y no se comunica con nada más. El lead accede a cada miembro en /crew/v1/*, a través de TLS mutuo fijado que transporta el secreto de la crew. Un miembro es un Collie completo sin puerta de acceso, y mantiene sus propios agentes, journal, subidas de archivos y registro de auditoría. La administración se realiza completamente mediante la CLI, sin acciones en la interfaz de Herdr. La propia conexión se especifica en CREW_PROTOCOL.md.

El código viaja a través de su propio SSH a cada máquina. crew add instala un miembro de esa forma y crew update lo actualiza. El enlace de la crew transporta datos de ejecución y nunca se convierte en un canal de distribución.

Un deputy es un par que el lead designó previamente. Vincula una puerta de reserva con tres rutas, y esa puerta nunca se publica. El silencio del lead la activa y la propia credencial de emparejamiento la consume, de modo que el teléfono puede comunicarse con el deputy mientras el lead esté ausente.

Miembros que no fueron instalados mediante install.sh

Un crew actualiza a cada miembro desde el teléfono, excepto a los miembros cuyos archivos pertenecen a otro gestor.

collie crew update y la actualización del crew con un toque desde el teléfono preparan una nueva versión junto a la anterior y la reemplazan. Eso funciona en las dos instalaciones que generan el script de instalación y Herdr, y no funciona en todas las instalaciones, por lo que el crew informa de las demás en lugar de marcarlas como fallidas.

Un miembro empaquetado espera a su gestor de paquetes. Donde pacman, nix o brew colocan los archivos, ese gestor es su propietario, y Collie no reemplazará un archivo que no le pertenece (una instalación por paquete). El crew nunca le envía una actualización, lo muestra como "espera al gestor de paquetes" con el comando para su prefijo donde se pueda indicar uno, y contabiliza la ejecución como completa sin él. Se nivela al ejecutar ese comando en esa máquina, y la línea se borra en la siguiente comprobación.

Un LEAD empaquetado sigue nivelando a sus miembros. El lead rechaza actualizarse a sí mismo por el mismo motivo, siendo esa la única causa del rechazo: tanto el teléfono como collie crew update nivelan cada miembro a la versión que el lead ejecuta en ese momento, requiriendo una sola confirmación global. Tras actualizar el lead mediante el gestor de paquetes y ejecutar collie restart en él, ningún elemento se nivela automáticamente; una confirmación adicional en la página Updates del teléfono actualiza los miembros a la nueva versión del lead.

Un checkout desde el código fuente constituye un miembro completo, siempre bajo un lead que también lo sea. Un miembro clonado y compilado manualmente recibe la actualización de equipo desde un lead basado en checkout: dicho lead envía su commit, recompila y reinicia exactamente igual que consigo mismo. Bajo un lead sin commit, collie crew update lo omite e indica ejecutar collie update --to-tag v<version> en esa máquina.

Así que un crew mixto es un crew normal. Un toque nivela a todos los miembros que el lead puede actualizar, nombra a los que no puede, y el crew queda nivelado nuevamente tras ejecutar sus gestores de paquetes.

El nombre del crew

El nombre de un crew es información visual, y solo el lead lo muestra. collie crew invite --name "the shed" nombra a un crew cuando se crea, y un crew creado sin --name se llama "collie crew". Para cambiarlo más tarde, ejecute collie crew rename <name> en el lead. El verbo reescribe el nombre en el propio crew-trust.json del lead y reinicia el bridge, por lo que collie crew status y la página del crew del teléfono muestran el nuevo nombre de inmediato.

No se envía nada a un miembro. El nombre viaja una sola vez, en la respuesta del lead a un registro, y el miembro lo almacena sin mostrarlo nunca. Una máquina que se une tras el cambio de nombre recibe el nombre nuevo, y los miembros que ya estaban en el crew conservan la cadena antigua en un campo que nadie lee. El nombre se recorta, tiene un máximo de 64 caracteres y no contiene caracteres de control. En un peer, o en una máquina que no pertenece a ningún crew, el verbo rechaza la acción e indica dónde ejecutarlo.

Actualización a 1.9.0 desde 1.7.0 o 1.8.x

Actualice cada miembro a 1.8.x antes de migrar el lead a 1.9.0. 1.9.0 utiliza una única versión del enlace de crew, y 1.8.0 es la compilación más antigua compatible.

No es necesario recordar qué versiones son esas. A partir de 1.8.0, el aviso de actualización indica cuándo la próxima versión cambia el enlace de crew, en la banda, en la tarjeta de Actualizaciones y en la notificación push diaria, indicando lo mismo: actualizar primero el lead, los miembros van después.

1.8.0 renombra los identificadores que lee una máquina. Las rutas de conexión, las dos claves de entorno, los tres archivos de estado y el prefijo del diario ahora indican crew (ADR 0039). El enlace se comporta exactamente igual que antes, y nada de lo automatizado mediante scripts debe modificarse el mismo día.

1.8.0 mantuvo compatibilidad con miembros 1.7.0 durante una versión; 1.9.0 ya no lo hace. Un lead 1.8.0 también respondía en las rutas antiguas, por lo que un miembro que continuara en 1.7.0 seguía comunicándose con él. 1.9.0 eliminó esta compatibilidad, tal como se definió en ADR 0039.

Un miembro que continúe en 1.7.0 bajo un lead 1.9.0 aparece dos veces, y en ningún caso en silencio. La comprobación previa del lead marca en rojo la verificación version, indicando ambas versiones y el comando a ejecutar; este fallo bloquea la actualización de crew en lugar de iniciar un despliegue que no puede completarse. En collie crew status, el mismo miembro muestra incompatible, con un motivo que finaliza en "this build speaks 2".

Actualice ese miembro desde su propia máquina. Un lead 1.9.0 ya no puede comunicarse con él a través del enlace; ejecute collie update en dicha máquina, actualícelo a 1.8.x o posterior, y el lead lo detectará en el siguiente sondeo.

Los nuevos nombres

Renombre las dos variables de entorno en su .env antes de migrar a 1.9.0. Una compilación 1.9.0 no lee la clave antigua ni emite advertencias sobre ella.

En un diario que abarque la actualización, busque mediante grep ambos prefijos:

journalctl --user -u collie | grep -E '\[(crew|pack)\]'

Una línea escrita antes de la actualización muestra [pack], y una línea escrita después muestra [crew]. Una vez que toda la crew esté en 1.8.0, filtre únicamente por [crew].