cml2tf 0.2.1

Convert CML2 lab topologies from YAML into HCL.

CML2TF: CML to Terraform converter

Converts existing Cisco Modeling Labs lab into Terraform HCL .tf files from exported lab topology YAML file.

This is an early version of the script. This version is compatible with terraform-provider-cml2 version 0.6.2/0.7.0. Not all features are implemented, yet. Please refer to TODO.md file for the list of unsupported features and current restrictions.

Installation

To use this package install it via PyPI pip install cml2tf. It's recommended to use either a virtual environment or use something like pipx to properly isolate the package.

Development

If you want to develop the package then PDM is needed. Follow their instructions on the web site to install PDM. This requires Python3, it's been tested w/ 3.8, 3.9, 3.10 and 3.11.

Once installed, you can get a development environment using the follwing steps:

1. Clone the repo

   git clone https://github.com/WojciechowskiPiotr/cml-terraform-converter.git
   

2. Go to your project folder

   cd cml-terraform-converter
   

3. Set up a Python venv. First make sure that you have Python 3 installed on your machine. We will then be using PDM to create an isolated environment with only the necessary packages.

   pdm venv create
   pdm venv activate
   

   Copy / paste the resulting string into your shell or use something like direnv to automate this.

   Note: Creation of the venv is only needed once, activation whenever you want to work with the venv!

4. Install dependencies

   pdm install --dev
   

5. Install the package as editable (optional, but eases development by installing the script / entry point). Don't commit it to the repo, though.

   pdm add --dev --editable .
   

   You can remove it again using

   pdm remove --dev .
   

Code should be formatted with ruff which is installed as part of the dev dependencies. Please ensure to format your code before submitting a PR, the GH action will fail otherwise.

Usage

First, export the lab topology from Cisco Modeling Labs to the YAML file and store it in the project folder. Log into your Cisco Modeling Labs instance to export the lab, enter the lab you want to export from the top menu, select Lab → Download Lab, and save the file.

To convert a lab into Terraform files, use the following command: cml2tf -i lab.yaml where lab.yaml is the name of the exported file.

As a result of running the script, a new folder lab will be created. The folder name is always the same as the exported YAML filename. It contains two files: variables.tf and main.tf. The first file contains variables like CML server URL, login, and password. Edit this file, providing the correct credentials. The main.tf has the topology for Terraform.

If a destination folder exists you need to use the -f option to overwrite its content. This will let you update the converted main.tf file. The variables.tf file, if it exists, remains unchanged.

If you want to have the configurations of the lab nodes separated out into individual files which then you can provide the -c / --configs flag. The main.tf file will include the exported configurations via file().

To read the full usage information issue cml2tf -h command.

usage: cml2tf [-h] [-i INPUT] [-o OUTDIR] [-f]

options:
  -h, --help            show this help message and exit

Input options:
  -i INPUT, --input INPUT
                        File with input lab topology in YAML exported from CML2

Output options:
  -o OUTDIR, --outdir OUTDIR
                        Output directory name where terraform files will be created (by default input topology filename)
  -c, --configs         store configurations in separate files
  -f, --force           Overwrite files if destination folder exists

Usage example: cml2tf -i topology.yaml

Known issues

Use GitHub Issues to report any problems or share ideas about expanding the script.

Getting involved

If you want to contribute to this project, feel free to fork it and then send your proposal using a Pull Request.