Add comments

2 files changed, 10 insertions, 0 deletions

diff --git a/docker-api/src/main/java/com/yahoo/vespa/hosted/dockerapi/ContainerResources.java b/docker-api/src/main/java/com/yahoo/vespa/hosted/dockerapi/ContainerResources.java
index 58347a1e8fd..36b7c35afc4 100644
--- a/docker-api/src/main/java/com/yahoo/vespa/hosted/dockerapi/ContainerResources.java
+++ b/docker-api/src/main/java/com/yahoo/vespa/hosted/dockerapi/ContainerResources.java
@@ -10,8 +10,17 @@ public class ContainerResources {
     public static final ContainerResources UNLIMITED = ContainerResources.from(0, 0, 0);
     private static final int CPU_PERIOD = 100_000; // 100 µs
 
+    /** Hard limit on container's CPU usage: Implemented using Completely Fair Scheduler (CFS) by allocating a given
+     * time within a given period, Container's processes are not bound to any specific CPU, which may create significant
+     * performance degradation as processes are scheduled on another CPU after exhausting the quota. */
     private final double cpus;
+
+    /** Soft limit on container's CPU usage:  When plenty of CPU cycles are available, all containers use as much
+     * CPU as they need. It prioritizes container CPU resources for the available CPU cycles.
+     * It does not guarantee or reserve any specific CPU access. */
     private final int cpuShares;
+
+    /** The maximum amount, in bytes, of memory the container can use. */
     private final long memoryBytes;
 
     ContainerResources(double cpus, int cpuShares, long memoryBytes) {
diff --git a/docker-api/src/main/java/com/yahoo/vespa/hosted/dockerapi/DockerImpl.java b/docker-api/src/main/java/com/yahoo/vespa/hosted/dockerapi/DockerImpl.java
index 5405e283b47..1d0295ebc68 100644
--- a/docker-api/src/main/java/com/yahoo/vespa/hosted/dockerapi/DockerImpl.java
+++ b/docker-api/src/main/java/com/yahoo/vespa/hosted/dockerapi/DockerImpl.java
@@ -245,6 +245,7 @@ public class DockerImpl implements Docker {
                     // See: https://docs.docker.com/config/containers/resource_constraints/#configure-the-default-cfs-scheduler
                     // --cpus requires API 1.25+ on create and 1.29+ on update
                     // NanoCPUs is supported in docker-java as of 3.1.0 on create and not at all on update
+                    // TODO: Simplify this to .withNanoCPUs(resources.cpu()) when docker-java supports it
                     .withCpuPeriod(resources.cpuQuota() > 0 ? resources.cpuPeriod() : null)
                     .withCpuQuota(resources.cpuQuota() > 0 ? resources.cpuQuota() : null);