add a flag for cpu_hard_limit

CHANGELOG.md

@@ -15,6 +15,7 @@ IMPROVEMENTS:
    [[GH-3781](https://github.com/hashicorp/nomad/issues/3781)]
  * discovery: Allow `check_restart` to be specified in the `service` stanza.
    [[GH-3718](https://github.com/hashicorp/nomad/issues/3718)]
+ * driver/docker: Support hard CPU limits [[GH-3825](https://github.com/hashicorp/nomad/issues/3825)]
  * driver/docker: Support advertising IPv6 addresses [[GH-3790](https://github.com/hashicorp/nomad/issues/3790)]
  * driver/docker; Support overriding image entrypoint [[GH-3788](https://github.com/hashicorp/nomad/issues/3788)]
  * driver/docker: Support adding or dropping capabilities [[GH-3754](https://github.com/hashicorp/nomad/issues/3754)]

client/driver/docker.go

@@ -119,6 +119,13 @@ const (
 	// https://docs.docker.com/engine/reference/run/#block-io-bandwidth-blkio-constraint
 	dockerBasicCaps = "CHOWN,DAC_OVERRIDE,FSETID,FOWNER,MKNOD,NET_RAW,SETGID," +
 		"SETUID,SETFCAP,SETPCAP,NET_BIND_SERVICE,SYS_CHROOT,KILL,AUDIT_WRITE"
+
+	// This is cpu.cfs_period_us: the length of a period.
+	// The default values is 100 milliseconds (ms) represented in microseconds (us).
+	// Below is the documnentation:
+	// https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt
+	// https://docs.docker.com/engine/api/v1.35/#
+	defaultCFSPeriodUS = 100000
 )
 
 type DockerDriver struct {
@@ -217,6 +224,7 @@ type DockerDriverConfig struct {
 	CapDrop              []string            `mapstructure:"cap_drop"`               // Flags to pass directly to cap-drop
 	ReadonlyRootfs       bool                `mapstructure:"readonly_rootfs"`        // Mount the container’s root filesystem as read only
 	AdvertiseIPv6Address bool                `mapstructure:"advertise_ipv6_address"` // Flag to use the GlobalIPv6Address from the container as the detected IP
+	CPUHardLimit         bool                `mapstructure:"cpu_hard_limit"`         // Enforce CPU hard limit.
 }
 
 func sliceMergeUlimit(ulimitsRaw map[string]string) ([]docker.ULimit, error) {
@@ -677,6 +685,9 @@ func (d *DockerDriver) Validate(config map[string]interface{}) error {
 			"advertise_ipv6_address": {
 				Type: fields.TypeBool,
 			},
+			"cpu_hard_limit": {
+				Type: fields.TypeBool,
+			},
 		},
 	}
 
@@ -1126,6 +1137,12 @@ func (d *DockerDriver) createContainerConfig(ctx *ExecContext, task *structs.Tas
 		VolumeDriver: driverConfig.VolumeDriver,
 	}
 
+	// Calculate CPU Quota
+	if driverConfig.CPUHardLimit {
+		percentTicks := float64(task.Resources.CPU) / float64(d.node.Resources.CPU)
+		hostConfig.CPUQuota = int64(percentTicks * defaultCFSPeriodUS)
+	}
+
 	// Windows does not support MemorySwap/MemorySwappiness #2193
 	if runtime.GOOS == "windows" {
 		hostConfig.MemorySwap = 0
@@ -1144,6 +1161,9 @@ func (d *DockerDriver) createContainerConfig(ctx *ExecContext, task *structs.Tas
 
 	d.logger.Printf("[DEBUG] driver.docker: using %d bytes memory for %s", hostConfig.Memory, task.Name)
 	d.logger.Printf("[DEBUG] driver.docker: using %d cpu shares for %s", hostConfig.CPUShares, task.Name)
+	if driverConfig.CPUHardLimit {
+		d.logger.Printf("[DEBUG] driver.docker: using %dms cpu quota and %dms cpu period for %s", hostConfig.CPUQuota, defaultCFSPeriodUS, task.Name)
+	}
 	d.logger.Printf("[DEBUG] driver.docker: binding directories %#v for %s", hostConfig.Binds, task.Name)
 
 	//  set privileged mode

website/source/docs/drivers/docker.html.md

@@ -355,6 +355,12 @@ The `docker` driver supports the following configuration in the job spec.  Only
       ]
     }
     ```
+
+* `cpu_hard_limit` - (Optional) `true` or `false` (default). Use hard CPU
+  limiting instead of soft limiting. By default this is `false` which means
+  soft limiting is used and containers are able to burst above their CPU limit
+  when there is idle capacity.
+
 * `advertise_ipv6_address` - (Optional) `true` or `false` (default). Use the container's 
    IPv6 address (GlobalIPv6Address in Docker) when registering services and checks.
    See [IPv6 Docker containers](/docs/job-specification/service.html#IPv6 Docker containers) for details.