AnsibleでPixelmonサーバーをバックアップする【エラー修正とアーカイブ作成の記録】

バックアップする対象と手順

Pixelmonサーバーの停止・圧縮・再開をAnsibleのPlaybookにまとめます。停止から再開までを一連の手順として実行できるようにします。

2026年4月の作業で対象にしたのは、WSL2上でDocker Composeにより管理していたサーバーの server ディレクトリです。稼働中の書き込みを避けるため、次の順序で処理する構成にしました。

1. バックアップ保存先を作成し、ファイル名に使う日時を取得します。
2. docker compose stop でコンテナを停止します。
3. server ディレクトリを tar で圧縮します。
4. docker compose start でコンテナを再開します。
5. 保存先で7日より古いアーカイブを探し、該当するファイルを削除します。

docker compose stop はコンテナを削除せずに停止する操作です。停止したコンテナは docker compose start で再開できます。Docker公式のdocker compose stopの説明

このPlaybookは、既存のAnsible環境とCompose設定を使います。インベントリの hosts、変数ファイルの roles/pixelmon/vars/main.yml、そこから読み込む base_dir と data_dir が別途必要です。コード内では base_dir 配下の server を圧縮対象にし、data_dir をComposeコマンドの実行場所にしています。

実行に必要なファイルと配置

この手順は、Linux上でAnsibleとDocker Composeが使え、PixelmonサーバーをComposeで起動できる環境が対象です。AnsibleのPlaybookは処理を順番に記述するファイルで、バックアップ対象はコンテナそのものではなくホスト側の server ディレクトリです。Dockerやゲームサーバーの新規構築は扱いません。

記事内で使うパスの関係は次のとおりです。変数ファイル全体は保存記録にないため、配置を理解するための例として示します。

~/ansible-minecraft/
  backup.yml                 バックアップのPlaybook
  hosts                      実行対象のインベントリ
  roles/pixelmon/vars/main.yml  base_dirとdata_dirの定義
~/pixelmon-data/              base_dirに相当する親ディレクトリ
  server/                    data_dirに相当するCompose実行場所・圧縮対象
    docker-compose.yml
    world/
    mods/
    config/
~/pixelmon-backups/           アーカイブの保存先

base_dir は圧縮対象の server が入る親ディレクトリ、data_dir はComposeファイルがあるディレクトリを指します。別の配置で使う場合は両方を実際のパスに合わせます。hosts はAnsibleの実行対象を列挙するファイルで、このPlaybookの対象は localhost です。

サーバーを停止する処理があるため、実行中は利用できない時間が生じます。また、同じWSL環境内へ保存する構成なので、環境全体を失った場合への備えには別の保存先も必要です。

通常ユーザーのデータをroot配下で探してしまった

最初の失敗では、停止タスクが /root/pixelmon-data/server に移動しようとしていました。保存画像の pwd は通常ユーザーのホーム配下を示しており、実際の配置先とPlaybookが参照するパスがずれています。

この時のコードには、Play全体に become: yes が指定されていました。対応としてPlay全体の指定を外し、Dockerの停止・再開タスクにだけ権限昇格を残しています。

ホームディレクトリの参照に使う ansible_env は、Ansibleが収集する環境情報です。権限昇格の指定とあわせて、どのユーザーの情報を基準にしているかを確認する必要があります。Ansible公式のFactsと変数の説明

ただし、保存画像だけでは当時の変数ファイル全体までは確認できません。ここで直接確認できるのは、参照先のずれと、権限昇格をタスク単位に変更したことです。

また、同じ画像には ansible.builtin.shell のキーが重複しているという警告も残っています。パスのエラーとは別の問題で、後に掲載したコードでは、圧縮タスクの ansible.builtin.shell を1つに整理しています。

圧縮タスクのwarn指定で止まった

次の実行ではコンテナ停止タスクまで進みましたが、圧縮タスクで warn が非対応のパラメータとして扱われました。

対応は、圧縮タスクに付けていた warn: false を削除することでした。当時のAnsibleの正確なバージョンは未確認です。

この失敗では、停止タスクが changed になった後、再開タスクへ進まずにPlaybookが終了しています。途中で失敗すると、コンテナを停止したままにする可能性がある構成でした。その後のコンテナ状態を示す記録はないため、実際にどの程度停止していたかまでは分かりません。

修正後のPlaybookを確認する

当時の修正後のPlaybookは次のとおりです。途中失敗時に再開処理へ進む仕組みは含まれていません。

---
# ~/ansible-minecraft/backup.yml
- name: Backup Pixelmon Server Data
  hosts: localhost
  connection: local
  vars_files:
    - roles/pixelmon/vars/main.yml

  tasks:
    - name: Create backup directory
      ansible.builtin.file:
        path: "{{ ansible_env.HOME }}/pixelmon-backups"
        state: directory
        mode: '0755'

    - name: Get current timestamp for backup file name
      ansible.builtin.command: date +%Y%m%d_%H%M%S
      register: timestamp
      changed_when: false

    - name: Stop Pixelmon container safely
      ansible.builtin.shell:
        cmd: "docker compose stop"
        chdir: "{{ data_dir }}"
      become: yes

    - name: Compress server data using tar
      ansible.builtin.shell:
        cmd: "tar -czf {{ ansible_env.HOME }}/pixelmon-backups/pixelmon_backup_{{ timestamp.stdout }}.tar.gz -C {{ base_dir }} server"

    - name: Restart Pixelmon container
      ansible.builtin.shell:
        cmd: "docker compose start"
        chdir: "{{ data_dir }}"
      become: yes

    - name: Find backups older than 7 days
      ansible.builtin.find:
        paths: "{{ ansible_env.HOME }}/pixelmon-backups"
        patterns: "pixelmon_backup_*.tar.gz"
        age: "7d"
      register: old_backups

    - name: Remove old backups
      ansible.builtin.file:
        path: "{{ item.path }}"
        state: absent
      with_items: "{{ old_backups.files }}"

手動実行で確認できた結果

backup.yml、hosts、変数ファイルを配置した ~/ansible-minecraft で次のコマンドを実行しました。-i hosts はインベントリの指定、-K は権限昇格用パスワードの入力を求める指定です。

ansible-playbook -i hosts backup.yml -K

実行結果では、停止・圧縮・再開の各タスクが changed となり、最後の集計は ok=7 changed=3 unreachable=0 failed=0 skipped=1 でした。

古いファイルを探すタスクは完了し、削除タスクは skipping になっています。この実行で古いバックアップが実際に削除されたことまで確認したわけではありません。

続いて保存先を確認すると、pixelmon_backup_20260427_195345.tar.gz が作成されていました。容量の表示は 2.1G でした。移行時に転送した23GBのアーカイブは旧環境のデータ一式で、ここで対象にした server ディレクトリはその一部です。23GBの内訳の記録は残っていません。

ls -lh ~/pixelmon-backups

運用に向けて残った確認

確認できたのは手動実行によるファイル作成までです。バックアップからの復元や定期実行は確認していません。継続運用に向けて次の点が残りました。

• 途中失敗時の再開：圧縮に失敗した場合にも再開処理へ進める構成と、その動作確認。
• 復元と起動の確認：アーカイブを別の場所へ展開し、必要なデータが揃っているか、復元したサーバーで動作するかの確認。
• 再開後の状態確認：Composeコマンドの成功に加え、サーバーログやクライアント接続で利用可能になったことの確認。
• 保存先と世代管理：同じ環境内の保存だけで十分かの検討と、古いファイルがある場合の削除処理の検証。
• 定期実行：Cronやsystemd timerによる実行設定と、失敗時に気づくための仕組み。

途中失敗への対応には、Ansibleの block と always を使う方法があります。ただし、不正なタスク定義や接続不能などでは実行されないため、あらゆる失敗からの復旧を保証するものではありません。掲載した当時のコードには含まれていないため、補足の改善案として扱います。Ansible公式のBlocksによるエラー処理の説明

同時期に行ったネットワークと旧ファイルの整理

バックアップの整備とあわせて、接続設定と旧環境の起動ファイルも整理していました。バックアップの実行結果とは分けて、残っている記録を示します。

Mirroredモードの設定と受信規則

当時の記事には、%USERPROFILE%\.wslconfig に次の設定を記載しています。

# %USERPROFILE%\.wslconfig
[wsl2]
networkingMode=mirrored

PowerShellでは25577/TCPの受信許可規則を作成しました。Mirroredモードの適用状態や、LAN内の別端末からの接続は未確認です。

New-NetFirewallRule -DisplayName "Minecraft Server 25577" -Direction Inbound -LocalPort 25577 -Protocol TCP -Action Allow

MirroredモードはWindows 11 22H2以降で利用でき、Microsoftの説明にはHyper-Vファイアウォールの受信設定も含まれています。掲載したWindows Firewallの規則だけで接続確認を済ませたことにはできません。Microsoft公式のWSLネットワーク（Mirroredモード）の説明

旧起動ファイルの削除

Docker Composeへ起動方法を揃えるため、旧環境から残っていた run.bat、run.sh、user_jvm_args.txt を確認しました。

この環境で不要と判断した3ファイルを削除しました。world、mods、config、docker-compose.yml は残しています。削除後はファイル一覧を確認しましたが、各データの内容を比較した記録はありません。

cd ~/pixelmon-data/server
rm run.bat run.sh user_jvm_args.txt
ls -la

バックアップファイルの作成まで進められた

停止・圧縮・再開をPlaybookにまとめ、途中のエラーを修正して、手動実行によるアーカイブ作成まで確認できました。一方、途中失敗への対応と復元テストは残っています。次の確認では、作成できたファイルからサーバーを戻せることと、失敗しても状態を把握して復旧できることを確かめる必要があります。