Document OOME information (docker#3536)

Author: Misty Stanley-Jones

compose/compose-file/index.md

@@ -347,6 +347,16 @@ services:
           memory: 20M
 ```
 
+##### Out Of Memory Exceptions (OOME)
+
+If your services or containers attempt to use more memory than the system has
+available, you may experience an Out Of Memory Exception (OOME) and a container,
+or the Docker daemon, might be killed by the kernel OOM killer. To prevent this
+from happening, ensure that your application runs on hosts with adequate memory
+and see [Understand the risks of running out of
+memory](/engine/admin/resource_constraints.md#understand-the-risks-of-running-out-of-memory).
+
+
 #### restart_policy
 
 Configures if and how to restart containers when they exit. Replaces

engine/admin/index.md

@@ -84,6 +84,15 @@ non-responsive, you can also
 threads to be added to the daemon log by sending the `SIGUSR` signal to the
 Docker daemon.
 
+### Out Of Memory Exceptions (OOME)
+
+If your containers attempt to use more memory than the system has available,
+you may experience an Out Of Memory Exception (OOME) and a container, or the
+Docker daemon, might be killed by the kernel OOM killer. To prevent this from
+happening, ensure that your application runs on hosts with adequate memory and
+see
+[Understand the risks of running out of memory](/engine/admin/resource_constraints.md#understand-the-risks-of-running-out-of-memory).
+
 ### Read the logs
 
 The daemon logs may help you diagnose problems. The logs may be saved in one of

engine/admin/resource_constraints.md

@@ -14,6 +14,43 @@ on when you should set such limits and the possible implications of setting them
 
 ## Memory
 
+### Understand the risks of running out of memory
+
+It is important not to allow a running container to consume too much of the
+host machine's memory. On Linux hosts, if the kernel detects that there is not
+enough memory to perform important system functions, it throws an `OOME`, or
+`Out Of Memory Exception`, and starts killing processes in order to free up
+memory. Any process is subject to killing, including Docker and other important
+applications. This can effectively bring the entire system down if the wrong
+process is killed.
+
+Docker attempts to mitigate these risks by adjusting the OOM priority on the
+Docker daemon so that it will be less likely to be killed than other processes
+on the system. The OOM priority on containers is not adjusted. This makes it more
+likely that an individual container will be killed than that the Docker daemon
+or other system processes will be killed. You should not try to circumvent
+these safeguards by manually setting `--oom-score-adj` to an extreme negative
+number on the daemon or a container, or by setting `--oom-disable-kill` on a
+container.
+
+For more information about the Linux kernel's OOM management, see
+[Out of Memory Management](https://www.kernel.org/doc/gorman/html/understand/understand016.html){: target="_blank" class="_" }.  
+
+You can mitigate the risk of system instability due to OOME by:
+
+- Perform tests to understand the memory requirements of your application before
+  placing it into production.
+- Ensure that your application runs only on hosts with adequate resources.
+- Limit the amount of memory your container can use, as described below.
+- Be mindful when configuring swap on your Docker hosts. Swap is slower and
+  less performant than memory but can provide a buffer against running out of
+  system memory. 
+- Consider converting your container to a [service](/engine/swarm/services.md),
+  and using service-level constraints and node labels to ensure that the
+  application runs only on hosts with enough memory
+
+### Limit a container's access to memory
+
 Docker can enforce hard memory limits, which allow the container to use no more
 than a given amount of user or system memory, or soft limits, which allow the
 container to use as much memory as it needs unless certain conditions are met,

engine/swarm/services.md

@@ -522,6 +522,18 @@ the requirement (for instance, if you request 4 CPUs and no node in the swarm
 has 4 CPUs), the service remains in a pending state until a node is available to
 run its tasks.
 
+#### Out Of Memory Exceptions (OOME)
+
+If your service attempts to use more memory than the swarm node has available,
+you may experience an Out Of Memory Exception (OOME) and a container, or the
+Docker daemon, might be killed by the kernel OOM killer. To prevent this from
+happening. ensure that your application runs on hosts with adequate memory and
+see
+[Understand the risks of running out of memory](/engine/admin/resource_constraints.md#understand-the-risks-of-running-out-of-memory).
+
+Swarm services allow you to use resource constraints, placement preferences, and
+labels to ensure that your service is deployed to the appropriate swarm nodes.
+
 ### Specify service placement preferences (--placement-pref)
 
 {% include edge_only.md section="feature" %}