Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@FloSch62
FloSch62 committed Dec 22, 2024
1 parent 126dd68 commit deb61ff
Show file tree
Hide file tree
Showing 4 changed files with 180 additions and 117 deletions.
10 changes: 8 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<div style="text-align: center;">
<p align="center">
<img src="./docs/img/st.clab.drawio.svg" alt="Drawio Example">
</div>
</p>



Expand Down Expand Up @@ -128,3 +128,9 @@ python clab2drawio.py -i <input_file.yaml>
> [!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.
---
133 changes: 72 additions & 61 deletions docs/clab2drawio.md
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,49 @@
# 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.

<p align="center">
<img src="./img/st.clab.drawio.svg" alt="Drawio Example">
</p>

![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.
<p align="center">
<img src="./img/grafana.png" alt="Grafana Example">
</p>

## Usage
To generate a network topology diagram from a containerlab YAML file, run the following command:

```bash
python clab2drawio.py -i <path_to_your_yaml_file>
```
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:

Expand All @@ -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

Expand Down Expand Up @@ -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:

<table>
<tr>
<td style="text-align: center;">
<a href="img/nokia_bright.png" target="_blank">
<img src="img/nokia_bright.png" alt="Nokia" style="width: 200px;">
</a>
<p>nokia</p>
</td>
</tr>
<tr>
<td style="text-align: center;">
<a href="img/modern_bright.png" target="_blank">
<img src="img/modern_bright.png" alt="Modern" style="width: 200px;">
</a>
<p>nokia_modern</p>
</td>
</tr>
<tr>
<td style="text-align: center;">
<a href="img/grafana.png" target="_blank">
<img src="img/grafana.png" alt="Grafana" style="width: 200px;">
</a>
<p>grafana</p>
</td>
</tr>
</table>

**_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 <path_to_yaml>
```

> [!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).
Expand Down Expand Up @@ -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)
73 changes: 45 additions & 28 deletions docs/drawio2clab.md
View file
Original file line number Diff line number Diff line change
@@ -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 (`<property>=<value>`), 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 `<property_name>=<value>`. 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.
<p align="center">
<img src="./img/drawio1.png" alt="Drawio Example">
</p>

![Drawio Example](img/drawio1.png)

The above image demonstrates how to correctly label nodes and links and add additional data to nodes for conversion.

Expand All @@ -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)
Loading

0 comments on commit deb61ff

Please sign in to comment.