The best labs are the labs that you can run anywhere, anytime, with a single click and preferrably for free.
Containerlab commoditized the labbing experience by providing a simple and easy to use tool to create and manage network topologies. But still you have to think a machine to run the lab on. Or, rather, you had.
We started to ship a Dev Container1 package for Containerlab that allows you to run containerlab-based labs in a GitHub Codespaces for free2 unlocking a whole new level of flexibility and convenience for users.
GitHub Codespaces is a cloud-based development environment by GitHub that allows you to spin up a fully configured personal dev environment in the cloud and start coding in seconds. If you think about Containerlab as a Lab-as-Code solution, you can quickly see how these two can be a perfect match.
With Containerlab in Codespaces you can:
Spin up an existing lab with a single click without having to install anything on your local machine.
Start with Containerlab using the cloud IDE provided by Codespaces.
Here is a quick demo how anyone can run the full SR Linux Streaming Telemetry lab by just clicking on a link. It is hard to imagine a more easy and convenient way to run your labs in the cloud.
Fancy a full demo? Check out the 17min video by Roman. Would you rather straight try it yourself, then click here.
The key ingredients in this recipe are GitHub codespaces and the Dev Container image that we provide for Containerlab. When a user clicks on a link3 to open the lab in Codespaces, GitHub spins up a Codespace environment and uses the Dev Container image to set it up. The Containerlab' Dev Container image has all the necessary tools and dependencies to run Containerlab:
containerlab binary
shell configuration
system packages and tools (gnmic, gnoic)
VS Code plugins
and anything else we consider useful to have in the environment
A user can choose to open the Codespace in a browser or in the local VS Code instance. In both cases, you get a fully functional environment with Containerlab installed and ready to use.
Codespaces environment boots for a couple of minutes, but once it is up and running, you see the familiar VS Code interface with the terminal window where you can run containerlab (and any other) commands.
As we mentioned, the Codepsaces environment is a VM in the cloud; you can install packages, run other workloads, and use the VM in any way you like, you have the full control of it. What makes Codespaces VM different from a any other VM in the cloud is that it is tightly integrated with GitHub and VS Code, and provides a configurable and ready-to-use environment.
We said it is free, but it is free to a certain extent, let's dig in.
The best part about Codespaces is that it has a suitable free tier. GitHub offers 120 cpu-hours/month and 15 GB storage for free7 to all users. This means that you can run a Codespace environment for 120 cpu-hours per month without any charges. This is a compelling offer for those who
want to spin up a lab provided by others to get through a tutorial or a demo
don't need to run the labs 24/7
want to demo labs on-the-go without managing the local environment
You can select which GitHub machine type you want to use for your project; each machine type is characterized by the amount of CPUs/RAM/Storage that it is equipped with, and based on that you can calculate how many cpu-hours you would consume running a lab with a chosen machine type.
By the time of this writing (Jun 2024) the following machine types were available for GitHub users by default and beefier machines can be requested via GitHub support form.
If you need more than 120 cpu-hours, you can pay for the additional usage (consult with pricing), and you can always stop the environment when you don't need it to save the quota.
Your cpu-hours counter is reset at the beginning of each month, so you can use the free plan every month. And by default you have a $0 spending limit, so you won't be charged unless you explicitly allowed it. Good!
Whenever you need to check what Codespaces environments you have running or created, you can do it in the Codespaces panel.
The panel allows you to see and interact with the available Codespaces environments, including starting, stopping, and deleting them. You can also check what repositories are associated with each environment which is useful for a Containerlab user to quickly identify the lab environments.
Codespaces expose a bunch of per-user settings at the github.com/settings/codespaces page. The following settings are worth mentioning:
Idle timeout and retention period
Maybe the most important settings that you can configure in Codespaces. They allow you to control how long the environment will be running and when it will be deleted. Read more on this in Billing section
Secrets
Secrets allow you to store sensitive information that will be available to your Codespaces environments. You can use them to store API keys, passwords, and other sensitive data that you don't want to expose in your code.
Setting Sync
To make codespaces env feel like home, you can sync your settings across all your Codespaces environments. This includes themes, keybindings, and other settings that you have configured in your local VS Code instance.
Editor preference
You can choose if you want to run the codespaces in a browser, in a local VS Code instance, or via a bridge to a JetBrains IDE.
It is always a good idea to periodically check how much of the cpu-hours you've consumed and check the remaining quota. Your billing information is available in the Billing settings.
The screenshot shows that 10 cpu-hours out of 120 available were consumed in the current month' period and the codespaces environments occupy 8.15 GB of storage out of 15 GB included. So far it is all well within the free tier limits.5
Note
All users by default have a $0 spending limit4, which means that if you exceed the free tier limits, your environments will be stopped and you will not be charged. You can change this limit to a higher value if you want to be able to use Codespaces even after you exceed the free tier limits.
To avoid any surprises and lower your anxiety levels, GitHub Codespaces have two important settings that you configure at github.com/settings/codespaces:
Idle timeout This setting allows you to "suspend" the running environment after a certain period of inactivity and defaults to 30 minutes. You can increase/decrease the timeout as you see fit. Consult with the docs to see what counts as activity and what doesn't.
Retention period When you stopped the codespaces environment or it was suspended due to inactivity, it will be automatically deleted after a certain period of time. The default (and maximum) retention period is 30 days, but you can change it to a shorter period. The stopped environment won't count against your cpu-hours quota, but it will still consume storage space, hence you might want to remove the stopped environments to free up the space.
Safe settings
To keep a tight control on the Codespaces free quota usage you can set the following in your Codespaces Settings:
Idle timeout to 15 minutes
Retention period to 1 day
That way you can be sure that the environment is not running when you don't need it and it will be deleted after a day of inactivity saving up on the storage space.
By now you should be willing to try running your labs in Codespaces. To our luck, it is super simple, all you need to do is create a .devcontainer/devcontainer.json file in your lab repository that will define the Codespaces environment. The file should look similar to this:
The image field points to the Containerlab Dev Container image that would define your Codespaces environment. Containerlab provides devcontainer images, and you can see all available tags on the package' page.
The image tag corresponds to the containerlab release version that is pre-installed in the image. You can choose the version that you want to use in your lab.
Another important part of the devcontainer.json file is the hostRequirements field that defines the machine type that Codespaces environment will run on. Codespaces offer a small selection of machine types that differ in the number of CPUs, RAM, and storage. You can choose the machine type that fits your lab requirements.
By the time of this writing (Jun 2024) the following machine types were available for GitHub users by default and beefier machines can be requested via GitHub support form.
Machine type
CPU
Memory (GB)
Storage (GB)
2 core
2
8
32
4 core
4
16
32
8 core
8
32
64
16 core
16
64
128
Using the machine types displayed above you can tune the hostRequirements section by choosing the machine type that fits the requirements of your lab.
Note
Codespaces VMs support nested virtualization, so you can run VM-based kinds
Testing the environment locally is a litmus test to ensure that the devcontainer.json file is correct and the environment can be started. But since the environment runs locally, it doesn't test the Codespaces-specific settings like the machine type and CPU/RAM requirements.
To deploy the environment locally, make sure you have Dev Containers VS Code extension installed and then use the VS Code command panel (Cmd/Ctrl+Shift+P) to execute Dev Containers: Rebuild And Reopen In Container action. This will trigger the VS Code to build the container and open the environment in the container.
Once you tested the environment locally, you should test it in Codespaces to ensure that the selected machine type is sufficient for your lab.
Hopefully you've been adding the Codespaces support in a git branch and created a PR for it. You can open the PR in the GitHub UI and click on the "Code" -> "Create codespace on codespaces" button to start the environment for the branch you're working on:
You'll get the environment up and running in a couple of minutes and you can test it to ensure that it works as expected.
Once you are satisfied with the environment, you can add a nice button to the README file that will allow users to start the environment with a single click.
Run this lab in GitHub Codespaces for free. Learn more about Containerlab for Codespaces. Machine type: 2 vCPU · 8 GB RAM
The URL used in the link uses deep link configuration provided by Codespaces, read more about it in the official docs.
Do not forget to change the lab repo URL and machine type in the code below!
---
<divalign=centermarkdown><ahref="https://codespaces.new/srl-labs/srlinux-vlan-handling-lab?quickstart=1"><imgsrc="https://gitlab.com/rdodin/pics/-/wikis/uploads/d78a6f9f6869b3ac3c286928dd52fa08/run_in_codespaces-v1.svg?sanitize=true"style="width:50%"/></a>**[Run](https://codespaces.new/srl-labs/srlinux-vlan-handling-lab?quickstart=1) this lab in GitHub Codespaces for free**.
[Learn more](https://containerlab.dev/manual/codespaces) about Containerlab for Codespaces.
<small>Machine type: 2 vCPU · 8 GB RAM</small></div>---
The key pillar behind Codespaces is the Containerlab' Dev Container image that defines the environment in which the lab will run. The Dev Container image is a Docker image that contains all the necessary tools and dependencies to run Containerlab and other tools that you might need in the lab.
The following two files define Containerlab's Dev Container image:
devcontainer.json - the Dev Container configuration file that defines how the environment is built, configured and launched.
Dockerfile - the Dockerfile that the Dev Container is built from.
The resulting Dev Container image contains the following tools and dependencies:
containerlab binary installed via the deb repository
Having a codespace-enabled lab makes it super easy for users to start the lab and get to the fun part of the labbing.
We encourage lab authors to add codespaces and clab-topo topics to the lab repository that supports Codespaces; that way users would be able to find the labs that they can run in Codespaces by following this link.
If you happen to have a private image that you want to use in Codespaces you can push this image to your personal GitHub registry.
To be able to access a private image you would need to (re)authenticate with the read:packages token entitlement against the GitHub registry. Thankfully, it is a matter of a copy-paste exerceise.
First, unset the existing token and request the one with read:packages capability:
unsetGITHUB_TOKEN&&ghauthrefresh-sread:packages
You will be prompted to authenticate with your GitHub account and the new token will be generated for you. Then you can login to the registry using the newly acquired token: