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.

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.

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.