Ansibleのsynchronizeモジュール設計入門｜rsync連携と差分転送でconfig配布・ログ回収を効率化する方法

運営：リナックスマスター.JP（代表 宮崎智広）
ＨＯＭＥ ＞ Linux技術 リナックスマスター.JP（Linuxマスター.JP） ＞ Ansible ＞ Ansibleのsynchronizeモジュール設計入門｜rsync連携と差分転送でconfig配布・ログ回収を効率化する方法
「Ansible で数十台のサーバーに同じ設定ファイルを配布したら、Playbook が返ってくるまで長時間かかった」
大量ホストへのファイル転送で copy モジュールが遅いと感じたとき、次の選択肢が synchronize モジュールです。

この記事では、RHEL 9系～Rocky Linux 9 を想定環境として、synchronize モジュールの仕組みから push/pull モードの使い分け、rsync_opts による転送制御、ログ回収・バックアップ設計まで説明します。copy との使い分け基準を中心に、設計の判断軸を整理します。

この記事のポイント

・synchronize モジュールは rsync をバックエンドに使い、差分転送で copy より大量ファイルの配布を高速化できる
・push（コントロールノード → 管理対象）と pull（管理対象 → コントロールノード）の 2 方向を切り替えられる
・rsync_opts でファイル除外・帯域制限・削除同期を制御して転送設計をカスタマイズできる
・管理対象ホストに rsync がないと Unreachable になるため事前インストールが必要


「このままじゃマズい」と感じていませんか？
参考書を開く気力もない、同年代に取り残される不安——
でも安心してください。プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
姓・名・メールの3つだけ／30秒／解除は3秒 ／ 詳細はこちら

なぜ copy モジュールでは大量ファイル転送が遅くなるのか

Ansible の copy モジュールは、コントロールノードでファイルを Base64 エンコードしてモジュールのコードと一緒に JSON に包み、SSH 経由で管理対象へ転送します。

この仕組みはシンプルで使いやすい反面、次の場面で限界が出てきます。

・転送するファイルが大きい（数十 MB 以上の設定ファイルやバイナリ）
・サーバー台数が多く、fork 数を上げても逐次転送の合計時間が長くなる
・すでに同じ内容のファイルが転送先にあり、差分だけを更新したい

copy モジュールはファイル全体を転送するため、差分転送の仕組みがありません。毎回同じ内容を全量送り続けるのは、特に多台数・大容量のファイル配布では無駄なトラフィックになります。

synchronize モジュールはこの問題を rsync のアルゴリズムで解決します。転送済みのファイルは差分だけを送るため、2 回目以降の実行が速くなります。

synchronize モジュールの仕組みと基本設計

synchronize モジュールは ansible.posix コレクションに含まれています。RHEL 9 / Rocky Linux 9 では次のコマンドでインストールできます。

出力例（環境により異なります）:

# ansible.posix コレクションのインストール
$ ansible-galaxy collection install ansible.posix

Starting galaxy collection install process
Process install dependency map
Starting collection install process
ansible.posix (1.5.4) was installed successfully

1. 基本構文と copy モジュールとの比較

copy モジュールと synchronize モジュールのタスクを並べて比較します。

出力例（環境により異なります）:

# --- copy モジュールの場合（ファイル 1 つ・owner/mode 設定あり）---
- name: 設定ファイルを配布
  ansible.builtin.copy:
    src: files/httpd.conf
    dest: /etc/httpd/conf/httpd.conf
    owner: root
    group: root
    mode: '0644'

# --- synchronize モジュールの場合（ディレクトリまるごと・差分転送）---
- name: 設定ディレクトリをrsync転送
  ansible.posix.synchronize:
    src: files/conf.d/
    dest: /etc/httpd/conf.d/
    rsync_opts:
      - "--no-motd"
      - "--exclude=*.swp"
copy はファイル 1 つに対して owner / group / mode を設定できる点が強みです。synchronize はディレクトリまるごと・差分転送・削除同期を扱う場面に向いています。

2. push モードと pull モードの使い分け

synchronize モジュールには転送方向を決める mode パラメータがあります。

・push（デフォルト）: コントロールノード → 管理対象ホスト（設定ファイルの配布に使う）
・pull: 管理対象ホスト → コントロールノード（ログ収集・バックアップ取得に使う）

pull モードでは src が管理対象ホスト側のパス、dest がコントロールノード側のパスになります。方向が逆になる点に注意してください。

Ansible の基本から構成管理の設計まで体系的に学べるAnsible 構成管理入門（ansible.linuxmaster.jp）もご参照ください。

出力例（環境により異なります）:

# pull モードでログをコントロールノードへ回収する例
- name: アクセスログをコントロールノードに回収
  ansible.posix.synchronize:
    src: /var/log/nginx/
    dest: /srv/collected-logs/{{ inventory_hostname }}/
    mode: pull
    rsync_opts:
      - "--no-motd"
      - "--include=access.log"
      - "--exclude=*"

3. rsync_opts で転送を制御する主なオプション

rsync_opts にリスト形式で rsync のオプションを渡せます。よく使う設定を整理します。

・--exclude=パターン: 除外するファイルパターン（*.log や .git など）
・--delete: 転送元に存在しないファイルを転送先から削除（ミラーリング）
・--bwlimit=KB: 帯域制限（本番ネットワークへの影響を抑えたい場合）
・--checksum: タイムスタンプではなくチェックサムで差分を判定（より厳密な同期）
・--no-motd: MOTD を表示しない（実行ログが余分な行で埋まるのを防ぐ）

--delete はミラーリングに便利ですが、転送先に追加したファイルがすべて消えます。初めて使う場合は Ansible の check モードで確認してから実行してください。

現場で使える設計パターン 3 選

1. 設定ファイルの push 配布パターン

Nginx の設定ディレクトリをまとめて各サーバーに配布し、変更があったときだけサービスをリロードするパターンです。

出力例（環境により異なります）:

- hosts: webservers
  tasks:
    - name: Nginx 設定ディレクトリを配布
      ansible.posix.synchronize:
        src: roles/nginx/files/conf.d/
        dest: /etc/nginx/conf.d/
        rsync_opts:
          - "--no-motd"
          - "--exclude=*.bak"
          - "--delete"
      notify: nginx 設定リロード

  handlers:
    - name: nginx 設定リロード
      ansible.builtin.service:
        name: nginx
        state: reloaded
手動で scp を実行していた運用と比べて、Playbook で管理すると「いつ・誰が・どの設定を配布したか」がコミット履歴と実行ログに残ります。

2. ログ回収パターン（pull モード）

複数サーバーのログをコントロールノードへ集約するパターンです。サーバーごとにディレクトリを分けて保存します。

出力例（環境により異なります）:

- hosts: webservers
  tasks:
    - name: Nginx アクセスログをコントロールノードに回収
      ansible.posix.synchronize:
        src: /var/log/nginx/access.log
        dest: /srv/logs/{{ inventory_hostname }}/
        mode: pull
        rsync_opts:
          - "--no-motd"
          - "--bwlimit=2048"
Ansible で設定管理とログ収集を 1 つの Playbook にまとめると、障害対応時のエビデンス取得が整理されます。

3. delegate_to を使ったサーバー間バックアップパターン

本番サーバーのデータをバックアップサーバーへ直接転送するパターンです。delegate_to でタスクの実行ホストをバックアップサーバーへ切り替え、本番サーバーから pull します。

出力例（環境により異なります）:

- hosts: webservers
  tasks:
    - name: Web ルートをバックアップサーバーへ同期
      ansible.posix.synchronize:
        src: /var/www/html/
        dest: /backups/{{ inventory_hostname }}/html/
        mode: pull
        rsync_opts:
          - "--no-motd"
          - "--delete"
          - "--exclude=.git"
      delegate_to: backup-server
delegate_to: backup-server としてタスクをバックアップサーバーで実行することで、コントロールノードを経由せずサーバー間で直接 rsync できます。

トラブルシュート｜よくあるエラーと対処

「rsync: not found」エラーが出た時の対処


fatal: [web01]: UNREACHABLE! => {
    "msg": "Failed to connect to the host via ssh: ...rsync: not found"
}
このエラーは、管理対象ホストに rsync がインストールされていない場合に出ます。synchronize モジュールはコントロールノードと管理対象ホストの両方に rsync が必要です。

Playbook に rsync のインストールタスクを追加して事前に準備してください。

出力例（環境により異なります）:

- name: rsync をインストール（RHEL 9系）
  ansible.builtin.dnf:
    name: rsync
    state: present
  become: yes

「Permission denied」が出た時の対処

転送先ディレクトリへの書き込み権限がない場合に出るエラーです。

出力例（環境により異なります）:

rsync: [sender] send_files failed to open ".../httpd.conf": Permission denied (13)
rsync error: some files/attrs were not transferred (see previous errors) (code 23)
synchronize タスクに become: yes を追加すると rsync が root 権限で実行されます。ただし rsync 経由の sudo には sudoers に NOPASSWD 設定が必要な場合があります。sudo の設定が難しい環境では、copy モジュールと組み合わせる構成も検討してください。

本記事のまとめ

用途 適切なモジュール 理由
単一ファイルの転送・権限設定 ansible.builtin.copy owner/group/mode を 1 つのタスクで設定できる
ディレクトリまるごと・差分転送 ansible.posix.synchronize rsync の差分転送で 2 回目以降の実行が高速
大量サーバーへの配布 ansible.posix.synchronize 転送量を削減しながら forks で並列配布できる
ログ収集・バックアップ ansible.posix.synchronize（pull） pullモードでコントロールノードへ集約できる
synchronize モジュールは copy で間に合わなくなった場面への自然な次の一手です。push と pull を使い分け、rsync_opts で転送を制御する設計を身につけると、ファイル配布・ログ収集・バックアップをすべて Playbook で管理できます。
現場で通用する安全なLinuxサーバー構築の「型」を体系的に身につけたい方へ、
Ansible を含む Linux サーバー管理の実践を 2 日間で学べます。
＞＞【初心者向けLinuxセミナー（2日間ハンズオン）】

関連記事

無料メルマガで学習を続ける

Linuxの実践スキルをメールで毎週お届け。
登録は30秒、解除もいつでも可。

登録無料・いつでも解除できます

暗記不要・1時間後にはサーバーが動く

3,100名以上が実践した「型」を無料で公開中

プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
その「型」を図解60Pにまとめた入門マニュアルを、完全無料でプレゼントしています。

姓・名・メールの3つだけ／30秒／解除は3秒 ／ 詳細はこちら

Linux無料マニュアル（図解60P） 名前とメールで30秒登録

運営

リナックスマスター.JP（代表 宮崎智広）

株式会社イーネットマーキュリーが運営するLinux教育サイトです。代表の宮崎智広は現役のLinuxサーバー管理者として20年以上の実務経験を持ち、累計3,100名以上のエンジニアを指導してきました。実践型のLinuxセミナーや無料マニュアルの配布を通じてLinux人材の育成に取り組んでいます。