Documentation seems wrong, and error message is unhelpful

[nhumrich]

Hello, I started up an image of rabbitmq, and on the readme it says that you can set the username and password with environment variables:

https://github.com/docker-library/docs/tree/master/rabbitmq#setting-default-user-and-password

But when I do that, I get an error:

error: RABBITMQ_DEFAULT_PASS is set but deprecated
error: RABBITMQ_DEFAULT_USER is set but deprecated
error: deprecated environment variables detected

Please use a configuration file instead; visit https://www.rabbitmq.com/configure.html to learn more

But the url in the error is just a general page for rabbitmq, and doesn't tell me at all how to configure rabbitmq for docker using environment variables. What are the new environment variables?

[wglambert]

Looks like the documentation needs to be updated for #467
I'll get a PR up shortly 👍

[yosifkit]

Already open: docker-library/docs#1996

[tianon]

But the url in the error is just a general page for rabbitmq, and doesn't tell me at all how to configure rabbitmq for docker using environment variables. What are the new environment variables?

The TLDR of the change in #467 is that in 3.9+, there are no environment variables. You should use a configuration file provided either via custom image, bind mount, Docker/Kubernetes config object, etc instead.

[cetra3]

This looks like a breaking change to the docker image but doesn't bump a major semver as I'm assuming this image is tracking the rabbitmq release version. Initial discussion for removing the script is here: #422

For anyone else hitting this issue, you can tag to 3.8 instead of latest / 3 while you migrate to a new way of doing things.

It would have been nice if before making this change that:

• The readme on docker hub clearly indicates that the env vars were about to be deprecated
• There is an easy upgrade path for users who are using these env vars (i.e, those using secrets)

[reggermont]

This looks like a breaking change to the docker image but doesn't bump a major semver as I'm assuming this image is tracking the rabbitmq release version. Initial discussion for removing the script is here: #422

For anyone else hitting this issue, you can tag to 3.8 instead of latest / 3 while you migrate to a new way of doing things.

It would have been nice if before making this change that:

• The readme on docker hub clearly indicates that the env vars were about to be deprecated
• There is an easy upgrade path for users who are using these env vars (i.e, those using secrets)

Totally agree. Deprecated also means "Support will be removed in the future", not "Support is already removed, thx bye"

[sithmein]

May I ask why this change was made in the first place? Pretty much every Docker image I know can be configured with environment variables (at least the basic settings). And using env variable for configuring containers is the standard approach for containerized applications. Reverting back to configuration files seems like a step back and make using the image considerably more complicated. Building an own image is additional work and requires a place to store it and using bind mounts is not always possible (e.g. if you start a sidecar container from within another container). Personally I believe this change is a huge mistake.

[michaelklishin]

@sithmein it may be the standard approach that works well for some applications. In the context of RabbitMQ,
environment variables are inferior to rabbitmq.conf in many ways:

• No typing is enforced, env variables are just strings
• No standard validations can be applied early enough
• Many end up storing secrets there
• When troubleshooting, communicating your configuration involves sharing configuration file(s) and half-a-dozen environment variables
• RabbitMQ and CLI tools can support the same environment variables, causing obscure conflicts that no one can reproduce outside of environments that use a specific image

rabbitmq.conf does not have the first two problems. advanced.config offers value encryption.

RABBITMQ_ERLANG_COOKIE is used by both earlier versions of this image and RabbitMQ CLI tools,
creating obscure shared secret mismatches that wasted a lot of time for a lot of people in the last few years

Heavy environment variable use in this image has proven to be counterproductive time and time again. It was pretty
directly responsible for time-consuming issues that no one
in the broader RabbitMQ community runs into.

Just mount a configuration file (in fact, you can mount a directory of them) and avoid a whole range of "container snowflake" issues. Go with the ecosystem flow, inventing your own means of configuration is entirely uncalled for in this
specific image.

[michaelklishin]

In addition, specific combinations of environment variables produced configuration files that were incorrect. This was not
a one-time issue, as issues in this repository — often used for questions — demonstrate.

When you use rabbitmq.conf you always can set anything that the RabbitMQ version you use supports. When inventing
your own means of configuration you are always catching up.

This list of issues with heavy environment variable abuse is long enough for me. Env variables were never designed to be a
primary way of configuring reasonably complex stateful distributed systems.

[sithmein]

The thing is we cannot mount a configuration file into the container because the RabbitMQ container itself is started from another container. And bind mount always refer to the host file system which we don't have access to.

What's the difference between providing a configuration file directly or letting the container read environment variables and create a configuration file on the fly? This is what many other official images we are using do.

Anyway, for us it's fine to stick with the 3.8 image.

[michaelklishin]

What's the difference between providing a configuration file directly or letting the container read environment variables and
create a configuration file on the fly

The difference is that if the user provides a file, this image can avoid maintaining an entire complex layer of shell script code.
As mentioned before, there are all kinds of image-specific issues that all come down to the
fact that the entrypoint tried to be smart and effectively invented its own configuration mechanism on top of
env variables and shell script. Such "configuration system" is

• unique to this image. No other RabbitMQ user, including those who use the K8S Operator for RabbitMQ in a recommended way, would use it
• prone to errors that can generate an incorrect config or a config that is technically correct but does not do what you expect
• constantly behind latest available RabbitMQ settings. There is no way this soup of env variables can provide access to 100% of configurable settings in practice, even for TLS listener options alone

We have a few years worth of evidence of these issues. Just go through the issues in this repo or rabbitmq-users group archives.

I find it hard to believe that there is no suitable way to get a configuration file into an image. It can be downloaded from
a URL, mounted, "pasted" from a secret/object, et cetera. If there really is no way, can you share a bit more context
about your environment? I guess your only option is to reinvent the environment variable/shell script soup in your
own image built on top of this one, and maintain it for as long as you need it.

RabbitMQ 3.8 will be out of general support in Jan 2022. Sticking to it for the
long term over newer releases is a losing proposition.

[michaelklishin]

One scenario where we see environment variables seem to be actively with the 3.8 versions of this image is
service containers on GitHub, GitLab and so on. Those containers cannot easily mount files.
They need a dedicated user and perhaps virtual hosts but typically not any RabbitMQ configuration per se.

A small feature in RabbitMQ itself that would simplify initial setup for service containers would be introducing a load_definitions counterpart that uses a remote URL instead of a local file. That would instantly take care of users/virtual host/permission setup, or maybe even topologies if needed: rabbitmq/rabbitmq-server#3249

Assuming that an HTTP API call against the management plugin-enabled container is possible on GItLab and such,
I don't see why it would not be possible to import a basic definition file with users/virtual hosts/permissions without any additional features. Then simply use that user
in your suites, creating new users over remote guest access has been the recommended way for many years.

[marcwittke]

Did you guys hear of semver?

[nhumrich]

find it hard to believe that there is no suitable way to get a configuration file into an image. It can be downloaded from
a URL, mounted, "pasted" from a secret/object, et cetera.

I think the biggest problem with this change is that you haven't updated the documentation at all to help those who don't understand docker as well. Literally none of these options are present in the documentation. The documentation says "get the config file there", with no path on how. For those coming from 3.8, there is essentially no upgrade path, without making them spend hours on learning docker/rabbit deeper.

I think a section in the documentation that shows an example of a config file, and a couple examples of how to get it to the right place, would go a long way.
For example, you say the config file can be downloaded from a URL, I have no idea how to do that, its not listed in the documentation at all, but that would probably solve my problems and a lot of people on this thread. If you reply in this thread with how, I would be willing to make the actual change to the documentation.