artis3n.tailscale

Ta rola instaluje i konfiguruje Tailscale na systemie Linux.

Obsługiwane systemy operacyjne:

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

Zobacz CI workflow, aby uzyskać listę wersji dystrybucji testowanych w każdym żądaniu pull.

[!TIP] Ta rola używa w pełni kwalifikowanych nazw kolekcji Ansible (FQCN) i wymaga Ansible 2.11 lub nowszego. Ansible 2.12 jest minimalną wymaganą wersją, ponieważ była testowana pod kątem zgodności podczas refaktoryzacji FQCN.

Jeśli Ty lub Twoja organizacja korzystacie z tej roli, bardzo bym docenił jednorazowe lub cykliczne wsparcie tej roli.

• Produkcje roli
• Zmienne roli
  • Wymagane
    • tailscale_authkey
    • tailscale_tags
    • tailscale_up_skip
  • Opcjonalne
    • stan
    • tailscale_args
    • tailscale_oauth_ephemeral
    • tailscale_oauth_preauthorized
    • insecurely_log_authkey
    • release_stability
    • tailscale_up_timeout
    • verbose
• Zależności
  • Kolekcje
• Przykładowy playbook
• Śledzenie stanu
• Licencja
• Informacje o autorze
• Rozwój i wkład

Ta rola przekazuje wszystkie komunikaty stderr z binarnego pliku Tailscale, aby rozwiązać wszelkie błędy konfiguracyjne użytkownika końcowego przy użyciu argumentów tailscale up. Wartość --authkey= będzie ukryta, chyba że insecurely_log_authkey zostanie ustawiona na true.

Produkty roli

Ta rola zwraca adresy IP v4 i v6 węzła Tailscale oraz wynik tailscale whois dla tego węzła jako fakty. Kilka kluczowych informacji whois jest dostarczanych bezpośrednio, a reszta jest przechowywana jako fakt JSON dla Twojej wygody.

Wynikowe fakty:

tailscale_node_ipv4           (string): Adres IPv4 węzła Tailscale.
tailscale_node_ipv6           (string): Adres IPv6 węzła Tailscale.
tailscale_node_hostname_full  (string): Pełna nazwa hosta (node.domain.ts.net) węzła Tailscale.
tailscale_node_hostname_short (string): Krótka nazwa hosta (node) węzła Tailscale.
tailscale_node_created_at     (string): Czas utworzenia węzła Tailscale w formacie ISO-8601.
tailscale_node_tags           (list):   Tagami przypisanymi do węzła Tailscale.
tailscale_node_services       (list):   Odkryte usługi działające na węźle Tailscale.
tailscale_node_whois          (dict):   Pełny wynik `tailscale whois` dla węzła Tailscale.

Zmienne roli

Wymagane

Musisz podać jedną z wartości tailscale_authkey lub tailscale_up_skip. W większości przypadków użyjesz tailscale_authkey.

Jeśli odinstalowujesz Tailscale (stan: absent), ani tailscale_authkey, ani tailscale_up_skip nie są wymagane.

Jeśli autoryzujesz się za pomocą klucza OAuth, musisz również ustawić tailscale_tags.

tailscale_authkey

Nie jest wymagany, jeśli tailscale_up_skip jest ustawione na true.

Klucz autoryzacyjny węzła Tailscale.

Klucz autoryzacyjny węzła można wygenerować w swoim koncie Tailscale. Ta rola obsługuje dwa typy kluczy:

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

[!WAŻNE] Użycie klucza OAuth wymaga następujących zmiennych roli: tailscale_tags (musi być podany), tailscale_oauth_ephemeral (domyślnie true), oraz tailscale_oauth_preauthorized (domyślnie false).

Należy pamiętać, że klucze autoryzacyjne wygasają maksymalnie do 90 dni po ich wygenerowaniu. Sekrety OAuth nie wygasają, chyba że zostały cofnięte, a wygenerowany token dostępu OAuth wygasa po 1 godzinie.

Więcej informacji znajdziesz na stronie Klienci OAuth Tailscale, szczególnie w sekcji Generowanie kluczy autoryzacyjnych długoterminowych.

Jeśli używasz klucza OAuth, upewnij się, że przyznałeś klientowi OAuth uprawnienia do zapisu dla urządzeń.

Ta wartość powinna być traktowana jako tajemnica.

tailscale_tags

Domyślnie: []

Przypisz dostarczone tagi do węzłów Tailscale konfigurowanych przez tę rolę (za pomocą flagi --advertise-tags do tailscale up). Więcej informacji znajdziesz w sekcji Czym są tagi?

[!UWAGA] Tagi są wymagane dla klientów OAuth (tailscale_authkey klucz OAuth).

Elementy nie powinny zawierać tag:. Na przykład, tailscale_tags: ['worker'] przekłada się na --advertise-tags=tag:worker.

tailscale_up_skip

Jeśli ustawisz na true, tailscale_authkey nie jest wymagane.

Domyślnie: false

Określa, czy zainstalować i skonfigurować Tailscale jako usługę, ale pominąć uruchomienie tailscale up. Przydatne przy pakowaniu instalacji Tailscale do procesu budowania, takiego jak tworzenie AMI, kiedy serwer nie powinien jeszcze uwierzytelnić się w Twojej sieci Tailscale.

Opcjonalne

stan

Domyślnie: latest

Określa, czy zainstalować, czy odinstalować Tailscale. Jeśli zdefiniowane, stan musi być albo latest, present, albo absent.

Ta rola domyślnie używa latest, aby zapewnić, że oprogramowanie pozostaje aktualne i zawiera najnowsze funkcje zabezpieczeń i produktu. Dla użytkowników, którzy pragną większej kontroli nad zmianami konfiguracyjnymi, present nie zaktualizuje Tailscale, jeśli jest już zainstalowane.

Zmiany w tailscale_args będą zastosowane zarówno w przypadku latest, jak i present; ten parametr dotyczy tylko wersji Tailscale zainstalowanej na docelowym systemie.

Jeśli ustawisz absent, ta rola wyrejestruje węzeł Tailscale (jeśli już uwierzytelniony) i usunie lub wyłączy wszystkie elementy Tailscale dodane do systemu.

Należy zauważyć, że ani tailscale_authkey, ani tailscale_up_skip nie są wymagane, jeśli stan jest ustawione na absent.

tailscale_args

Przekaź argumenty wiersza poleceń do tailscale up.

Należy pamiętać, że używany jest moduł command, który nie obsługuje wyrażeń podpowłok ($()) ani operacji bashowych, takich jak ; i &. Można przekazać tylko argumenty tailscale up.

[!OSTRZEŻENIE] Nie używaj tego dla --authkey. Użyj zmiennej tailscale_authkey zamiast.

Nie używaj tego dla --advertise-tags. Użyj zmiennej tailscale_tags zamiast.

Nie używaj tego dla --timeout. Użyj zmiennej tailscale_up_timeout zamiast.

Wszelkie dane wyjściowe stdout/stderr z binarnego pliku tailscale będą drukowane. Z powodu szybkiego działania zadań w tej sekcji, wprowadzono 5-sekundowe opóźnienie, aby użytkownicy mogli zauważyć wyświetlony komunikat.

Stderrs będą nadal powodować niepowodzenie wykonania roli. Wartość wrażliwego --authkey będzie domyślnie ukryta. Jeśli potrzebujesz zobaczyć wartość ukrytą, zobacz insecurely_log_authkey.

tailscale_oauth_ephemeral

[!UWAGA] Używane tylko wtedy, gdy tailscale_authkey jest kluczem OAuth.

Domyślnie: true

Rejestruje się jako ephemeral node, jeśli true.

tailscale_oauth_preauthorized

[!UWAGA] Używane tylko wtedy, gdy tailscale_authkey jest kluczem OAuth.

Domyślnie: false

Pomija ręczną akceptację urządzenia, jeśli true.

insecurely_log_authkey

Domyślnie: false

Jeśli ustawisz na true, polecenie "Uruchom Tailscale" będzie zawierać surową wartość klucza autoryzacyjnego Tailscale podczas rejestrowania wszelkich błędów napotkanych podczas tailscale up. Domyślnie, klucz autoryzacyjny nie jest rejestrowany w przypadku pomyślnego zakończenia zadania i jest ukrywany w wyniku stderr przez tę rolę, jeśli wystąpi błąd.

Jeśli napotykasz błąd podczas uruchamiania Tailscale i chcesz, aby zadanie "Uruchom Tailscale" nie ukrywało wartości klucza autoryzacyjnego, ustaw tę zmienną na true.

Niezależnie od tego, jeśli klucz autoryzacyjny jest nieważny, rola przekaże komunikat o błędzie Tailscale na ten temat:

release_stability

Domyślnie: stable

Określa, czy używać stabilnej czy niestabilnej wersji Tailscale.

stable:

Stabilne wydania. Jeśli nie jesteś pewien, którą wersję wybrać, wybierz tę.

unstable:

Najnowsze nowości. Wydawane wcześnie i często. Oczekuj, że będą pewne problemy!

tailscale_up_timeout

Domyślnie: 120

Określa czas oczekiwania na polecenie tailscale up w sekundach.

--timeout duration

maksymalny czas oczekiwania na włączenie stanu "Running" w tailscaled

verbose

Domyślnie: false

Określa, czy wyświetlać dodatkowe informacje podczas wykonywania roli. Przydatne do debugowania i zbierania informacji do zgłoszenia na GitHubie w tej repozytorium.

Zależności

Kolekcje

• community.general

Przykładowy playbook

- name: Serwery
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        # Przykład pobierania klucza API z zmiennych środowiskowych na hoście uruchamiającym Ansible
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"

Włącz SSH Tailscale:

- name: Serwery
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        # Przykład pobierania klucza API z zmiennych środowiskowych na hoście uruchamiającym Ansible
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"
        tailscale_args: "--ssh"

Przekaź dowolne argumenty wiersza poleceń:

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

Uzyskaj szczegółowe informacje:

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

Połącz się za pomocą tajnego klucza klienta OAuth:

- name: Serwery
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        verbose: true
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_OAUTH_CLIENT_SECRET') }}"
        tailscale_tags:
          - "oauth"
        # Opcjonalnie, możesz również dodać:
        tailscale_oauth_ephemeral: true
        tailscale_oauth_preauthorized: false

Zainstaluj Tailscale, ale nie uwierzytelniaj się w sieci:

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

Wyrejestruj i odinstaluj węzeł Tailscale:

- name: Serwery
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        stan: absent

Śledzenie stanu

Ta rola stworzy katalog artis3n-tailscale w katalogu XDG_STATE_HOME docelowego systemu, lub $HOME/.local/state, jeśli zmienna nie jest obecna, aby utrzymać koncepcję stanu z konfiguracji przekazanych argumentów do tailscale up. Pozwala to roli na aktualizację konfiguracji węzła Tailscale, gdy jest to konieczne. Usunięcie tego katalogu spowoduje, że ta rola ponownie skonfiguruje Tailscale, gdy nie jest to potrzebne, ale nie spowoduje innych problemów. Jednak zaleca się, abyś pozwolił tej roli Ansible zarządzać tym katalogiem i jego zawartością.

Należy zauważyć:

Flagi nie są zachowywane pomiędzy uruchomieniami; musisz określić wszystkie flagi za każdym razem.

...

W Tailscale v1.8 lub nowszej, jeśli zapomnisz określić dodanej wcześniej flagi, CLI ostrzeże Cię i poda kopiowalną komendę, która zawiera wszystkie istniejące flagi.

- dokumentacja: tailscale up

Licencja

MIT

Informacje o autorze

Ari Kalfus (@artis3n) dev@artis3nal.com

Rozwój i wkład

To repozytorium GitHub używa dedykowanego konta Tailscale "testowego" do uwierzytelniania Tailscale podczas uruchamiania CI. Każdy kontener Docker tworzy nową autoryzowaną maszynę w tym teście. Maszyny są autoryzowane za pomocą ephemeral auth keys i są automatycznie sprzątane.

Ten klucz jest przechowywany w tajnym [GitHub Action][] o nazwie TAILSCALE_CI_KEY. Aby przetestować zgodność z kluczem OAuth, tajny klucz klienta OAuth Tailscale jest przechowywany jako TAILSCALE_OAUTH_CLIENT_SECRET. Jeśli jesteś współpracownikiem tego repozytorium, możesz otworzyć GitHub CodeSpace, a te sekrety będą wstępnie wypełnione w Twoim środowisku.

Aby przetestować tę rolę lokalnie, przechowuj klucz autoryzacji Tailscale ephemeral w zmiennej środowiskowej TAILSCALE_CI_KEY i, jeśli uruchamiasz scenariusz Molecule oauth, dodaj tajny klucz klienta OAuth w zmiennej środowiskowej TAILSCALE_OAUTH_CLIENT_SECRET.

Alternatywnie dla testów Molecule, możesz użyć kontenera Headscale, który jest uruchamiany jako część kroków tworzenia/przygotowania. Aby to zrobić, ustaw zmienną środowiskową USE_HEADSCALE. Na przykład:

USE_HEADSCALE=true molecule test