URGENT: 1.20.0 breaking changes must be clearly mentioned at the TOP of release logs

[KieranP]

As part of our security posture, we regularly update our production dependencies. This includes Vault. However, todays updates broke all our production sites for 12 minutes because of a BIG breaking change listed way down in the release notes, namely:

server: disable_mlock configuration option is now required for integrated storage and no longer has a default. If you are using the default value with integrated storage, you must now explicitly set disable_mlock to true or false or Vault server will fail to start. [https://github.com/hashicorp/vault/pull/29974]

About 2 minutes after the updates applied, we started getting alerts and other indications that Vault had not booted back up, including uptime monitors screaming. But the logs from Vault didn't mention anything as to why, it just wouldn't boot.

So we checked the most recent Vault release notes, but there was no clearly labeled major breakage changed noted mentioned between 1.19.0 and 1.20.0. This delayed a quick resolution. Eventually we found the breakage note (buried 1/2 way down the release notes), made the needed config change, and Vault came back online, followed shortly by our production servers.

A breaking change like this absolutely must be at the top of the release notes, clearly highlighted! I would also argue that such a breaking change should be reserved for a major release i.e. v2.0.0, not a minor release.

[jimrosenfeld]

Another breaking change - this note was added to the Azure auth docs for 1.20.x:

Note: When creating a role, you must specify either bound_service_principal_ids or bound_group_ids. These parameters are mutually exclusive - you cannot set both, but you must set one of them.

It was not present in the 1.19.x version, and previous versions would allow you to define roles without one of those parameters. In 1.20.x, this breaks Azure authentication with an error saying one of those are required.

This is called out in the Azure auth plugin changelog and I agree it's prudent to check all of those when they change, but it would be appreciated if breaking changes in plugins bundled with Vault were called out in the main Vault changelog when plugin updates introduce them.