Requirements for AWS RoboMaker compatible containers
You must meet a set of requirements to run a AWS RoboMaker Compatible Container (container image) and to start a simulation successfully. If you've met these requirements, and you're still having trouble running the simulation, see Simulation jobs and Simulation WorldForge.
Your container image can't use VOLUME in the Dockerfile. If
VOLUME is in the Dockerfile, your simulation WILL fail with a 4XX error code.
Your container image can't use EXPOSE in the Dockerfile. If
EXPOSE is in the Dockerfile, AWS RoboMaker WILL fail your simulation with a 4XX error
code.
Your container image MUST be less than or
equal to 20 GB in size compressed. If your container image is greater than 20 GB
compressed, AWS RoboMaker WILL fail the simulation with
a 4XX error code.
You can't specify CMD in your Dockerfile. If you do, AWS RoboMaker
overwrites it with the package name and launch file. Instead, you can use the
command parameter in the launchConfig of each
simulation application or robot application within your CreateSimulationJob request to provide a list of
launch commands. This is set as CMD in the simulation job. An
example command is ["/bin/bash", "-c", "sleep
365d"].
If you want to add tools to your simulation job, you MUST install bash to your container image. Your
tools are launched with ["/bin/bash", "-c",
"<command>"].
If your container is running ROS and you need communication between your robot application and your simulation application, you should set up the following robotics frameworks:
-
ROS Master
-
Gazebo Master
-
ROS IP
You can't customize the /etc/resolv.conf file in your container.
AWS RoboMaker overwrites the file with its own file.
If you're running your Dockerfile on AWS, you can't MOUNT the image. If you specify Mount in the
Dockerfile, AWS RoboMaker WILL fail your simulation
with a 4XX error code.
Your container image can't use system calls that are blocked by the default
Docker seccomp profile. For information about blocked system calls,
see Seccomp security profiles
To specify a user that runs an image, you can specify a USER
keyword in the Dockerfile. If you don't specify a user, AWS RoboMaker uses the root user
in the container.
In your container image, you can specify either the USER as
either a name or a UID:GID. If your container image doesn't have a
UID, it has a default value of 1000.
Your container image can't store data in /opt/amazon/robomaker or
in any of its subfolders. Only AWS RoboMaker can use that directory. Your simulation
might not behave properly if you use that directory.
The following runtime configurations are not supported.
| Docker Run Argument | Description | |
|---|---|---|
| 1 |
-\-add-host
|
Add a custom host-to-IP mapping (host:ip) |
| 2 |
-\-attach , -a
|
Attach to STDIN, STDOUT or STDERR |
| 3 |
-\-blkio-weight
|
Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) |
| 4 |
-\-blkio-weight-devi ce
|
Block IO weight (relative device weight) |
| 5 |
-\-cap-add
|
Add Linux capabilities |
| 6 |
-\-cap-drop
|
Drop Linux capabilities |
| 7 |
-\-cgroup-parent
|
Optional parent cgroup for the container |
| 8 |
-\-cgroupns
|
API 1.41+ <https://docs.d ocker.com/engine/api/ v1.41/>__Cgroup namespace to use (host|private) 'host': Run the container in the Docker host's cgroup namespace 'private': Run the container in its own private cgroup namespace '': Use the cgroup namespace as configured by the default-cgroupns-mode option on the daemon (default) |
| 9 |
-\-cidfile
|
Write the container ID to the file |
| 10 |
-\-cpu-count
|
CPU count (Windows only) |
| 11 |
-\-cpu-percent
|
CPU percent (Windows only) |
| 12 |
-\-cpu-period
|
Limit CPU CFS (Completely Fair Scheduler) period |
| 13 |
-\-cpu-quota
|
Limit CPU CFS (Completely Fair Scheduler) quota |
| 14 |
-\-cpu-rt-period
|
API 1.25+ <https://docs.d ocker.com/engine/api/ v1.25/>__Limit CPU real-time period in microseconds |
| 15 |
-\-cpu-rt-runtime
|
API 1.25+ <https://docs.d ocker.com/engine/api/ v1.25/>__Limit CPU real-time runtime in microseconds |
| 16 |
-\-cpu-shares , -c
|
CPU shares (relative weight) |
| 17 |
-\-cpus
|
API 1.25+ <https://docs.d ocker.com/engine/api/ v1.25/>__Number of CPUs |
| 18 |
-\-cpuset-cpus
|
CPUs in which to allow execution (0-3, 0,1) |
| 19 |
-\-cpuset-mems
|
MEMs in which to allow execution (0-3, 0,1) |
| 20 |
-\-detach , -d
|
Run container in background and print container ID |
| 21 |
-\-detach-keys
|
Override the key sequence for detaching a container |
| 22 |
-\-device
|
Add a host device to the container |
| 23 |
-\-device-cgroup-rul e
|
Add a rule to the cgroup allowed devices list |
| 24 |
-\-device-read-bps
|
Limit read rate (bytes per second) from a device |
| 25 |
-\-device-read-iops
|
Limit read rate (IO per second) from a device |
| 26 |
-\-device-write-bps
|
Limit write rate (bytes per second) to a device |
| 27 |
-\-device-write-iops
|
Limit write rate (IO per second) to a device |
| 28 |
-\-disable-content-t rust
|
Skip image verification |
| 29 |
-\-dns
|
Set custom DNS servers |
| 30 |
-\-dns-opt
|
Set DNS options |
| 31 |
-\-dns-option
|
Set DNS options |
| 32 |
-\-dns-search
|
Set custom DNS search domains |
| 33 |
-\-domainname
|
Container NIS domain name |
| 34 |
-\-gpus
|
API 1.40+ <https://docs.d ocker.com/engine/api/ v1.40/>__GPU devices to add to the container ('all' to pass all GPUs) |
| 35 |
-\-group-add
|
Add additional groups to join |
| 36 |
-\-health-cmd
|
Command to run to check health |
| 37 |
-\-health-interval
|
Time between running the check (msm|h) (default 0s) |
| 38 |
-\-health-retries
|
Consecutive failures needed to report unhealthy |
| 39 |
-\-health-start-peri od
|
API 1.29+ <https://docs.d ocker.com/engine/api/ v1.29/>__Start period for the container to initialize before starting health-retries countdown (msm|h) (default 0s) |
| 40 |
-\-health-timeout
|
Maximum time to allow one check to run (msm|h) (default 0s) |
| 41 |
-\-help
|
Print usage |
| 42 |
-\-hostname , -h
|
Container host name |
| 43 |
-\-init
|
API 1.25+ <https://docs.d ocker.com/engine/api/ v1.25/>__Run an init inside the container that forwards signals and reaps processes |
| 44 |
-\-interactive , -i
|
Keep STDIN open even if not attached |
| 45 |
-\-io-maxbandwidth
|
Maximum IO bandwidth limit for the system drive (Windows only) |
| 46 |
-\-io-maxiops
|
Maximum IOps limit for the system drive (Windows only) |
| 47 |
-\-ip
|
IPv4 address (e.g., 172.30.100.104) |
| 48 |
-\-ip6
|
IPv6 address (e.g., 2001:db8::33) |
| 49 |
-\-ipc
|
IPC mode to use |
| 50 |
-\-isolation
|
Container isolation technology |
| 51 |
-\-kernel-memory
|
Kernel memory limit |
| 52 |
-\-label , -l
|
Set meta data on a container |
| 53 |
-\-label-file
|
Read in a line delimited file of labels |
| 54 |
-\-link
|
Add link to another container |
| 55 |
-\-link-local-ip
|
Container IPv4/IPv6 link-local addresses |
| 56 |
-\-log-driver
|
Logging driver for the container |
| 57 |
-\-log-opt
|
Log driver options |
| 58 |
-\-mac-address
|
Container MAC address (e.g., 92:d0:c6:0a:29:33) |
| 59 |
-\-memory , -m
|
Memory limit |
| 60 |
-\-memory-reservation
|
Memory soft limit |
| 61 |
-\-memory-swap
|
Swap limit equal to memory plus swap: '-1' to enable unlimited swap |
| 62 |
-\-memory-swappiness
|
Tune container memory swappiness (0 to 100) |
| 63 |
-\-name
|
Assign a name to the container |
| 64 |
-\-net
|
Connect a container to a network |
| 65 |
-\-net-alias
|
Add network-scoped alias for the container |
| 66 |
-\-network
|
Connect a container to a network |
| 67 |
-\-network-alias
|
Add network-scoped alias for the container |
| 68 |
-\-no-healthcheck
|
Disable any container-specified HEALTHCHECK |
| 69 |
-\-oom-kill-disable
|
Disable OOM Killer |
| 70 |
-\-oom-score-adj
|
Tune host's OOM preferences (-1000 to 1000) |
| 71 |
-\-pid
|
PID namespace to use |
| 72 |
-\-pids-limit
|
Tune container pids limit (set -1 for unlimited) |
| 73 |
-\-platform
|
API 1.32+ <https://docs.d ocker.com/engine/api/ v1.32/>__Set platform if server is multi-platform capable |
| 74 |
-\-privileged
|
Give extended privileges to this container |
| 75 |
-\-publish , -p
|
Publish a container's port(s) to the host |
| 76 |
-\-publish-all , -P
|
Publish all exposed ports to random ports |
| 77 |
-\-pull
|
Pull image before running ("always" " never") |
| 78 |
-\-read-only
|
Mount the container's root filesystem as read only |
| 79 |
-\-restart
|
Restart policy to apply when a container exits |
| 80 |
-\-rm
|
Automatically remove the container when it exits |
| 81 |
-\-runtime
|
Runtime to use for this container |
| 82 |
-\-security-opt
|
Security Options |
| 83 |
-\-shm-size
|
Size of /dev/shm |
| 84 |
-\-sig-proxy
|
Proxy received signals to the process |
| 85 |
-\-stop-timeout
|
API 1.25+ <https://docs.d ocker.com/engine/api/ v1.25/>__Timeout (in seconds) to stop a container |
| 86 |
-\-storage-opt
|
Storage driver options for the container |
| 87 |
-\-sysctl
|
Sysctl options |
| 88 |
-\-tmpfs
|
Mount a tmpfs directory |
| 89 |
-\-tty , -t
|
Allocate a pseudo-TTY |
| 90 |
-\-ulimit
|
Ulimit options |
| 91 |
-\-userns
|
User namespace to use |
| 92 |
-\-uts
|
UTS namespace to use |
| 93 |
-\-volume , -v
|
Bind mount a volume |
| 94 |
-\-volume-driver
|
Optional volume driver for the container |
| 95 |
-\-volumes-from
|
Mount volumes from the specified container(s) |
If you run a simulation job with the preceding runtime configurations, AWS RoboMaker
WILL fail your simulation with a
4XX error code.
Your container image:
-
MUST be Open Container Initiative (OCI)
complaint. -
MUST be built for the X86_64 architecture. If it's built for a different architecture, AWS RoboMaker WILL fail the simulation with a
4XXerror code. -
MUST be less than or equal to 40 GB in size uncompressed. If your container image is greater than 40 GB uncompressed, AWS RoboMaker WILL fail the simulation with a
4XXerror code. -
MUST have a V2 image manifest, schema version 2 compatible.
-
MUST use a base image that is based on Linux. If you don't use a base image that is based on Linux, AWS RoboMaker WILL fail the simulation with a
4XXerror code. -
MUST use a development environment and operating system that are compatible with each other. The following are examples of compatible combinations of development environments and operating systems:
-
Robot Operating System (ROS) Melodic – ubuntu:bionic
-
Robot Operating System (ROS) 2 Foxy – ubuntu:focal
If you don't use a compatible combination of robotics framework and operating system, your simulation might show unexpected behavior.
-
The following are the binary requirements for your container image:
To support GUI streaming, we recommend installing and sourcing the following binaries:
-
devilspie
We recommend that your container image use absolute paths for its executables. We also recommend that the executable inside the container runs correctly. Your simulation WILL fail if it can't find the path to your executables.
Your container image:
-
MUST have glvnd installed if using OpenGL in your applications.
-
MUST have NVIDIA CUDA 11.2 or lower if using CUDA in your applications.
-
MUST have OpenGL version 4.6 or lower if using OpenGL in your applications.
-
MUST have Vulkan version 1.2 or lower if using Vulkan APIs in your applications.
-
MUST have OpenCL version 1.2 or lower if using OpenCL in your applications.
Note
AWS RoboMaker supports Vulkan only for offscreen rendering and is not operational
in GUI displays. So, streamUI should be set to false if using
Vulkan.
For detailed instructions on how GPU images can be created, see Creating images to run GPU applications.
A container image MUST provide an entrypoint
script for sourcing. The entrypoint script MUST
have exec "${@:1}" as the last line so that AWS RoboMaker can run the
entrypoint script. Running the entrypoint script gives you the ability to use
the roslaunch command.
package-namelaunch-file command to run the containers.
Your container image can't use VOLUME in the Dockerfile. If
VOLUME is in the Dockerfile, your simulation WILL fail with a 4XX error code.
The EXPOSE keyword in your Dockerfile is ignored by AWS RoboMaker. Any
ports exposed by the EXPOSE keyword are not automatically exposed
by the system. If you would like to expose ports on your simulation, you can use
AWS RoboMaker port forwarding configuration.
AWS RoboMaker uses the following environment variables. If you run your simulation on AWS, AWS RoboMaker overwrites any value that you specify for these environment variables:
-
ROBOMAKER* -
DCV_VIRTUAL_SESSION -
XDG_SESSION_ID -
DCV_SESSION_ID -
XDG_SESSION_TYPE -
XDG_RUNTIME_DIR -
SHLVL -
XAUTHORITY
You can't specify CMD in your Dockerfile. If you do, AWS RoboMaker
overwrites with the command in your simulation launchConfig.
If your container is running ROS and you need communication between your robot application and your simulation application, you should set up the following robotics frameworks:
-
ROS Master
-
Gazebo Master
-
ROS IP
You can't customize the /etc/resolv.conf file in your container.
AWS RoboMaker overwrites the file with its own file.
If you're running your Dockerfile on AWS, you can't MOUNT the image. If you specify Mount in the
Dockerfile, AWS RoboMaker WILL fail your simulation
with a 4XX error code.
Your container image can't use system calls that are blocked by the default
Docker seccomp profile. For information about blocked system calls,
see Seccomp security profiles
To specify a user that runs an image, you can specify a USER
keyword in the Dockerfile. If you don't specify a user, AWS RoboMaker uses the root user
in the container.
In your container image, you can specify the USER as either a
name or a UID:GID. If your container image doesn't have a UID, it
has a default value of 1000.
Your container image can't store data in /opt/amazon/robomaker or
in any of its subfolders. Only AWS RoboMaker can use that directory. Your simulation
might not behave properly if you use that directory.
The following runtime configurations are not supported.
| Docker Run Argument | Description | |
|---|---|---|
| 1 |
--add-host
|
Add a custom host-to-IP mapping (host:ip) |
| 2 |
--attach , -a
|
Attach to STDIN, STDOUT or STDERR |
| 3 |
--blkio-weight
|
Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) |
| 4 |
--blkio-weight-devi ce
|
Block IO weight (relative device weight) |
| 5 |
--cap-add
|
Add Linux capabilities |
| 6 |
--cap-drop
|
Drop Linux capabilities |
| 7 |
--cgroup-parent
|
Optional parent cgroup for the container |
| 8 |
--cgroupns
|
API 1.41+ <https://docs.d ocker.com/engine/api/ v1.41/>__Cgroup namespace to use (host|private) 'host': Run the container in the Docker host's cgroup namespace 'private': Run the container in its own private cgroup namespace '': Use the cgroup namespace as configured by the default-cgroupns-mode option on the daemon (default) |
| 9 |
--cidfile
|
Write the container ID to the file |
| 10 |
--cpu-count
|
CPU count (Windows only) |
| 11 |
--cpu-percent
|
CPU percent (Windows only) |
| 12 |
--cpu-period
|
Limit CPU CFS (Completely Fair Scheduler) period |
| 13 |
--cpu-quota
|
Limit CPU CFS (Completely Fair Scheduler) quota |
| 14 |
--cpu-rt-period
|
API 1.25+ <https://docs.d ocker.com/engine/api/ v1.25/>__Limit CPU real-time period in microseconds |
| 15 |
--cpu-rt-runtime
|
API 1.25+ <https://docs.d ocker.com/engine/api/ v1.25/>__Limit CPU real-time runtime in microseconds |
| 16 |
--cpu-shares , -c
|
CPU shares (relative weight) |
| 17 |
--cpus
|
API 1.25+ <https://docs.d ocker.com/engine/api/ v1.25/>__Number of CPUs |
| 18 |
--cpuset-cpus
|
CPUs in which to allow execution (0-3, 0,1) |
| 19 |
--cpuset-mems
|
MEMs in which to allow execution (0-3, 0,1) |
| 20 |
--detach , -d
|
Run container in background and print container ID |
| 21 |
--detach-keys
|
Override the key sequence for detaching a container |
| 22 |
--device
|
Add a host device to the container |
| 23 |
--device-cgroup-rul e
|
Add a rule to the cgroup allowed devices list |
| 24 |
--device-read-bps
|
Limit read rate (bytes per second) from a device |
| 25 |
--device-read-iops
|
Limit read rate (IO per second) from a device |
| 26 |
--device-write-bps
|
Limit write rate (bytes per second) to a device |
| 27 |
--device-write-iops
|
Limit write rate (IO per second) to a device |
| 28 |
--disable-content-t rust
|
Skip image verification |
| 29 |
--dns
|
Set custom DNS servers |
| 30 |
--dns-opt
|
Set DNS options |
| 31 |
--dns-option
|
Set DNS options |
| 32 |
--dns-search
|
Set custom DNS search domains |
| 33 |
--domainname
|
Container NIS domain name |
| 34 |
--gpus
|
API 1.40+ <https://docs.d ocker.com/engine/api/ v1.40/>__GPU devices to add to the container ('all' to pass all GPUs) |
| 35 |
--group-add
|
Add additional groups to join |
| 36 |
--health-cmd
|
Run to check health |
| 37 |
--health-interval
|
Time between running the check (msm|h) (default 0s) |
| 38 |
--health-retries
|
Consecutive failures needed to report unhealthy |
| 39 |
--health-start-peri od
|
API 1.29+ <https://docs.d ocker.com/engine/api/ v1.29/>__Start period for the container to initialize before starting health-retries countdown (msm|h) (default 0s) |
| 40 |
--health-timeout
|
Maximum time to allow one check to run (msm|h) (default 0s) |
| 41 |
--help
|
Print usage |
| 42 |
--hostname , -h
|
Container host name |
| 43 |
--init
|
API 1.25+ <https://docs.d ocker.com/engine/api/ v1.25/>__Run an init inside the container that forwards signals and reaps processes |
| 44 |
--interactive , -i
|
Keep STDIN open even if not attached |
| 45 |
--io-maxbandwidth
|
Maximum IO bandwidth limit for the system drive (Windows only) |
| 46 |
--io-maxiops
|
Maximum IOps limit for the system drive (Windows only) |
| 47 |
--ip
|
IPv4 address (e.g., 172.30.100.104) |
| 48 |
--ip6
|
IPv6 address (e.g., 2001:db8::33) |
| 49 |
--ipc
|
IPC mode to use |
| 50 |
--isolation
|
Container isolation technology |
| 51 |
--kernel-memory
|
Kernel memory limit |
| 52 |
--label , -l
|
Set meta data on a container |
| 53 |
--label-file
|
Read in a line delimited file of labels |
| 54 |
--link
|
Add link to another container |
| 55 |
--link-local-ip
|
Container IPv4/IPv6 link-local addresses |
| 56 |
--log-driver
|
Logging driver for the container |
| 57 |
--log-opt
|
Log driver options |
| 58 |
--mac-address
|
Container MAC address (e.g., 92:d0:c6:0a:29:33) |
| 59 |
--memory , -m
|
Memory limit |
| 60 |
--memory-reservation
|
Memory soft limit |
| 61 |
--memory-swap
|
Swap limit equal to memory plus swap: '-1' to enable unlimited swap |
| 62 |
--memory-swappiness
|
Tune container memory swappiness (0 to 100) |
| 63 |
--name
|
Assign a name to the container |
| 64 |
--net
|
Connect a container to a network |
| 65 |
--net-alias
|
Add network-scoped alias for the container |
| 66 |
--network
|
Connect a container to a network |
| 67 |
--network-alias
|
Add network-scoped alias for the container |
| 68 |
--no-healthcheck
|
Disable any container-specified HEALTHCHECK |
| 69 |
--oom-kill-disable
|
Disable OOM Killer |
| 70 |
--oom-score-adj
|
Tune host's OOM preferences (-1000 to 1000) |
| 71 |
--pid
|
PID namespace to use |
| 72 |
--pids-limit
|
Tune container pids limit (set -1 for unlimited) |
| 73 |
--platform
|
API 1.32+ <https://docs.d ocker.com/engine/api/ v1.32/>__Set platform if server is multi-platform capable |
| 74 |
--privileged
|
Give extended privileges to this container |
| 75 |
--publish , -p
|
Publish a container's port(s) to the host |
| 76 |
--publish-all , -P
|
Publish all exposed ports to random ports |
| 77 |
--pull
|
Pull image before running ("always" " never") |
| 78 |
--read-only
|
Mount the container's root filesystem as read only |
| 79 |
--restart
|
Restart policy to apply when a container exits |
| 80 |
--rm
|
Automatically remove the container when it exits |
| 81 |
--runtime
|
Runtime to use for this container |
| 82 |
--security-opt
|
Security Options |
| 83 |
--shm-size
|
Size of /dev/shm |
| 84 |
--sig-proxy
|
Proxy received signals to the process |
| 85 |
--stop-timeout
|
API 1.25+ <https://docs.d ocker.com/engine/api/ v1.25/>__Timeout (in seconds) to stop a container |
| 86 |
--storage-opt
|
Storage driver options for the container |
| 87 |
--sysctl
|
Sysctl options |
| 88 |
--tmpfs
|
Mount a tmpfs directory |
| 89 |
--tty , -t
|
Allocate a pseudo-TTY |
| 90 |
--ulimit
|
Ulimit options |
| 91 |
--userns
|
User namespace to use |
| 92 |
--uts
|
UTS namespace to use |
| 93 |
--volume , -v
|
Bind mount a volume |
| 94 |
--volume-driver
|
Optional volume driver for the container |
| 95 |
--volumes-from
|
Mount volumes from the specified container(s) |
If you run a simulation job with the preceding runtime configurations, AWS RoboMaker
WILL fail your simulation with a
4XX error code.
