Skip to content

Webhook server and metrics server use different values to turn off #3604

Open

Description

@camilamacedo86

What

controller-runtime turns its servers off in two different ways:

Server Option Type Turns off with What 0 does
Metrics metricsserver.Options.BindAddress string "0" turns it off
Health probe manager.Options.HealthProbeBindAddress string "0" or "" turns it off
pprof manager.Options.PprofBindAddress string "0" or "" turns it off
Webhook webhook.Options.Port int any value below zero, documented as -1 uses the default 9443

So a project that turns everything off locally passes
--metrics-bind-address=0 --health-probe-bind-address=0 --webhook-port=-1.
Users who expect --webhook-port=0 to work like the other flags get a
webhook server on 9443 instead, with no warning.

Why it matters

It is not homogeneous, which makes it very difficult and confusing for end users. Ideally, everything should work in the same way.
Having a clear convention here would be very helpful in reducing confusion and avoiding misleading behavior.

Why the webhook server cannot use 0 as it is

webhook.Options.Port is an int, and 0 is its zero value, so an unset portis 0. If 0 turned the server off, every caller that relies on the default 9443 would silently stop serving webhooks which can be harder yet for end users.

Proposal

Use one format for every server: replace the webhook server's Host and Port
with a BindAddress, the same option the metrics server and the health probe
already have.

  • add webhook.Options.BindAddress: "0" turns the webhook server off, and any
    other value is the address to listen on, such as :9443;
  • deprecate Host and Port in the same release, and remove them in a later
    one. Until then, Port < 0 keeps turning the server off and an unset
    BindAddress keeps today's default, :9443, so nothing breaks;
  • document the rule once for all servers: "0" turns the server off.

If replacing Port is too large a change, an alternative is to make it a
*int, so that an unset port keeps the default 9443 and 0 turns the server
off, matching the other servers.

Activity

  1. manenim commented on Oct 3, 2026

    @manenim

    I'd be interested in implementing the backward-compatible BindAddress approach if this is still available. I'd preserve the existing Host/Port defaults and negative-port disable behavior, and cover explicit binding, disabling, and legacy configuration in tests.

    Would maintainers welcome that approach? I'd like to agree on precedence when both BindAddress and Host/Port are set before starting.

  2. troy0820 commented on Oct 5, 2026

    @troy0820
    Member

    When we created the PR to disable the webhook server, this comment came from that discussion:
    #3481 (comment)

    We have shipped this already with v0.25 and documented it. The zero value defaults the webhook to port 9334.

    I am curious, beyond the consistency to change it to set it to zero, with your proposal making it a pointer will disable the webhook changing it's already shipped behavior from -1 to 0?

    If we decide to allow that to happen, would it be fair to say that:

    1. Not applying anything would set it to the default to 9334
    2. Explicitly setting it to 0 would disable it

    I believe this would break the Options and I am not sure we are willing to do that.

    FYI: @sbueringer

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions