+1 looks good to me. We should only keep one configuration file that users can modify. However, this will increase the difficulty for developers: if they want to modify a configuration, they need to first view the Lua code and then add the corresponding configuration in config.yaml. Of course, we can solve this problem through documentation
Thanks, Ming Wen, Apache APISIX PMC Chair On Thu, 30 May 2024 at 00:56, Zeping Bai <bzp20000...@gmail.com> wrote: > Hi, community. > > I am posting to this mailing list a proposal to remove the > config-default.yaml default configuration file, and below I will describe > the background and reasons for this and consider the benefits to us. > > The proposal does not represent a community resolution, although I am a > committer in the APISIX community. We still want to hear a variety of > voices to make sure this is truly beneficial. > > *# Background* > > Now APISIX has two configuration files, the user configuration file > *config.yaml* and the default configuration file *config-default.yaml*. > When APISIX starts up, it reads these two configuration files and merges > and overwrites the user configuration file with the default configuration > to create the configuration that is actually used at runtime. > > The recommendation from the developers is that users should only modify the > user configuration file *config.yaml*, while ensuring that > *config-default.yaml* remains intact. > This is documented here: > https://apisix.apache.org/docs/apisix/next/installation-guide/ > > > APISIX's default configuration can be found in conf/config-default.yaml > file and it should not be modified. > > It is bound to the source code and the configuration should only be > changed by the methods mentioned above. > > Users often ask how they should modify custom configurations, or encounter > unintended problems after modifying the default configuration file. > When explaining to them why they should not modify the default > configuration file but copy those keys that need to be modified to the user > configuration file and then modify them, and explaining the logic of > merging the user configuration file with the default configuration file, I > do find this issue to be a troubling one. > > Also, some PRs encountered errors when improving config-default.yaml. For > example: https://github.com/apache/apisix/pull/11284 > > Let's shift our attention to other major open source projects in the world, > I have indeed seen very few implementations with such built-in annoyances. > Often software can have its default configuration hard-coded into the > program, bundled into a binary for distribution, and the user can use a new > configuration file, which they will load at runtime and override the > modified keys into the default configuration. > This way, the user only needs to remember that he should modify > *config.yaml* and nothing else; and APISIX will start normally without > providing any configuration. This really reduces the cost of understanding. > > Therefore, I suggest the following. > > *# Proposal* > > 1. Remove *config-default.yaml* and move its contents to a Lua file as a > Lua table > 2. Fix test errors > 3. Use documentation to explicitly document all configuration items, which > ideally should be generated from the schema. > > This is APISIX enhancement work, which is not perceived by users unless > they are using APISIX in a non-correct way. > > *# Benefit* > > 1. Reduce the cost of explaining about the section, and the cost of > understanding for the user. > 2. Reduce the APISIX code base > 3. Improve the documentation quality through the entire process. > > *# The End* > > The discussion is asking for feedback, and you can reply to the email > directly to the mailing list. > We can discuss constructive feedback. If there is no constructive feedback, > I will start working on it. > > -- > Best regards! > Zeping Bai @bzp2010 >
