artis3n.tailscale

Diese Rolle installiert und konfiguriert Tailscale auf einem Linux-Ziel.

Unterstützte Betriebssysteme:

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

Siehe den CI-Workflow für die Liste der Distribution-Versionen, die in jedem Pull-Request aktiv getestet werden.

[!TIPP] Diese Rolle verwendet die vollständig qualifizierten Sammlungsnamen (FQCN) von Ansible und erfordert daher Ansible 2.11+. Ansible 2.12 ist die minimale erforderliche Version, da dies die getestete Version für die Kompatibilität während der FQCN-Refaktorisierung war.

Wenn Sie oder Ihre Organisation von dieser Rolle profitieren, würde ich mich sehr über eine einmalige oder regelmäßige Unterstützung dieser Rolle freuen.

• Rollen-Ausgaben
• Rollen-Variablen
  • Erforderlich
    • tailscale_authkey
    • tailscale_tags
    • tailscale_up_skip
  • Optional
    • state
    • tailscale_args
    • tailscale_oauth_ephemeral
    • tailscale_oauth_preauthorized
    • insecurely_log_authkey
    • release_stability
    • tailscale_up_timeout
    • verbose
• Abhängigkeiten
  • Sammlungen
• Beispiel-Playbook
• Statusverfolgung
• Lizenz
• Autoreninformationen
• Entwicklung und Mitwirkung

Diese Rolle wird Fehlermeldungen des Tailscale-Binaries zurückgeben, um Konfigurationsfehler mit den tailscale up-Argumenten zu beheben. Der Wert für --authkey= wird anonymisiert, es sei denn, insecurely_log_authkey wird auf true gesetzt.

Rollen-Ausgaben

Diese Rolle liefert die IPv4- und IPv6-Adressen des Tailscale-Knotens sowie die Ausgabe von tailscale whois zu dem Knoten als Fakten. Einige wichtige Informationen von whois werden direkt bereitgestellt, der Rest der whois-Ausgabe wird als JSON-Fakt zur Verfügung gestellt.

Ausgegebene Fakten:

tailscale_node_ipv4           (string): Die IPv4-Adresse des Tailscale-Knotens.
tailscale_node_ipv6           (string): Die IPv6-Adresse des Tailscale-Knotens.
tailscale_node_hostname_full  (string): Der vollständige Hostname (node.domain.ts.net) des Tailscale-Knotens.
tailscale_node_hostname_short (string): Der kurze Hostname (node) des Tailscale-Knotens.
tailscale_node_created_at     (string): Der ISO-8601-Zeitstempel, zu dem der Tailscale-Knoten erstellt wurde.
tailscale_node_tags           (list):   Die dem Tailscale-Knoten zugewiesenen Tags.
tailscale_node_services       (list):   Die auf dem Tailscale-Knoten entdeckten Dienste.
tailscale_node_whois          (dict):   Die vollständige Ausgabe von `tailscale whois` für den Tailscale-Knoten.

Rollen-Variablen

Erforderlich

Einer der Werte tailscale_authkey oder tailscale_up_skip muss vorhanden sein. In den meisten Fällen werden Sie tailscale_authkey verwenden.

Wenn Sie Tailscale deinstallieren (state: absent), sind weder tailscale_authkey noch tailscale_up_skip erforderlich.

Wenn Sie sich mit einem OAuth-Schlüssel authentifizieren, müssen Sie auch tailscale_tags festlegen.

tailscale_authkey

Wird nicht benötigt, wenn tailscale_up_skip auf true gesetzt ist.

Ein Tailscale Knoten-Authorization Auth-Schlüssel.

Ein Node-Autorisierungs-Schlüssel kann unter Ihrem Tailscale-Konto generiert werden. Die Rolle unterstützt zwei Arten von Schlüsseln:

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

[!WICHTIG] Die Verwendung eines OAuth-Schlüssels erfordert die folgenden Rollenvariablen: tailscale_tags (muss bereitgestellt werden), tailscale_oauth_ephemeral (standardmäßig true), und tailscale_oauth_preauthorized (standardmäßig false).

Bitte beachten Sie, dass Auth-Schlüssel nach maximal 90 Tagen ablaufen, nachdem sie generiert wurden. OAuth-Geheimnisse laufen nicht ab, es sei denn, sie werden widerrufen, und das generierte OAuth-Zugangs-token läuft nach 1 Stunde ab.

Für weitere Informationen siehe die Seite zu Tailscales OAuth-Clients, insbesondere Generierung von langfristigen Auth-Schlüsseln.

Wenn ein OAuth-Schlüssel verwendet wird, stellen Sie sicher, dass dem OAuth-Client das write-Gerätescope gewährt wird.

Dieser Wert sollte als sensibles Geheimnis behandelt werden.

tailscale_tags

Standard: []

Wendet die bereitgestellten Tags auf die Tailscale-Knoten an, die von dieser Rolle konfiguriert werden (über das --advertise-tags-Flag für tailscale up). Für weitere Informationen siehe Was sind Tags?

[!HINWEIS] Tags sind erforderlich für OAuth-Clients (tailscale_authkey OAuth-Schlüssel).

Einträge sollten tag: nicht einschließen. Beispiel: tailscale_tags: ['worker'] wird zu --advertise-tags=tag:worker.

tailscale_up_skip

Wenn auf true gesetzt, ist tailscale_authkey nicht erforderlich.

Standard: false

Ob Tailscale als Dienst installiert und konfiguriert werden soll, aber das Ausführen von tailscale up übersprungen werden soll. Hilfreich bei der Verpackung einer Tailscale-Installation in einen Build-Prozess, wie z.B. bei der Erstellung eines AMIs, wenn der Server sich noch nicht mit Ihrem Tailscale-Netzwerk authentifizieren soll.

Optional

state

Standard: latest

Ob Tailscale installiert oder deinstalliert werden soll. Wenn definiert, muss state entweder latest, present oder absent sein.

Diese Rolle verwendet standardmäßig latest, um sicherzustellen, dass Ihre Software aktuell bleibt und die neuesten Sicherheits- und Produktfunktionen enthält. Für Benutzer, die mehr Kontrolle über Konfigurationsänderungen wünschen, wird present Tailscale nicht aktualisieren, wenn es bereits installiert ist.

Änderungen an tailscale_args werden sowohl unter latest als auch unter present angewendet; dieser Parameter wirkt sich nur auf die Version von Tailscale aus, die auf dem Zielsystem installiert ist.

Wenn auf absent gesetzt, wird diese Rolle den Tailscale-Knoten abmelden (falls bereits authentifiziert) und alle Tailscale-Ressourcen entfernen oder deaktivieren, die dem System hinzugefügt wurden.

Beachten Sie, dass weder tailscale_authkey noch tailscale_up_skip erforderlich sind, wenn state auf absent gesetzt ist.

tailscale_args

Übergeben Sie Befehlszeilenargumente an tailscale up.

Bitte beachten Sie, dass das command-Modul verwendet wird, das Subshell-Ausdrücke ($()) oder Bash-Operationen wie ; und & nicht unterstützt. Es können nur tailscale up-Argumente übergeben werden.

[!VORSICHT] Nicht für --authkey verwenden. Verwenden Sie stattdessen die Variable tailscale_authkey.

Nicht für --advertise-tags verwenden. Verwenden Sie stattdessen die Variable tailscale_tags.

Nicht für --timeout verwenden. Verwenden Sie stattdessen die Variable tailscale_up_timeout.

Alle stdout/stderr-Ausgaben des tailscale-Binaries werden ausgegeben. Da die Aufgaben in diesem Abschnitt schnell ablaufen, wird eine Pause von 5 Sekunden eingeführt, um den Benutzern mehr Zeit zu geben, um zu bemerken, dass eine Nachricht ausgegeben wurde.

Fehlermeldungen führen weiterhin zum Fehlschlagen der Ausführung der Rolle. Der sensitive Wert --authkey wird standardmäßig anonymisiert. Wenn Sie den anonymisierten Wert einsehen müssen, sehen Sie sich insecurely_log_authkey an.

tailscale_oauth_ephemeral

[!HINWEIS] Nur verwendet, wenn tailscale_authkey ein OAuth-Schlüssel ist.

Standard: true

Registriert sich als ephemerer Knoten, wenn true.

tailscale_oauth_preauthorized

[!HINWEIS] Nur verwendet, wenn tailscale_authkey ein OAuth-Schlüssel ist.

Standard: false

Überspringt die manuelle Gerätegenehmigung, wenn true.

insecurely_log_authkey

Standard: false

Wenn auf true gesetzt, wird der Befehl "Tailscale hochbringen" den rohen Wert des Tailscale-Authkeys enthalten, wenn Fehler protokolliert werden, die während tailscale up aufgetreten sind. Standardmäßig wird der Authkey bei erfolgreichen Aufgabenabschlüssen nicht protokolliert und in der stderr-Ausgabe dieser Rolle anonymisiert, wenn ein Fehler auftritt.

Wenn Sie beim Hochbringen von Tailscale auf einen Fehler stoßen und möchten, dass die Aufgabe "Tailscale hochbringen" nicht den Wert des Authkeys anonymisiert, setzen Sie diese Variable auf true.

Unabhängig davon wird, wenn der Authkey ungültig ist, die Rolle die Fehlermeldung von Tailscale zu diesem Fakt weiterhin relayen:

release_stability

Standard: stable

Ob die stabile oder instabile Version von Tailscale verwendet werden soll.

stable:

Stabile Releases. Wenn Sie sich nicht sicher sind, welche Version Sie verwenden sollen, wählen Sie diese.

unstable:

Die neueste Version. Häufige Updates. Erwarten Sie Unregelmäßigkeiten!

tailscale_up_timeout

Standard: 120

Definiert die Timeout-Dauer für den tailscale up-Befehl in Sekunden.

--timeout Dauer

   maximale Zeit, die gewartet werden soll, bis tailscaled in einen laufenden Zustand übergeht

verbose

Standard: false

Ob zusätzliche Informationen während der Ausführung der Rolle ausgegeben werden sollen. Hilfreich für das Debugging und das Sammeln von Informationen, die in einem GitHub-Issue in diesem Repository eingereicht werden sollen.

Abhängigkeiten

Sammlungen

• community.general

Beispiel-Playbook

- name: Server
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        # Beispiel: Abrufen des API-Schlüssels aus den Umgebungsvariablen auf dem Host, der Ansible ausführt
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"

Aktivieren Sie Tailscale SSH:

- name: Server
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        # Beispiel: Abrufen des API-Schlüssels aus den Umgebungsvariablen auf dem Host, der Ansible ausführt
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"
        tailscale_args: "--ssh"

Willkürliche Befehlszeilenargumente übergeben:

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

Get verbose output:

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

Verbindung über ein OAuth-Client-Geheimnis herstellen:

- name: Server
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        verbose: true
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_OAUTH_CLIENT_SECRET') }}"
        tailscale_tags:
          - "oauth"
        # Optional kann auch hinzugefügt werden:
        tailscale_oauth_ephemeral: true
        tailscale_oauth_preauthorized: false

Tailscale installieren, aber nicht mit dem Netzwerk authentifizieren:

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

Deregisterieren und Deinstallieren eines Tailscale-Knotens:

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

Statusverfolgung

Diese Rolle erstellt ein Verzeichnis artis3n-tailscale im XDG_STATE_HOME des Ziels, oder $HOME/.local/state, falls die Variable nicht vorhanden ist, um einen Status in Bezug auf die Konfiguration der an tailscale up übergebenen Argumente beizubehalten. Dies ermöglicht der Rolle, die Konfiguration eines Tailscale-Knotens bei Bedarf idempotent zu aktualisieren. Wenn Sie dieses Verzeichnis löschen, wird diese Rolle Tailscale neu konfigurieren, wenn es nicht benötigt wird, aber es bricht sonst nichts. Es wird jedoch empfohlen, dass Sie diese Ansible-Rolle mit diesem Verzeichnis und seinen Inhalten verwalten.

Beachten Sie, dass:

Flags werden zwischen den Ausführungen nicht gespeichert; Sie müssen bei jeder Angabe alle Flags angeben.

...

In Tailscale v1.8 oder höher, wenn Sie vergessen, ein zuvor hinzugefügtes Flag anzugeben, wird die CLI Sie warnen und einen kopierbaren Befehl bereitstellen, der alle vorhandenen Flags enthält.

- docs: tailscale up

Lizenz

MIT

Autoreninformationen

Ari Kalfus (@artis3n) dev@artis3nal.com

Entwicklung und Mitwirkung

Dieses GitHub-Repository verwendet ein dediziertes "Test"-Tailscale-Konto, um Tailscale während CI-Ausführungen zu authentifizieren. Jeder Docker-Container erstellt eine neue autorisierte Maschine in diesem Testkonto. Die Maschinen werden mit [ephemeren Authkeys][] autorisiert und automatisch bereinigt.

Dieser Authkey wird in einem GitHub Action Secret mit dem Namen TAILSCALE_CI_KEY gespeichert. Um die Kompatibilität des OAuth-Authkeys zu testen, wird das Tailscale OAuth-Client-Geheimnis als TAILSCALE_OAUTH_CLIENT_SECRET gespeichert. Wenn Sie ein Mitwirkender an diesem Repository sind, können Sie ein GitHub CodeSpace öffnen und diese Geheimnisse werden Ihnen in der Umgebung vorab ausgefüllt.

Um diese Rolle lokal zu testen, speichern Sie den Tailscale ephemeren Authkey in einer TAILSCALE_CI_KEY-Umgebungsvariablen und, wenn Sie das oauth Molecule-Szenario ausführen, fügen Sie ein OAuth-Client-Geheimnis in einer TAILSCALE_OAUTH_CLIENT_SECRET-Umgebungsvariablen hinzu.

Alternativ für Molecule-Tests, können Sie einen Headscale-Container verwenden, der als Teil der Erstellungs-/Vorbereitungs-Schritte gestartet wird. Dazu setzen Sie eine USE_HEADSCALE-Umgebungsvariable. Beispiel:

USE_HEADSCALE=true molecule test