Drupal 8 now bubbles all cacheability metadata: cache contexts & cache tags. This allows even the tiniest part of the page to indicate that it becomes invalid when a cache tag changes or that it varies by a certain cache context.
But many parts of the page are composed of tinier parts (think: entities contain fields; also when rendered). So it's only logical that the composed part varies by all the cache tags and all the cache contexts of the individual parts of the composition. This already works great.
But one part was missing so far: the ability to say that something is not cacheable, and that therefore anything that contains that thing should not be cacheable.
That's what max-age allows you to do.
When $build['#cache']['max-age'] is not set, permanent cacheability (Cache::PERMANENT) is assumed. To indicate that a render array is not cacheable at all, set $build['#cache']['max-age'] = 0 (i.e. zero seconds). And to indicate that a render array is cacheable only for a limited amount of time, e.g. 5 minutes, set $build['#cache']['max-age'] = 300; // 5 * 60 = 300.
Comments
Is this change record
Is this change record accurate? I tried to set $vars['#cache']['max-age'] on a tiny part, but found that it didn't bubble. After a few hours of debugging, I finally found this module https://www.drupal.org/project/cache_control_override that refer two core issues, one of which is Postponed. Maybe I'm missing something, but I couldn't get "max-age" to bubble without adding that module.