From deb61ffc413ca628c66348ba12e3c84fd9c619b5 Mon Sep 17 00:00:00 2001 From: flosch62 Date: Sun, 22 Dec 2024 10:18:25 +0100 Subject: [PATCH] update readme --- README.md | 10 +++- docs/clab2drawio.md | 133 ++++++++++++++++++++++++-------------------- docs/drawio2clab.md | 73 ++++++++++++++---------- docs/grafana.md | 81 ++++++++++++++++++--------- 4 files changed, 180 insertions(+), 117 deletions(-) diff --git a/README.md b/README.md index a28b375..2ff3176 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ The `clab-io-draw` project unifies two tools, `clab2drawio` and `drawio2clab`. These tools facilitate the conversion between [Containerlab](https://github.com/srl-labs/containerlab) YAML files and Draw.io diagrams, making it easier for network engineers and architects to visualize, document, and share their network topologies. -
+

Drawio Example -

+

@@ -128,3 +128,9 @@ python clab2drawio.py -i > [!NOTE] > For advanced functionality—like > [Grafana Dashboard](docs/grafana.md) generation (`-g, --gf_dashboard`),interactive mode (`-I`), layout customizations, or theming (`--theme`) refer to [clab2drawio.md](docs/clab2drawio.md#usage). + +## Contributions & Feedback + +All feedback and contributions are welcome! If you have suggestions, please open an issue or pull request on the GitHub repository. + +--- \ No newline at end of file diff --git a/docs/clab2drawio.md b/docs/clab2drawio.md index 7f2e2f3..286f363 100644 --- a/docs/clab2drawio.md +++ b/docs/clab2drawio.md @@ -1,21 +1,29 @@ # clab2drawio -`clab2drawio` is a tool designed to automatically generate network topology diagrams from [Containerlab](https://github.com/srl-labs/containerlab) YAML files, rendering them into visually appealing diagrams using Draw.io. This tool simplifies the process of visualizing network designs and configurations, making it easier for network engineers and architects to document and share their containerlab environments. +**`clab2drawio`** automatically generates network topology diagrams from Containerlab +YAML files, outputting them as visually appealing Draw.io diagrams. +It can optionally create [Grafana](./grafana.md) dashboards +for real-time network monitoring. + +

+ Drawio Example +

-![Drawio ](img/drawio1.png) ## Features -- **Automatic Diagram Generation**: Converts containerlab YAML configurations into detailed Draw.io diagrams in vertical and horizontal layouts. -- **Automatic Node Placement**: Attempts to determine the best placement for nodes automatically. However, for complex topologies, this can be challenging. -- **Graph-level-Based Layout**: Organizes nodes into graph-level based on their connectivity for clearer topology visualization. Users can influence node placement by specifying graph-level directly in the containerlab configuration. Also possible with `-I` to set it interactive -- **Graph-icon Support**: Enhances node visualization by allowing users to specify graph-icon labels such as router, switch, or host to define custom icons for nodes in the generated diagrams. -- **Customizable Styles**: Supports customization of node and link styles within the diagrams. -- **Grafana Dahsboards**: Supports to autogenerate Grafana dashboards in Grafana style. (WIP) - - ![Grafana ](img/grafana.png) - - - For more detailed information about this feature, including compatibility, usage guidelines, and future enhancements, please see the [Grafana Dashboard Documentation](./grafana.md). +- **Automatic Diagram Generation**: Produces detailed Draw.io diagrams in vertical + or horizontal layouts. +- **Graph-level-Based Layout**: Organizes nodes based on `graph-level` labels + in the YAML, which can be edited interactively with `-I`. +- **Node Icon Customization**: Utilizes `graph-icon` labels to specify icons + (e.g., `router`, `switch`, `host`). +- **Customizable Styles**: Users can apply or create custom Draw.io themes +- **Grafana Dashboards**: Generates Grafana dashboards for monitoring node and link + states. See [grafana.md](./grafana.md) for details. +

+ Grafana Example +

## Usage To generate a network topology diagram from a containerlab YAML file, run the following command: @@ -23,13 +31,19 @@ To generate a network topology diagram from a containerlab YAML file, run the fo ```bash python clab2drawio.py -i ``` -The output will be a Draw.io diagram file saved in the output path. In case without -o, the file will be saved in folder of the input file. You can open this file with Draw.io to view and further edit your network topology diagram. +> [!NOTE] +> By default, the `.drawio` file is saved in the same folder as the input YAML. +> Use `-o` to specify a different path. + +> [!TIP] +> Use `-I` for an interactive mode that prompts for `graph-level` and `graph-icon` if you have them not set in clab.yml +> labels. ## Advanced Usage ### Influencing Node Placement -The tool attempts to automatically determine the best placement for nodes. However, achieving an optimal layout for complex topologies might be challenging. You can influence node placement behavior through the `graph-level` and `graph-icon` labels in the containerlab file, which supports both vertical and horizontal layouts. The `graph-level` label impacts the placement of nodes along the primary axis of the chosen layout A lower `graph-level` number (e.g., `graph-level: 1`) indicates a position towards the start of the canvas, while a higher number places the node further along the primary axis. This feature allows you to suggest a specific hierarchy for each node, aiding the tool in organizing the topology more effectively. +You can guide node placement through `graph-level` labels: Example configuration to set node graph-level: @@ -47,7 +61,9 @@ spine1: graph-level: 2 # This node will be placed below graph-level 1 nodes on the canvas graph-icon: switch # This node will use the switch icon ``` -Using graph-level helps manage the vertical alignment of nodes in the generated diagram, making it easier to visualize the hierarchical structure of your network. +> [!TIP] +> Lower `graph-level` values place nodes toward the top or left (depending on layout). +> Higher values push them further down or to the right. ### Command-Line Arguments @@ -100,39 +116,32 @@ Using graph-level helps manage the vertical alignment of nodes in the generated - `--verbose`: Enable verbose output for debugging purposes. -## Customization -The tool allows for customization of node and link styles within the generated diagrams, making it possible to adjust the appearance to fit specific requirements or preferences. - -Below are some example images of the available custom styles: - - - - - - - - - - - -
- - Nokia - -

nokia

-
- - Modern - -

nokia_modern

-
- - Grafana - -

grafana

-
- -**_NOTE:_** drawio diagrams created with default_labels: true, cannot be used by drawio2clab +--- + +### Customization + +You can apply different style themes such as `nokia`, `nokia_modern` or `grafana`: + +```bash +python clab2drawio.py --theme nokia_modern -i +``` + +> [!TIP] +> Create your own style file and specify it with `--theme /path/to/stylefile.yml`. Or place it in styles, than you can just use it like `nokia_modern` + + + +### Example Styles + +| Theme | Preview | +| :------------: | :------------------------------------: | +| **nokia** | ![Nokia](img/nokia_bright.png) | +| **nokia_modern** | ![Modern](img/modern_bright.png) | +| **grafana** | ![Grafana](img/grafana.png) | + +> [!NOTE] +> drawio diagrams created with default_labels: true, cannot be used by drawio2clab +--- ### Custom Styles To customize styles, you can edit or copy the `example.yaml` configuration file. This file defines the base style, link style, source and target label styles, and custom styles for different types of nodes based on their roles (e.g., routers, switches, servers). @@ -168,17 +177,19 @@ icon_to_group_mapping: host: "server" ``` -### Applying Styles -Custom styles are applied to nodes and links based on the configurations specified in the style configuration files located in the `styles` directory by default. To apply a new style to a node type, update its corresponding style definition in the appropriate YAML file. These styles determine the appearance of nodes and links in the generated diagram, including shapes, colors, and icons. - -If you wish to create a completely new style, you can create a new YAML file with your custom configurations. This file can be placed in any directory, and you can specify its path when running the script using the `--theme` option. - -### Advanced Styling -For users looking to further customize their diagrams with more advanced styling options, such as custom icons, specific dimensions, or additional visual attributes, you can directly edit the styles within the Draw.io interface. - -To get the style data from Draw.io for a specific element: -1. Create or select the element in your Draw.io diagram. -2. Right-click on the element and select "Edit Style" from the context menu. -3. A style definition string will be displayed in a text box. You can copy this string and incorporate it into your custom style file or directly modify it within Draw.io for immediate effect. - +> [!TIP] +> For users looking to further customize their diagrams with more advanced styling options, such as custom icons, specific dimensions, or additional visual attributes, you can directly edit the styles within the Draw.io interface. +> To get the style data from Draw.io for a specific element: +> 1. Create or select the element in your Draw.io diagram. +> 2. Right-click on the element and select "Edit Style" from the context menu. +> 3. A style definition string will be displayed in a text box. +> +> You can copy this string and incorporate it into your custom style file or directly modify it within Draw.io for immediate effect. + +## Further Documentation & References + +- [Containerlab Documentation](https://containerlab.dev) +- [clab2drawio.md](./clab2drawio.md) +- [drawio2clab.md](./drawio2clab.md) +- [grafana.md](./grafana.md) diff --git a/docs/drawio2clab.md b/docs/drawio2clab.md index 23dfda6..9a80492 100644 --- a/docs/drawio2clab.md +++ b/docs/drawio2clab.md @@ -1,36 +1,48 @@ # Drawio2Clab -Drawio2Clab is a tool that converts .drawio diagrams to YAML format, specifically designed for network topologies. It parses XML files exported from draw.io (or diagrams.net), extracts information about nodes and links, and generates a structured YAML representation of the network. This process streamlines the setup of complex network topologies within [Containerlab](https://github.com/srl-labs/containerlab) environments, facilitating an easy and efficient way to manage container-based networking labs. +**`drawio2clab`** converts `.drawio` (XML) diagrams back into Containerlab-compatible +YAML files. This allows you to plan and sketch topologies in Draw.io, then easily +deploy them in a containerized lab environment. + +> [!NOTE] +> For best results, ensure that your Draw.io nodes and links are well-labeled and that custom properties (for node kind, management IP, etc.) are used consistently. ## Features - Converts .drawio diagrams to Containerlab-compatible YAML. -- Allows selection of specific diagrams within a .drawio file. -- Supports block and flow styles for YAML endpoints. -- Extracts detailed node and link information for precise topology representation. +- Supports specifying node details (e.g., `type`, `kind`, `mgmt-ipv4`, `labels`) + directly in Draw.io. +- Allows selection of a specific diagram within a multi-page `.drawio` file. +- Output can be in `block` or `flow` style YAML. + + ## Drawing Constraints -When creating your .drawio diagrams, please adhere to the following constraints to ensure successful conversion: +> [!IMPORTANT] +> Label your nodes and links properly. Node attributes can be added in Draw.io +> as custom properties (`=`), which `drawio2clab` will parse. -- **Node Labeling**: All nodes must be labeled. To label a node, click on the node and start typing. +- **Node Labeling**: Click on a node and start typing to label it. +- **Link Labeling**: Double-click on a link to add a label (closest labels to + each endpoint are used). +- **Node Data**: Provide extra data (like `type`, `kind`, or `labels`) in + the `custom properties` panel in Draw.io. -- **Link Labeling**: All links need to be labeled. To label a link, double-click on the link and type your label. Only the labels closest to the source and destination will be considered. - -### Adding Node Data +- **Adding Node Data** In addition to labeling, nodes can contain additional data to further define the network configuration. The following attributes can be added to a node: -- `type`: Specify the type of the node. E.g., "ixrd2", "ixrd3". -- `kind`: Specify the kind of the node, by default nokia_srlinux -- `mgmt-ipv4`: Assign a management IPv4 address to the node. -- `group`: Define a group to which the node belongs. -- `labels`: Add custom labels for additional metadata or categorization. - -To add these attributes to a node, select the node and add custom properties in the format `=`. Ensure each attribute is properly formatted according to the capabilities of draw.io for defining custom properties. + - `type`: Specify the type of the node. E.g., "ixrd2", "ixrd3". + - `kind`: Specify the kind of the node, by default nokia_srlinux + - `mgmt-ipv4`: Assign a management IPv4 address to the node. + - `group`: Define a group to which the node belongs. + - `labels`: Add custom labels for additional metadata or categorization. +--- -Those attributes will be added to the clab nodes. +

+ Drawio Example +

-![Drawio Example](img/drawio1.png) The above image demonstrates how to correctly label nodes and links and add additional data to nodes for conversion. @@ -39,19 +51,24 @@ The above image demonstrates how to correctly label nodes and links and add addi Convert a .drawio file to YAML: ```bash -python drawio2clab.py -i input_file.xml -o output_file.yaml +python drawio2clab.py -i input_file.drawio ``` -Specify a diagram name and output style: - -```bash -python drawio2clab.py -i input_file.xml -o output_file.yaml --diagram-name "Diagram 1" --style flow -``` +> [!TIP] +> If your `.drawio` file has multiple diagrams, use +> `--diagram-name "Diagram 1"` to specify which one to process. ### Arguments -- `-i`, `--input`: Input `.drawio` XML file. -- `-o`, `--output`: Output YAML file. +- `-i, --input`: Path to `.drawio` XML file. +- `-o, --output`: Path to the output YAML file. - `--style`: YAML style (`block` or `flow`). Default is `flow`. -- `--diagram-name`: Name of the diagram to parse. -- `--default-kind`: The default kind for nodes. Default is 'nokia_srlinux' +- `--diagram-name`: Name of the diagram to parse if multiple diagrams exist. +- `--default-kind`: Default kind for nodes (e.g., `nokia_srlinux`). + +## Further Documentation & References + +- [Containerlab Documentation](https://containerlab.dev) +- [clab2drawio.md](./clab2drawio.md) +- [drawio2clab.md](./drawio2clab.md) +- [grafana.md](./grafana.md) diff --git a/docs/grafana.md b/docs/grafana.md index 1998877..6ae3813 100644 --- a/docs/grafana.md +++ b/docs/grafana.md @@ -2,46 +2,73 @@ The `-g, --gf_dashboard` command line option is designed to automate the generation of Grafana dashboards with all it's rules from your YAML configuration files. When using this option, it is important to note the following specifics: -![Grafana ](img/grafana.png) +

+ Grafana Example +

-#### Features -- Ports are showing up and down (red/green) -- Links are showing it's bandwidth + colors for utilization - - All trafic is outgoing metric -#### Compatibility -- **Grafana Version:** Works optimally with Grafana version **>10.0.0**. Recomendation: **11.2.0**. -- **Plugin Requirement:** It requires the Flowcplugin [Flow plugin](https://grafana.com/grafana/plugins/andrewbmchugh-flow-panel). This plugin is essential for rendering the custom visualizations generated by the script. +> [!IMPORTANT] +> - **Grafana Version:** This feature works optimally with Grafana versions **>10.0.0**. Recommendation: **11.2.0**. +> - **Plugin Requirement:** Requires the [Flow plugin](https://grafana.com/grafana/plugins/andrewbmchugh-flow-panel). This plugin is essential for rendering the custom visualizations generated by the script. + +## Features + +- **Link Monitoring**: Displays link utilization and status (up/down) in a color-coded manner. +- **Port Monitoring**: Displays node port statuses (red/green). +- **Prometheus Integration**: Built for use with common streaming telemetry data + (e.g., from `gnmic`). ### Usage To generate a dashboard, execute the following command: ```bash -python clab2drawio.py -i -g --theme grafana_dark +python clab2drawio.py -i -g --theme grafana ``` -Ensure that you replace `` with the actual path to your YAML configuration file. Use it with grafana_dark or your own grafana compatible theme. +> [!TIP] +> Use a Grafana-compatible theme like `grafana_dark` for a more cohesive look. + +### Output + +When `-g` is used, the script generates: + +1. A **Grafana dashboard JSON** file. +2. A **Panel YAML** configuration file +3. A **Draw.io diagram**. -When the `-g` flag is used, the script generates the following: -1. Grafana dashboard JSON file -2. Panel YAML configuration file -3. draw.io diagram +> [!NOTE] +> The drawio diagram needs to be exported to svg, see below ### Additional Options -`--grafana-config` -Specify the path to a Grafana YAML configuration file using the --grafana-config option. This allows you to customize Grafana settings for your dashboard generation. If omitted, the script uses default configurations. + +The `--grafana-config` option lets you customize Grafana Flow Panel settings. If omitted, the default configuration is used. + +> [!NOTE] +> - **Targets:** Defines Prometheus queries and legends (e.g., operational state, traffic rates). +> - **Thresholds:** Preconfigured color coding: +> - `operstate`: Red (down), Green (up). +> - `traffic`: Gray (low), Green (normal), Yellow/Orange/Red (high). +> - **Label Config:** Units (`bps`), decimal precision (1), and value mappings. + +To use a custom configuration: ```bash -python clab2drawio.py -i -g --theme grafana --grafana-config +python clab2drawio.py -i -g --theme grafana --grafana-config ``` -Replace with the path to your YAML configuration file and with the path to your Grafana configuration file. The default is `core/grafana/config/default_grafana_panel_config.yml` + +> [!TIP] +> Customize targets, thresholds, or labels in your YAML to align with your network's metrics and visualization needs. #### To export the diagram as an SVG: To get a full guide: [https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/src/README.md#using-drawio-to-create-your-svg](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/src/README.md#using-drawio-to-create-your-svg) -1. Open the generated draw.io diagram using the draw.io application with the svgdata plugin enabled, or use the online version at [https://app.diagrams.net/?p=svgdata](https://app.diagrams.net/?p=svgdata). -2. Go to File -> Export -> SVG to export the diagram as an SVG file. +1. Open the generated draw.io diagram using the draw.io application or use the online version at [https://app.diagrams.net/?p=svgdata](https://app.diagrams.net/?p=svgdata). +> [!IMPORTANT] +> The svgdata plugin needs to be enabled +2. **File** -> **Export** -> **SVG**. +3. Paste the resulting SVG data into Grafana’s Flow panel. -The generated dashboard JSON will include the panel configuration but without the SVG data. To complete the dashboard, you need to either: -- Copy and paste the SVG data into the designated SVG box in the Grafana dashboard editor. -- Upload the SVG file to a hosting service and reference the URL in the Grafana dashboard editor. +> [!NOTE] +> The generated dashboard JSON will include the panel configuration but without the SVG data. To complete the dashboard, you need to either: +> - Copy and paste the SVG data into the designated SVG box in the Grafana dashboard editor. +> - Upload the SVG file to a hosting service and reference the URL in the Grafana dashboard editor. By following these steps, you can generate a complete Grafana dashboard with the diagram, panel configuration, and dashboard JSON file. @@ -244,7 +271,9 @@ processors: ``` +## Further Documentation & References - -#### Contributing -Feedback and contributions are welcome to help advance this feature towards a more robust and flexible implementation. If you are interested in contributing or have suggestions, please refer to the project's contribution guidelines or submit an issue on the project's GitHub repository. +- [Containerlab Documentation](https://containerlab.dev) +- [clab2drawio.md](./clab2drawio.md) +- [drawio2clab.md](./drawio2clab.md) +- [grafana.md](./grafana.md)