Appendix: Container Configuration

This section describes the properties of container configuration.

Properties

The following properties of container configuration file are supported in the expected JSON format:

Below are the supported properties in the JSON:

pod_sandbox_id <string, REQUIRED>

The ID of an existing pod sandbox to create this container under. The pod sandbox must already be created.

config <object, REQUIRED>

Configuration for creating the container.

metadata <object, REQUIRED>

Metadata of the container, used to uniquely identify it.

name <string, REQUIRED>: Container names must be unique globally, not just unique to the pod sandbox.

image <object, REQUIRED>

Image to use with this container. The image must already be pulled and exist in the local cache.

image <string, REQUIRED>: The image URI from the local cache in the form <image-uri[:tag|@digest]>. Use the qcmctl image list command to query the local cache and identify the correct URI to use.

command <array of strings, OPTIONAL>

The command to execute in the container.

Note:

This overrides the Entrypoint field in the OCI image.

args <array of strings, OPTIONAL>

The arguments for the command.

Note:

This overrides the Cmd field in the OCI image.

working_dir <string, OPTIONAL>

The current working directory to be set when launching the container command.

Note:

This overrides the WorkingDir field in the OCI image. If neither the OCI image or the above configuration has this set, it defaults to "/".

envs <array of objects, OPTIONAL>

A set of key/value pairs specifying the environment variables to set in the container.

Note:

This is merged with the Env field in the OCI image. If an environment variable with the same key exists in the OCI image, this configuration takes precedence.

Each object can specify:

key <string, REQUIRED>: The name of the environment variable.
value <string, OPTIONAL>: The value to set the environment variable to.

mounts <array of objects, OPTIONAL>

Path mappings to be applied inside the container.

Note:

The mappings from container_path → host_path are applied as process manager symbolic links.

Each object can specify:

container_path <string, REQUIRED>: Path of the mount within the Container.
host_path <string, REQUIRED>: Path of the mount on the host.

labels <array of objects, OPTIONAL>

A list of key or value pairs that may be used to scope and select individual resources.

annotations <array of objects, OPTIONAL>

A list of key or value pairs that may be used to store and retrieve arbitrary metadata. Some default annotations are defined in the OCI image spec (see table). Annotations currently used by the containers include:

org.opencontainers.image.os
org.opencontainers.image.os.version
org.opencontainers.image.architecture
org.opencontainers.image.variant
org.opencontainers.image.author
org.opencontainers.image.created
org.opencontainers.image.stopSignal

log_path <string, OPTIONAL>

Path on the host in which to store the container's output (STDOUT and STDERR), relative to the log_directory specified on the pod sandbox configuration (i.e., output would be saved to log_directory/log_path).

If log_directory was not specified on the pod sandbox, then this path is relative to Qcmgr's root_directory/containers/logs.

If the log_path is not specified, then the container ID is used by default.

stop_signal <integer, OPTIONAL>

The stop signal used by the container runtime to terminate the container. The signal values are defined by the CRI API Signal enum. This value takes precedence over any values specified in annotations or the OCI image.

qnx <object, OPTIONAL>

QNX specific configuration.

resources <object, OPTIONAL>

Resources specification for the container.

rlimits <array of objects, OPTIONAL>

Set limits on the container processes.

Note:

The limits are process-based, and each child of the parent container process inherits the same limits.

For more details on each limit, refer to prlimit(), prlimit64() of the C Library Reference.

Each object can specify:

type <string, REQUIRED>

The RLIMIT_* to apply; can be one of the following values:

RLIMIT_AS
RLIMIT_CHANNELS_NP
RLIMIT_CORE
RLIMIT_CPU
RLIMIT_DATA
RLIMIT_FREEMEM
RLIMIT_MQUEUE_NUM_NP
RLIMIT_MQUEUE_SIZE_NP
RLIMIT_NOCONN_NP
RLIMIT_NOFILE
RLIMIT_NPROC
RLIMIT_NTHR
RLIMIT_OFILE
RLIMIT_RSS
RLIMIT_SHM_HANDLES_NP
RLIMIT_SIGEVENT_NP
RLIMIT_STACK
RLIMIT_TIMERS_NP
RLIMIT_VMEM

soft <string, REQUIRED>

The soft (current) limit to set for the resource.

Note:

Setting this field to RLIM_INFINITY means no limit.

hard <string, REQUIRED>

The hard (ceiling) limit to set for the resource.

Note:

Setting this field to RLIM_INFINITY means no limit.

cpu_affinity <string, OPTIONAL>

A processor affinity mask or runmask used to associate the container processes to a specific processor or cluster of processors. This field is mutually exclusive with cpu_cluster option. For details, refer to Processor affinity, clusters, runmasks, and inherit masks in the Programmer's Guide. If not specified, this defaults to all CPUs.

cpu_cluster <string, OPTIONAL>

A CPU cluster name to associate the container processes to a specific processor or cluster of processors. This field is mutually exclusive with cpu_affinity option. For details, refer to Processor affinity, clusters, runmasks, and inherit masks in the Programmer's Guide. If not specified, this defaults to all CPUs.

security_context <object, OPTIONAL>

Security specification for the container.

run_as_user <integer, OPTIONAL>: UID to run the container process as. This overrides values from the User field in the OCI image. If the OCI image does not specify a UID, this field must be set. If a UID range was specified when starting qcmgr (via the -U option), this value must be within this range. In addition, the UID must already exist on the system.
run_as_group <integer, OPTIONAL>: GID to run the container process as. This overrides values from the User field in the OCI image. Only valid when run_as_user is specified. If a GID range was specified when starting qcmgr (via the -G option), this value must be within this range.
secpol_type <string, OPTIONAL>: The name of a security type to apply a security policy on the container processes. For details, refer to Using security policies in the System Security Guide. If not specified, the security type of qrunc is used unless a type change when spawning was forced through policy. For details, refer to default_spawn_type in the System Security Guide.

hooks <object, OPTIONAL>

Custom actions to perform during the container lifecycle as per the OCI runtime specification.

createRuntime <array of objects, OPTIONAL>

A set of commands to run as part of the create operation after the runtime environment has been created and before the mounts are applied. Path resolves in runtime environment and executes in runtime environment. A failure in any of these hooks causes the create operation to fail.

path <strings, REQUIRED>: Absolute path to run.
args <array of strings, OPTIONAL>: The arguments to pass to the program.
env <array of strings, OPTIONAL>: Environment variables to set while running the program. If unconfigured, the hook's environment is populated solely by the minimum PATH defined by QNX (defined by _CS_PATH. For details, refer to Configuration Strings in the QNX OS User's Guide If configured, only the configured variables are set. No environment variables are inherited from either the runtime or container environment.
timeout <integer, OPTIONAL>: Number of seconds to wait before aborting the hook. Must be > 0 if specified.
Note:
Omitting this field internally sets a timeout of INT64_MAX; effectively disabling the timeout.

createContainer <array of objects, OPTIONAL>

A set of commands to run as part of the create operation after the runtime environment has been created and after the mounts are applied. Path resolves in runtime environment and executes in runtime environment. A failure in any of these hooks causes the create operation to fail.

Each object can specify the same fields as in the createRuntime object.

startContainer <array of objects, OPTIONAL>

A set of commands to run as part of the start operation before the container process is started. Path resolves in container environment and executes in container environment. A failure in any of these hooks causes the start operation to fail.

Each object can specify the same fields as in the createRuntime object.

postStart <array of objects, OPTIONAL>

A set of commands to run as part of the start operation after the container process is started. Path resolves in runtime environment and executes in runtime environment. A failure in any of these hooks leads a warning being logged, but doesn't fail the start operation.

Each object can specify the same fields as in the createRuntime object

postStop <array of objects, OPTIONAL>

A set of commands to run as part of the remove operation after the container is deleted. Path resolves in runtime environment and executes in runtime environment. A failure in any of these hooks leads a warning being logged, but doesn't fail the remove operation.

Each object can specify the same fields as in the createRuntime object

Sample Configurations

View the following examples of various container configurations.

Minimal configuration

{
   "pod_sandbox_id": "581dab1756f70b116570fe4a69b41205d74c6eb8534eff88bcec8641ef16cacd",
   "config": {
      "metadata": {
         "name": "container1"
      },
      "image": {
         "image": "<aws_account_id>.dkr.ecr.us-east-1.amazonaws.com/hello-container:v0"
      },
      "qnx": {
         "security_context": {
            "run_as_user": 1000,
            "run_as_group": 1000
         }
      }
   }
}

Simple configuration for starting a user app

{
   "pod_sandbox_id": "16786af2a967444036f0b394e833e2fddfd865006b77635afa58dfc97678dc32",
      "config": {
         "metadata": {
            "name": "container2"
         },
         "image": {
            "image": "<aws_account_id>.dkr.ecr.us-east-1.amazonaws.com/my-base-image:v0"
         },
         "working_dir": "/usr/bin",
         "command": [
            "./my-app"
         ],
         "args": [
            "-i",
            "20"
         ],
         "envs": [
            {
               "key": "ENV_1",
               "value": "VAL_1"
            },
            {
               "key": "ENV_2",
               "value": "VAL_2"
            }
         ],
         "mounts": [
            {
               "container_path": "/myroot",
               "host_path": "/data/home/root"
            }
         ],
         "qnx": {
            "security_context": {
            "run_as_user": 1000,
            "run_as_group": 1000
         }
      }
   }
}

Full configuration example with all options set

{
   "pod_sandbox_id": "c6c853cce5df47816c3ae3fc2ecfb23e0493226c099e1b30447fb70f808a8e99/",
   "config": {
      [
         "metadata": {
            "name": "container3"
         },
         "image": {
            "image": "989677723404.dkr.ecr.us-east-1.amazonaws.com/my-base-image:v1"
         },
         "working_dir": "/",
         "command": [
            "/bin/tail"
         ],
         "args": [
            "-F",
            "/dev/null"
         ],
         "envs": [
            {
               "key": "ENV_1",
               "value": "VAL_1"
            },
            {
               "key": "ENV_2",
               "value": "VAL_2"
            }
         ],
         "mounts": [
            {
               "container_path": "/mydata",
               "host_path": "/data/home/root/cont3_data"
            },
            {
               "container_path": "/dev/null",
               "host_path": "/dev/null"
            },
            {
               "container_path": "/dev/socket",
               "host_path": "/dev/socket"
            },
            {
               "container_path": "/dev/random",
               "host_path": "/dev/random"
            }
         ],
      ],
      "annotations": {
         "com.example.gpu-cores": "2"
      },
      "stop_signal": 13,
      "log_path": "container3/log.txt",
      "qnx": {
         "resources": {
            "rlimits": [
               {
                  "type": "RLIMIT_CPU",
                  "soft": "10",
                  "hard": "100"
               },
               {
                  "type": "RLIMIT_NPROC",
                  "soft": "10",
                  "hard": "20"
               }
            ],
            "cpu_cluster": "_all"
         },
         "security_context": {
            "run_as_user": 101,
            "run_as_group": 101,
            "secpol_type": "type1"
         },
         "hooks": {
            "createRuntime": [
               {
                  "path": "/etc/scripts/data-setup.sh",
                  "env": [
                     "ARG1=VAL1",
                     "ARG2=VAL2"
                  ]
               }
            ],
            "createContainer": [
               {
                  "path": "chown",
                  "args": [
                     "-R",
                     "/data/home/root/cont3_data",
                     "101:101"
                  ]
               }
            ],
            "startContainer": [
               {
                  "path": "/setup_paths.sh"
               }
            ],
            "postStart": [
               {
                  "path": "/etc/scripts/upstream-notify.sh",
                  "args": [
                     "--endpoint",
                     "test_server"
                  ],
                  "env": [
                     "ARG3=VAL3"
                  ],
                  "timeout": 5
               }
            ],
            "postStop": [
               {
                  "path": "/etc/scripts/data-backup.sh"
               },
               {
                  "path": "/etc/scripts/data-flush.sh"
               }
            ]
         }
      }
   }
}

Page updated: July 16, 2026