cohydra.node.docker

Docker containers in the simulation.

Functions

expand_volume_shorthand

Expand a volume string to something the Docker runtime understands.

log_to_file

Log the container’s output.

Classes

DockerNode

A DockerNode represents a docker container.

cohydra.node.docker.expand_volume_shorthand(key_value)[source]

Expand a volume string to something the Docker runtime understands.

Parameters

key_value (str or dict) – The volume configuration

Returns

Return the volume’s name / path and a settings dictionary.

Return type

tuple

cohydra.node.docker.log_to_file(container, log_path, stdout=False, stderr=False)[source]

Log the container’s output.

This opens a stream to the docker container’s log output and writes it into a file.

Parameters

  • log_path (str) – The file path to the log file.

  • stdout (bool) – Whether stdout should be logged.

  • stderr (bool) – Whether stderr should be logged.

class cohydra.node.docker.DockerNode(name, docker_image=None, docker_build_dir=None, dockerfile='Dockerfile', pull=False, cpus=0.0, memory=None, command=None, volumes=None, exposed_ports=None, environment_variables=None)[source]

Bases: cohydra.node.base.Node

A DockerNode represents a docker container.

Parameters

  • name (str) – The name of the node (and container). It must consist only of alphanumeric characters and -, _ and ..

  • docker_image (str) – The name of the docker image to use. If not specified, docker_file and docker_build_dir must be set.

  • docker_build_dir (str) – The context directory (relative path possible) to execute the build in.

  • docker_file (str) – The (absolute or relative) path to the Dockerfile.

  • pull (bool) – Whether to always pull the image specified in docker_image.

  • cpus (float) – The number of virtual CPUs to assign (1.0 meaning 1 vCPU).

  • memory (str) – The amount of memmory to allow the container to use. Example: ‘128m’.

  • command (str) – An optional command to override the standard command on container start specified by the Dockerfile.

  • volumes (list of dict or list of str) – A dictionary of volumes. Each entry has a name or (absolute) path as key and settings or a absolute path inside the container as value. See examples/volumes_and_ports.py.

  • exposed_ports (dict) – A dictionary of port mappings. The key is the container internal port and the value can be an exposed port or a list of ports.

  • environment_variables (dict or list) – A dictonary of environment variables or a list of environment variables. If a list is specified each item should be in the form 'KEY=VALUE'.

docker_image = None

The docker image to use.

docker_build_dir = None

The context to build the image in.

dockerfile = None

The path to the Dockerfile.

pull = None

Enforce pulling the image from a registry

cpus = None

The number of vCPUs.

memory = None

The amount of memory for the container.

command = None

The startup command.

volumes = None

The volumes for the container.

exposed_ports = None

Ports to expose on the host.

environment_variables = None

Environment variables in the container.

container = None

The container instance.

container_pid = None

The PID of the container.

command_executor = None

The executor for running commands in the container. This is useful for a scripted Workflow.

property docker_image_tag

A tag for the container’s image during build time.

Returns

The computed tag.

Return type

str

wants_ip_stack()[source]

Indicates whether a IP stack shall be installed onto the node.

Installing is handled by the Channel.

Returns

True indicates that a ns-3 IP stack shall be installed when preparing this node.

Return type

bool

prepare(simulation)[source]

This runs a setup on network interfaces and starts the container.

build_docker_image()[source]

Build the image for the container.

start_docker_container(log_directory, hosts=None)[source]

Start the docker container.

All docker containers are labeled with “ns-3” as the creator.

Parameters

  • log_directory (str) – The path to the directory to put log files in.

  • hosts (dict) – A dictionary with hostnames as keys and IP addresses (a list) as value.

stop_docker_container()[source]

Stop the container.

setup_host_interfaces()[source]

Setup the interfaces (bridge, tap, VETH pair) on the host and connect them to the container.

add_interface(interface, name=None, prefix='eth')

Add an interface to the node.

Warning: Do not call this function manually.

The functionality is handled by the network and channels.

Parameters

  • interface (Interface) – The interface to add.

  • name (str) – The name of the interface.

  • prefix (str) – If no name is supplied, the function works out a name by appending a number to the prefix.

execute_command(command, user=None)

Execute a command within the node.

Parameters

  • command (str or list of str) – The command to execute.

  • user (str) – If a user (name) is specified, the command is executed as this user. Warning: Not all nodes support this feature.

go_offline()

Disconnect the node from all channels.

go_online()

Connect the node back to all channels.

set_position(x, y, z=0)

Set the position of the node and updates the mobitlity model.

Parameters

  • x (float) – The x-position.

  • y (float) – The y-position.

  • z (float) – The z-position.

Inheritance Diagramm

Inheritance diagram of cohydra.node.docker