topology_docker.node

topology_docker base node module.

Classes

• DockerNode: An instance of this class will create a detached Docker container.

class topology_docker.node.DockerNode(identifier, image='ubuntu:latest', registry=None, command='bash', binds=None, network_mode='none', hostname=None, environment=None, privileged=True, tty=True, shared_dir_base='/tmp/topology/docker/', shared_dir_mount='/var/topology', create_host_config_kwargs=None, create_container_kwargs=None, **kwargs)

An instance of this class will create a detached Docker container.

This node binds the shared_dir_mount directory of the container to a local path in the host system defined in self.shared_dir.

Parameters:

• identifier (str) – Node unique identifier in the topology being built.
• image (str) – The image to run on this node, in the form repository:tag.
• registry (str) – Docker registry to pull image from.
• command (str) – The command to run when the container is brought up.
• binds (str) –

  Directories to bind for this container separated by a ; in the form:

  '/tmp:/tmp;/dev/log:/dev/log;/sys/fs/cgroup:/sys/fs/cgroup'
  

• network_mode (str) – Network mode for this container.
• hostname (str) – Container hostname.
• environment (list or dict) –

  Environment variables to pass to the container. They can be set as a list of strings in the following format:

  ['environment_variable=value']
  

  or as a dictionary in the following format:

  {'environment_variable': 'value'}
  

• privileged (bool) – Run container in privileged mode or not.
• tty (bool) – Whether to allocate a TTY or not to the process.
• shared_dir_base (str) – Base path in the host where the shared directory will be created. The shared directory will always have the name of the container inside this directory.
• shared_dir_mount (str) – Mount point of the shared directory in the container.
• create_host_config_kwargs (dict) – Extra kwargs arguments to pass to docker-py’s create_host_config() low-level API call.
• create_container_kwargs (dict) – Extra kwargs arguments to pass to docker-py’s create_container() low-level API call.

Read only public attributes:

Variables:

• image (str) – Name of the Docker image being used by this node. Same as the image keyword argument.
• container_id (str) – Unique container identifier assigned by the Docker daemon in the form of a hash.
• container_name (str) – Unique container name assigned by the framework in the form {identifier}_{pid}_{timestamp}.
• shared_dir (str) – Share directory in the host for this container. Always /tmp/topology/{container_name}.
• shared_dir_mount (str) – Directory inside the container where the shared_dir is mounted. Same as the shared_dir_mount keyword

_get_network_config()

Defines the network configuration for nodes of this type.

This method should be overriden when implementing a new node type to return a dictionary with its network configuration by setting the following components:

‘mapping’

This is a dictionary of dictionaries, each parent-level key defines one network category, and each category must have these three keys: netns, managed_by, and prefix, and can (optionally) have a connect_to key).

‘netns’

Specifies the network namespace (inside the docker container) where all the ports belonging to this category will be moved after their creation. If set to None, then the ports will remain in the container’s default network namespace.

‘managed_by’

Specifies who will manage different aspects of this network category depending on its value (which can be either docker or platform).

‘docker’

This network category will represent a network created by docker (identical to using the docker network create command) and will be visible to docker (right now all docker-managed networks are created using docker’s ‘bridge’ built-in network plugin, this will likely change in the near future).

‘platform’

This network category will represent ports created by the Docker Platform Engine and is invisible to docker.

‘prefix’

Defines a prefix that will be used when a port/interface is moved into a namespace, its value can be set to ‘’ (empty string) if no prefix is needed. In cases where the parent network category doesn’t have a netns (i.e. ‘netns’ is set to None) this value will be ignored.

‘connect_to’

Specifies a Docker network this category will be connected to, if this network doesn’t exists it will be created. If set to None, this category will be connected to a uniquely named Docker network that will be created by the platform.

‘default_category’

Every port that didn’t explicitly set its category (using the “category” attribute in the SZN definition) will be set to this category.

This is an example of a network configuration dictionary as expected to be returned by this funcition:

{
    'default_category': 'front_panel',
    'mapping': {
        'oobm': {
            'netns': 'oobmns',
            'managed_by': 'docker',
            'connect_to': 'oobm'
            'prefix': ''
        },
        'back_panel': {
            'netns': None,
            'managed_by': 'docker',
            'prefix': ''
        },
        'front_panel': {
            'netns': 'front',
            'managed_by': 'platform',
            'prefix': 'f_'
        }
    }
}

Returns:The dictionary defining the network configuration. Return type:dict

Inheritance

disable()

Disable the node.

In Docker implementation this pauses the container.

enable()

Enable the node.

In Docker implementation this unpauses the container.

notify_add_bilink(nodeport, bilink)

Get notified that a new bilink was added to a port of this engine node.

Parameters:

• nodeport ((pynml.nml.Node, pynml.nml.BidirectionalPort)) – A tuple with the specification node and port being linked.
• bilink (pynml.nml.BidirectionalLink) – The specification bidirectional link added.

notify_add_biport(node, biport)

Get notified that a new biport was added to this engine node.

Parameters:

• node (pynml.nml.Node) – The specification node that spawn this engine node.
• biport (pynml.nml.BidirectionalPort) – The specification bidirectional port added.

Return type:

str

Returns:

The assigned interface name of the port.

notify_post_build()

Get notified that the post build stage of the topology build was reached.

set_port_state(portlbl, state)

Set the given port label to the given state.

Parameters:

• portlbl (str) – The label of the port.
• state (bool) – True for up, False for down.

start()

Start the docker node and configures a netns for it.

stop()

Request container to stop.