artis3n.tailscale

Ce rôle installe et configure Tailscale sur une machine Linux.

Systèmes d'exploitation supportés :

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

Consultez le flux de travail CI pour voir la liste des versions de distribution testées dans chaque demande de tirage.

[!ASTUCE] Ce rôle utilise des noms de collection Ansible complètement qualifiés (FQCN) et nécessite donc Ansible 2.11 ou plus. La version 2.12 est la version minimale requise car c'est celle qui a été testée pour la compatibilité lors de la refonte des FQCN.

Si vous ou votre organisation tirez de la valeur de ce rôle, j'apprécierais beaucoup un soutien unique ou récurrent par le biais d'un sponsoring de ce rôle.

• Sorties du rôle
• Variables du rôle
  • Requises
    • tailscale_authkey
    • tailscale_tags
    • tailscale_up_skip
  • Facultatives
    • state
    • tailscale_args
    • tailscale_oauth_ephemeral
    • tailscale_oauth_preauthorized
    • insecurely_log_authkey
    • release_stability
    • tailscale_up_timeout
    • verbose
• Dépendances
  • Collections
• Exemple de playbook
• Suivi de l'état
• Licence
• Informations sur l'auteur
• Développement et contribution

Ce rôle transmettra tous les messages d'erreur du binaire Tailscale pour résoudre les erreurs de configuration de l'utilisateur final avec les arguments tailscale up. La valeur --authkey= sera cachée à moins que insecurely_log_authkey soit définie sur true.

Sorties du rôle

Ce rôle fournit les adresses IP v4 et v6 du nœud Tailscale ainsi que la sortie de tailscale whois concernant le nœud en tant que faits. Plusieurs informations clés de whois sont fournies directement, le reste de la sortie whois est stocké sous forme de fait JSON pour votre commodité.

Faits sortis :

tailscale_node_ipv4           (string) : L'adresse IPv4 du nœud Tailscale.
tailscale_node_ipv6           (string) : L'adresse IPv6 du nœud Tailscale.
tailscale_node_hostname_full  (string) : Le nom d'hôte complet (node.domain.ts.net) du nœud Tailscale.
tailscale_node_hostname_short (string) : Le nom d'hôte court (node) du nœud Tailscale.
tailscale_node_created_at     (string) : L'horodatage ISO-8601 de la création du nœud Tailscale.
tailscale_node_tags           (list)   : Les tags assignés au nœud Tailscale.
tailscale_node_services       (list)   : Les services découverts en cours d'exécution sur le nœud Tailscale.
tailscale_node_whois          (dict)   : La sortie complète de `tailscale whois` concernant le nœud Tailscale.

Variables du rôle

Requises

Au moins tailscale_authkey ou tailscale_up_skip doit être présent. Dans la plupart des cas, vous utiliserez tailscale_authkey.

Si vous désinstallez Tailscale (state: absent), ni tailscale_authkey ni tailscale_up_skip ne sont requis.

Si vous vous authentifiez avec une clé OAuth, vous devez également définir tailscale_tags.

tailscale_authkey

N'est pas requis si tailscale_up_skip est défini sur true.

Une clé d'autorisation de nœud Tailscale.

Une clé d'autorisation de nœud peut être générée sous votre compte Tailscale. Le rôle prend en charge deux types de clés :

• Auth key (tskey-auth-XXX-YYYYY) https://login.tailscale.com/admin/authkeys
• OAuth key (tskey-client-XXX-YYYY) https://login.tailscale.com/admin/settings/oauth

[!IMPORTANT] Utiliser une clé OAuth nécessite les variables de rôle suivantes : tailscale_tags (doit être fournie), tailscale_oauth_ephemeral (par défaut true), et tailscale_oauth_preauthorized (par défaut false).

Notez que les clés d'autorisation expirent jusqu'à un maximum de 90 jours après leur génération. Les secrets OAuth n'expirent pas, sauf s'ils sont révoqués, et le jeton d'accès OAuth généré expire après 1 heure.

Pour plus d'informations, consultez la page des [clients OAuth] de Tailscale, en particulier Génération de clés d'autorisation à long terme.

Si une clé OAuth est utilisée, assurez-vous d'accorder le champ write pour les appareils au client OAuth.

Cette valeur doit être considérée comme un secret sensible.

tailscale_tags

Valeur par défaut : []

Applique les tags fournis aux nœuds Tailscale configurés par ce rôle (via le flag --advertise-tags à tailscale up). Pour plus d'informations, consultez Qu'est-ce que les tags ?

[!NOTE] Les tags sont requis pour les clients OAuth (tailscale_authkey avec clé OAuth).

Les entrées ne doivent pas inclure tag:. Par exemple, tailscale_tags: ['worker'] se traduira par --advertise-tags=tag:worker.

tailscale_up_skip

Si défini sur true, tailscale_authkey n'est pas requis.

Valeur par défaut : false

Indique s'il faut installer et configurer Tailscale en tant que service mais sauter l'exécution de tailscale up. Utile lors de l'intégration d'une installation de Tailscale dans un processus de build, comme la création d'une AMI, lorsque le serveur ne doit pas encore s'authentifier à votre réseau Tailscale.

Facultatives

state

Valeur par défaut : latest

Indique s'il faut installer ou désinstaller Tailscale. Si défini, state doit être soit latest, present, soit absent.

Ce rôle utilise latest par défaut pour aider à garantir que votre logiciel reste à jour et incorpore les dernières fonctionnalités de sécurité et de produit. Pour les utilisateurs qui désirent plus de contrôle sur les dérives de configuration, present n'installera pas Tailscale s'il est déjà installé.

Les changements apportés à tailscale_args seront appliqués sous latest et present; ce paramètre n'impacte que la version de Tailscale installée sur le système cible.

Si défini sur absent, ce rôle désenregistrera le nœud Tailscale (s'il est déjà authentifié) et nettoiera ou désactivera tous les artefacts Tailscale ajoutés au système.

Notez que ni tailscale_authkey ni tailscale_up_skip ne sont requis si state est défini sur absent.

tailscale_args

Passez des arguments de ligne de commande à tailscale up.

Notez que le module est utilisé, qui ne prend pas en charge les expressions de sous-shell ($()) ou les opérations bash comme ; et &. Seuls les arguments de tailscale up peuvent être passés.

[!CAUTION] Ne l'utilisez pas pour --authkey. Utilisez plutôt la variable tailscale_authkey.

Ne l'utilisez pas pour --advertise-tags. Utilisez plutôt la variable tailscale_tags.

Ne l'utilisez pas pour --timeout. Utilisez plutôt la variable tailscale_up_timeout.

Toute sortie stdout/stderr du binaire tailscale sera imprimée. Comme les tâches avancent rapidement dans cette section, une pause de 5 secondes est introduite pour laisser plus de temps aux utilisateurs pour réaliser qu'un message a été imprimé.

Les erreurs continueront à faire échouer l'exécution du rôle. La valeur sensible de --authkey sera cachée par défaut. Si vous devez voir la valeur non masquée, consultez insecurely_log_authkey.

tailscale_oauth_ephemeral

[!NOTE] Utilisé uniquement lorsque tailscale_authkey est une clé OAuth.

Valeur par défaut : true

Enregistré comme un nœud éphémère, si true.

tailscale_oauth_preauthorized

[!NOTE] Utilisé uniquement lorsque tailscale_authkey est une clé OAuth.

Valeur par défaut : false

Sautez l'approbation manuelle des appareils, si true.

insecurely_log_authkey

Valeur par défaut : false

Si défini sur true, la commande "Amener Tailscale Up" inclura la valeur brute de la clé d'authentification Tailscale lors de l'enregistrement des erreurs rencontrées pendant tailscale up. Par défaut, la clé d'authentification n'est pas enregistrée lors des réussites de tâches et est cachée dans la sortie stderr de ce rôle si une erreur se produit.

Si vous rencontrez une erreur lors de l'activation de Tailscale et que vous souhaitez que la tâche "Amener Tailscale Up" ne masque pas la valeur de la clé, définissez cette variable sur true.

Quoi qu'il en soit, si la clé est invalide, le rôle transmettra le message d'erreur de Tailscale sur ce fait :

release_stability

Valeur par défaut : stable

Indique s'il faut utiliser la version stable ou instable de Tailscale.

stable :

Versions stables. Si vous n'êtes pas sûr de la version à utiliser, choisissez celle-ci.

unstable :

La dernière version. Publiée tôt et souvent. Attendez-vous à quelques problèmes !

tailscale_up_timeout

Valeur par défaut : 120

Définit la durée limite pour la commande tailscale up en secondes.

--timeout durée

   temps maximum d'attente pour que tailscaled entre dans un état d'exécution

verbose

Valeur par défaut : false

Indique s'il faut afficher des informations supplémentaires lors de l'exécution du rôle. Utile pour le débogage et la collecte d'informations à soumettre dans un problème GitHub sur ce dépôt.

Dépendances

Collections

• community.general

Exemple de playbook

- name: Serveurs
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        # Exemple de récupération de la clé API à partir des variables d'environnement sur l'hôte exécutant Ansible
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"

Activer Tailscale SSH :

- name: Serveurs
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        # Exemple de récupération de la clé API à partir des variables d'environnement sur l'hôte exécutant Ansible
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"
        tailscale_args: "--ssh"

Passer des arguments de ligne de commande arbitraires :

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

Obtenir une sortie détaillée :

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

Se connecter en utilisant un secret de client OAuth :

- name: Serveurs
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        verbose: true
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_OAUTH_CLIENT_SECRET') }}"
        tailscale_tags:
          - "oauth"
        # En option, inclure également :
        tailscale_oauth_ephemeral: true
        tailscale_oauth_preauthorized: false

Installer Tailscale, mais ne pas s'authentifier sur le réseau :

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

Désenregistrer et désinstaller un nœud Tailscale :

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

Suivi de l'état

Ce rôle créera un répertoire artis3n-tailscale dans le répertoire XDG_STATE_HOME de la cible, ou $HOME/.local/state si la variable n'est pas présente, afin de maintenir un concept d'état à partir de la configuration des arguments passés à tailscale up. Cela permet au rôle de mettre à jour de manière idempotente la configuration d'un nœud Tailscale si nécessaire. La suppression de ce répertoire entraînera la reconfiguration de Tailscale alors qu'elle ne sera pas nécessaire, mais ne cassera rien d'autre. Cependant, il est recommandé de laisser ce rôle Ansible gérer ce répertoire et son contenu.

Notez que :

Les flags ne persistent pas entre les exécutions ; vous devez spécifier tous les flags chaque fois.

...

Dans Tailscale v1.8 ou plus, si vous oubliez de spécifier un flag que vous avez ajouté auparavant, l'CLI vous avertira et fournira une commande copiable qui inclut tous les flags existants.

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

Licence

MIT

Informations sur l'auteur

Ari Kalfus (@artis3n) dev@artis3nal.com

Développement et contribution

Ce dépôt GitHub utilise un compte Tailscale "test" dédié pour authentifier Tailscale lors des exécutions CI. Chaque conteneur Docker crée une nouvelle machine autorisée dans ce compte de test. Les machines sont autorisées avec des clés d'authentification éphémères et sont automatiquement nettoyées.

Cette clé d'authentification est stockée dans un secret d'Action GitHub nommé TAILSCALE_CI_KEY. Pour tester la compatibilité de la clé d'authentification OAuth, un secret de client OAuth Tailscale est stocké sous TAILSCALE_OAUTH_CLIENT_SECRET. Si vous êtes un collaborateur de ce dépôt, vous pouvez ouvrir un CodeSpace GitHub et ces secrets seront pré-remplis pour vous dans l'environnement.

Pour tester ce rôle localement, stockez la clé d'authentification éphémère Tailscale dans une variable d'environnement TAILSCALE_CI_KEY et, si vous exécutez le scénario Molecule oauth, ajoutez un secret de client OAuth dans une variable d'environnement TAILSCALE_OAUTH_CLIENT_SECRET.

Alternativement pour les tests Molecule, vous pouvez utiliser un conteneur Headscale qui est lancé dans le cadre des étapes de création/préparation. Pour cela, définissez une variable d'environnement USE_HEADSCALE. Par exemple :

USE_HEADSCALE=true molecule test