artis3n.tailscale

GitHub last commit GitHub

このロールは、Linux ターゲットに Tailscale をインストールして構成します。

サポートされているオペレーティングシステム:

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

各プルリクエストでテストされたディストリビューションのバージョンのリストについては、CI ワークフローを参照してください。

[!TIP] このロールは Ansible の完全修飾コレクション名（FQCN）を使用するため、Ansible 2.11 以上が必要です。 Ansible 2.12 は、FQCN リファクタリング中に互換性テストを行ったため、最小限の必要バージョンとして設定されています。

もしあなたやあなたの組織がこのロールから価値を得られるのであれば、このロールの 1 回限りまたは定期的なスポンサーシップを非常に感謝します。

ロールの出力
ロールの変数
- 必須
- オプション
依存関係
- コレクション
例のプレイブック
状態の追跡
ライセンス
著者情報
開発と貢献

このロールは、Tailscale バイナリからのすべての stderr メッセージを表示し、tailscale up 引数に関するユーザーの設定エラーを解決します。 --authkey= の値は、insecurely_log_authkey が true に設定されていない限り、表示されません。

logged stderr

ロールの出力

このロールは、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 アカウントの下で生成できます。このロールは、2 つの種類のキーをサポートします。

認証キー (tskey-auth-XXX-YYYYY) https://login.tailscale.com/admin/authkeys
OAuth キー (tskey-client-XXX-YYYY) https://login.tailscale.com/admin/settings/oauth

[!IMPORTANT] OAuth キーを使用する場合は、次のロール変数が必要です： tailscale_tags（提供する必要があります）、 tailscale_oauth_ephemeral（デフォルトはtrue）、および tailscale_oauth_preauthorized（デフォルトはfalse）。

認証キーは、生成後最大 90 日間で期限切れになります。 OAuth シークレットは取り消されない限り期限切れになりませんが、生成された OAuth アクセストークンは 1 時間後に期限切れになります。

詳細については、Tailscale の OAuth クライアントページ、特に長期間生存する認証キーの生成を参照してください。

OAuth キーを使用する場合は、OAuth クライアントに write デバイススコープを付与することを忘れないでください。

この値は機密情報として扱われるべきです。

tailscale_tags

デフォルト: []

このロールによって構成された Tailscale ノードに指定されたタグを適用します（tailscale up への --advertise-tags オプションを通じて）。詳細については、タグとは？を参照してください。

[!NOTE] OAuth クライアントにはタグが必要です（tailscale_authkey の OAuth キー）。

エントリーには tag: を含めないでください。たとえば、tailscale_tags: ['worker'] は --advertise-tags=tag:worker に翻訳されます。

tailscale_up_skip

true に設定されている場合、tailscale_authkey は不要です。

デフォルト: false

Tailscale をサービスとしてインストールおよび構成するが、tailscale up の実行をスキップするかどうか。サーバーがまだ Tailscale ネットワークに認証しない必要がある場合のビルドプロセスへの 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 にコマンドラインオプションを渡します。

使用されている command モジュールは、サブシェル式 ($()) や ; や & などの bash 操作をサポートしていません。 tailscale up の引数のみを渡すことができます。

[!CAUTION] --authkey には使用しないでください。 代わりに tailscale_authkey 変数を使用してください。

--advertise-tags には使用しないでください。 代わりに tailscale_tags 変数を使用してください。

--timeout には使用しないでください。 代わりに tailscale_up_timeout 変数を使用してください。

tailscale バイナリからのすべての stdout/stderr 出力が印刷されます。このセクションのタスクは迅速に進むため、メッセージの印刷をユーザーが認識できるように、5 秒のポーズが導入されています。

printed stdout

Stderrs はロールの実行の失敗を続けます。機密性の高い --authkey 値は、デフォルトでマスクされます。未マスクの値を表示する必要がある場合は、insecurely_log_authkey を参照してください。

tailscale_oauth_ephemeral

[!NOTE] tailscale_authkey が OAuth キーの場合のみ使用されます。

デフォルト: true

true の場合、一時的ノードとして登録します。

tailscale_oauth_preauthorized

[!NOTE] tailscale_authkey が OAuth キーの場合のみ使用されます。

デフォルト: false

手動デバイス承認をスキップします（true の場合）。

insecurely_log_authkey

デフォルト: false

true に設定されている場合、"Tailscale を起動する" コマンドは、tailscale up の途中で発生したエラーのログに Tailscale authkey の生値を含みます。デフォルトでは、成功したタスクの完了時に authkey はログに記録されず、エラーが発生した場合にはこのロールによって stderr 出力でマスクされます。

redacted authkey

Tailscale を起動する際にエラーが発生し、authkey の値をマスクせずに "Tailscale を起動する" タスクを実行させたい場合は、この変数を true に設定してください。

それでも、authkey が無効な場合、ロールは Tailscale からその事実に関するエラーメッセージを中継します：

invalid authkey

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:
        # Ansible を実行しているホストの環境変数から API キーを取得する例
        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 は警告を表示し、すべての既存のフラグを含むコピー可能なコマンドを提供します。

- docs: tailscale up

ライセンス

MIT

著者情報

Ari Kalfus (@artis3n) dev@artis3nal.com

開発と貢献

この GitHub リポジトリは、CI 実行時に Tailscale に認証するために専用の "テスト" Tailscale アカウントを使用します。各 Docker コンテナは、そのテストアカウントに新しい認可されたマシンを作成します。マシンは [一時的認証キー][] を使用して認証され、自動的にクリーンアップされます。

この authkey は、TAILSCALE_CI_KEY という名前の [GitHub Actions シークレット][] に保存されています。 OAuth authkey の互換性をテストするために、Tailscale OAuth クライアントシークレットが TAILSCALE_OAUTH_CLIENT_SECRET として保存されています。このリポジトリのコラボレーターであれば、 GitHub Codespaces を開いて、これらのシークレットを環境に事前入力することができます。

このロールをローカルでテストするには、Tailscale の一時的認証キーを TAILSCALE_CI_KEY 環境変数に保存し、もし oauth Molecule シナリオを実行している場合、OAuth クライアントシークレットを TAILSCALE_OAUTH_CLIENT_SECRET 環境変数に追加します。

[Zさらに、Molecule テストのために、生成/準備手順の一部としてスピンアップされる Headscale コンテナを使用できます。そのためには、USE_HEADSCALE 環境変数を設定します。たとえば：

USE_HEADSCALE=true molecule test

プロジェクトについて

Install and enable a Tailscale node.

role tailscale vpn networking

インストール

ansible-galaxy install artis3n.tailscale

GitHub リポジトリ

475 スター

75 フォーク

8 オープンな問題

ライセンス

mit

ダウンロード

587.5k

所有者

Ari Kalfus