artis3n.tailscale

Este rol instala y configura Tailscale en un sistema Linux.

Sistemas operativos soportados:

• Debian / Ubuntu
• CentOS / RedHat
• Rocky Linux / AlmaLinux
• Amazon Linux 2023 / Amazon Linux 2
• Fedora
• Arch Linux
• OpenSUSE
• Oracle Linux
• Raspbian

Consulta el workflow de CI para ver la lista de versiones de distribución que se prueban activamente en cada solicitud de extracción.

[!TIP] Este rol utiliza nombres de colección totalmente calificados de Ansible (FQCN) y, por lo tanto, requiere Ansible 2.11 o superior. La versión mínima requerida es Ansible 2.12, ya que fue la versión probada para compatibilidad durante la reestructuración FQCN.

Si tú o tu organización obtienen valor de este rol, agradecería mucho un patrocinio una vez o de forma recurrente.

• Salidas del rol
• Variables del rol
  • Requeridas
    • tailscale_authkey
    • tailscale_tags
    • tailscale_up_skip
  • Opcionales
    • estado
    • tailscale_args
    • tailscale_oauth_ephemeral
    • tailscale_oauth_preauthorized
    • insecurely_log_authkey
    • release_stability
    • tailscale_up_timeout
    • verbose
• Dependencias
  • Colecciones
• Ejemplo de Playbook
• Seguimiento de estado
• Licencia
• Información del autor
• Desarrollo y contribución

Este rol mostrará cualquier mensaje de error del binario de Tailscale para resolver cualquier error de configuración del usuario final con los argumentos de tailscale up. El valor de --authkey= será ocultado a menos que insecurely_log_authkey esté configurado como true.

Salidas del rol

Este rol proporciona las direcciones IP v4 y v6 del nodo Tailscale, así como la salida de tailscale whois contra el nodo como hechos. Se proporcionan varias piezas clave de información de whois directamente, y el resto de la salida de whois se almacena como un hecho JSON para tu conveniencia.

Hechos que se proporcionan:

tailscale_node_ipv4           (string): La dirección IPv4 del nodo Tailscale.
tailscale_node_ipv6           (string): La dirección IPv6 del nodo Tailscale.
tailscale_node_hostname_full  (string): El nombre de host completo (node.domain.ts.net) del nodo Tailscale.
tailscale_node_hostname_short (string): El nombre de host corto (node) del nodo Tailscale.
tailscale_node_created_at     (string): La marca temporal ISO-8601 de cuándo se creó el nodo Tailscale.
tailscale_node_tags           (list):   Las etiquetas asignadas al nodo Tailscale.
tailscale_node_services       (list):   Los servicios descubiertos que se ejecutan en el nodo Tailscale.
tailscale_node_whois          (dict):   La salida completa de `tailscale whois` contra el nodo Tailscale.

Variables del rol

Requeridas

Se debe presentar uno de tailscale_authkey o tailscale_up_skip. En la mayoría de los casos, utilizarás tailscale_authkey.

Si estás desinstalando Tailscale (state: absent), no se requiere tailscale_authkey ni tailscale_up_skip.

Si estás autenticándote con una clave OAuth, también debes establecer tailscale_tags.

tailscale_authkey

No se requiere si tailscale_up_skip está configurado como true.

Una clave de autorización de nodo Tailscale.

Se puede generar una clave de autorización de nodo en tu cuenta de Tailscale. El rol admite dos tipos de claves:

• Clave de autorización (tskey-auth-XXX-YYYYY) https://login.tailscale.com/admin/authkeys
• Clave OAuth (tskey-client-XXX-YYYY) https://login.tailscale.com/admin/settings/oauth

[!IMPORTANTE] El uso de una clave OAuth requiere las siguientes variables del rol: tailscale_tags (debe ser proporcionada), tailscale_oauth_ephemeral (por defecto es true), y tailscale_oauth_preauthorized (por defecto es false).

Ten en cuenta que las claves de autorización caducan hasta un máximo de 90 días después de ser generadas. Los secretos OAuth no caducan a menos que sean revocados, y el token de acceso OAuth generado caduca después de 1 hora.

Para más información, consulta la página de Tailscale sobre clientes OAuth, especialmente Generación de claves de autorización de larga duración.

Si se utiliza una clave OAuth, asegúrate de otorgar el alcance de dispositivos write al cliente OAuth.

Este valor debe tratarse como un secreto sensible.

tailscale_tags

Predeterminado: []

Aplica las etiquetas proporcionadas a los nodos Tailscale configurados por este rol (a través de la opción --advertise-tags de tailscale up). Para más información, consulta ¿Qué son las etiquetas?

[!NOTA] Las etiquetas son necesarias para los clientes OAuth (tailscale_authkey con clave OAuth).

Las entradas no deben incluir tag:. Por ejemplo, tailscale_tags: ['worker'] se traduce en --advertise-tags=tag:worker.

tailscale_up_skip

Si está configurado como verdadero, no se requiere tailscale_authkey.

Predeterminado: false

Indica si se debe instalar y configurar Tailscale como un servicio, pero omitir la ejecución de tailscale up. Es útil cuando se empaqueta una instalación de Tailscale en un proceso de construcción, como la creación de AMI, cuando el servidor aún no debe autenticarse en tu red Tailscale.

Opcionales

estado

Predeterminado: latest

Indica si se debe instalar o desinstalar Tailscale. Si se define, estado debe ser latest, present o absent.

Este rol utiliza latest por defecto para ayudar a asegurar que tu software se mantenga actualizado e incorpore las últimas características de seguridad y producto. Para los usuarios que deseen más control sobre la deriva de configuración, present no actualizará Tailscale si ya está instalado.

Los cambios en tailscale_args se aplicarán tanto en latest como en present; este parámetro solo afecta la versión de Tailscale instalada en el sistema de destino.

Si se establece en absent, este rol desregistrará el nodo Tailscale (si ya está autenticado) y limpiará o deshabilitará todos los artefactos de Tailscale agregados al sistema.

Ten en cuenta que ni tailscale_authkey ni tailscale_up_skip son requeridos si estado está configurado como absent.

tailscale_args

Pasa argumentos de línea de comandos a tailscale up.

Ten en cuenta que se utiliza el módulo command, que no admite expresiones de subceldas ($()) ni operaciones bash como ; y &. Sólo se pueden pasar argumentos de tailscale up.

[!PRECAUCIÓN] No uses esto para --authkey. Usa la variable tailscale_authkey en su lugar.

No uses esto para --advertise-tags. Usa la variable tailscale_tags en su lugar.

No uses esto para --timeout. Usa la variable tailscale_up_timeout en su lugar.

Cualquier salida stdout/stderr del binario de tailscale se imprimirá. Dado que las tareas se mueven rápidamente en esta sección, se introduce una pausa de 5 segundos para dar más tiempo a los usuarios para darse cuenta de que se imprimió un mensaje.

Los errores continuarán fallando la ejecución del rol. El valor sensible de --authkey se ocultará por defecto. Si necesitas ver el valor no ocultado, consulta insecurely_log_authkey.

tailscale_oauth_ephemeral

[!NOTA] Usado solo cuando tailscale_authkey es una clave OAuth.

Predeterminado: true

Registrar como un nodo efímero, si es true.

tailscale_oauth_preauthorized

[!NOTA] Usado solo cuando tailscale_authkey es una clave OAuth.

Predeterminado: false

Omitir la aprobación manual del dispositivo, si es true.

insecurely_log_authkey

Predeterminado: false

Si se establece como true, el comando "Llevar Tailscale Up" incluirá el valor real de la clave de autorización de Tailscale al registrar cualquier error encontrado durante tailscale up. Por defecto, la clave de autorización no se registra en las finalizaciones de tareas exitosas y se oculta en la salida stderr de este rol si ocurre un error.

Si estás encontrando un error al llevar Tailscale arriba y deseas que la tarea "Llevar Tailscale Up" no oculte el valor de la clave de autorización, configura esta variable en true.

Sin embargo, si la clave de autorización es inválida, el rol relatará el mensaje de error de Tailscale al respecto:

release_stability

Predeterminado: stable

Indica si se debe utilizar la rama estable o inestable de Tailscale.

stable:

Lanzamientos estables. Si no estás seguro de qué rama usar, elige esta.

unstable:

La vanguardia. Se lanza temprano y a menudo. ¡Espera irregularidades!

tailscale_up_timeout

Predeterminado: 120

Define la duración del tiempo de espera para el comando tailscale up en segundos.

--timeout duration

   cantidad máxima de tiempo a esperar a que tailscaled entre en estado de ejecución

verbose

Predeterminado: false

Indica si se debe mostrar información adicional durante la ejecución del rol. Útil para depuración y recopilación de información para enviar en un problema de GitHub en este repositorio.

Dependencias

Colecciones

• community.general

Ejemplo de Playbook

- name: Servidores
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        # Ejemplo sacando la clave de API de las variables de entorno en el host que ejecuta Ansible
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"

Habilitar Tailscale SSH:

- name: Servidores
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        # Ejemplo sacando la clave de API de las variables de entorno en el host que ejecuta Ansible
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"
        tailscale_args: "--ssh"

Pasar argumentos de línea de comandos arbitrarios:

- name: Servidores
  hosts: all
  tasks:
    - name: Usar Headscale
      include_role:
        name: artis3n.tailscale
      vars:
        tailscale_args: "--login-server='http://localhost:8080'"
        tailscale_authkey: "{{ lookup('env', 'HEADSCALE_KEY') }}"

Obtener salida detallada:

- name: Servidores
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        verbose: true
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"

Conectar usando un secreto de cliente OAuth:

- name: Servidores
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        verbose: true
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_OAUTH_CLIENT_SECRET') }}"
        tailscale_tags:
          - "oauth"
        # Opcionalmente, también incluye:
        tailscale_oauth_ephemeral: true
        tailscale_oauth_preauthorized: false

Instalar Tailscale, pero no autenticarse en la red:

- name: Servidores
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        tailscale_up_skip: true

Desregistrar y desinstalar un nodo Tailscale:

- name: Servidores
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        state: absent

Seguimiento de estado

Este rol creará un directorio artis3n-tailscale en el directorio XDG_STATE_HOME del destino, o $HOME/.local/state si la variable no está presente, con el fin de mantener un concepto de estado de la configuración de los argumentos pasados a tailscale up. Esto permite que el rol actualice de forma idempotente la configuración de un nodo Tailscale cuando sea necesario. Eliminar este directorio llevará a que este rol reconfigure Tailscale cuando no sea necesario, pero no romperá nada. Sin embargo, se recomienda que dejes que este rol de Ansible administre este directorio y su contenido.

Ten en cuenta que:

Las banderas no se persisten entre ejecuciones; debes especificar todas las banderas cada vez.

...

En Tailscale v1.8 o posterior, si olvidas especificar una bandera que agregaste antes, la CLI te advertirá y proporcionará un comando copiables que incluye todas las banderas existentes.

- [docs: tailscale up][tailscale up docs]

Licencia

MIT

Información del autor

Ari Kalfus (@artis3n) dev@artis3nal.com

Desarrollo y contribución

Este repositorio de GitHub utiliza una cuenta de Tailscale "de prueba" dedicada para autenticar Tailscale durante las ejecuciones de CI. Cada contenedor de Docker crea una nueva máquina autorizada en esa cuenta de prueba. Las máquinas son autorizadas con claves de autorización efímeras y se limpian automáticamente.

Esta clave de autorización se almacena en un secreto de GitHub Action con el nombre TAILSCALE_CI_KEY. Para probar la compatibilidad de la clave de autorización OAuth, un secreto de cliente OAuth de Tailscale se almacena como TAILSCALE_OAUTH_CLIENT_SECRET. Si eres colaborador en este repositorio, puedes abrir un CodeSpace de GitHub y estos secretos se pre-poblarán para ti en el entorno.

Para probar este rol localmente, almacena la clave de autorización efímera de Tailscale en una variable de entorno TAILSCALE_CI_KEY y, si ejecutas el escenario de molécula oauth, agrega un secreto de cliente OAuth en una variable de entorno TAILSCALE_OAUTH_CLIENT_SECRET.

Alternativamente, para pruebas de [Molecule][], puedes usar un contenedor Headscale que se active como parte de los pasos de creación/preparación. Para hacer esto, establece una variable de entorno USE_HEADSCALE. Por ejemplo:

USE_HEADSCALE=true molecule test