--- title: "Cisco機器をAnsibleで設定変更する手順：cisco.ios・cisco.nxos・cisco.aciのPlaybook例【2026年10月】" url: "https://www.issoh.co.jp/tech/details/18465/" published: 2026-10-17 updated: 2026-10-17 categories: ["自動化"] publisher: "株式会社一創" --- # Cisco機器をAnsibleで設定変更する手順：cisco.ios・cisco.nxos・cisco.aciのPlaybook例【2026年10月】 Cisco機器をAnsibleで操作するときは、対象がIOS系のスイッチか、Nexusか、ACIのファブリックかで使うコレクションも接続方式も変わります。この記事では、2026年10月時点のcisco.ios 11.6.0、cisco.nxos 13.0.0、cisco.aci 2.13.0を例に、VLAN追加・ACL書き換え・トランクの許可VLAN変更・テナントからEPGまでの作成を、そのまま試せるPlaybookで解説します。最新版で直った不具合や、毎回changedになるモジュールの癖など、Cisco向けに書くときに詰まる箇所もまとめました。 ## まとめ｜IOSとNexusはリソースモジュール、ACIはAPIC向けに書き分ける IOS／IOS XEには`cisco.ios`、Nexusには`cisco.nxos`を入れ、どちらも`ios_vlans`や`nxos_l2_interfaces`のようなリソースモジュールを`state: merged`で使うのが基本です。NexusはSSHのnetwork\_cliに加えて、NX-APIを使うhttpapi接続も選べます。 ACIは考え方が違います。スイッチに入るのではなく、コントローラーであるAPICのREST APIへ`cisco.aci`のモジュールで設定を送ります。cisco.nxosは13.0.0未満だと、既定のトランクに対する許可VLANの絞り込みが`merged`で効かない不具合があるため、Nexusを扱うなら13.0.0以上へ上げてから書き始めてください。 ## cisco.ios・cisco.nxos・cisco.aciの3コレクションの違いと選び方 Ansibleでネットワーク機器を操作する仕組みと、Linuxサーバー管理との違いは[Ansibleネットワーク自動化の始め方](https://www.issoh.co.jp/tech/details/18463/)で解説しています。ここではCisco製品に絞って、どのコレクションを入れるかを整理します。 ### 対象機器と接続方式で決まるCisco向け3コレクションの役割分担 3つのコレクションは、対象のOSと通信の相手で分かれます。 | コレクション | 主な対象 | 接続方式 | | ---------- | --------------------- | ------------------------ | | cisco.ios | Catalystなど IOS／IOS XE | network\_cli | | cisco.nxos | Nexus・MDS | network\_cli または httpapi | | cisco.aci | ACIファブリック（APIC） | APICのREST API | ACIのリーフやスパインもNX-OSベースのスイッチですが、ACIモードで動いている間は`cisco.nxos`で個別に設定しません。ファブリックの設定はAPICが持っているので、Ansibleからの変更もAPICに対して行います。IOS XRのルーターは別の`cisco.iosxr`コレクションの担当です。IOS XRとIOS XEの違いは[IOS-XRとは](https://www.issoh.co.jp/tech/details/5187/)を参照してください。 ### 2026年10月時点の版と必要なansible-core・Pythonの条件 Galaxyで確認した最新は、cisco.iosが11.6.0（2026年9月17日）、cisco.nxosが13.0.0（同日）、cisco.aciが2.13.0（2025年12月9日）です。[cisco.nxosのリポジトリ](https://github.com/ansible-collections/cisco.nxos)はansible-core 2.16.0以上での検証を明記しており、[cisco.aciのリポジトリ](https://github.com/CiscoDevNet/ansible-aci)はAnsible 2.16以上とPython 3.10以上を要件に挙げています。PyPIの`ansible-core`の最新2.21.5はPython 3.12以上が必要なので、制御ノードのPythonは3.12以上にそろえるのが手堅い選択です。 ``` python3 -m venv ~/.venv/cisco source ~/.venv/cisco/bin/activate pip install ansible-core ansible-pylibssh ansible-galaxy collection install ansible.netcommon cisco.ios cisco.nxos cisco.aci ansible-galaxy collection list | grep -E "cisco|netcommon" ``` 注意したいのは、docs.ansible.comのモジュールページに表示される版が最新と一致しないことです。2026年10月時点で、cisco.nxosのページは11.2.0の内容を表示しています。手元の版の仕様は`ansible-doc cisco.nxos.nxos_l2_interfaces`で確かめてください。 ## cisco.iosでVLAN作成とポート設定を変更するPlaybookの書き方 接続設定（`ansible_network_os: cisco.ios.ios`とenableモード）とバックアップの手順は兄弟記事で扱ったので、ここでは設定変更の書き方に進みます。Playbookの基本構文は[Ansible Playbookの書き方と実行手順](https://www.issoh.co.jp/tech/details/18457/)にまとめています。 ### ios\_vlansでVLANを追加しrenderedで投入コマンドを確かめる [ios\_vlansの文書](https://docs.ansible.com/projects/ansible/latest/collections/cisco/ios/ios%5Fvlans%5Fmodule.html)は、IOS XE 17.13.01を載せたCatalyst 9000（CML上）でテストしたと書いています。VLANを追加するPlaybookは次のとおりです。 ``` --- - name: アクセススイッチにVLANを追加 hosts: ios gather_facts: false tasks: - name: VLAN 110と120を作成 cisco.ios.ios_vlans: config: - vlan_id: 110 name: SALES - vlan_id: 120 name: GUEST shutdown: enabled state: merged register: result - name: 投入されたコマンドを表示 ansible.builtin.debug: var: result.commands ``` `state: merged`を`rendered`に変えると、機器に接続せずに投入予定のコマンドだけを返します。変更申請に貼る資料を作る段階ではrenderedで出力を取り、承認後にmergedへ戻して流す手順にすると、申請内容と実際の投入が食い違いません。 ### ios\_configのparentsとlinesでACLの階層を書き換える リソースモジュールが無い設定は`ios_config`で書きます。[ios\_configの文書](https://docs.ansible.com/projects/ansible/latest/collections/cisco/ios/ios%5Fconfig%5Fmodule.html)にあるACLの例を、管理用ACLの入れ替えに置き換えた形です。 ``` - name: 管理用ACLを定義どおりに入れ替える cisco.ios.ios_config: parents: ip access-list extended MGMT-IN lines: - 10 permit ip host 192.0.2.10 any log - 20 permit ip host 192.0.2.11 any log - 30 deny ip any any log before: no ip access-list extended MGMT-IN match: exact ``` `parents`で設定の階層を指定し、`lines`にその中の行を書きます。`match: exact`は、機器上のACLが`lines`と完全に一致しない限り、`before`でACLを消してから作り直す指定です。文書には、省略形のコマンド（`int`など）は冪等にならないとも書かれています。running-configに表示されるとおりの綴りとインデントで書かないと、毎回changedになり差分が読めなくなります。 ## Nexusをcisco.nxosで設定変更する手順とNX-API接続への切り替え Nexusは、IOSと同じSSHのCLI接続に加えて、HTTPSのNX-APIでも操作できます。どちらを選んでもPlaybookのタスクは同じで、変わるのはgroup\_varsだけです。 ### network\_cliとNX-API（httpapi）の比較とgroup\_vars設定 [NX-OSのプラットフォームガイド](https://docs.ansible.com/projects/ansible/latest/network/user%5Fguide/platform%5Fnxos.html)によると、NX-APIを使うには機器側で先に有効化が必要で、その作業自体はCLI接続から`nxos_nxapi`モジュールで行えます。また、enableモードへの昇格はNX-APIでは使えません。 ``` # 1回目：CLI接続のままNX-APIを有効化する - name: NX-APIを有効化 hosts: nxos gather_facts: false tasks: - cisco.nxos.nxos_nxapi: enable_http: false enable_https: true # 2回目以降：group_vars/nxos.yml を書き換える ansible_connection: ansible.netcommon.httpapi ansible_network_os: cisco.nxos.nxos ansible_user: netops ansible_password: "{{ vault_nxos_password }}" ansible_httpapi_use_ssl: true ansible_httpapi_validate_certs: true ``` ガイドの表では、NX-APIの経路はWebプロキシ経由、CLIの経路は踏み台サーバー（ジャンプホスト）経由と整理されています。踏み台越しにしか届かない機器はSSHの`network_cli`、HTTPSが直接届く管理ネットワークならNX-APIというように、経路で決めてください。同じガイドの対応表では、Nexus 3000と9000はNX-OS 7.0(3)I2(5)以降が対象です。 ### nxos\_vlansとnxos\_l2\_interfacesでのトランク許可VLAN設定例 VLANを作り、アップリンクのトランクに通す作業を2つのリソースモジュールで書きます。[nxos\_l2\_interfacesの文書](https://docs.ansible.com/projects/ansible/latest/collections/cisco/nxos/nxos%5Fl2%5Finterfaces%5Fmodule.html)のパラメータ名に沿った形です。 ``` --- - name: NexusにVLANを追加してトランクへ通す hosts: nxos gather_facts: false tasks: - name: VLAN 110と120を作成 cisco.nxos.nxos_vlans: config: - vlan_id: 110 name: SALES - vlan_id: 120 name: GUEST state: merged - name: Ethernet1/49のトランク設定 cisco.nxos.nxos_l2_interfaces: config: - name: Ethernet1/49 mode: trunk trunk: native_vlan: 1 allowed_vlans: 1,110,120 state: merged ``` 文書は`allowed_vlans`を「トランクに設定されるVLANはこれだけになる」一覧と説明しています。今通しているVLANを書き漏らすと、そのVLANの通信が止まります。流す前に`state: gathered`で現在の許可VLANを取得し、書き足す形で一覧を作ってください。 ### nxos\_rollbackのチェックポイントで変更前に戻せるようにする NX-OSには設定のチェックポイント機能があり、Ansibleからは[nxos\_rollback](https://docs.ansible.com/projects/ansible/latest/collections/cisco/nxos/nxos%5Frollback%5Fmodule.html)で扱えます。`checkpoint_file`で保存し、`rollback_to`で戻すという2つの引数だけのモジュールです。 ``` - name: 変更前にチェックポイントを作る cisco.nxos.nxos_rollback: checkpoint_file: before_vlan_change.cfg # ここに変更タスクを置く # 切り戻しが必要になったら別Playbookで実行する - name: チェックポイントの状態へ戻す cisco.nxos.nxos_rollback: rollback_to: before_vlan_change.cfg ``` 文書の注意書きには、NX-API経由だとタイムアウトする場合があると書かれています。切り戻しは急ぐ場面で使うものなので、ロールバック用のPlaybookだけはnetwork\_cli接続で流せるよう、インベントリを分けておくと安心です。 ## ACIをcisco.aciで操作しテナント・BD・EPGをまとめて作成する手順 ACIでは、テナント、VRF、ブリッジドメイン（BD）、アプリケーションプロファイル（AP）、EPGという論理オブジェクトをAPICに作っていきます。cisco.aciのモジュールはこのオブジェクト単位で分かれています。 ### APICへの接続はhttpapiプラグインで認証情報をインベントリにまとめる [aci\_tenantの文書](https://docs.ansible.com/projects/ansible/latest/collections/cisco/aci/aci%5Ftenant%5Fmodule.html)の例は、タスクごとに`host`・`username`・`password`を書き、`delegate_to: localhost`で実行する形です。この書き方はタスクの数だけAPICへログインし直します。リポジトリの[Optimizing Playbooks](https://github.com/CiscoDevNet/ansible-aci/blob/develop/docs/optimizing.md)は、httpapiプラグインを使えばログインが1回で済み、トークンが切れても自動で再ログインすると説明しています。 ``` # inventory.ini [aci] apic_cluster ansible_host=apic1.example.jp,apic2.example.jp,apic3.example.jp [aci:vars] ansible_connection=ansible.netcommon.httpapi ansible_network_os=cisco.aci.aci ansible_user=ansible ansible_password="{{ vault_apic_password }}" ``` `ansible_host`にAPICをカンマ区切りで並べると、先頭から順に試し、1台が落ちていても次のAPICで実行を続けます。証明書の検証を外す`validate_certs: false`は、文書が自己署名証明書を使う自前の環境に限るとしているので、本番ではAPICに正規の証明書を入れてください。 ### テナントからEPGまで依存順に作るPlaybookとstate: queryでの確認 [aci\_epgの文書](https://docs.ansible.com/projects/ansible/latest/collections/cisco/aci/aci%5Fepg%5Fmodule.html)は、使うテナントとAPが先に存在している必要があると注意しています。上位のオブジェクトから順にタスクを並べます。 ``` --- - name: ACIに業務用のテナントを作る hosts: aci gather_facts: false vars: tenant: sales tasks: - cisco.aci.aci_tenant: tenant: "{{ tenant }}" state: present - cisco.aci.aci_vrf: tenant: "{{ tenant }}" vrf: sales_vrf state: present - cisco.aci.aci_bd: tenant: "{{ tenant }}" bd: web_bd vrf: sales_vrf state: present - cisco.aci.aci_ap: tenant: "{{ tenant }}" ap: web_app state: present - cisco.aci.aci_epg: tenant: "{{ tenant }}" ap: web_app epg: web_epg bd: web_bd state: present ``` 作成後の確認は`state: query`です。`tenant`を指定すれば1件、省けば全テナントを返します。削除は`state: absent`ですが、テナントを消すと配下のBDやEPGもまとめて消えるため、テナント単位のabsentはPlaybookに常駐させないでください。[aci\_bdの文書](https://docs.ansible.com/projects/ansible/latest/collections/cisco/aci/aci%5Fbd%5Fmodule.html)にあるとおり、各モジュールは既定で作業の前後にGETを送って状態を確かめます。 ## Cisco向けPlaybookの落とし穴とcisco.nxos 13.0.0の変更点 ここからは、文書や変更履歴に書かれているのに見落とされやすい挙動を3つ挙げます。どれもエラーにはならず、気付かないまま本番に流れる種類のものです。 ### 13.0.0未満のnxos\_l2\_interfaces：mergedと既定トランクの問題 [cisco.nxosの変更履歴](https://github.com/ansible-collections/cisco.nxos/blob/main/CHANGELOG.rst)の13.0.0には、許可VLANが既定（1〜4094）のままのトランクに対して`state: merged`で絞り込みをかけると、何も投入されなかった不具合の修正が載っています。既定の全範囲に「追加」する処理になっていたため、結果として無動作になっていました。13.0.0からは一覧で置き換える動きに変わっています。 この不具合はエラーを出しません。Playbookは成功し、トランクは全VLANを通したままです。12系以前を使っている環境では、該当タスクの`result.commands`が空になっていないかを確かめ、コレクションを上げてから流し直してください。同じ13.0.0では`nxos_route_maps`の`match.metric`の書式が変わる互換性のない変更も入っているので、ルートマップを書いているPlaybookは更新前に直します。 ### accessモードは毎回changedになり冪等性が保たれない nxos\_l2\_interfacesの文書は、accessモードは機器から取得した情報に表れないため、`mode: access`を指定すると毎回changedになると明記しています。同じPlaybookを2回流して2回目にchangedが出ないことを確かめる運用をしていると、ここで必ず引っかかります。 NX-OSではswitchportにしたポートの既定のモードがaccessなので、アクセスポートでは`mode`を書かずに`access.vlan`だけを指定する書き方で回避できます。チェックモードでの差分確認に頼っているチームは、この1項目だけ例外として扱う決めごとを作ってください。冪等性そのものの考え方は[冪等性とは](https://www.issoh.co.jp/tech/details/13382/)で扱っています。 ### nxos\_vlansのoverriddenはVLAN 1まで含めて全VLANを書き換える [nxos\_vlansの文書](https://docs.ansible.com/projects/ansible/latest/collections/cisco/nxos/nxos%5Fvlans%5Fmodule.html)は、overriddenがVLAN 1を含む機器上の全VLANを、タスクに書いた内容で上書きすると注意しています。文書の実行例では、タスクに書かれていなかったVLAN 3が消えています。 VLANの一覧を台帳から生成して全量を管理する場合でも、最初はmergedで足りないVLANを足す運用から始め、overriddenは`state: gathered`で取得した全量と台帳の差分がゼロになってから使います。ACIのBDやEPGに相当する論理設定をNexus単体で持っている構成ほど、VLANを1つ消したときの影響範囲は広くなります。 ## Cisco機器の設定変更をAnsibleで自動化する条件と見送る場面 判断の軸は、同じ変更を何台に流すかと、Playbookをレビューする人がいるかの2つです。 ### Ansibleで進める条件：同じ変更を多数の機器へ流しGitで審査できる 拠点ごとのアクセススイッチに同じVLANを足す、Nexusのペアに同じトランク設定を入れる、ACIでテナントを顧客や部署ごとに量産するといった作業は、Ansibleに向いています。台数が多いほど手入力の打ち間違いが減り、Playbookがそのまま作業記録になります。PlaybookとインベントリをGitで管理し、変更をプルリクエストで2人以上が確認できる体制があることを条件にしてください。 実行を画面から行いたい、誰がいつ流したかを監査に残したい場合は、[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/)で整理しています。 ### Ansibleを使わず手作業や別の管理方法を残す機器規模と運用条件 Nexusが2台で変更が年に数回なら、Playbookを書いて保守する手間のほうが大きくなります。この規模ではバックアップの取得だけを自動化し、変更は手順書で行うほうが現実的です。また、ACIのファブリックでリーフにSSHで入り、`cisco.nxos`で設定を流す運用は避けます。APIC側の設定と食い違い、どちらが正しいのかを誰も説明できなくなるからです。 ネットワーク機器とサーバーの構成管理をCI/CDのパイプラインに組み込み、Playbookのレビューから実行までを回す仕組みを整えたい場合は、[DevOps・CI/CD導入支援](https://www.issoh.co.jp/service/system/devops/)でご相談を承っています。 ## よくある質問 CiscoとAnsibleの組み合わせについて、検索されることの多い質問に答えます。 ### ansibleパッケージを入れればcisco.iosやcisco.nxosも使えますか？ 利用可能です。pipの`ansible`パッケージにはCiscoのコレクションも同梱されています。ただし同梱されるのはそのパッケージの公開時点の版で、Galaxyの最新版より古い場合がある点には注意が必要です。cisco.nxos 13.0.0の不具合修正のように新しい版が必要なときは、`ansible-core`に必要なコレクションだけを`ansible-galaxy`で入れるほうが版を管理しやすくなります。 ### ACIはTerraformとAnsibleのどちらで管理すべきですか？ APICの論理設定を全量で宣言し、差分を計画として確認してから適用したいならTerraform、既存の運用手順を順番どおりに自動化したいならAnsibleが合います。どちらもAPICのREST APIを使う点は同じです。両方で同じテナントを触ると管理が二重になるため、テナント単位でどちらが持つかを決めます。ツールの比較は[構成管理ツールの比較と選び方](https://www.issoh.co.jp/column/details/15293/)を参照してください。 ### Ansibleで使えるCiscoのモジュール一覧はどこで確認できますか？ docs.ansible.comのコレクション索引に、コレクションごとのモジュール一覧があります。たとえば[cisco.aciの索引](https://docs.ansible.com/projects/ansible/latest/collections/cisco/aci/index.html)には、テナントやEPGから契約、L3Outまで細かく分かれたモジュールが並びます。手元の版と一致させたいときは、`ansible-doc -l cisco.nxos`のように制御ノード上で一覧を出してください。 ### Nexusで設定変更の前に差分だけを確認する方法はありますか？ リソースモジュールなら`state: rendered`で投入予定のコマンドを確認できます。こちらは機器に接続しません。現在の設定と比べた差分まで見たいときは、`ansible-playbook`に`--check --diff`を付けて実行します。ただし前述のとおり`mode: access`を含むタスクは毎回差分ありと表示されるので、その行は読み飛ばす前提で確認します。 ### Catalyst CenterやNexus Dashboardがある環境でもAnsibleは必要ですか？ 管理ツールが機器の設定を持っている範囲では、その管理ツールのAPIを操作するのが原則です。Ansibleを使うなら、機器へ直接入るのではなく管理ツール側に向けたコレクションやREST APIの呼び出しに切り替えます。管理ツールの対象外の機器や、テンプレート化しにくい個別設定だけをAnsibleで扱う線引きにすると、二重管理を避けられます。 ## 関連記事 - [Ansibleネットワーク自動化の始め方：network\_cliで設定変更とバックアップを自動化する手順【2.21系】](https://www.issoh.co.jp/tech/details/18463/)：Cisco機器に接続するインベントリとバックアップの基本。 - [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 Towerとは：automation controllerへの改称とSurvey・Webhook・RBACの設定手順【AAP 2.7】](https://www.issoh.co.jp/tech/details/18459/)：ネットワーク変更の実行を承認付きで管理する方法。 - [Ansibleによる運用自動化の進め方：対象作業の選び方と費用対効果・失敗パターン](https://www.issoh.co.jp/column/details/18092/)：どの作業から自動化するかの判断。 --- 出典: [Cisco機器をAnsibleで設定変更する手順：cisco.ios・cisco.nxos・cisco.aciのPlaybook例【2026年10月】]()（株式会社一創）