Must CpuPeriod and CpuQuota be used together?

I’m trying to determine if it’s mandatory to use CpuPeriod and CpuQuota in the same configuration or not.

I have seen this configuration:

"createOptions": {
  "HostConfig": {
    "Memory": 268435456,
    "MemorySwap": 536870912,
    "CpuPeriod": 25000
  }
}

Is it wrong? Meaning, should CpuPeriod only be used if you have a CpuQuota variable as well?

Basing my question on this document, where it mentions “Specify the CPU CFS scheduler period, which is used alongside --cpu-quota.” : Runtime options with Memory, CPUs, and GPUs | Docker Documentation

Just out of curiosity, where can you use this json configuration? Is it Azure?

Back to the question.

I could learn more about CPU related features and schedulers, but I don’t know why you would set CpuPeriod and not CpuQuota. The documentation you quoted mentions that CpuPeriod has a default value: 10000, but it does not mention that for CpuQuota.

There is an other parameter in the docs, “--cpus”, which is CpuQuota / CpuPeriod

It means if you want to achieve the same as you could by using --cpus (which is probably Cpus in your config if it exists), you need both values. Since we know CpuPeriod has a default value, it is not required to set, but CpuQuota probably is.

Let’s say CpuQuota also has a default value. I think the logical value would be the default CpuPeriod multiplied by the sum of the CPUs (threads). Let’s also say you have 4 CPUs. It would mean you could use 400000 periods. Then you want to make sure a container can use CPU resources equivalent to the periods of one and a half CPU. To get 1.5, you would need to set CpuPeriod to 266666.666667.

Now CpuQuota / CpuPeriod = 400000 / 266666.666667 = 1.5

Using that number is not too user friendly, so I think setting CpuQuota and using the default value of CpuPeriod is much easier way to limit CPU resources. Of course the easiest is just using Cpus if that is allowed in your configuration file.

An other speculation

In this case let’s say the default value of CpuQuota is 0. Then by dividing 0 by 25000 (or anything), you get an other 0. It either means unlimited and you did not limit CPU resources, or it means you won’t be able to use any CPU resources.

So I think if CpuQuota has a default value, it is probably 0 and when you devide CpuQuota by CpuPeriod then 0 means unlimited, and this is why you need to set it if you want any limit while the other value is optional.

If you play with the values in command line, you will see that you can safely set --cpu-quota to 0, but can’t set to less then 1000 otherwise.

time docker run --cpu-period=25000 --cpu-quota=1 --rm ubuntu:20.04 echo hello
docker: Error response from daemon: CPU cfs quota can not be less than 1ms (i.e. 1000).

If you want to understand how things work, the best way is to try it. Except when you want to understand how your neighbour’s windows break :slight_smile: Fortunately these cpu limit parameters will not do any harm.

Hi @rimelek, thanks so much for walking through this logic. Yes, these settings would be used in Azure to limit CPU resources, they show an example in the article below. Would you say this example is sound or should it be corrected? It’s sounding like there are a few ways to do a single task perhaps.

It confirms that I could learn more about cpu limits :slight_smile: I tried this command:

time docker run --cpu-period=999  --rm ubuntu:20.04 echo hello
docker: Error response from daemon: CPU cfs period can not be less than 1ms (i.e. 1000) or larger than 1s (i.e. 1000000).

So it must do something without the cpu quota. Microsoft can make mistakes, but in this case I would say they are probably right and I was wrong, so the default value of the quota is not simply 0, or it doesn’t work the way I thought. Probably this is why the Docker documentation says:

For most use-cases, --cpus is a more convenient alternative.

If you really want to know the background, you can run some stress test with different parameters. I have some examples here where I used only --cpus: learn-docker/projects/p09 at 907d27d9eb063aa19b8c5e924dc8784c95321ed4 · itsziget/learn-docker · GitHub

I can’t do that now.

Thanks, that’s very helpful. Agreed, Microsoft can sometimes be wrong or have typos etc. But I will test things out, thanks for the link. I’m not the most knowledgeable myself about the CPU options, but this helps a lot.