---
title: "Ansibleネットワーク自動化の始め方：network_cliで設定変更とバックアップを自動化する手順【2.21系】"
url: "https://www.issoh.co.jp/tech/details/18463/"
published: 2026-10-17
updated: 2026-10-18
categories: ["自動化"]
publisher: "株式会社一創"
---

# Ansibleネットワーク自動化の始め方：network\_cliで設定変更とバックアップを自動化する手順【2.21系】

Ansibleでルーターやスイッチを操作するときは、Linuxサーバーとは違い、モジュールが機器の上ではなく制御ノードで動きます。この記事では、ansible-core 2.21系とcisco.iosコレクション11.6.0を例に、network\_cli接続のインベントリの書き方、設定バックアップの自動化、IPアドレス変更をリソースモジュールで流す手順を、そのまま使える設定例とともに解説する構成です。管理接続を失う失敗パターンと、ネットワーク自動化をAnsibleで進めるかどうかの判断まで扱います。

## まとめ｜ネットワーク自動化はバックアップから始め変更はリソースモジュールで流す

最初に自動化するのは設定バックアップです。機器の状態を変えないので失敗しても影響が出ず、インベントリと接続設定の誤りをここで洗い出せます。接続は`ansible.netcommon.network_cli`、特権モードは`become_method: enable`で指定し、パスワードはAnsible Vaultで暗号化します。

設定変更に進んだら、生のコマンドを流す`ios_config`ではなく、`ios_l3_interfaces`のようなリソースモジュールを`state: merged`で使います。`overridden`は管理用インターフェースの設定まで消す恐れがあるため、検証機で確かめるまで本番では使いません。同型機が少なく変更も月に数回なら、Ansibleより手順書の整備が先です。

## Ansibleでネットワーク機器を操作する仕組みとLinuxサーバー管理との違い

Ansibleの基本である「SSHでつないでPythonのモジュールを送り込む」動きは、ネットワーク機器ではそのまま成り立ちません。エージェントレスの仕組みそのものは[Ansibleとは](https://www.issoh.co.jp/tech/details/6533/)で解説しているので、ここでは違いだけを押さえます。

### モジュールは機器でなく制御ノードで動くためPythonの導入が不要

公式の[ネットワーク自動化の違いを説明する文書](https://docs.ansible.com/ansible/latest/network/getting%5Fstarted/network%5Fdifferences.html)は、ネットワークモジュールが管理対象ではなく制御ノードで実行されると明記しています。多くのネットワーク機器はPythonを実行できないからです。制御ノード上のモジュールがSSHでCLIにログインし、コマンドを打ち、返ってきた文字列を解析します。

この構造から、実務上の違いが2つ生まれます。1つは、バックアップファイルが機器ではなく制御ノードに保存されること。もう1つは、機器の数が増えるほど制御ノードのCPUとSSHセッション数が先に詰まることです。数百台を相手にするなら、`forks`の値と制御ノードの性能を先に見積もります。

### network\_cli・netconf・httpapiの接続方式の違いと選ぶ基準

接続方式は変数`ansible_connection`で選びます。同じ文書の表を整理すると次のとおりです。表では接頭辞を省いていますが、実際の値は`ansible.netcommon.network_cli`のように`ansible.netcommon.`を付けた完全修飾名で書きます。

| ansible\_connection | 通信の中身       | 向いている対象                   |
| ------------------- | ----------- | ------------------------- |
| network\_cli        | SSH経由のCLI   | IOS・EOS・JunosなどCLIを持つ機器全般 |
| netconf             | SSH経由のXML   | NETCONF有効のJunos・IOS XEなど  |
| httpapi             | HTTPSのAPI   | REST APIを持つ機器やSDNコントローラー  |
| local               | providerで指定 | 非推奨のため新規には使わない            |

迷ったらnetwork\_cliから始めてください。対応機種が最も広く、手作業のCLIと同じコマンドが通るため、結果を人が読んで確かめられます。古い記事に多い`connection: local`と`provider`の組み合わせは、公式文書では非推奨という位置付けです。そうしたPlaybookを引き継いだ場合は、接続方式の書き換えから手を付けます。

## 制御ノードの準備とインベントリ、network\_cliの接続設定の書き方

ここからは、Cisco IOS／IOS XEのスイッチ2台を相手にする構成で手順を示します。AristaやJuniperでも、コレクション名と`ansible_network_os`の値を変えれば同じ流れです。

### ansible-core 2.21系とcisco.iosなど機種別コレクションの導入手順

2026年10月時点で、PyPIの`ansible-core`の最新は2.21.5（10月5日公開）で、Python 3.12以上を要求します。ネットワーク用の部品は本体に含まれないので、共通部品の`ansible.netcommon`と機種別のコレクションを別に入れます。

```
python3 -m venv ~/.venv/netauto
source ~/.venv/netauto/bin/activate
pip install ansible-core ansible-pylibssh
ansible-galaxy collection install ansible.netcommon cisco.ios
ansible-galaxy collection list | grep -E "netcommon|cisco.ios"
```

Galaxyで確認した最新は、ansible.netcommonが8.7.1（2026年9月22日）、cisco.iosが11.6.0（9月17日）です。[cisco.iosのリポジトリ](https://github.com/ansible-collections/cisco.ios)には、ansible-core 2.16.0以上で検証し、機器側はCML上のIOS XE 17.3でテストしたと書かれています。古いIOSの機器はプロンプトや出力の形が違うことがあるため、まず1台で確かめます。

### group\_varsに書くansible\_network\_osとenableモードの変数

機種ごとの接続設定は、グループ変数にまとめます。[IOSのプラットフォームガイド](https://docs.ansible.com/ansible/latest/network/user%5Fguide/platform%5Fios.html)の例に、タイムアウトの指定を足した形です。

```
# inventory.yml
all:
  children:
    ios:
      hosts:
        sw01:
          ansible_host: 192.0.2.11
        sw02:
          ansible_host: 192.0.2.12

# group_vars/ios.yml
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: cisco.ios.ios
ansible_user: netops
ansible_password: "{{ vault_ios_password }}"
ansible_become: true
ansible_become_method: enable
ansible_become_password: "{{ vault_ios_enable_password }}"
ansible_command_timeout: 60
```

`ansible_network_os`はグループ名ではなく、コレクションの完全修飾名で書きます。特権モードへの移行は`become`で行い、公式文書はnetwork\_cliかhttpapiとの組み合わせでのみ使えるとしています。パスワードの変数は、`ansible-vault encrypt_string`で暗号化した値を別ファイルに置き、平文をGitに入れないでください。暗号化と復号の手順は[Ansible Vaultの使い方](https://www.issoh.co.jp/tech/details/18471/)で解説しています。

### ssh\_typeのlibsshとparamikoの違いと30秒の既定タイムアウト

[network\_cli接続プラグインの文書](https://docs.ansible.com/ansible/latest/collections/ansible/netcommon/network%5Fcli%5Fconnection.html)によると、SSHの実装を決める`ssh_type`の既定は`auto`です。ansible-pylibsshが入っていればlibsshを使い、無ければparamikoに切り替えます。paramikoの指定は非推奨で、2028年2月1日以降のリリースで削除される予定です。上の手順で`ansible-pylibssh`を一緒に入れたのはこのためです。

もう1つ詰まりやすいのがタイムアウトです。コマンドの応答待ちは`ansible_command_timeout`、接続の確立は`ansible_connect_timeout`で、どちらも既定は30秒です。設定が大きいコアスイッチではrunning-configの出力に30秒以上かかり、途中で接続が閉じられます。上のgroup\_varsで60秒にしているのはこの対策です。

## 設定バックアップを自動化するPlaybookとファイルの保存先・世代管理

最初のPlaybookはバックアップにします。機器の状態を一切変えないので、認証やenableの設定に誤りがあっても実害が出ません。Playbookの基本的な書き方は[Ansible Playbookの書き方と実行手順](https://www.issoh.co.jp/tech/details/18457/)を参照してください。

### ios\_configのbackupオプションで保存先を明示して退避する書き方

[ios\_configの文書](https://docs.ansible.com/ansible/latest/collections/cisco/ios/ios%5Fconfig%5Fmodule.html)では、`backup: true`で実行前のrunning-configを丸ごと保存できます。保存先の既定値は、同じ文書の中で「Playbookのルート」と「カレントディレクトリ」の2通りに書かれており、記述が揃っていません。実行場所によって保存先が変わる事故を避けるため、`backup_options`で明示します。

```
---
- name: IOS機器の設定バックアップ
  hosts: ios
  gather_facts: false
  tasks:
    - name: running-configを機器ごとのディレクトリへ保存
      cisco.ios.ios_config:
        backup: true
        backup_options:
          dir_path: "{{ playbook_dir }}/backups"
          filename: "{{ inventory_hostname }}.cfg"
```

`ansible-playbook -i inventory.yml backup.yml`で実行すると、`backups/sw01.cfg`と`backups/sw02.cfg`ができます。`filename`を省くとホスト名と日時からファイル名が作られますが、ここでは機器ごとに固定の名前にしています。固定名にする理由は次のh3のとおりです。

### 固定ファイル名とGitで差分履歴を残す世代管理とcli\_backupの使い分け

日時入りのファイル名で毎日保存すると、ファイルは増えるのに「何が変わったか」は見えません。固定の名前で上書きし、`backups`ディレクトリをGitで管理すれば、`git log -p backups/sw01.cfg`で誰がいつどの行を変えたかを追えます。手作業の変更が紛れ込んだ場合も、翌朝のバックアップの差分で見つかります。

IOSとJunosなど機種が混ざる環境では、機種別のモジュールを並べる代わりに[ansible.netcommon.cli\_backup](https://docs.ansible.com/ansible/latest/collections/ansible/netcommon/cli%5Fbackup%5Fmodule.html)が使えます。netcommon 4.2.0で追加された、機種を問わずテキストの設定を取得するモジュールです。network\_cli接続で`ansible_network_os`が設定されたホストを対象に動くため、機種が混ざっていてもタスクは1つで済みます。

```
    - name: 機種を問わずrunning-configを保存
      ansible.netcommon.cli_backup:
        dir_path: "{{ playbook_dir }}/backups"
        filename: "{{ inventory_hostname }}.cfg"
```

## リソースモジュールでIPアドレスなどの設定変更を安全に流す手順

設定変更には、コマンド文字列を送る`ios_config`と、設定を構造化データで渡すリソースモジュールの2系統があります。新しく書くなら後者を勧めます。現在の設定と比べて差分のコマンドだけを作るため、同じPlaybookを何度流しても結果が変わりません。この性質は[冪等性とは](https://www.issoh.co.jp/tech/details/13382/)で詳しく扱っています。

### ios\_l3\_interfacesのmergedでインターフェースのIPを変更する例

「ansible ipアドレス 変更」で探している場合に使うのが、L3インターフェースのリソースモジュールです。[ios\_l3\_interfacesの文書](https://docs.ansible.com/ansible/latest/collections/cisco/ios/ios%5Fl3%5Finterfaces%5Fmodule.html)の形に沿って、GigabitEthernet0/2へアドレスを設定します。

```
---
- name: Gi0/2のIPアドレス変更
  hosts: sw01
  gather_facts: false
  tasks:
    - name: 指定したインターフェースだけにIPを設定
      cisco.ios.ios_l3_interfaces:
        config:
          - name: GigabitEthernet0/2
            ipv4:
              - address: 192.0.2.1/24
        state: merged
      register: result

    - name: 実際に投入されたコマンドを表示
      ansible.builtin.debug:
        var: result.commands
```

アドレスは「アドレス/プレフィックス長」で書きます。文書の実行例では、`ip address dhcp`だったインターフェースに対して`ip address 192.168.0.2 255.255.255.0`が投入され、shutdownやspeedの行はそのまま残っています。mergedは書いた項目だけを足すか置き換え、書いていない設定には触れません。

### renderedで投入コマンドを事前確認しsave\_whenで保存する流れ

本番の前に、どのコマンドが流れるかを機器に触れずに確かめられます。[リソースモジュールの文書](https://docs.ansible.com/ansible/latest/network/user%5Fguide/network%5Fresource%5Fmodules.html)によると、`state: rendered`は渡した設定を機器のネイティブな形式に変換して返すだけで、機器とは通信しません。上のタスクの`merged`を`rendered`に変え、結果の`rendered`キーを表示すれば、変更申請の資料にそのまま貼れます。

投入後は設定の保存も必要です。`ios_config`の`save_when`は既定が`never`で、何もしなければrunning-configだけが変わり、再起動で元に戻ります。変更タスクの後ろに次の1タスクを置きます。

```
    - name: running-configがstartup-configと異なれば保存
      cisco.ios.ios_config:
        save_when: modified
```

### overriddenとreplacedで管理用インターフェースを消す失敗パターン

リソースモジュールのstateには、merged、replaced、overridden、deletedなどがあります。名前が似ていても影響範囲がまるで違います。

| state      | 書いていない設定の扱い     | 本番での使いどころ        |
| ---------- | --------------- | ---------------- |
| merged     | そのまま残す          | 日常の変更はこれ         |
| replaced   | 書いたインターフェース内は消す | 1ポートを定義どおりに作り直す  |
| overridden | 全インターフェースで消す    | 検証済みの全量定義がある場合だけ |
| deleted    | 指定範囲を既定値に戻す     | 撤去作業             |

公式文書はoverriddenについて、管理用インターフェースの設定まで上書きして機器にアクセスできなくなる恐れがあると注意しています。Playbookに管理用VLANのインターフェースを書き忘れたままoverriddenを流すと、そのアドレスが消え、Ansible自身も以降の機器につながらなくなります。遠隔地の機器なら現地対応です。overriddenを使うのは、`state: gathered`で取得した全量を定義の土台にし、検証機で差分ゼロを確かめた後に限ります。

## Ansibleでネットワーク自動化を進める条件と手作業やSDNを残す場面

判断の軸は、台数と変更頻度、それに変更を誰がレビューするかです。ツールの機能で選ぶと、使われないPlaybookが残ります。

### Ansibleで進める条件：同型機が多く変更をGitでレビューできる体制

Ansibleが効くのは、同じ設定を何十台にも流す作業です。VLANの追加、NTPやsyslogの送信先の変更、ローカルアカウントの入れ替えなどが典型で、手作業では1台ずつの打ち間違いが起きます。加えて、PlaybookとインベントリをGitで管理し、変更をプルリクエストでレビューできる担当者が2人以上いることを条件にします。1人で書いて1人で流すなら、手順書と大差がありません。

実行の窓口を画面にしたい、実行履歴を監査に残したいという要件が出たら、[Ansible Towerの機能と設定手順](https://www.issoh.co.jp/tech/details/18459/)や、無償の[AWXをKubernetesへ導入する手順](https://www.issoh.co.jp/tech/details/18461/)を検討してください。どの運用作業から自動化するかの選び方と費用対効果は、[Ansibleによる運用自動化の進め方](https://www.issoh.co.jp/column/details/18092/)で整理しています。

### SDNコントローラーや手作業を残しAnsibleを使わない場面

Cisco ACIのようなSDNコントローラーで管理しているファブリックでは、個々のスイッチへnetwork\_cliで設定を流しません。コントローラーの設定と食い違い、次の同期で上書きされるか、不整合の原因になります。Ansibleを使うならコントローラーのAPIに対してhttpapi接続やベンダーのコレクションで操作し、スイッチ単体には触れない線引きにします。

拠点ルーターが数台で変更が年に数回なら、Ansibleは過剰です。ただしバックアップだけは台数が少なくても自動化する価値があります。故障交換のときに最新の設定が手元にあるかどうかで、復旧時間が変わるからです。社内のネットワークとサーバーの構成管理を、CI/CDのパイプラインに組み込んで回す仕組みまで相談したい場合は、[DevOps・CI/CD導入支援](https://www.issoh.co.jp/service/system/devops/)で承っています。

## よくある質問

Ansibleでのネットワーク自動化について、検索されることの多い質問に答えます。

### Ansibleで操作するためにネットワーク機器側で必要な準備は何ですか？

SSHでログインできる状態にすることが前提です。Cisco IOSなら、ホスト名とドメイン名を設定してRSA鍵を生成し、vtyでSSHを許可し、Ansible用のローカルユーザーを作ります。enableパスワードを使う構成では、その値もVaultで暗号化して渡します。機器にPythonやエージェントを入れる必要はありません。制御ノードから機器の管理用アドレスへSSHが届くことも、ファイアウォールの設定で確かめておきます。

### connection: localで書かれた古いPlaybookはまだ動きますか？

公式文書では`connection: local`は非推奨とされています。今は動いていても、コレクションを更新したときに止まる危険を抱えた状態なので、動いているうちに書き換えるのが安全です。書き換えは、Playbookから`connection: local`と`provider`を消し、グループ変数に`ansible_connection: ansible.netcommon.network_cli`と`ansible_network_os`を書く形になります。

### showコマンドの結果だけを取得したい場合はどのモジュールを使いますか？

機種を問わず1つのコマンドを送るなら`ansible.netcommon.cli_command`、IOSで複数のshowコマンドを順に送るなら`cisco.ios.ios_command`を使います。どちらも結果を`register`で受け取れば、`debug`で表示したりファイルに書き出したりできます。インターフェースやVLANの状態を構造化データで欲しい場合は、リソースモジュールの`state: gathered`のほうが後の処理が楽です。

### ansible sdnで検索するとCisco ACIの情報が多いのはなぜですか？

SDNの代表的な製品であるCisco ACIに、Ansibleのコレクションが用意されているためです。ACIではコントローラー（APIC）のAPIに対して設定を投げる形になり、本記事のnetwork\_cliでスイッチに入る方法とは接続方式が異なります。Cisco製品ごとのコレクションとモジュールの違いは「[Cisco機器をAnsibleで設定変更する手順：cisco.ios・cisco.nxos・cisco.aciのPlaybook例【2026年10月】](https://www.issoh.co.jp/tech/details/18465/)」で解説しています。

### AWXやAnsible Towerからネットワーク機器のPlaybookを実行できますか？

実行できます。インベントリとgroup\_varsはそのまま使え、SSHのユーザー名とパスワード、enableパスワードは認証情報の機能で渡します。Playbookの中にパスワードを書かずに済み、誰がいつどの機器に変更を流したかを確認できるのが実行履歴です。ネットワークの変更は影響範囲が広いので、承認を挟める画面からの実行は監査の面でも効きます。

## 関連記事

- [Ansibleとは？エージェントレスの仕組みとメリット・デメリット、Red Hat AAPの制約](https://www.issoh.co.jp/tech/details/6533/)：ネットワーク自動化の前提となるAnsible本体の仕組み。
- [Ansible Playbookの書き方と実行手順：–checkでのdry-runとhandlers【2.21系】](https://www.issoh.co.jp/tech/details/18457/)：バックアップや設定変更のPlaybookを書くための基本。
- [Ansibleによる運用自動化の進め方：対象作業の選び方と費用対効果・失敗パターン](https://www.issoh.co.jp/column/details/18092/)：どのネットワーク作業から自動化するかの判断。
- [Ansible Towerとは：automation controllerへの改称とSurvey・Webhook・RBACの設定手順【AAP 2.7】](https://www.issoh.co.jp/tech/details/18459/)：ネットワーク変更の実行を画面と承認で管理する方法。
- [構成管理ツールの比較と選び方｜Ansible・Terraform・Chef・Puppet・OpenTofuの選定条件](https://www.issoh.co.jp/column/details/15293/)：Ansible以外の構成管理ツールとの比較。

---

出典: [Ansibleネットワーク自動化の始め方：network\_cliで設定変更とバックアップを自動化する手順【2.21系】](<https://www.issoh.co.jp/tech/details/18463/>)（株式会社一創）