What does --memory-reservation flag do in practice?

Question

Docs say:

Under this configuration, when the container consumes memory more than 200M and less than 500M, the next system memory reclaim attempts to shrink container memory below 200M.

But what does this actually mean?

Let's say I have a container running Solr, and:
docker run -m 1G --memory-reservation 768M solr

What effect does it have on the Solr process inside the container when it starts using 800M memory? Nothing?

Is it only if/when memory usage subsequently drops below 768M... this flag allows docker to reclaim the memory from the solr container? ...otherwise the container would continue to consume whatever the high-water memory usage was?

How does this relate to swarm scheduling? If swarm always allocates 1G for the container because of -m then is --memory-reservation not useful in this context?

Answer 1

The --memory-reservation option sets up cgroup in the container to ensure that at least 800Mb can be allocated to the process. In case cgroup_v1 this value can be found in memory.soft_limit_in_bytes. You can read the (outdated) manual under the 'Soft limits' section. In the case of cgroup_v2 this setting can be found in memory.low file. Read more in cgroup_v2 documentation.

More info on the reclaim process is here: http://linux-mm.org/PageOutKswapd

From what I can tell, your Solr process can use 800MB and as long as there is no contention from other cgroups then memory won't be reclaimed. It can keep the memory and use up to the hard limit of 1GB. If there is contention then the kernel will attempt to reclaim the memory but as per the doc's soft limits is a best-effort feature.. no guarantees.