3. gc-docker

This tool generates IPU device definitions for Docker, so the IPU devices can be used inside a container. It can be used either to start a container with docker run or to display the Docker command that would be executed.

See Using IPUs from Docker for more information about Graphcore Docker images and for more examples of using gc-docker.

3.1. Start a container with IPU devices

The default action is to start a Docker container. All options and arguments specified after -- are passed directly to docker run.

Here are some examples, where {docker_opts} are options passed to docker run:

$ gc-docker -- {docker_opts} # start a container with all IPU devices
$ gc-docker --device-id {id} -- {docker_opts} # start a container with specified device
$ gc-docker --binary {docker_bin} -- {docker_opts} # specify path to the docker binary

You can specify multiple --device-id options. You can find out the available device IDs with gc-info command. If the device ID refers to multiple IPU devices, all the IPUs that are part of that ID will be available in the container.

When you select a subset of device IDs, please note that inside the container the device ID sequence always starts from 0.

Note

Docker gives each container a hostname when it is created. When using our non-Pod – PCIe – systems, this is the unique container ID. However, when using our IPU Pod systems, the assigned hostname is the underlying machine name because each container is given direct access to the host network. In this case, Docker will give multiple containers the same hostname. You can always override this behaviour by using --hostname to specify a hostname, for example:

$ gc-docker -- --hostname <name>

3.2. Show Docker command

The --echo option displays the Docker command with IPU device definitions.

An example:

$ gc-docker --echo -- {docker_opts}  # display docker command and don't start container

3.3. Usage

3.3.1. Commands

`-e, --echo`	Display docker command and don’t start a container
`-h, --help`	Produce help message
`--version`	Version number

3.3.2. Command options

`-d {arg}, --device-id {arg}`	Device id
`-b {arg}, --binary {arg}`	Docker binary (default: /usr/bin/docker)
`--no-default-env`	Don’t pass through default environment variables to the container
`--pass-env {arg}`	Environment variables to be passed to the container
`--command`	arg

3.3.3. Examples

gc-docker -- {dockers_opts}                      # start a container with all available IPU devices
gc-docker --device-id {id} -- {docker_opts}      # start a container with specified IPU device(s)
gc-docker --binary {docker_bin} -- {docker_opts} # specify path to the docker binary
gc-docker --echo -- {docker_opts}                # display docker command and don't start container

3.3.4. Notes

This command generates device definitions for docker run command.

By default a container is started with ‘docker run {docker_opts}’.

If –echo option is defined, the docker command is displayed.

You can set the path to docker with –binary option.

By default ‘–ipc=host’ will be set.

Everything after ‘–’ is passed directly to docker run.

Search help