Container management configuration

Customize the deployment and management of containers.

1: Container configuration
2: Manager configuration

1 - Container configuration

Customize the deployment of a container instance.

Properties

To control all aspects of the container instance behavior.

Property	Type	Default	Description
container_name	string	<container_id>	User-defined name for the container, if omitted the internally auto-generated container ID will be set
Image
name	string		Fully qualified image reference, that follows the OCI Image Specification, the format is: `host[:port]/[namespace/]name:tag`
Image - decryption
keys	string[]		Private keys (GPG private key ring, JWE or PKCS7) used for decrypting the container’s image, the format is: `filepath_private_key[:password]`
recipients	string[]		Recipients (only for PKCS7 and must be an x509) used for decrypting the container’s image, the format is: `pkcs7:filepath_x509_certificate`
Networking
domain_name	string	<container_name>-domain	Domain name inside the container, if omitted the `container_name` with suffix -domain will be set
host_name	string	<container_name>-host	Host name for the container, if omitted the `container_name` with suffix -host will be set
network_mode	string	bridge	The container’s networking capabilities type based on the desired communication mode, the possible options are: bridge or host
extra_hosts	string[]		Extra host name to IP address mappings added to the container network configuration, the format is: `hostname:ip`. If the IP of the host machine is to be added to the container’s hosts file the reserved host_ip[_<network-interface>] must be provided. If only host_ip (the network-interface part is skipped) is used, by default it will be resolved to the host’s IP on the default bridge network interface for containerm (the default configuration is kanto-cm0) and add it to the container’s hosts file. If the IP of a container in the same bridge network is to be added to the hosts file the reserved container_<container-host_name> must be provided.
Networking - port mappings
proto	string	tcp	Protocol used for the port mapping from the container to the host, the possible options are: tcp and udp
container_port	int		Port number on the container that is mapped to the host port
host_ip	string	0.0.0.0	Host IP address
host_port	int		Beginning of the host ports range
host_port_end	int	<host_port>	Ending of the host ports range
Host resources - devices
path_on_host	string		Path to the device on the host
path_in_container	string		Path to the device in the container
cgroup_permissions	string	rwm	Cgroup permissions for the device access, possible options are: r(read), w(write), m(mknod) and all combinations are possible
privileged	bool	false	Grant root capabilities to all devices on the host system
Host resources - mount points
source	string		Path to the file or directory on the host that is referred from within the container
destination	string		Path to the file or directory that is mounted inside the container
propagation_mode	string	rprivate	Bind propagation for the mount, supported are: rprivate, private, rshared, shared, rslave or slave
Process
env	string[]		Environment variables that are set into the container
cmd	string[]		Command with arguments that is executed upon the container’s start
I/O
open_stdin	bool		Open the terminal’s standard input for an interaction with the current container
tty	bool		Attach standard streams to a TTY
Resource management
memory	string		Hard memory limitation of the container as a number with a unit suffix of B, K, M and G, the minimum allowed value is 3M
memory_reservation	string		Soft memory limitation of the container as a number with a unit suffix of B, K, M and G, if `memory` is specified, the `memory_reservation` must be smaller than it
memory_swap	string		Total amount of memory and swap that the container can use as a number with a unit suffix of B, K, M and G, use -1 to allow the container to use unlimited swap
Lifecycle
type	string	unless-stopped	The container’s restart policy, the supported types are: always, no, on-failure and unless-stopped
maximum_retry_count	int		Maximum number of retries that are made to restart the container on exit with fail, if the `type` is on-failure
retry_timeout	int		Timeout period in seconds for each retry that is made to restart the container on exit with fail, if the `type` is on-failure
Logging
type	string	json-file	Type in which the logs are produced, the possible options are: json-file or none
max_files	int	2	Maximum log files before getting rotated
max_size	string	100M	Maximum log file size before getting rotated as a number with a unit suffix of B, K, M and G
root_dir	string	<meta_path>/containers/<container_id>	Root directory where the container’s log messages are stored
mode	string	blocking	Messaging delivery mode from the container to the log driver, the supported modes are: blocking and non-blocking
max_buffer_size	string	1M	Maximum size of the buffered container’s log messages in a non-blocking mode as a number with a unit suffix of B, K, M and G

Example

The minimal required configuration to spin up an InfluxDB container instance.

{
  "image": {
    "name": "docker.io/library/influxdb:1.8.4"
  }
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

Be aware that some combinations may require property removal

{
    "container_name": "",
    "image": {
        "name": "",
        "decrypt_config": {
            "keys": [],
            "recipients": []
        }
    },
    "domain_name": "",
    "host_name": "",
    "mount_points": [
        {
            "destination": "",
            "source": "",
            "propagation_mode": "rprivate"
        }
    ],
    "config": {
        "env": [],
        "cmd": []
    },
    "io_config": {
        "open_stdin": false,
        "tty": false
    },
    "host_config": {
        "devices": [
            {
                "path_on_host": "",
                "path_in_container": "",
                "cgroup_permissions": "rwm"
            }
        ],
        "network_mode": "bridge",
        "privileged": false,
        "extra_hosts": [],
        "port_mappings": [
            {
                "proto": "tcp",
                "container_port": 0,
                "host_ip": "0.0.0.0",
                "host_port": 0,
                "host_port_end": 0
            }
        ],
        "resources": {
            "memory": "",
            "memory_reservation": "",
            "memory_swap": ""
        },
        "restart_policy": {
            "type": "unless-stopped",
            "maximum_retry_count": 0,
            "retry_timeout": 0
        },
        "log_config": {
            "driver_config": {
                "type": "json-file",
                "max_files": 2,
                "max_size": "100M",
                "root_dir": ""
            },
            "mode_config": {
                "mode": "blocking",
                "max_buffer_size": "1M"
            }
        }
    }
}

2 - Manager configuration

Customize the container manager components.

Properties

To control all aspects of the container manager behavior.

Property	Type	Default	Description
home_dir	string	/var/lib/container-management	Home directory for the container manager data
exec_root_dir	string	/var/run/container-management	Root directory for the container manager’s executable artifacts
container_client_sid	string	container-management.service.local.v1.service-containerd-client	Unique identifier that is used for an interaction with the runtime
network_manager_sid	string	container-management.service.local.v1.service-libnetwork-manager	Unique identifier that is used for networking
default_ctrs_stop_timeout	int	30	Timeout in seconds for a container to stop gracefully, otherwise its root process will be force stopped
Runtime
default_ns	string	kanto-cm	Namespace that is used by the runtime for isolation
address_path	string	/run/containerd/containerd.sock	Path to the runtime’s communication endpoint
home_dir	string	/var/lib/container-management	Home directory for the runtime data
exec_root_dir	string	/var/run/container-management	Root directory for the runtime’s executable artifacts
image_dec_keys	string[]		Private keys (GPG private key ring, JWE or PKCS7) used for decrypting container images, the format is: `filepath_private_key[:password]`
image_dec_recipients	string[]		Recipients (only for PKCS7 and must be an x509) used for decrypting container images, the format is: `pkcs7:filepath_x509_certificate`
runc_runtime	string	io.containerd.runc.v2	Runc communication mode, the possible values are: io.containerd.runtime.v1.linux, io.containerd.runc.v1 and io.containerd.runc.v2
image_expiry	string	744h	Time period for the cached images and content to be kept in the form of e.g. 72h3m0.5s
image_expiry_disable	bool	false	Disable expiry management of cached images and content, must be used with caution as it may lead to large memory volumes being persistently allocated
lease_id	string	kanto-cm.lease	Lease identifier to be used for container resources persistence
Registry access - secure
user_id	string		User unique identifier to authenticate to the image registry
password	string		Password to authenticate to the image registry
root_ca	string		PEM encoded CA certificates file
client_cert	string		PEM encoded certificate file to authenticate to the image registry
client_key	string		PEM encoded unencrypted private key file to authenticate to the image registry
Registry access - insecure
insecure_registries	string[]	localhost	Image registries that do not use valid certificates or do not require a HTTPS connection, the format is: `host[:port]`
Networking
home_dir	string	/var/lib/container-management	Home directory for the network manager data
exec_root_dir	string	/var/run/container-management	Root directory for the network manager’s executable artifacts
Networking - bridge
name	string	kanto-cm0	Bridge name
ip4	string		Bridge IPv4 address
fcidr4	string		IPv4 address range for the bridge, using the standard CIDR notation
gwip4	string		Bridge gateway IPv4 address
enable_ip6	bool	false	Permit the bridge IPv6 support
mtu	int	1500	Bridge maximum transmission unit in bytes
icc	bool	true	Permit the inter-container communication
ip_tables	bool	true	Permit the IP tables rules
ip_forward	bool	true	Permit the IP forwarding
ip_masq	bool	true	Permit the IP masquerading
userland_proxy	bool	false	Forbid the userland proxy for the loopback traffic
Local communication
protocol	string	unix	Communication protocol used for accessing the gRPC server, the possible values are: tcp, tcp4, tcp6, unix or unixpacket
address_path	string	/run/container-management/container-management.sock	Path to the gRPC server’s communication endpoint
Digital twin
enable	bool	true	Permit the container manager digital twin representation
home_dir	string	/var/lib/container-management	Home directory for the digital twin data
features	string[]	ContainerFactory, SoftwareUpdatable, Metrics	Features that will be registered for the container manager digital twin, the possible values are: ContainerFactory, SoftwareUpdatable and Metrics
Digital twin - connectivity
broker_url	string	tcp://localhost:1883	Address of the MQTT server/broker that the container manager will connect for the local communication, the format is: `scheme://host:port`
keep_alive	int	20000	Keep alive duration in milliseconds for the MQTT requests
disconnect_timeout	int	250	Disconnect timeout in milliseconds for the MQTT server/broker
client_username	string		Username that is a part of the credentials
client_password	string		Password that is a part of the credentials
connect_timeout	int	30000	Connect timeout in milliseconds for the MQTT server/broker
acknowledge_timeout	int	15000	Acknowledge timeout in milliseconds for the MQTT requests
subscribe_timeout	int	15000	Subscribe timeout in milliseconds for the MQTT requests
unsubscribe_timeout	int	5000	Unsubscribe timeout in milliseconds for the MQTT requests
Digital twin - connectivity - TLS
root_ca	string		PEM encoded CA certificates file
client_cert	string		PEM encoded certificate file to authenticate to the MQTT server/broker
client_key	string		PEM encoded unencrypted private key file to authenticate to the MQTT server/broker
Logging
log_file	string	log/container-management.log	Path to the file where the container manager’s log messages are written
log_level	string	INFO	All log messages at this or a higher level will be logged, the log levels in descending order are: ERROR, WARN, INFO, DEBUG and TRACE
log_file_count	int	5	Log file maximum rotations count
log_file_max_age	int	28	Log file rotations maximum age in days, use 0 to not remove old log files
log_file_size	int	2	Log file size in MB before it gets rotated
syslog	bool	false	Route logs to the local syslog
Deployment
enable	bool	true	Permit the deployment manager service providing installation/update of containers via the container descriptor files
mode	string	update	Deployment manager mode, the possible values are: init (container descriptors are processed only on first start, new containers are deployed and started), update (container descriptors are processed on each restart, new containers can be deployed and started, existing containers may be updated, no container removals)
home_dir	string	/var/lib/container-management	Home directory for the deployment manager data
ctr_dir	string	/etc/container-management/containers	Directory containing descriptors of containers that will be automatically deployed on first start or updated on restart

Example

The minimal required configuration that sets a timeout period of 5 seconds for the managed containers to stop gracefully.

{
    "manager": {
        "default_ctrs_stop_timeout": 5
    },
    "log": {
        "log_file": "/var/log/container-management/container-management.log"
    }
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

Be aware that in the registry configuration the host (used as a key) has to be set instead of the default empty string, the format is: host[:port]

{
    "manager": {
        "home_dir": "/var/lib/container-management",
        "exec_root_dir": "/var/run/container-management",
        "container_client_sid": "container-management.service.local.v1.service-containerd-client",
        "network_manager_sid": "container-management.service.local.v1.service-libnetwork-manager",
        "default_ctrs_stop_timeout": 30
    },
    "containers": {
        "default_ns": "kanto-cm",
        "address_path": "/run/containerd/containerd.sock",
        "exec_root_dir": "/var/run/container-management",
        "home_dir": "/var/lib/container-management",
        "image_dec_keys": [],
        "image_dec_recipients": [],
        "runc_runtime": "io.containerd.runc.v2",
        "image_expiry": "744h",
        "image_expiry_disable": false,
        "lease_id": "kanto-cm.lease",
        "registry_configurations": {
            "": {
                "credentials": {
                    "user_id": "",
                    "password": ""
                },
                "transport": {
                    "root_ca": "",
                    "client_cert": "",
                    "client_key": ""
                }
            }
        },
        "insecure_registries": [
            "localhost"
        ]
    },
    "network": {
        "home_dir": "/var/lib/container-management",
        "exec_root_dir": "/var/run/container-management",
        "default_bridge": {
            "name": "kanto-cm0",
            "ip4": "",
            "fcidr4": "",
            "enable_ip6": false,
            "mtu": 1500,
            "icc": true,
            "ip_tables": true,
            "ip_forward": true,
            "ip_masq": true,
            "userland_proxy": false
        }
    },
    "grpc_server": {
        "protocol": "unix",
        "address_path": "/run/container-management/container-management.sock"
    },
    "things": {
        "enable": true,
        "home_dir": "/var/lib/container-management",
        "features": [
            "ContainerFactory",
            "SoftwareUpdatable",
            "Metrics"
        ],
        "connection": {
            "broker_url": "tcp://localhost:1883",
            "keep_alive": 20000,
            "disconnect_timeout": 250,
            "client_username": "",
            "client_password": "",
            "connect_timeout": 30000,
            "acknowledge_timeout": 15000,
            "subscribe_timeout": 15000,
            "unsubscribe_timeout": 5000,
            "transport": {
                "root_ca": "",
                "client_cert": "",
                "client_key": ""
            }
        }
    },
    "log": {
        "log_file": "log/container-management.log",
        "log_level": "INFO",
        "log_file_count": 5,
        "log_file_size": 2,
        "log_file_max_age": 28,
        "syslog": false
    },
    "deployment": {
        "enable": true,
        "mode": "update",
        "home_dir": "/var/lib/container-management",
        "ctr_dir": "/etc/container-management/containers"
    }
}