🐛 fix(crd): +kubebuilder:default={} now includes nested field defaults in generated CRDs

[camilamacedo86]

Problem

Using +kubebuilder:default={} on an object field does not include nested defaults in the generated CRD schema. Then, CRD shows default: {} instead of a populated object with merged nested defaults.

Therefore, users looking at the CRD schema cannot see what default values will actually be applied, leading to confusion and bug reports (see #622).

---

Example

Go

type Spec struct {
    // +kubebuilder:default={}
    Config *PolicyConfig `json:"config,omitempty"`
}

type PolicyConfig struct {
    // +kubebuilder:default=20
    RateLimit int32 `json:"rateLimit,omitempty"`

    // +kubebuilder:default=50
    MaxFileSize int32 `json:"maxFileSize,omitempty"`
}

Before (broken)

config:
  type: object
  default: {}   # empty
  properties:
    rateLimit:
      type: integer
      default: 20
    maxFileSize:
      type: integer
      default: 50

After (fixed)

config:
  type: object
  default:
    rateLimit: 20
    maxFileSize: 50
  properties:
    rateLimit:
      type: integer
      default: 20
    maxFileSize:
      type: integer
      default: 50

Fix

When a schema has default: {} (empty object):

1. Walk the schema tree using the visitor pattern
2. Collect nested property defaults
3. Merge them into the parent default object
4. Preserve both parent and nested defaults (required for K8s recursive defaulting)

Result: users get a fully populated default object.

For users regenerating CRDs:

When you regenerate CRDs with this version, you'll see a one-time diff showing merged defaults:

    config:                                                 
  -   default: {}                                                                               
  +   default:
  +     rateLimit: 20                                                                           
  +     maxFileSize: 50             

This is cosmetic only - runtime behaviour is unchanged. Review and commit the updated CRD.

No action required for existing resources - they continue to work unchange

Fixes: #622

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: camilamacedo86
Once this PR has been reviewed and has the lgtm label, please assign alvaroaleman for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[sbueringer]

This seems like a breaking change to me.

Additional I think the CRDs we generate already behave this way as the apiserver recursively defaults top down

[camilamacedo86]

Hi @sbueringer,

This seems like a breaking change to me.

This is not a breaking change.

The actual runtime behavior stays the same. The Kubernetes API server already applies defaults recursively from top to bottom.

• Before this PR:
  If a user omits the field, the API server defaults it to {} and then fills in the nested defaults.
  Final result: {rateLimit: 20, maxFileSize: 50}

• After this PR:
  If a user omits the field, the API server defaults it directly to {rateLimit: 20, maxFileSize: 50}, and still applies nested defaults.
  Final result: {rateLimit: 20, maxFileSize: 50}

So the end result is identical.

What actually changes is only the generated CRD YAML:

• Before: default: {}
• After: shows the full default values explicitly

This just makes the defaults easier to understand.

Additionally I think the CRDs we generate already behave this way as the apiserver recursively defaults top down

Yes, exactly — this PR doesn’t change that behavior. It just makes it visible in the schema and avoids confusion (as described in #622).

Before, users would see default: {} and think nested defaults weren’t working.
Now they can clearly see what values will be applied.

I also added tests to confirm this behaviour, and that is not a breaking change.

[k8s-ci-robot]

PR needs rebase.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.