Tóm tắt: Thay đổi nhỏ theo dòng lệnh → cisco.iosxr.iosxr_config (lines + parents, hoặc src từ template). Thay đổi có cấu trúc (interface, BGP, static route, ACL) → resource module như cisco.iosxr.iosxr_interfaces với state: merged/replaced/overridden. Luôn chạy --check trên 1 host trước, bật backup: true, và gắn comment cho commit. Inventory và kết nối network_cli xem ở Thu thập inventory IOS XR bằng Ansible.
Luồng hoạt động
flowchart LR A["playbook + template"] --> B["ansible-playbook --check"] B -->|"xem commands"| C{"Đúng ý?"} C -->|Không| A C -->|Có| D["chạy thật, backup: true"] D -->|"network_cli"| E[("Router IOS XR")] E -->|"commit + comment"| F["show configuration commit list"]
Cấu hình
Chọn module
| Trường hợp | Module | Ghi chú |
|---|---|---|
| Vài dòng lệnh, cần đúng vị trí trong cây config | cisco.iosxr.iosxr_config + lines/parents |
So với running-config, chỉ gửi dòng còn thiếu |
| Cả khối config từ Jinja2 | cisco.iosxr.iosxr_config + src |
src nhận file template, render theo biến host |
| Interface (description, mtu, enabled) | cisco.iosxr.iosxr_interfaces |
Resource module, idempotent |
| IP trên interface | cisco.iosxr.iosxr_l3_interfaces |
|
| BGP process / neighbor | cisco.iosxr.iosxr_bgp_global, cisco.iosxr.iosxr_bgp_neighbor_address_family |
|
| Static route, ACL | cisco.iosxr.iosxr_static_routes, cisco.iosxr.iosxr_acls |
|
| Chỉ chạy lệnh show / exec | cisco.iosxr.iosxr_command |
Không dùng để cấu hình |
iosxr_config theo dòng lệnh
- name: Cập nhật description uplink
hosts: iosxr
gather_facts: false
tasks:
- name: Đặt description và MTU
cisco.iosxr.iosxr_config:
parents: interface GigabitEthernet0/0/0/1
lines:
- description to-pe2-hcm
- mtu 9192
comment: "CHG-1234 uplink description"
backup: true
backup_options:
dir_path: backup/
filename: "{{ inventory_hostname }}.cfg"
register: result
- name: In lệnh đã (hoặc sẽ) gửi
ansible.builtin.debug:
var: result.commandsTham số hay dùng của iosxr_config:
| Tham số | Ý nghĩa |
|---|---|
lines / parents |
Dòng lệnh và đường dẫn cha trong cây config (ví dụ router bgp 65001 → neighbor 192.0.2.2) |
src |
File config hoặc template Jinja2, loại trừ với lines |
match |
line (mặc định), strict, exact, none (luôn gửi) |
replace |
line (mặc định), block (gửi lại cả khối nếu khác), config (thay toàn bộ, dùng với src) |
before / after |
Lệnh gửi trước/sau lines, chỉ khi có thay đổi |
comment / label |
Ghi vào commit, xem lại bằng show configuration commit list detail |
exclusive |
Vào configure exclusive, khoá config khỏi session khác |
backup + backup_options |
Lưu running-config trước khi đổi |
iosxr_config từ template
router bgp {{ bgp_asn }}
neighbor {{ peer_ip }}
remote-as {{ peer_asn }}
description {{ peer_desc }}
address-family ipv4 unicast
route-policy {{ rpl_in }} in
route-policy {{ rpl_out }} out- name: Thêm BGP neighbor từ template
cisco.iosxr.iosxr_config:
src: templates/bgp_neighbor.j2
comment: "CHG-1235 new peer {{ peer_ip }}"IOS XR không cho neighbor eBGP nhận/gửi route nếu chưa gắn route-policy in/out. Đảm bảo RPL đã tồn tại trước, nếu không commit sẽ báo lỗi.
Resource module
- name: Interface theo kiểu khai báo
hosts: iosxr
gather_facts: false
tasks:
- name: Description + MTU + bật interface
cisco.iosxr.iosxr_interfaces:
config:
- name: GigabitEthernet0/0/0/1
description: to-pe2-hcm
mtu: 9192
enabled: true
state: merged
- name: Gán IPv4
cisco.iosxr.iosxr_l3_interfaces:
config:
- name: GigabitEthernet0/0/0/1
ipv4:
- address: 192.0.2.0/31
state: mergedstate |
Hành vi |
|---|---|
merged |
Thêm/sửa thuộc tính khai báo, giữ phần khác |
replaced |
Thay toàn bộ thuộc tính của các mục được khai báo |
overridden |
Thay toàn bộ cấu hình loại đó trên thiết bị (mục không khai báo bị xoá) |
deleted |
Xoá cấu hình của mục khai báo (để trống config = xoá hết) |
gathered |
Đọc config hiện tại ra dạng structured (kết quả ở key gathered) |
rendered |
Sinh lệnh CLI offline, không cần kết nối (kết quả ở key rendered) |
parsed |
Parse text config có sẵn (running_config) ra structured |
state: overridden với iosxr_interfaces hay iosxr_l3_interfaces sẽ dọn mọi interface không có trong config, kể cả interface management. Chỉ dùng khi biến chứa đầy đủ toàn bộ interface.
Chạy
# 1. Chạy thử trên 1 host, xem lệnh sẽ gửi
ansible-playbook -i inventory/hosts.yml push_description.yml --check -l pe1-hni -v
# 2. Chạy thật, giới hạn số router cùng lúc
ansible-playbook -i inventory/hosts.yml push_description.yml -f 5
# 3. Kiểm tra trên router
# show configuration commit list detail
# show configuration commit changes last 1Muốn rollback, đăng nhập router và dùng rollback configuration last 1 (xem IOS XR CLI cheatsheet).
Lỗi thường gặp
| Triệu chứng | Nguyên nhân | Cách xử lý |
|---|---|---|
Lần nào chạy cũng changed |
Dòng trong lines khác cách IOS XR hiển thị (viết tắt, thừa khoảng trắng, IP/mask khác format) |
Viết đúng như show running-config hiển thị, kể cả thụt lề và dạng address 192.0.2.0/31 vs 192.0.2.0 255.255.255.254 |
% Failed to commit one or more configuration items |
Lệnh hợp lệ cú pháp nhưng bị từ chối khi commit (thiếu RPL, trùng IP...) | Trên router: show configuration failed |
| Commit treo / báo đang có session khác | Có người đang giữ configure exclusive |
show configuration sessions, chờ hoặc clear configuration sessions <id> |
| Resource module bỏ qua thuộc tính | Thuộc tính không có trong argspec của collection đang cài | Nâng cisco.iosxr, xem lại tài liệu module đúng phiên bản |
--check vẫn báo changed nhưng không gửi gì |
Đúng hành vi: check mode chỉ tính commands |
Xem result.commands, không dùng changed làm bằng chứng |
| Backup không thấy file | backup_options.dir_path tương đối theo thư mục playbook |
Dùng đường dẫn tuyệt đối hoặc kiểm tra thư mục backup/ cạnh playbook |
Lỗi kết nối, timeout, unable to open shell xem Ansible network troubleshooting.