artis3n.tailscale

此角色用于在 Linux 目标上安装和配置 Tailscale。

支持的操作系统：

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

请查看 CI 工作流 以获取在每个拉取请求中积极测试的发行版版本列表。

[!提示] 此角色使用 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
• 依赖关系
  • 集合
• 示例剧本
• 状态跟踪
• 许可证
• 作者信息
• 开发与贡献

此角色会将 Tailscale 二进制文件的任何 stderr 消息上升到上层，以解决与 tailscale up 参数相关的终端用户配置错误。 --authkey= 的值将被隐去，除非 insecurely_log_authkey 被设置为 true。

角色输出

此角色提供 Tailscale 节点的 IPv4 和 IPv6 地址，以及针对该节点的 tailscale whois 输出作为事实。 提供几个重要的 whois 信息，其他的 whois 输出将以 JSON 事实的形式保存，以方便您使用。

输出的事实：

tailscale_node_ipv4           (string): Tailscale 节点的 IPv4 地址。
tailscale_node_ipv6           (string): Tailscale 节点的 IPv6 地址。
tailscale_node_hostname_full  (string): Tailscale 节点的完整主机名 (node.domain.ts.net)。
tailscale_node_hostname_short (string): Tailscale 节点的短主机名 (node)。
tailscale_node_created_at     (string): Tailscale 节点创建的 ISO-8601 时间戳。
tailscale_node_tags           (list): 分配给 Tailscale 节点的标签。
tailscale_node_services       (list): 在 Tailscale 节点上发现的服务。
tailscale_node_whois          (dict): 针对 Tailscale 节点的 `tailscale whois` 完整输出。

角色变量

必需

必须存在 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 密钥，请确保为 OAuth 客户端授予 write 设备范围。

此值应视为敏感机密。

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 材料。

请注意，如果 state 设置为 absent，则 tailscale_authkey 和 tailscale_up_skip 都不是必需的。

tailscale_args

向 tailscale up 传递命令行参数。

请注意使用 命令 模块，该模块不支持子 Shell 表达式 ($()) 或 bash 操作如 ; 和 &。 只能传递 tailscale up 参数。

[!注意] 不要为 --authkey 使用此参数。 请使用 tailscale_authkey 变量。

不要为 --advertise-tags 使用此参数。 请使用 tailscale_tags 变量。

不要为 --timeout 使用此参数。 请使用 tailscale_up_timeout 变量。

tailscale 二进制输出的任何 stdout/stderr 都将被打印。 由于此部分任务执行迅速，添加了5秒延迟，以给予用户更多时间意识到信息已被打印。

Stderrs 将继续导致角色的执行失败。 敏感的 --authkey 值将默认被隐去。 如果您需要查看未被隐去的值，请查看 insecurely_log_authkey。

tailscale_oauth_ephemeral

[!注意] 仅在 tailscale_authkey 为 OAuth 密钥时使用。

默认: true

如果为 true，则注册为 临时节点。

tailscale_oauth_preauthorized

[!注意] 仅在 tailscale_authkey 为 OAuth 密钥时使用。

默认: false

如果为 true，跳过 手动设备批准。

insecurely_log_authkey

默认: false

如果设置为 true，则“启动 Tailscale”命令将在 tailscale up 遇到错误时包含 Tailscale 授权密钥的原始值。 默认情况下，在成功任务完成中不记录授权密钥，并且在发生错误时会在此角色的 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

示例剧本

- name: 服务器
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        # 示例：从运行 Ansible 的主机的环境变量中提取 API 密钥
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"

启用 Tailscale SSH:

- name: 服务器
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        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

状态跟踪

此角色将在目标的 XDG_STATE_HOME 目录中创建 artis3n-tailscale 目录， 如果变量不存在，则使用 $HOME/.local/state， 以维护从传递给 tailscale up 的参数配置的状态概念。 这使得角色在需要时可以幂等地更新 Tailscale 节点的配置。 删除此目录将导致该角色在不必要时重新配置 Tailscale， 但不会破坏任何东西。 不过，建议您让此 Ansible 角色管理此目录及其内容。

请注意：

标志在运行之间不会持久化；您必须每次都指定所有标志。

...

在 Tailscale v1.8 或更高版本中，如果您忘记指定之前添加的标志， CLI 将警告您并提供一个可复制的命令，该命令将包含所有现有标志。

- 文档：tailscale up

许可证

MIT

作者信息

Ari Kalfus (@artis3n) dev@artis3nal.com

开发与贡献

此 GitHub 存储库使用专用的“测试” Tailscale 帐户在 CI 运行期间身份验证 Tailscale。 每个 Docker 容器会在该测试帐户中创建一个新的授权机器。 这些机器是使用 临时授权密钥 进行授权的，并会自动清理。

此授权密钥存储在名为 TAILSCALE_CI_KEY 的 [GitHub Action 密钥][] 中。 为了测试 OAuth 授权密钥的兼容性，将 Tailscale OAuth 客户端密钥存储为 TAILSCALE_OAUTH_CLIENT_SECRET。 如果您是该存储库的协作者， 可以打开 GitHub CodeSpace，这些密钥将为您预填充在环境中。

要在本地测试此角色，请将 Tailscale 临时授权密钥存储在 TAILSCALE_CI_KEY 环境变量中， 如果运行 oauth Molecule 场景，则添加 OAuth 客户端密钥到 TAILSCALE_OAUTH_CLIENT_SECRET 环境变量。

另外，对于 Molecule 测试， 您可以使用 Headscale 容器，该容器是在创建/准备步骤的一部分中启动的。 为此，设置一个 USE_HEADSCALE 环境变量。 例如：

USE_HEADSCALE=true molecule test