API guidelines for default values

[jenshu]

Currently/historically we've handled default values in our API in a few different ways:

• Add a +kubebuilder:default marker in the API docs (which will set a default value in the CRD); in the code, assume that the value is always set (i.e. no need for nil checks or further defaulting in the code)
• Add a +kubebuilder:default in the API and add redundant defaulting in the code (in this case, it's possible for the defaults in the CRD and code to get out of sync, and one can argue that the defaulting in code is unnecessary since the field will already have a default from the CRD)
• Do the defaulting in the code and just add API doc comments to document it (in this case, the defaults in the docs and code can get out of sync, but the advantage is that we don't bloat the persisted resource with fields that the user didn't explicitly set)

We should come up with a formalized policy on how to deal with defaults, and update the API guidelines and code to follow the policy (possibly even add a linter if applicable).

Keep in mind the following scenarios:

• Data plane (envoy or agentgateway) has a default value for this field; should we re-define the default in the CRD/code, or not set a default and just document that we inherit the default from the data plane?
• Data plane has a default value but we want to override it with a different default

[Mike-4-prog]

Hi @jenshu, Saw this issue a while ago, and I just tried to brainstorm a bit about it, especially looking at the API guidelines you posted. The main questions I see coming up from your examples are things like:

• how to avoid CRD defaults and code-level defaults getting out of sync

• when it actually makes sense not to persist defaults in the CRD

• and how defaults that originate in the data plane (Envoy / agentgateway) should be represented in the API docs

One way to move this forward might be to make the expectations more explicit in the API guidelines, for example, spelling out when +kubebuilder:default should be used versus when defaults should live only in code, how inherited data plane defaults should be documented, and generally discouraging defining the same default in multiple places.

If it would be helpful, I’d be glad to draft a documentation-focused update to api/README.md that adds a small “Default Values” section with clear guidance and examples, and we can iterate from there.

Happy to follow whatever direction makes the most sense for the task though.

[jenshu]

Hi @Mike-4-prog thanks for the offer! I think that before we update the docs, we need to come to a consensus on what the guidelines should be. I think I'm going to convert this to a discussion so that maintainers and others can weigh in. Once we've made a decision, we'd be glad to have you update the docs if you are interested!

[timflannagan]

cc @howardjohn @shashankram @lgadban as well since this has come up a couple of times. Would be good to formalize our guidance on defaulting here.