2026.10.17 自動化

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

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

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

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

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

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とはで解説しているので、ここでは違いだけを押さえます。

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

公式のネットワーク自動化の違いを説明する文書は、ネットワークモジュールが管理対象ではなく制御ノードで実行されると明記しています。多くのネットワーク機器は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のリポジトリには、ansible-core 2.16.0以上で検証し、機器側はCML上のIOS XE 17.3でテストしたと書かれています。古いIOSの機器はプロンプトや出力の形が違うことがあるため、まず1台で確かめます。

group_varsに書くansible_network_osとenableモードの変数

機種ごとの接続設定は、グループ変数にまとめます。IOSのプラットフォームガイドの例に、タイムアウトの指定を足した形です。

# 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の使い方で解説しています。

ssh_typeのlibsshとparamikoの違いと30秒の既定タイムアウト

network_cli接続プラグインの文書によると、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の書き方と実行手順を参照してください。

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

ios_configの文書では、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が使えます。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を何度流しても結果が変わりません。この性質は冪等性とはで詳しく扱っています。

ios_l3_interfacesのmergedでインターフェースのIPを変更する例

「ansible ipアドレス変更」で探している場合に使うのが、L3インターフェースのリソースモジュールです。ios_l3_interfacesの文書の形に沿って、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で保存する流れ

本番の前に、どのコマンドが流れるかを機器に触れずに確かめられます。リソースモジュールの文書によると、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の機能と設定手順や、無償のAWXをKubernetesへ導入する手順を検討してください。どの運用作業から自動化するかの選び方と費用対効果は、Ansibleによる運用自動化の進め方で整理しています。

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

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

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

よくある質問

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月】」で解説しています。

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

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