Terraform Logarithm function deep dive

Recently I’ve been preparing some internal training on terraform functions and came round the most unexpected Logarithm function. My first thought was who on the Earth might want to use terraform to calculate logarithms or is it just a cool feature for parents helping children with homework? Nevertheless it was on the list so I decided to include it in my slides but first of all I needed to understand the purpose and the use of it myself.

A quick reminder of what a logarithm is:

In mathematics, the logarithm is the inverse function to exponentiation. That means the logarithm of a number x to the base b is the exponent to which b must be raised, to produce x. For example, since 1000 = 10^3, the logarithm base 10 of 1000 is 3, or log10 (1000) = 3.

How is the function described in Terraform docs:

log returns the logarithm of a given number in a given base.

The syntax is log(number, base)

This seem to look ok but what are the use cases? Further down the line it suggests to use log and ceil together to find the minimum number of binary digits required to represent a given number of distinct values or to put it simple you can find out how many bits you’ll need to write a decimal number. Considering Terraform is supporting multiple providers there is a possibility that you might want to do it so let’s take a closer look at log and ceil combination.

ceil returns the closest whole number that is greater than or equal to the given value, which may be a fraction — basically it rounds the number UP to the next whole number

Let’s put them together:

Let’s check if the results are correct:

Binary of 15–1111–4 bits

Binary of 16–10000–5 bits — WAIT??!! That doesn’t look right!

Binary of 17–10001–5 bits

At this point I got very confused and went back to Wikipedea:

“The number of digits (bits) in the binary representation of a positive integer n is the integral part of 1 + log2 n, i.e.

Historically, the floor of x has been–and still is–called the integral part or integer part of x.”

Which means that terraform example was always rounding the logarithm up to the next whole number expecting that it should be enough but this logic clearly fails for a number of scenarios and even for 1 as a given number (where the logarithm will be 0 for any base)— while ceil function would return 0 back it clearly needs 1 bit to write it. The approach described on Wikipedia seems to make more sense — instead of rounding the result up you round it down and add +1 to it.

Let’s retest:

floor returns the closest whole number that is less than or equal to the given value, which may be a fraction

This time our binary of 16 is 5 as it should be and “1" scenario seems to be working fine as well.

The conclusion:

In the unlikely scenario you need to find the minimum number of binary digits required to represent a given number of distinct values using terraform you need to use log and floor functions together and add +1 to the result.

Hope you found this article entertaining and if you want to know more you can visit the links below :-)

Resources used:

https://developer.hashicorp.com/terraform/language/functions/log https://developer.hashicorp.com/terraform/language/functions/ceil https://developer.hashicorp.com/terraform/language/functions/floor https://en.wikipedia.org/wiki/Logarithm https://en.wikipedia.org/wiki/Binary_logarithm https://en.wikipedia.org/wiki/Binary_number