artis3n.tailscale

Эта роль устанавливает и настраивает Tailscale на целевой системе под управлением Linux.

Поддерживаемые операционные системы:

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

Смотрите CI workflow для списка версий дистрибутивов, которые активно тестируются в каждом пулл-запросе.

[!TIP] Эта роль использует полностью квалифицированные имена коллекций Ansible (FQCN), поэтому требуется Ansible версии 2.11 и выше. Необходимая минимальная версия - Ansible 2.12, так как именно эта версия была протестирована на совместимость во время реорганизации FQCN.

Если вы или ваша организация получают выгоду от этой роли, я буду очень благодарен за одноразовую или регулярную поддержку этой роли.

• Выводы роли
• Переменные роли
  • Обязательные
    • tailscale_authkey
    • tailscale_tags
    • tailscale_up_skip
  • Необязательные
    • state
    • tailscale_args
    • tailscale_oauth_ephemeral
    • tailscale_oauth_preauthorized
    • insecurely_log_authkey
    • release_stability
    • tailscale_up_timeout
    • verbose
• Зависимости
  • Коллекции
• Пример Playbook
• Отслеживание состояния
• Лицензия
• Информация об авторе
• Разработка и участие

Эта роль будет выводить любые сообщения ошибки от двоичного файла Tailscale, чтобы решить любые ошибки конфигурации конечного пользователя с аргументами tailscale up. Значение --authkey= будет скрыто, если переменная insecurely_log_authkey не установлена в true.

Выводы роли

Эта роль предоставляет IP v4 и v6 адреса узла Tailscale, а также вывод команды tailscale whois относительно узла в виде фактов. Несколько ключевых данных whois предоставляются непосредственно, остальные данные выводятся как JSON-факт для вашего удобства.

Выводимые факты:

tailscale_node_ipv4           (строка): IPv4 адрес узла Tailscale.
tailscale_node_ipv6           (строка): IPv6 адрес узла Tailscale.
tailscale_node_hostname_full  (строка): Полное имя хоста (node.domain.ts.net) узла Tailscale.
tailscale_node_hostname_short (строка): Короткое имя хоста (node) узла Tailscale.
tailscale_node_created_at     (строка): ISO-8601 временная метка создания узла Tailscale.
tailscale_node_tags           (список): Теги, присвоенные узлу Tailscale.
tailscale_node_services       (список): Обнаруженные сервисы, работающие на узле Tailscale.
tailscale_node_whois          (словарь): Полный вывод `tailscale whois` относительно узла Tailscale.

Переменные роли

Обязательные

Одна из переменных tailscale_authkey или tailscale_up_skip должна присутствовать. В большинстве случаев вы будете использовать tailscale_authkey.

Если вы удаляете Tailscale (state: absent), ни tailscale_authkey, ни tailscale_up_skip не требуются.

Если вы аутентифицируетесь с помощью OAuth ключа, вам также необходимо установить tailscale_tags.

tailscale_authkey

Не требуется, если tailscale_up_skip установлено в true.

Ключ аутентификации узла Tailscale.

Ключ аутентификации узла можно сгенерировать в вашем аккаунте Tailscale. Роль поддерживает два типа ключей:

• Ключ аутентификации (tskey-auth-XXX-YYYYY) https://login.tailscale.com/admin/authkeys
• OAuth ключ (tskey-client-XXX-YYYY) https://login.tailscale.com/admin/settings/oauth

[!ВАЖНО] Использование OAuth ключа требует следующих переменных роли: tailscale_tags (должен быть предоставлен), tailscale_oauth_ephemeral (по умолчанию равно true), и tailscale_oauth_preauthorized (по умолчанию равно false).

Обратите внимание, что ключи аутентификации истекают через максимум 90 дней после их генерации. Секреты OAuth не истекают, если их не отозвали, и сгенерированные токены доступа OAuth истекают через 1 час.

Для получения дополнительной информации смотрите страницу Tailscale о клиентах OAuth, особенно Генерация долгоживущих ключей аутентификации.

Если используется OAuth ключ, обязательно предоставьте области write для устройств OAuth клиента.

Это значение следует считать конфиденциальным секретом.

tailscale_tags

По умолчанию: []

Применить указанные теги к узлам Tailscale, настроенным этой ролью (с помощью флага --advertise-tags к tailscale up). Для получения дополнительной информации смотрите Что такое теги?

[!ПРИМЕЧАНИЕ] Теги обязательны для OAuth клиентов (tailscale_authkey OAuth ключ).

Записи не должны содержать tag:. Например, tailscale_tags: ['worker'] переводится как --advertise-tags=tag:worker.

tailscale_up_skip

Если установлено в true, tailscale_authkey не требуется.

По умолчанию: false

Необходимо установить и настроить Tailscale как службу, но пропустить запуск tailscale up. Полезно, когда Tailscale установка упаковывается в процесс сборки, например, создание AMI, когда сервер еще не должен аутентифицироваться в вашей Tailscale сети.

Необязательные

state

По умолчанию: latest

Необходимо установить или удалить Tailscale. Если определено, state должно быть либо latest, present, или absent.

Эта роль по умолчанию использует latest, чтобы помочь гарантировать, что ваше программное обеспечение остается актуальным и включает последние функции безопасности и продукта. Для пользователей, желающих большего контроля над изменениями конфигурации, present не обновит Tailscale, если он уже установлен.

Изменения в tailscale_args будут применяться как при latest, так и при present; этот параметр влияет только на версию Tailscale, установленную в целевой системе.

Если установлено в absent, эта роль де-регистрирует узел Tailscale (если уже аутентифицирован) и очищает или отключает все артефакты Tailscale, добавленные в систему.

Обратите внимание, что ни tailscale_authkey, ни tailscale_up_skip не требуются, если state установлено в absent.

tailscale_args

Передайте аргументы командной строки к tailscale up.

Обратите внимание, что используется модуль, который не поддерживает выражения подсистемы ($()) или операции bash, такие как ; и &. Можно передавать только аргументы tailscale up.

[!ОСТОРОЖНО] Не используйте это для --authkey. Используйте переменную tailscale_authkey вместо этого.

Не используйте это для --advertise-tags. Используйте переменную tailscale_tags вместо этого.

Не используйте это для --timeout. Используйте переменную tailscale_up_timeout вместо этого.

Любой вывод stdout/stderr от двоичного файла tailscale будет напечатан. Поскольку задачи в этом разделе выполняются быстро, введено 5 секунд паузы, чтобы пользователи имели больше времени для восприятия сообщения.

Сообщения stderr продолжат прекращать выполнение роли. Чувствительное значение --authkey по умолчанию будет скрыто. Если вам нужно увидеть не скрытое значение, смотрите insecurely_log_authkey.

tailscale_oauth_ephemeral

[!ПРИМЕЧАНИЕ] Используется только когда tailscale_authkey является OAuth ключом.

По умолчанию: true

Зарегистрировать как эпhemeral node, если установлено в true.

tailscale_oauth_preauthorized

[!ПРИМЕЧАНИЕ] Используется только когда tailscale_authkey является OAuth ключом.

По умолчанию: false

Пропустить ручное одобрение устройства, если установлено в true.

insecurely_log_authkey

По умолчанию: false

Если установлено в true, команда "Запустить Tailscale" будет включать необработанное значение ключа аутентификации Tailscale при регистрации любых ошибок, возникающих во время tailscale up. По умолчанию ключ аутентификации не регистрируется в успешных завершениях задач и скрывается в выводе stderr этой роли, если возникает ошибка.

Если вы сталкиваетесь с ошибкой при запуске Tailscale и хотите, чтобы задача "Запустить Tailscale" не скрывала значение ключа аутентификации, установите эту переменную в true.

Тем не менее, если ключ аутентификации недействителен, роль передаст сообщение об ошибке Tailscale на этот факт:

release_stability

По умолчанию: stable

Использовать стабильную или нестабильную версию Tailscale.

stable:

Стабильные версии. Если вы не уверены, какую версию использовать, выберите эту.

unstable:

Самая последняя версия. Выпускается часто и без колебаний. Ожидайте некоторые недоработки!

tailscale_up_timeout

По умолчанию: 120

Определяет время ожидания для команды tailscale up в секундах.

--timeout duration

   максимальное время ожидания для перехода tailscaled в состояние "Работает".

verbose

По умолчанию: false

Выводить дополнительную информацию во время выполнения роли. Полезно для отладки и сбора информации для отправки в проблему на GitHub по этому репозиторию.

Зависимости

Коллекции

• community.general

Пример Playbook

- name: Серверы
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        # Пример извлечения API ключа из переменных окружения на хосте, выполняющем Ansible
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"

Включите Tailscale SSH:

- name: Серверы
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        # Пример извлечения API ключа из переменных окружения на хосте, выполняющем Ansible
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"
        tailscale_args: "--ssh"

Передача произвольных аргументов командной строки:

- name: Серверы
  hosts: all
  tasks:
    - name: Использовать Headscale
      include_role:
        name: artis3n.tailscale
      vars:
        tailscale_args: "--login-server='http://localhost:8080'"
        tailscale_authkey: "{{ lookup('env', 'HEADSCALE_KEY') }}"

Получить подробный вывод:

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

Подключение с использованием секрета клиента OAuth:

- name: Серверы
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        verbose: true
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_OAUTH_CLIENT_SECRET') }}"
        tailscale_tags:
          - "oauth"
        # Также можно включить:
        tailscale_oauth_ephemeral: true
        tailscale_oauth_preauthorized: false

Установить Tailscale, но не аутентифицироваться в сети:

- name: Серверы
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        tailscale_up_skip: true

Де-регистрировать и удалить узел Tailscale:

- name: Серверы
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        state: absent

Отслеживание состояния

Эта роль создаст директорию artis3n-tailscale в XDG_STATE_HOME целевой системы, или в $HOME/.local/state, если переменная не установлена, для поддержания концепции состояния от конфигурации аргументов, переданных tailscale up. Это позволяет роли избыточно обновлять конфигурацию узла Tailscale при необходимости. Удаление этой директории приведет к тому, что эта роль перенастроит Tailscale, когда это не требуется, но ничего другого не сломает. Тем не менее, рекомендуется позволить этой Ansible роли управлять этой директорией и ее содержимым.

Обратите внимание на следующее:

Флаги не сохраняются между запусками; вы должны указывать все флаги каждый раз.

...

В Tailscale v1.8 или позже, если вы забудете указать флаг, который добавили ранее, CLI предупредит вас и предоставит копируемую команду, которая включает все существующие флаги.

- docs: tailscale up

Лицензия

MIT

Информация об авторе

Ари Кальфус (@artis3n) dev@artis3nal.com

Разработка и участие

Этот репозиторий на GitHub использует специальную учетную запись Tailscale "test" для аутентификации Tailscale во время выполнения CI. Каждая Docker-контейнер создает новую авторизованную машину в этой тестовой учетной записи. Машины авторизуются с помощью эпhemeral auth keys и автоматически очищаются.

Этот ключ аутентификации хранится в [секрете GitHub Action][] с именем TAILSCALE_CI_KEY. Для тестирования совместимости ключа OAuth аутентификации клиентский секрет Tailscale хранится как TAILSCALE_OAUTH_CLIENT_SECRET. Если вы являетесь соавтором этого репозитория, вы можете открыть GitHub CodeSpace, и эти секреты будут предварительно заполнены для вас в окружении.

Чтобы протестировать эту роль локально, сохраните ключ аутентификации Tailscale в переменной окружения TAILSCALE_CI_KEY и, если вы запускаете сценарий Molecule с oauth, добавьте клиентский секрет OAuth в переменную окружения TAILSCALE_OAUTH_CLIENT_SECRET.

Также для тестирования Molecule вы можете использовать контейнер Headscale, который создается как часть этапов создания/подготовки. Для этого установите переменную окружения USE_HEADSCALE. Например:

USE_HEADSCALE=true molecule test