deploy command#
Description#
The deploy command spins up a lab using the topology expressed via topology definition file.
Usage#
containerlab [global-flags] deploy [local-flags]
aliases: dep
Flags#
topology#
With the global --topo | -t flag a user sets the path to the topology definition file that will be used to spin up a lab.
When the topology path refers to a directory, containerlab will look for a file with .clab.yml extension in that directory and use it as a topology definition file.
When the topology file flag is omitted, containerlab will try to find the matching file name by looking at the current working directory.
If more than one file is found for directory-based path or when the flag is omitted entirely, containerlab will fail with an error.
name#
With the global --name | -n flag a user sets a lab name. This value will override the lab name value passed in the topology definition file.
vars#
Global --vars option for using specified json or yaml file to load template variables from for generating topology file.
Default is to lookup files with "_vars" suffix and common json/yaml file extensions next to topology file. For example, for mylab.clab.gotmpl template of topology definition file, variables from mylab.clab_vars.yaml file will be used by default, if it exists, or one with .json or .yml extension.
See documentation on Generated topologies for more information and examples on how to use these variables.
reconfigure#
The local --reconfigure | -c flag instructs containerlab to first destroy the lab and all its directories and then start the deployment process. That will result in a clean (re)deployment where every configuration artefact will be generated (TLS, node config) from scratch.
Without this flag present, containerlab will reuse the available configuration artifacts found in the lab directory.
Refer to the configuration artifacts page to get more information on the lab directory contents.
max-workers#
With --max-workers flag, it is possible to limit the number of concurrent workers that create containers or wire virtual links. By default, the number of workers equals the number of nodes/links to create.
runtime#
Containerlab nodes can be started by different runtimes, with docker being the default one. Besides that, containerlab has experimental support for podman, and ignite runtimes.
A global runtime can be selected with a global --runtime | -r flag that will select a runtime to use. The possible value are:
docker- defaultpodman- experimental supportignite
timeout#
A global --timeout flag drives the timeout of API requests that containerlab send toward external resources. Currently the only external resource is the container runtime (i.e. docker).
In a busy compute the runtime may respond longer than anticipated, in that case increasing the timeout may help.
The default timeout is set to 2 minutes and can be changed to values like 30s, 10m.
export-template#
The local --export-template flag allows a user to specify a custom Go template that will be used for exporting topology data into topology-data.json file under the lab directory. If not set, the default template path is /etc/containerlab/templates/export/auto.tmpl.
To export full topology data instead of a subset of fields exported by default, use --export-template /etc/containerlab/templates/export/full.tmpl. Note, some fields exported via full.tmpl might contain sensitive information like TLS private keys. To customize export data, it is recommended to start with a copy of auto.tmpl and change it according to your needs.
log-level#
Global --log-level parameter can be used to configure logging verbosity of all containerlab operations. --debug | -d option is a shorthand for --log-level debug and takes priority over --log-level if specified.
Following values are accepted, ordered from most verbose to least: trace, debug, info, warning, error, fatal. Default level is info.
It should be useful to enable more verbose logging when something doesn't work as expected, to better understand what's going on, and to provide more useful output logs when reporting containerlab issues, while making it more terse in production environments.
node-filter#
The local --node-filter flag allows users to specify a subset of topology nodes targeted by deploy command. The value of this flag is a comma-separated list of node names as they appear in the topology.
When a subset of nodes is specified, containerlab will only deploy those nodes and links belonging to all selected nodes and ignore the rest. This can be useful e.g. in CI/CD test case scenarios, where resource constraints may prohibit the deployment of a full topology.
Read more about node filtering in the documentation.
Environment variables#
CLAB_RUNTIME#
Default value of "runtime" key for nodes, same as global --runtime | -r flag described above. Affects all containerlab commands in the same way, not just deploy.
Intended to be set in environments where non-default container runtime should be used, to avoid needing to specify it for every command invocation or in every configuration file.
Example command-line usage: CLAB_RUNTIME=podman containerlab deploy
CLAB_VERSION_CHECK#
Can be set to "disable" value to prevent deploy command making a network request to check new version to report if one is available.
Useful when running in an automated environments with restricted network access.
Example command-line usage: CLAB_VERSION_CHECK=disable containerlab deploy
CLAB_LABDIR_BASE#
To change the lab directory location, set CLAB_LABDIR_BASE environment variable accordingly. It denotes the base directory in which the lab directory will be created.
The default behavior is to create the lab directory in the current working dir.
Examples#
Deploy a lab using the given topology file#
Deploy a lab and regenerate all configuration artifacts#
Deploy a lab without specifying topology file#
Given that a single topology file is present in the current directory.