自動化

Cisco機器をAnsibleで設定変更する手順：cisco.ios・cisco.nxos・cisco.aciのPlaybook例【2026年10月】

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ネットワーク自動化の始め方で解説しています。ここでは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とはを参照してください。

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のリポジトリはansible-core 2.16.0以上での検証を明記しており、cisco.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の書き方と実行手順にまとめています。

ios_vlansでVLANを追加しrenderedで投入コマンドを確かめる

ios_vlansの文書は、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の文書にある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のプラットフォームガイドによると、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の文書のパラメータ名に沿った形です。

---
- 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で扱えます。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の文書の例は、タスクごとにhost・username・passwordを書き、delegate_to: localhostで実行する形です。この書き方はタスクの数だけAPICへログインし直します。リポジトリのOptimizing Playbooksは、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の文書は、使うテナントと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の文書にあるとおり、各モジュールは既定で作業の前後にGETを送って状態を確かめます。

Cisco向けPlaybookの落とし穴とcisco.nxos 13.0.0の変更点

ここからは、文書や変更履歴に書かれているのに見落とされやすい挙動を3つ挙げます。どれもエラーにはならず、気付かないまま本番に流れる種類のものです。

13.0.0未満のnxos_l2_interfaces：mergedと既定トランクの問題

cisco.nxosの変更履歴の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項目だけ例外として扱う決めごとを作ってください。冪等性そのものの考え方は冪等性とはで扱っています。

nxos_vlansのoverriddenはVLAN 1まで含めて全VLANを書き換える

nxos_vlansの文書は、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の機能と設定手順やAWXをKubernetesへ導入する手順を検討します。どの運用作業から手を付けるかはAnsibleによる運用自動化の進め方で整理しています。

Ansibleを使わず手作業や別の管理方法を残す機器規模と運用条件

Nexusが2台で変更が年に数回なら、Playbookを書いて保守する手間のほうが大きくなります。この規模ではバックアップの取得だけを自動化し、変更は手順書で行うほうが現実的です。また、ACIのファブリックでリーフにSSHで入り、cisco.nxosで設定を流す運用は避けます。APIC側の設定と食い違い、どちらが正しいのかを誰も説明できなくなるからです。

ネットワーク機器とサーバーの構成管理をCI/CDのパイプラインに組み込み、Playbookのレビューから実行までを回す仕組みを整えたい場合は、DevOps・CI/CD導入支援でご相談を承っています。

よくある質問

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を使う点は同じです。両方で同じテナントを触ると管理が二重になるため、テナント単位でどちらが持つかを決めます。ツールの比較は構成管理ツールの比較と選び方を参照してください。

Ansibleで使えるCiscoのモジュール一覧はどこで確認できますか？

docs.ansible.comのコレクション索引に、コレクションごとのモジュール一覧があります。たとえばcisco.aciの索引には、テナントや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で扱う線引きにすると、二重管理を避けられます。

関連記事

お気に入りに入れた記事の一覧

この記事は以下の記事からリンクされています

この記事に関連するサービス

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.10.16　テックブログ バーガーキング不正アクセスで約1,118万件の情報漏洩｜対象確認・案内メールの真偽と運営側のログ点検
  2. 2026.10.16　テックブログ ソースネクスト不正アクセスで最大2,252万件流出｜ログインできない理由・パスワード再設定と会員APIの点検
  3. 2026.10.15　テックブログ リゾートトラスト不正アクセス：会員2.6万件・カハラ横浜3.6万件の対象確認と窓口
  4. 2026.10.15　テックブログ 銀のさら不正アクセス：最大650万件の対象確認と窓口、パスワード変更の手順
  5. 2026.10.16　テックブログ ワラウ不正アクセスで連携トークン流出｜Yahoo! JAPAN ID再連携と対象確認

RELATED POSTS 関連記事

一覧へ戻る

目次