medusa/the_information_nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update tech_docs/networking/iac_github_project.md

Browse Source
This commit is contained in:
medusa
2025-08-02 14:42:04 -05:00
parent f2fbe07dd7
commit 1b4ff4d36b
1 changed files with 628 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

628
tech_docs/networking/iac_github_project.md
View File

@@ -1,6 +1,634 @@
Below is a vendor-agnostic, scalable-template review written in “meta-config” form. Below is a vendor-agnostic, scalable-template review written in “meta-config” form.
It is intentionally abstract (no literal values, no vendor CLI) so it can be mechanically translated to any NOS or rendered by an automation pipeline. It is intentionally abstract (no literal values, no vendor CLI) so it can be mechanically translated to any NOS or rendered by an automation pipeline.
--------------------------------------------------------
1. Meta-Template Structure
--------------------------------------------------------
┌─ object: device
│ ├─ role: head-end-dmvpn-hub
│ ├─ platform: <vendor-agnostic>
│ └─ lifecycle: golden-template → instance-template → device-config
└─
Each stanza below is a YAML-ish block that can be turned into:
- Jinja2 / Ansible variables
- Terraform schema
- OpenConfig YANG
- TTP/TTK parser
--------------------------------------------------------
2. Inventory & Naming
--------------------------------------------------------
inventory:
site_id: "{{ site_id }}" # AAA-BBB-CCC-NNN
function: headend
routing_domain: "{{ rd_index }}"
hostname_pattern: "{{ site_id }}-{{ function }}-{{ sequence }}"
--------------------------------------------------------
3. OS / Image Management
--------------------------------------------------------
image:
golden_version: "{{ lookup('golden_db', platform) }}"
fallback_version: "{{ golden_version | fallback }}"
boot_order: [primary, secondary, usb]
--------------------------------------------------------
4. Global Service Knobs
--------------------------------------------------------
global:
service:
tcp_keepalives: { in: true, out: true }
timestamps: { debug: msec, log: msec, tz: local }
password_encryption: true
sequence_numbers: true
counters_max_age: 10
dhcp: false
pad: false
--------------------------------------------------------
5. Security Baseline
--------------------------------------------------------
security:
auth_failure_rate: 3
password_policy:
min_length: 8
complexity: high
aaa:
method_order: [tacacs, local]
accounting: start-stop
sources:
- { ip: "{{ tacacs_vip }}", vrf: mgmt }
secrets:
enable: "{{ vault.encrypted(enable_secret) }}"
snmp:
version: 3
auth: sha
priv: aes-128
acl: "{{ snmp_acl }}"
--------------------------------------------------------
6. VRF & Loopback Plan
--------------------------------------------------------
vrfs:
- name: mgmt
rd: "{{ site_id }}:1"
interfaces: [MgmtEth0/0/0]
- name: dmvpn
rd: "{{ site_id }}:2"
interfaces: [Loopback-DMVPN, Tunnel-*]
loopbacks:
- name: system
vrf: default
mask: /32
- name: tunnel_source
vrf: dmvpn
mask: /32
--------------------------------------------------------
7. Underlay Interfaces
--------------------------------------------------------
underlay:
uplinks:
- id: 1
type: p2p
media: ethernet
mtu: 9216
vrf: default
ospf: { area: 0, auth: md5, hello: 1, dead: 4 }
- id: 2
type: p2p
media: ethernet
mtu: 9216
vrf: dmvpn
ospf: { area: 0, auth: md5, hello: 1, dead: 4 }
--------------------------------------------------------
8. Overlay (DMVPN) Definition
--------------------------------------------------------
overlay:
type: dmvpn-hub
tunnel_ifs:
- id: 1
src_loopback: tunnel_source
vrf: dmvpn
mtu: 1400
tcp_mss: 1360
nhrp:
auth: "{{ nhrp_key }}"
net_id: "{{ site_id }}"
holdtime: 600
shortcut: true
redirect: true
ipsec:
profile: dmvpn_profile
transform: { enc: aes256-gcm, pfs: group20 }
bgp_listen_range: "{{ tunnel_net }}"
bgp_peer_group:
name: spokes
asn: "{{ bgp_asn }}"
rr_client: true
next_hop_self: true
send_default: true
max_peers: "{{ spoke_limit }}"
--------------------------------------------------------
9. QoS Framework
--------------------------------------------------------
qos:
classifier:
- { name: voice, dscp: ef }
- { name: interactive_vid, dscp: [af41,af42,af43] }
- { name: critical_data, dscp: [af31,af32,af33] }
- { name: business_data, dscp: [af21,af22,af23] }
- { name: bulk_data, dscp: [af11,af12,af13] }
- { name: scavenger, dscp: cs1 }
- { name: net_mgmt, dscp: cs2 }
shaper:
- parent: physical
cir: "{{ circuit_bw }}"
child_policy: per_class
per_class:
voice: { priority_pct: 30 }
interactive_vid: { bw_pct: 15, wred: true }
critical_data: { bw_pct: 20, wred: true }
business_data: { bw_pct: 25, wred: true }
bulk_data: { bw_pct: 10, wred: true }
scavenger: { bw_pct: 5, wred: true }
class_default: { bw_pct: 20, fair_queue: true }
--------------------------------------------------------
10. NetFlow / Telemetry
--------------------------------------------------------
telemetry:
exporter:
- { dst: "{{ collector_vip }}", vrf: mgmt, dscp: af21, proto: udp/9996 }
cache:
active_timeout: 60
inactive_timeout: 15
fields:
- { match: [ipv4_src, ipv4_dst, tos, proto, port_src, port_dst, direction] }
- { collect: [bytes, pkts, first_seen, last_seen, next_hop] }
--------------------------------------------------------
11. Routing Policy
--------------------------------------------------------
policy:
ospf:
areas:
0: { auth: md5, type: p2p_only }
default_originate: true
bgp:
local_as: "{{ bgp_asn }}"
communities:
- { name: blackhole, pattern: "65400:666" }
- { name: transit_nyc, pattern: "65400:1111" }
- { name: transit_clt, pattern: "65400:2222" }
- { name: transit_brm, pattern: "65400:3333" }
route_maps:
- { name: deny_default, seq: 10, action: deny, match: prefix=0.0.0.0/0 }
- { name: spokes_in, seq: 20, action: permit }
- { name: spokes_out, seq: 10, action: permit, set: [community=local_site] }
--------------------------------------------------------
12. Monitoring & SLA
--------------------------------------------------------
sla:
icmp_probes:
- { target: "{{ anycast_gw }}", src: tunnel_1, freq: 180, owner: dmvpn }
logging:
hosts:
- { ip: "{{ loghost1 }}", vrf: mgmt, facility: local1 }
- { ip: "{{ loghost2 }}", vrf: mgmt, facility: local1 }
levels:
- { trap: informational, origin_id: loopback }
--------------------------------------------------------
13. Hardening & ACLs
--------------------------------------------------------
acl:
mgmt_plane:
- { src: "{{ mgmt_net }}", dst: device, proto: ssh }
- { src: "{{ mgmt_net }}", dst: device, proto: snmp }
control_plane:
- { src: "{{ spoke_net }}", dst: device, proto: ipsec }
- { src: "{{ spoke_net }}", dst: device, proto: nhrp }
data_plane:
- { name: undesirable_udp, action: drop, rate: 8kbps }
--------------------------------------------------------
14. Automation Hooks
--------------------------------------------------------
automation:
pre_checks:
- validate_image_md5
- validate_crypto_modulus
post_checks:
- bgp_established
- ipsec_sa_count
- sla_probe_up
drift_detection:
- periodic: "{{ 24h }}"
- source_of_truth: git
- remediation: on_change
--------------------------------------------------------
15. Extensibility Notes
--------------------------------------------------------
- All IP literals live in inventory or vault; template never embeds them.
- All BGP communities, NHRP keys, SNMP strings are vaulted and templated.
- QoS class names & DSCP values are constants; per-link CIR is dynamic.
- The entire config is rendered in three artifacts:
1. golden-template.yaml (this document)
2. per-site variables (YAML or JSON)
3. vendor renderer (Jinja2, YDK, NAPALM, etc.)
This single source-of-truth can therefore drive Cisco IOS-XE, Juniper vSRX, Aruba CX, OpenBSD, or a virtual container image without further human touch.
---
Yes—​the structure you showed is **exactly** the next logical layer under the vendor-agnostic “meta-template” I sketched.
Think of the meta-template as the **contract** (what must exist, how it behaves), and your `config_components/` tree as the **concrete implementation** that an automation engine (Ansible, Salt, Nornir, etc.) consumes to stamp out per-device artifacts.
Below is a mapping that keeps the two layers coherent and keeps every artifact reusable across chassis types or vendors.
--------------------------------------------------------
1. Directory ↔ Meta-Template Mapping
--------------------------------------------------------
config_components/
├── core_settings/
│ ├── 00_licensing.j2 ← global.image (golden version, feature licences)
│ ├── 10_system_settings.j2 ← global.service knobs, hostname, NTP, banner
│ └── 20_aaa.j2 ← security.aaa, tacacs sources, local users
├── network_services/
│ ├── 30_vlans.j2 ← vrfs.* (L3 VNIs) + any underlay VLANs
│ └── 40_routing.j2 ← policy.ospf, policy.bgp, route-maps, NHRP
├── interfaces/
│ ├── 50_port_profiles/
│ │ ├── access_port.j2 ← not used on a DMVPN hub, but kept for reuse
│ │ └── trunk_port.j2 ← likewise reusable
│ └── 60_interface_assignments.j2
│ ← underlay.*, overlay.tunnel_ifs, QoS service-policy attachment
├── policies/
│ ├── 70_qos.j2 ← qos.classifier + qos.shaper + qos.per_class
│ └── 80_access_lists.j2 ← acl.mgmt_plane + acl.control_plane + ACL fragments
└── data/
├── site-01.yml ← inventory + per-site variable overlay
└── site-02.yml
--------------------------------------------------------
2. Data-file Inheritance Model
--------------------------------------------------------
data/site-XX.yml
├── inherits: "dmvpn_hub.yml" # shared across all hubs
├── overlays:
│ ├── hostname: "{{ site_id }}-hub-01"
│ ├── tunnel_net: "10.130.108.0/25"
│ ├── circuit_bw: "1 Gbps"
│ └── bgp_asn: 65400
└── secrets: "@vault/dmvpn/{{ site_id }}"
The meta-template (YAML in my previous reply) becomes the **schema** that every data file must satisfy; the J2 files become the **renderer**.
--------------------------------------------------------
3. Rendering Flow
--------------------------------------------------------
1. Inventory script loads `data/site-01.yml`
2. Validates against meta-template schema (pydantic, jsonschema, or yamale)
3. Renders each `.j2` file in numerical order into a single running-config stanza
4. Post-render hooks (linting, drift check, push via Nornir/Napalm)
--------------------------------------------------------
4. Vendor-Neutral Abstraction Tips
--------------------------------------------------------
- Keep **no literals** inside `.j2`; every value is `{{ var }}` or `{{ var | default }}`.
- Use **macro includes** for multi-vendor syntax:
`{% import 'vendor/ios.j2' as syntax %}` vs `{% import 'vendor/junos.j2' %}`
- Store **feature flags** in the data file so the same J2 can be skipped on platforms that lack a capability (e.g., crypto-isakmp on Cisco, security-ike on JunOS).
- If a component is unused (e.g., access_port.j2 on an ASR), the data file simply omits that key and the macro renders nothing.
--------------------------------------------------------
5. Quick Starter Skeleton
--------------------------------------------------------
config_components/
├── _macros/
│ ├── vendor/
│ │ ├── ios.j2
│ │ └── junos.j2
├── core_settings/
│ └── … (as above)
├── network_services/
│ └── …
└── data/
├── dmvpn_hub.yml ← shared variables & schema
├── site-01.yml ← per-site override
└── site-02.yml
With this, the **meta-template** remains the single source of truth, your **config_components/** tree remains tidy, and any future chassis or vendor swap is a one-line change in the renderer macro—not a rewrite of the logic.
---
Below is the **vendor-agnostic YAML fragment** that maps every CLI-level knob you listed to a single, automation-friendly variable path.
No literals, no vendor syntax—just the contract the Jinja2 (or any renderer) will later expand into IOS, JunOS, EOS, etc.
```yaml
global_system:
hostname: "{{ inventory_hostname }}"
boot:
image: "{{ golden_image | default('unset') }}"
config_register: "{{ config_register | default('0x2102') }}"
secrets:
enable: "{{ vault.encrypted(enable_secret) }}"
clock:
timezone: "{{ tz_name | default('UTC') }}"
offset: "{{ tz_offset | default(0) }}"
summer_time:
rules: "{{ summer_rules | default('none') }}" # e.g., 'usa', 'eu', 'recurring'
domain:
name: "{{ dns_domain }}"
name_servers: "{{ dns_servers | default([]) }}"
logging:
buffered:
size: "{{ log_buffer_bytes | default(1048576) }}"
console: "{{ log_console | default(false) }}"
monitor: "{{ log_monitor | default('informational') }}"
hosts:
- { ip: "{{ log_host_1 }}", vrf: "{{ log_vrf | default('mgmt') }}",
proto: "{{ log_proto | default('udp') }}", port: "{{ log_port | default(514) }}" }
- { ip: "{{ log_host_2 }}", vrf: "{{ log_vrf | default('mgmt') }}",
proto: "{{ log_proto | default('udp') }}", port: "{{ log_port | default(514) }}" }
```
Usage notes:
- `vault.encrypted(...)` is a Jinja2 filter that pulls the secret from the vault at render time.
- `inventory_hostname` is injected by Ansible/Nornir.
- The lists (`dns_servers`, `hosts`) are idempotent arrays—​renderers can loop (`{% for %}`) to generate one CLI stanza per element.
---
Below is a **deployment-ready YAML scaffold** that expands every knob in your latest checklist into **parameter-only** form—​no literals, no CLI, just the variables an automation engine will resolve at render time.
Copy this into `data/<site>.yml`, fill in the blanks, and feed it to the Jinja2 fragments you already keep in `config_components/`.
```yaml
###############################################################################
# AAA
###############################################################################
aaa:
new_model: true
tacacs:
servers:
- { ip: "{{ tacacs1 }}", vrf: "{{ mgmt_vrf }}", key: "{{ vault.tacacs_key }}" }
- { ip: "{{ tacacs2 }}", vrf: "{{ mgmt_vrf }}", key: "{{ vault.tacacs_key }}" }
group_name: "{{ tacacs_group | default('GTAC') }}"
auth_login_default: "{{ aaa_login_method | default(['group tacacs', 'local']) }}"
auth_enable_default: "{{ aaa_enable_method | default(['group tacacs', 'enable']) }}"
auth_commands_15: "{{ aaa_cmd_method | default(['group tacacs', 'local']) }}"
accounting_commands_15:
type: "{{ acct_type | default('start-stop') }}"
group: "{{ acct_group | default('GTAC') }}"
local_users:
- { name: "{{ local_admin }}", priv: 15, secret: "{{ vault.local_secret }}" }
###############################################################################
# VRFs
###############################################################################
vrfs:
- name: "{{ mgmt_vrf }}"
rd: "{{ site_id }}:1"
af: [ipv4, ipv6]
- name: "{{ dmvpn_vrf }}"
rd: "{{ site_id }}:2"
af: [ipv4]
###############################################################################
# CRYPTO
###############################################################################
crypto:
keyring:
name: "{{ keyring_name }}"
vrf: "{{ dmvpn_vrf }}"
psk_list:
- { ip: "{{ spoke_range }}", key: "{{ vault.psk }}" }
isakmp:
policy:
id: "{{ isakmp_policy_id | default(10) }}"
encr: "{{ isakmp_encr | default('aes') }}"
auth: "{{ isakmp_auth | default('pre-share') }}"
group: "{{ isakmp_group | default('14') }}"
ipsec:
transform:
name: "{{ ipsec_transform }}"
esp: "{{ ipsec_esp | default('esp-aes 256 esp-sha-hmac') }}"
mode: "{{ ipsec_mode | default('transport') }}"
profile:
name: "{{ ipsec_profile }}"
pfs: "{{ ipsec_pfs | default(false) }}"
idle_time: "{{ ipsec_idle | default(60) }}"
###############################################################################
# DMVPN TUNNEL
###############################################################################
tunnel:
id: "{{ tunnel_id | default(1) }}"
ip: "{{ tunnel_ip }}"
mask: "{{ tunnel_mask }}"
source: "{{ tunnel_source_intf }}"
mode: "{{ tunnel_mode | default('gre multipoint') }}"
key: "{{ tunnel_key }}"
vrf: "{{ dmvpn_vrf }}"
ipsec_profile: "{{ ipsec_profile }}"
nhrp:
net_id: "{{ nhrp_net_id }}"
auth: "{{ nhrp_key }}"
server_only: true
shortcut: true
redirect: true
tcp_mss: "{{ tunnel_tcp_mss | default(1360) }}"
qos_pre_classify: true
output_policy: "{{ qos_policy_out | default('WAN_QOS_OUTBOUND') }}"
###############################################################################
# ROUTING – OSPF
###############################################################################
ospf:
- pid: "{{ ospf_pid_uplink | default(1) }}"
vrf: "{{ mgmt_vrf }}"
rid: "{{ loopback0_ip }}"
ref_bw: "{{ ospf_ref_bw | default(100000) }}"
passive_default: true
areas:
- id: "{{ ospf_area_uplink | default(0) }}"
auth: message-digest
networks:
- { prefix: "{{ uplink_net }}", mask: "{{ uplink_wildcard }}", passive: false }
- pid: "{{ ospf_pid_dmvpn | default(22) }}"
vrf: "{{ dmvpn_vrf }}"
rid: "{{ tunnel_rid }}"
areas:
- id: "{{ ospf_area_dmvpn | default(0) }}"
auth: message-digest
networks:
- { prefix: "{{ tunnel_net }}", mask: "{{ tunnel_wildcard }}", passive: false }
###############################################################################
# ROUTING – BGP
###############################################################################
bgp:
asn: "{{ bgp_asn }}"
rid: "{{ loopback0_ip }}"
log_changes: true
neighbors:
- { ip: "{{ ebgp_peer1 }}", remote_as: "{{ ebgp_as1 }}", desc: "To-VPN-Core-1",
ebgp_multihop: 2, update_source: "{{ loopback0_intf }}", pw: "{{ vault.bgp_pw }}" }
- { ip: "{{ ebgp_peer2 }}", remote_as: "{{ ebgp_as2 }}", desc: "To-VPN-Core-2",
ebgp_multihop: 2, update_source: "{{ loopback0_intf }}", pw: "{{ vault.bgp_pw }}" }
listen:
range: "{{ spoke_range }}"
peer_group: "{{ spoke_pg | default('REMOTE-OFFICE') }}"
limit: "{{ spoke_limit | default(300) }}"
af_ipv4:
networks:
- { prefix: "{{ local_summary_net }}", mask: "{{ local_summary_mask }}" }
peer_policies:
- group: "{{ spoke_pg }}"
activate: true
rr_client: true
next_hop_self_all: true
default_originate: true
soft_reconfig: true
route_map_in: "{{ rm_spoke_in }}"
route_map_out: "{{ rm_spoke_out }}"
###############################################################################
# QOS
###############################################################################
qos:
class_maps:
- name: VOICE
match: [dscp ef]
- name: INTERACTIVE_VIDEO
match: [dscp cs4, dscp af41-af43]
- name: CRITICAL_DATA
match: [dscp af31-af33]
- name: BUSINESS_DATA
match: [dscp af21-af23]
- name: BULK_DATA
match: [dscp af11-af13]
- name: SCAVENGER
match: [dscp cs1]
policy_maps:
- name: "{{ qos_policy_out }}"
classes:
- { name: VOICE, priority_pct: 30 }
- { name: INTERACTIVE_VIDEO, bw_remaining_pct: 15, wred: true }
- { name: CRITICAL_DATA, bw_remaining_pct: 20, wred: true }
- { name: BUSINESS_DATA, bw_remaining_pct: 25, wred: true }
- { name: BULK_DATA, bw_remaining_pct: 10, wred: true }
- { name: SCAVENGER, bw_remaining_pct: 5, wred: true }
- { name: class-default, bw_remaining_pct: 20, fair_queue: true }
###############################################################################
# ACL / PREFIX / COMMUNITY
###############################################################################
acls:
standard:
- name: "{{ snmp_acl }}"
rules:
- { action: permit, src: "{{ mgmt_net1 }}" }
- { action: permit, src: "{{ mgmt_net2 }}" }
extended:
- name: "{{ qos_acl_bulk }}"
rules: "{{ qos_rules_bulk | default([]) }}"
prefix_lists:
- name: DEFAULT
rules:
- { seq: 5, action: permit, prefix: 0.0.0.0/0 }
community_lists:
- name: BLACKHOLE
type: expanded
rules:
- { action: permit, regex: "_666$" }
###############################################################################
# SNMP
###############################################################################
snmp:
location: "{{ snmp_location }}"
contact: "{{ snmp_contact }}"
groups:
- { name: NOC_RO, version: 3, sec: authPriv, read_view: VIEW-STD }
users:
- { name: "{{ snmp_user }}", group: NOC_RO,
auth: sha, auth_pw: "{{ vault.snmp_auth }}",
priv: aes128, priv_pw: "{{ vault.snmp_priv }}" }
hosts:
- { ip: "{{ snmp_trap_host }}", vrf: "{{ mgmt_vrf }}",
version: 3, user: "{{ snmp_user }}" }
traps:
enable: "{{ snmp_traps | default(['snmp','bgp','ospf','link']) }}"
###############################################################################
# INTERFACES (underlay + mgmt)
###############################################################################
interfaces:
mgmt:
- name: "{{ mgmt_intf }}"
vrf: "{{ mgmt_vrf }}"
ip: "{{ mgmt_ip }}"
mask: "{{ mgmt_mask }}"
uplinks:
- name: "{{ uplink1_intf }}"
desc: "To Core-1"
ip: "{{ uplink1_ip }}"
mask: "{{ uplink1_mask }}"
ospf: { area: "{{ ospf_area_uplink }}", cost: 10 }
qos_out: "{{ qos_policy_out }}"
- name: "{{ uplink2_intf }}"
desc: "To Core-2"
ip: "{{ uplink2_ip }}"
mask: "{{ uplink2_mask }}"
ospf: { area: "{{ ospf_area_uplink }}", cost: 10 }
qos_out: "{{ qos_policy_out }}"
###############################################################################
# SLA
###############################################################################
sla:
probes:
- { type: icmp-echo, target: "{{ anycast_gw }}",
src: "{{ tunnel_intf }}", freq: 180, owner: DMVPN }
###############################################################################
# CONTROL-PLANE POLICING / MISC
###############################################################################
control_plane:
policy_in: "{{ cpp_policy | default('drop-udp') }}"
line:
con0:
exec_timeout: "{{ con_timeout | default('10 0') }}"
vty:
exec_timeout: "{{ vty_timeout | default('10 0') }}"
transport: "{{ vty_transport | default('ssh') }}"
acl_in: "{{ vty_acl | default('SECURE_ACCESS') }}"
```
Save this file as `data/<site>.yml`, merge it with the vault, and render.
The Jinja2 fragments in `config_components/` need only reference the keys above—​no further CLI details leak into the YAML.
---
Below is a vendor-agnostic, scalable-template review written in “meta-config” form.
It is intentionally abstract (no literal values, no vendor CLI) so it can be mechanically translated to any NOS or rendered by an automation pipeline.
-------------------------------------------------------- --------------------------------------------------------
1. Meta-Template Structure 1. Meta-Template Structure
-------------------------------------------------------- --------------------------------------------------------