Semaphore UI をコードとして管理する：Ansible Collection を作った話

用語

本題に入る前に、いくつかの用語を整理しておきます。

Ansible Collection — ロール、モジュール、プラグインを含められる自動化のパッケージ。ほとんどのモジュールは Python（Linux サーバーやネットワーク機器向け）または PowerShell（Windows 向け）で書かれています。
Ansible Role — あらかじめ定義されたタスクのまとまりで、変数、テンプレート、ファイル、ハンドラーを含められます。ロールはコレクションに同梱することも、単独で存在させることもできます。
Config as Code (CaC) — 設定をコードとして定義・管理する手法。手作業の設定に代えて、自動化・再利用・バージョン管理を可能にします。

はじめに

私は Kristian といいます。Semaphore UI のインストール環境をコードで管理するための Ansible Collection、ebdruplab.semaphoreui の作者です。

きっかけ

このプロジェクトは、Ansible への理解を深めるための取り組みとして始まりました。それまでの私は、他の人が作ったコレクションやロールを使うか、ansible.builtin.cmd と register、Jinja2 テンプレートをつなぎ合わせて目的を果たすばかりでした。

最初に興味を持ったのは、かなりマイナーなネットワーク機器を自動化する必要が生じたときです。具体的には、データベースのシリアル番号が正しく設定されているかを検証する作業でした。そのプロジェクトのあとは PowerShell を使う普段の仕事に戻りましたが、新しいコンサルティングの案件で再び Ansible に引き戻されました。その案件では、パッチ管理から Ansible ノードの構築支援、ベストプラクティスの助言、Red Hat Single Sign-On をインストールするためのコンテンツ作成まで、あらゆることを扱いました。

Ansible との付き合いは 7 年になります。CLI から始めて Ansible Automation Platform (AAP) v2 に移り、最終的にはそこから離れました。なぜか。AAP は強力ですが重厚な製品で、大企業向けに作られています。OpenShift 以外で構築するのは骨が折れますし、ライセンス費用もそれ相応です。

なぜ Semaphore UI なのか

Semaphore UI は、そのシンプルさで私を惹きつけました。パッケージ 1 つ、サーバー 1 台（エンタープライズ規模が必要な場合を除く）で済みます。10 個のポートを 10 通りの方法で行き来する 6 台の VM は必要ありません。

たしかに AAP の execution environments はよくできています。しかし、その維持管理はまた別の話です。Semaphore UI はパッチ適用も運用も簡単で、応答が速く直感的なインターフェイスを備えています。高度な機能がいくつか欠けているのは事実ですが、私の用途では機能とコストのバランスがちょうどよいのです。

Semaphore のことは homelab コミュニティで初めて耳にしましたが、実際に試すまでは特に気に留めていませんでした。Ansible Galaxy を確認して該当するコレクションがないと分かった時点で、決断は簡単でした。これを自分の学習プロジェクトにしよう、と。コードはすべて自分で書いたのか？いいえ、全体を通して AI の助けを借りました。それでもプロジェクトは少しずつ形になっていきました。ここで 30 分、あそこで 1 時間。気づけば Semaphore API 全体を Python モジュールに置き換えていました。

何ができるのか

ebdruplab.semaphoreui で何ができるかは Ansible Galaxy に例があります。ここでもいくつか挙げてみます。

プロジェクトの作成と管理 — Semaphore のプロジェクトをコードとして定義し、繰り返し同じようにデプロイできます

- name: Create project with token and custom settings
  ebdruplab.semaphoreui.project_create:
    host: http://localhost
    port: 3000
    api_token: "{{ semaphore_token }}"
    name: "My Project"
    alert: true
    alert_chat: "#alerts"
    max_parallel_tasks: 5
    demo: false

インベントリの設定 — 静的・動的インベントリをプログラムから管理できます

- name: Create static inventory
  ebdruplab.semaphoreui.project_inventory_create:
    host: http://localhost
    port: 3000
    session_cookie: "{{ login_result.session_cookie }}"
    project_id: 1
    inventory:
      name: "Local Static Inventory"
      type: "static"
      inventory: "localhost ansible_connection=local"
      ssh_key_id: 42
      become_key_id: 7

ジョブテンプレートの設定 — UI に触れずにテンプレートを作成・更新できます

- name: Create template with UI-style override flags
  ebdruplab.semaphoreui.project_template_create:
    host: http://localhost
    port: 3000
    api_token: "{{ semaphore_token }}"
    project_id: 1
    template:
      name: "ff"
      playbook: "f"
      repository_id: 1
      inventory_id: 1
      environment_id: 1
      type: ""
      arguments: "[]"
      task_params:
        allow_override_tags: true
        allow_override_limit: true
        tags: ["t"]
        limit: ["t"]

ユーザーの管理 — ユーザーの作成とプロジェクトへの割り当てを自動化できます

- name: Create a new user
  ebdruplab.semaphoreui.user_create:
    host: http://localhost
    port: 3000
    session_cookie: "{{ login_result.session_cookie }}"
    name: "Jane Smith"
    username: "jsmith"
    email: "[email protected]"
    password: "supersecure123"
    admin: true
    alert: true

既存プロジェクトのバックアップ — 稼働中のプロジェクトを YAML にエクスポートしてバージョン管理下に置けます

- hosts: localhost
  gather_facts: false
  roles:
    - role: ebdruplab.semaphoreui.project_backup
      vars:
        project_backup_semaphore_host: "https://semaphore.example.com"
        project_backup_semaphore_api_token: "{{ lookup('env', 'SEMAPHORE_TOKEN') }}"
        project_backup_project_name: "My Project"

復元と移行 — YAML 定義からプロジェクト構成一式を数秒で再デプロイできます。

- hosts: localhost
  gather_facts: false
  vars_files:
    - vars/project.yml
  roles:
    - role: ebdruplab.semaphoreui.project_deploy

Config as Code — ebdruplab.project_deploy

1 つのモジュールが 2 つになり、2 つが 10 個になりました。最終的にコレクションは 92 モジュールに達し、プロジェクト、テンプレート、インベントリなど幅広い領域をカバーしています。

あるとき、これらのモジュールをつなぐ「のり」となるロールがほしいという要望がユーザーから寄せられました。それが ebdruplab.project_deploy です。Semaphore UI のプロジェクトがどうあるべきかを定義し、Ansible を通じて宣言的に作成できます。

最小構成のプロジェクト定義は次のようになります。

project_deploy_config:
  project:
    name: "My Project"
    alert: false
    alert_chat: ""
    max_parallel_tasks: 0
    demo: false

  users_access:
    - username: "admin"
      role: "Owner"

  keys:
    repo_login:
      name: "Git Login"
      type: login_password
      login_password:
        login: "git-user"
        password: "{{ vault_git_password }}"

  repositories:
    - name: "Example Repo"
      git_url: "https://github.com/example/repo.git"
      git_branch: "main"
      key_name: "Git Login"

  views:
    main:
      title: "Main"
      position: 0

  inventories:
    local_inventory:
      name: "Local Inventory"
      type: "static"
      inventory: "localhost ansible_connection=local"

  environments:
    default_env:
      name: "Default Environment"
      env:
        APP_ENV: "prod"

  templates:
    deploy_job:
      name: "Deploy"
      type: "job"
      repository_name: "Example Repo"
      inventory_name: "Local Inventory"
      environment_name: "Default Environment"
      view_title: "Main"
      playbook: "playbooks/site.yml"

  schedules: {}
  integrations: {}

ドキュメントは Ansible Galaxy で公開されており、GitHub リポジトリの project_deploy と project_backup の両方に examples/ と test/ フォルダーが含まれているので、導入の助けになります。

Config as Code コンバーター — ebdruplab.project_backup

project_deploy を作ったあと、別のアイデアが浮かびました。コード経由で作られていない既存の Semaphore プロジェクトはどうするのか、という点です。まさにそれを解決するために ebdruplab.project_backup を作りました。既存のプロジェクトを取り込み、project_deploy と互換性のある YAML 変数ファイルとしてエクスポートします。これで一巡します。ゼロから始める場合でも、既存の環境を移行する場合でも、すべてをバージョン管理下に置けます。

はじめかた

コレクションはコマンド 1 つでインストールできます。

ansible-galaxy collection install ebdruplab.semaphoreui

その後は Ansible Galaxy の完全なドキュメントを参照するか、GitHub のサンプルを見てみてください。

不具合を見つけた場合やアイデアがある場合は、遠慮なく issue／feature／question を作成してください — https://github.com/Ebdruplab/ansible-collection_ebdruplab/issues 。それ以外なら、Semaphore UI の Discord サーバーあたりにいます（TrimmerWolf7）。

このコレクションがお役に立てば幸いです。