1. Home
2. User manual

Containerlab labs in Codespaces#

The best labs are the labs that you can run anywhere, anytime, with a single click and preferably 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.

Labs in Codespaces#

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:

1. Spin up an existing lab with a single click without having to install anything on your local machine.
2. 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 an easier 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, please go ahead.

How does it work?#

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.

Codespaces#

As we mentioned, the Codespaces 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.

Free plan#

The best part about Codespaces is that it has a suitable free tier. GitHub offers 120 cpu-hours/month and 15 GB storage for free4 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!

Control panel#

Whenever you need to check what Codespaces environments you have running or created, you can do it in the Codespaces panel.

[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 settings#

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.

Billing#

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.

[billing]

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.6

To avoid any surprises and lower your anxiety levels, GitHub Codespaces have two important settings that you configure at github.com/settings/codespaces:

1. 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.
2. 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.

Adding codespaces to your lab#

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:

{
    "image": "ghcr.io/srl-labs/containerlab/devcontainer-dind-slim:0.68.0",
    "hostRequirements": {
        "cpus": 4, // (1)!
        "memory": "8gb",
        "storage": "32gb"
    }
}

1. 4-core machine type is used in this example, you can tune the machine type to fit your lab requirements. Maybe it will fit in a 2-core/4GB machine, or you need a beefier 8-core machine, it is up to you.

For a complete Dev Container specification, check out the official docs.

Image#

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.

Host requirements#

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.

Using the machine types displayed above you can tune the hostRequirements section by choosing the machine type that fits the requirements of your lab.

Testing the environment#

Once you added the .devcontainer/devcontainer.json file to your lab repository, you can test the environment locally and in Codespaces.

Local testing#

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.

Remote testing#

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:

[pr-codespaces]

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.

Launching the environment#

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.

---
<div align=center markdown>
<a href="https://codespaces.new/srl-labs/srlinux-vlan-handling-lab?quickstart=1">
<img src="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>

---

Check out srl-labs/srl-streaming-telemetry README where this button is used to start the lab in Codespaces.

And of course, you can always launch the Codespace using the GitHub UI by clicking on the "Code" button.

[start]

1. Click on the "Code" button in the GitHub UI.
2. Start the Codespace on the main branch using the devcontainer settings defined in the .devcontainer/devcontainer.json file.
3. Or open up an advanced menu
4. And configure the Codespace settings manually.

Dev Container#

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.

Containerlab has four devcontainer images that differ in the way the docker is setup and the tools installed (slim and regular variants):

1. Docker in Docker (dind) - is the devcontainer that is meant to contain an isolated docker environment inside the container. This image is suitable for Codespaces.
2. Docker outside of Docker (dood) - is a devcontainer image that mounts the docker socket from the outside, and therefore can reuse the images existing on the host machine. This image is mostly used with DevPod.

You will find the devcontainer definition files in containerlab/.devcontainer directory where:

1. devcontainer.json - the Dev Container configuration file that defines how the environment is built, configured and launched.
2. Dockerfile and slim.Dockerfile - the Dockerfile files that the Dev Container is built from.

The resulting Dev Container image (in a non-slim variant) contains the following tools and dependencies:

• containerlab binary installed via the deb repository
• docker in docker setup
• gNMIc and gNOIc tools
• Go SDK
• Python 3 with uv
• gh CLI tool
• zsh shell with oh-my-zsh configuration
• VS Code plugins

Catalog of Codespaces-enabled labs#

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.

Tips, tricks and known issues#

Authenticating with ghcr.io container registry#

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 exercise.

First, unset the existing token and request the one with read:packages capability:

unset GITHUB_TOKEN && gh auth refresh -s read: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:

gh auth token | \
docker login ghcr.io -u $(cat /home/vscode/.config/gh/hosts.yml | \
grep user: | awk '{print $2}') --password-stdin

Of course you can also install tailscale or any other 0-tier VPN to access any other self-hosted private registry.

Comments