WIP: Add networking-lab with devstack-nxsw-vxlan

Introduces a new networking-lab directory for network-focused scenarios
that don't require full OpenShift deployments. Includes first scenario:
devstack-nxsw-vxlan with spine-and-leaf topology featuring:

- 4 Cisco NX-OS switches (2 spine + 2 leaf) with OSPF underlay
- Devstack node with trunk port for VLAN-tagged traffic
- 2 Ironic baremetal nodes attached to leaf switches
- Individual POAP scripts and configs per switch
- VXLAN/EVPN ready configuration
- SVG topology diagram
- Automated POAP md5sum management script and pre-commit hook

Point-to-point links consolidated in 10.1.1.0/24 to preserve
10.1.2.0/24+ address space for future use.

Signed-off-by: Harald Jensås <hjensas@redhat.com>

Author: hjensas

.gitignore

@@ -1,3 +1,5 @@
 **/__pycache__/
 .ansible/*
 .venv/*
+*.gz.b64
+*.tar.gz

.pre-commit-config.yaml

@@ -57,6 +57,12 @@ repos:
       language: system
       files: ^scenarios/sno-nxsw/poap\.py$
       pass_filenames: false
+    - id: networking-lab-poap-md5sums
+      name: Format networking-lab POAP scripts with md5sum management
+      entry: scenarios/networking-lab/manage-poap-md5sums.sh
+      language: system
+      files: ^scenarios/networking-lab/.*-poap\.py$
+      pass_filenames: false
 
   - repo: https://github.com/ansible/ansible-lint
     rev: v6.22.2

03-install_devstack.yml

@@ -0,0 +1,41 @@
+---
+# Copyright Red Hat, Inc.
+# All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+- name: Setup Devstack Installation
+  hosts: localhost
+  gather_facts: true
+  strategy: linear
+  pre_tasks:
+    - name: Load stack output vars from file
+      ansible.builtin.include_vars:
+        file: "{{ hotstack_work_dir | default(playbook_dir) }}/{{ stack_name }}-outputs.yaml"
+        name: stack_outputs
+
+    - name: Add controller-0 to the Ansible inventory
+      ansible.builtin.add_host: "{{ stack_outputs.controller_ansible_host }}"
+
+    - name: Add devstack node with ProxyJump through controller
+      ansible.builtin.add_host: "{{ stack_outputs.devstack_ansible_host }}"
+
+- name: Install Devstack
+  hosts: devstack
+  gather_facts: true
+  vars:
+    scenario_dir: "{{ hotstack_work_dir | default(playbook_dir) }}/scenarios/{{ scenario_name | default('networking-lab/devstack-nxsw-vxlan') }}"
+  roles:
+    - role: devstack_installer
+      vars:
+        devstack_local_conf_template: "{{ scenario_dir }}/local.conf.j2"

bootstrap_devstack.yml

@@ -0,0 +1,24 @@
+---
+# Copyright Red Hat, Inc.
+# All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+- name: Bootstrap virtual infrastructure on Openstack cloud
+  ansible.builtin.import_playbook: 01-infra.yml
+
+- name: Bootstrap controller node
+  ansible.builtin.import_playbook: 02-bootstrap_controller.yml
+
+- name: Install DevStack
+  ansible.builtin.import_playbook: 03-install_devstack.yml

roles/devstack_installer/README.md

@@ -0,0 +1,101 @@
+# Devstack Installer Role
+
+This role installs and configures DevStack. The actual devstack configuration is provided by a `local.conf.j2` template from the scenario directory, making each scenario self-contained and customizable.
+
+## Requirements
+
+- Ubuntu 24.04 (Noble) target system
+- User `stack` with sudo privileges and home directory at `/opt/stack`
+- Accessible via SSH (potentially through a jump host)
+- Network interface configured (typically via heat template cloud-init)
+- A `local.conf.j2` template in the scenario directory
+
+## Execution Flow
+
+The role performs the following steps:
+
+1. **System Update**: Updates all packages to latest versions
+2. **Reboot if needed**: Checks for `/var/run/reboot-required` and reboots if kernel/core packages were updated
+3. **Wait for system**: Waits for system to come back online (up to 5 minutes)
+4. **Install dependencies**: Installs git, python3, and python3-pip
+5. **Verify network**: Checks that the trunk interface is UP
+6. **Clone devstack**: Clones the devstack repository
+7. **Generate config**: Creates local.conf from the scenario template
+8. **Run stack.sh**: Executes devstack installation
+9. **Mark complete**: Creates completion marker for idempotency
+
+## Role Variables
+
+Available variables are listed below, along with default values (see `defaults/main.yml`):
+
+### Required Variables
+```yaml
+# Path to the local.conf.j2 template (must be provided by the playbook)
+devstack_local_conf_template: "{{ scenario_dir }}/local.conf.j2"
+```
+
+### Optional Variables
+```yaml
+# DevStack repository configuration
+devstack_repo_url: https://opendev.org/openstack/devstack
+devstack_repo_dest: /opt/stack/devstack
+devstack_branch: master
+
+# Network interface for physical bridge (should match heat template netplan config)
+# The heat template uses MAC matching to create a predictable name
+devstack_public_interface: trunk0
+
+# System updates (set to false to skip for faster iterations during development)
+devstack_update_packages: true
+```
+
+## Dependencies
+
+None.
+
+## Example Playbook
+
+```yaml
+- name: Install Devstack
+  hosts: devstack
+  gather_facts: true
+  vars:
+    scenario_dir: "{{ playbook_dir }}/scenarios/networking-lab/devstack-nxsw-vxlan"
+  roles:
+    - role: devstack_installer
+      vars:
+        devstack_local_conf_template: "{{ scenario_dir }}/local.conf.j2"
+```
+
+## Scenario Structure
+
+Each scenario should provide its own `local.conf.j2` template:
+
+```
+scenarios/
+  networking-lab/
+    devstack-nxsw-vxlan/
+      heat_template.yaml
+      local.conf.j2          # Devstack configuration template
+      bootstrap_vars.yml
+```
+
+The `local.conf.j2` template can use Jinja2 variables and can be as simple or complex as needed. For a minimal configuration, it can be a static file without any template variables.
+
+## Features
+
+- Scenario-specific configuration via local.conf.j2 templates
+- Network configuration handled by heat template (cloud-init)
+- Updates all packages before installation (dist-upgrade)
+- Automatic reboot if kernel or core packages are updated
+- Waits for system to be fully available after reboot
+- Idempotent - can be re-run safely (checks for .stack.sh.complete marker)
+- SSH access via jump host through controller
+
+## License
+
+Apache 2.0
+
+## Author Information
+
+This role was created as part of the HotStack project.

roles/devstack_installer/defaults/main.yml

@@ -0,0 +1,16 @@
+---
+# Devstack installer defaults
+
+# Path to local.conf.j2 template (must be provided by playbook or scenario)
+devstack_local_conf_template: ""
+
+# Devstack repository
+devstack_repo_url: https://opendev.org/openstack/devstack
+devstack_repo_dest: /opt/stack/devstack
+devstack_branch: master
+
+# Network interface for physical bridge (configured by heat template via MAC matching)
+devstack_public_interface: trunk0
+
+# System updates and reboot
+devstack_update_packages: true  # Set to false to skip package updates

roles/devstack_installer/meta/main.yml

@@ -0,0 +1,12 @@
+---
+galaxy_info:
+  author: HotStack Project
+  description: Install and configure DevStack using scenario-specific configuration templates
+  license: Apache-2.0
+  min_ansible_version: "2.15"
+  platforms:
+    - name: Ubuntu
+      versions:
+        - noble
+
+dependencies: []

roles/devstack_installer/tasks/main.yml

@@ -0,0 +1,90 @@
+---
+- name: Verify devstack_local_conf_template is provided
+  ansible.builtin.assert:
+    that:
+      - devstack_local_conf_template is defined
+      - devstack_local_conf_template | length > 0
+    fail_msg: "devstack_local_conf_template must be provided (path to local.conf.j2)"
+
+- name: Update all packages to latest version
+  become: true
+  ansible.builtin.apt:
+    upgrade: dist
+    update_cache: true
+    cache_valid_time: 3600
+  register: apt_upgrade
+  when: devstack_update_packages | bool
+
+- name: Check if reboot is required
+  become: true
+  ansible.builtin.stat:
+    path: /var/run/reboot-required
+  register: reboot_required_file
+  when: devstack_update_packages | bool
+
+- name: Reboot the system if required
+  become: true
+  ansible.builtin.reboot:
+    msg: "Reboot initiated by Ansible for kernel updates"
+    connect_timeout: 5
+    reboot_timeout: 300
+    pre_reboot_delay: 0
+    post_reboot_delay: 30
+    test_command: uptime
+  when:
+    - devstack_update_packages | bool
+    - reboot_required_file.stat.exists
+
+- name: Install required packages
+  become: true
+  ansible.builtin.apt:
+    name:
+      - git
+      - python3
+      - python3-pip
+    state: present
+    update_cache: true
+
+- name: Verify trunk interface is up
+  ansible.builtin.command: ip link show {{ devstack_public_interface }}
+  register: interface_status
+  changed_when: false
+  failed_when: "'UP' not in interface_status.stdout"
+
+- name: Clone devstack repository
+  ansible.builtin.git:
+    repo: "{{ devstack_repo_url }}"
+    dest: "{{ devstack_repo_dest }}"
+    version: "{{ devstack_branch }}"
+    force: false
+
+- name: Generate local.conf from scenario template
+  ansible.builtin.template:
+    src: "{{ devstack_local_conf_template }}"
+    dest: "{{ devstack_repo_dest }}/local.conf"
+    owner: stack
+    group: stack
+    mode: '0644'
+
+- name: Run stack.sh
+  ansible.builtin.command:
+    cmd: ./stack.sh
+    chdir: "{{ devstack_repo_dest }}"
+    creates: "{{ devstack_repo_dest }}/.stack.sh.complete"
+  environment:
+    HOME: /opt/stack
+  register: devstack_install
+
+- name: Create completion marker
+  ansible.builtin.file:
+    path: "{{ devstack_repo_dest }}/.stack.sh.complete"
+    state: touch
+    owner: stack
+    group: stack
+    mode: '0644'
+  when: devstack_install.rc == 0
+
+- name: Display stack.sh output summary
+  ansible.builtin.debug:
+    msg: "Devstack installation completed successfully!"
+  when: devstack_install.rc == 0

roles/heat_stack/tasks/main.yml

@@ -36,6 +36,18 @@
     msg:
       "{{ _latest_snapset.output }}"
 
+- name: Compress files for user data
+  when: compress_heat_files | default([]) | length > 0
+  block:
+    - name: Create tar archives and compress
+      ansible.builtin.shell: |
+        tar -czf "{{ item.archive }}.tar.gz" {{ item.files | join(' ') }}
+        base64 -w0 "{{ item.archive }}.tar.gz" > "{{ item.archive }}.tar.gz.b64"
+      args:
+        chdir: "{{ stack_template_path | dirname }}"
+      loop: "{{ compress_heat_files }}"
+      changed_when: true
+
 - name: Create stack
   openstack.cloud.stack:
     cloud: "{{ os_cloud }}"

scenarios/networking-lab/README.md

@@ -0,0 +1,45 @@
+# Networking Lab Scenarios
+
+This directory contains networking-focused lab scenarios designed for testing, development, and learning various network topologies and configurations without requiring a full OpenShift deployment.
+
+## Available Scenarios
+
+### devstack-nxsw-vxlan
+A spine-and-leaf Cisco NX-OS topology with VXLAN overlay capabilities, featuring:
+- 4 Cisco NX-OS switches (2 spine, 2 leaf)
+- Devstack node for OpenStack development
+- Ironic nodes for bare metal provisioning
+- VXLAN/EVPN ready configuration
+
+See [devstack-nxsw-vxlan/README.md](devstack-nxsw-vxlan/README.md) for detailed documentation.
+
+## Managing POAP Scripts
+
+All POAP scripts (`*-poap.py`) in networking lab scenarios include md5sum validation. Use the `manage-poap-md5sums.sh` script to automatically update md5sums after modifying any POAP scripts:
+
+```bash
+./scenarios/networking-lab/manage-poap-md5sums.sh
+```
+
+This script:
+- Finds all `*-poap.py` files in networking-lab scenarios
+- Removes old md5sum lines
+- Calculates and adds new md5sum lines
+- Runs automatically via pre-commit hooks
+
+## Contributing
+
+When adding new networking lab scenarios:
+1. Create a descriptive directory name
+2. Follow the existing file structure
+3. Include comprehensive README documentation
+4. Document network topology with diagrams (SVG preferred)
+5. Provide example configurations and validation steps
+6. Include troubleshooting guidance
+7. If using POAP scripts, name them `*-poap.py` for automatic md5sum management
+
+## Related Documentation
+
+- [Main Scenarios README](../README.md)
+- [Hotstack Documentation](../../README.md)
+- [Switch Configuration Guide](../../docs/virtual_switches.md)