Status

Current state: VotingAccepted

Discussion thread: https://lists.apache.org/thread/kc87jkgyvf9x7nwmgwrhx6fs6w0tqymj

...

{
  "apiKey": 93,
  "type": "request",
  "listeners": ["broker", "controller"],
  "name": "UnregisterControllerRequest",
  "validVersions": "0",
  "flexibleVersions": "0+",
  "fields": [
    { "name": "ControllerId", "type": "int32", "versions": "0+",
       "about": "The controller ID to unregister." }
  ]
}"about": "The controller ID to unregister." }
  ]
}

This request can return the following errors:

• an UNSUPPORTED_VERSION  error if the cluster's MetadataVersion does not support UnregisterControllerRecord 
• a CONTROLLER_ID_NOT_REGISTERED  error if no registration exists for the requested controller ID. This is similar to the BROKER_ID_NOT_REGISTERED error in the case of brokers.
• a NOT_CONTROLLER  error if the request does not arrive at the active controller
• an INVALID_REQUEST error if the request arrives at the active controller. This is known to be a "mistaken" request, as it is expected controllers are not running when they are unregistered. See the User Experience for more details.

UnregisterControllerResponse

...

kafka-cluster unregister-controller --controller-id 99901

When the user executes this command to unregister controller 99901:

1. UnregisterControllerRequest is sent to the active controller
2. The active controller writes an UnregisterControllerRecord to the metadata log
3. When this record is committed, return a response to the user for unregistering the controller
4. The active controller's state machine removes the registration for controller 99901, meaning feature upgrades no longer consider node 99901's supported features
5. The registration from controller 9990 1 is removed from the metadata image

...

kafka-metadata-quorum remove-controller --controller-id 99901 --controller-directory-id EXAMPLE_UUID --unregister

When the user executes this command, kafka tries to remove 9990 1 as a voter AND unregister it:

1. RemoveRaftVoterRequest  is sent to the active controller
2. The KRaft leader writes a VotersRecord without voter 9990 1 to the metadata log
3. When this record is committed, return a response to the user for removing the voter
4. UnregisterControllerRequest is sent to the active controller if steps 1-3 were successful
   1. If steps 1-3 were not successful, return the error and direct the user to use kafka-cluster unregister-controller instead.
5. The active controller writes an UnregisterControllerRecord to the metadata log
6. When this record is committed, return a response to the user for unregistering the controller
7. The active controller's state machine removes the registration for controller 99901, meaning feature upgrades no longer consider node 99901's supported features
8. The registration from controller 9990 1 is removed from the metadata image

...

Because this KIP is introducing a new metadata record alongside a new MetadataVersion, it means that existing clusters who have a stale controller registration will not be able to unregister it, and unblock feature upgrades thereafter. The main reason for not supporting this in existing clusters is that in many environments, operators can simply bring up another controller node with the same node ID to "refresh" its registration. Additionally, the interest of keeping this design simple, some of the potential workarounds for existing clusters have been moved to the Rejected Alternatives section.

...

This approach would be one way existing clusters could support unregistering stale controller registrations without updating the MV. However, the main issue with this approach is that it is unsafe. A user who unregisters a controller before updating the software versions on all controllers to support this feature would crash the controllers with an older software version.

Additionally, combined mode deployments where the broker and controller use the same ID make reusing the same metadata record for unregistering both brokers and controller too complex compared to introducing a new record for unregistering controllers.

Non-durably unregister controllers

...