KafkaRebalance

Expand a field to see its description, example, and default behavior. Nested fields are grouped under their parent.

API group: krabka.io
Scope: Namespaced
Resource name: kafkarebalances
Short names: kr

Required fields must be present when their parent object exists. [] denotes an array item; {key} denotes a map value. status is written by the operator. Reconcile-time checks and runtime defaults can add requirements beyond the schema.

Examples are illustrative JSON values. Open “View JSON example” for an object or array. Adapt names, endpoints, and credentials to your cluster. Kubernetes applies schema defaults when the containing object exists. Runtime and omission notes describe operator behavior. Status examples show reported data.

Runtime notes and domain examples were reviewed against operator source at b409b56.

View the complete CRD manifest at 618d621

Example manifest

This example includes the required spec fields. Adapt its values and create any referenced resources before applying it.

apiVersion: krabka.io/v1alpha1
kind: KafkaRebalance
metadata:
  name: example
  namespace: default
  labels:
    krabka.io/cluster: my-cluster
spec:
  authorizationSecretRef:
    name: my-cluster-rebalancer-auth
    key: token

krabka.io/v1alpha1

Served API version · Storage version · 31 schema entries

Complete OpenAPI schema (JSON)

{
  "description": "Auto-generated derived type for KafkaRebalanceSpec via `CustomResource`",
  "properties": {
    "spec": {
      "properties": {
        "authorizationSecretRef": {
          "description": "Bearer credential for `removeBrokers`, read from a Secret in this\nresource's namespace. When omitted, the operator derives\n`<cluster>-rebalancer-auth` / `token` from the `krabka.io/cluster`\nlabel. The token is never written to status.",
          "nullable": true,
          "properties": {
            "key": {
              "description": "Key within the Secret's `data` map.",
              "type": "string"
            },
            "name": {
              "description": "Kubernetes Secret name.",
              "type": "string"
            }
          },
          "required": [
            "key",
            "name"
          ],
          "type": "object"
        },
        "brokers": {
          "description": "Broker ids targeted by `removeBrokers` or `addBrokers`.",
          "items": {
            "format": "int32",
            "type": "integer"
          },
          "type": "array"
        },
        "endpoint": {
          "description": "Connect-RPC base URL of the `krabka-rebalancer` service, for\nexample `http://my-cluster-rebalancer.kafka.svc:9300`. When this\nfield is absent, the operator derives\n`http://<cluster>-rebalancer.<namespace>.svc.cluster.local:9300`\nfrom the `krabka.io/cluster` label.",
          "nullable": true,
          "type": "string"
        },
        "goals": {
          "description": "Optimization goals to apply, by name, for example `RackAware` and\n`ReplicaDistribution`. When this field is absent or empty, the\nrebalancer uses its full default goal registry in priority\norder.",
          "items": {
            "type": "string"
          },
          "nullable": true,
          "type": "array"
        },
        "mode": {
          "default": "full",
          "description": "Proposal scope. The operator always sends this explicitly to the\nrebalancer, including the default `full` mode.",
          "enum": [
            "full",
            "removeBrokers",
            "addBrokers"
          ],
          "type": "string"
        },
        "throttleBytesPerSec": {
          "description": "Replication throttle in bytes per second while the proposal\nexecutes. This is KIP-73. When this field is absent, the rebalancer\nuses its own `--default-throttle-bytes-per-sec`.",
          "format": "int64",
          "minimum": 1,
          "nullable": true,
          "type": "integer"
        }
      },
      "type": "object"
    },
    "status": {
      "nullable": true,
      "properties": {
        "conditions": {
          "default": [],
          "description": "Kubernetes-style condition list. The `type` of the active\ncondition holds the rebalance state. It is one of\n`PendingProposal`, `ProposalReady`, `Rebalancing`, `Ready`,\n`NotReady`, and `Stopped`.",
          "items": {
            "properties": {
              "lastTransitionTime": {
                "description": "RFC3339 timestamp.",
                "type": "string"
              },
              "message": {
                "description": "Human-readable message.",
                "type": "string"
              },
              "reason": {
                "description": "CamelCase machine reason.",
                "type": "string"
              },
              "status": {
                "description": "`True`, `False`, or `Unknown`.",
                "type": "string"
              },
              "type": {
                "description": "For example, `Ready`.",
                "type": "string"
              }
            },
            "required": [
              "lastTransitionTime",
              "message",
              "reason",
              "status",
              "type"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "observedGeneration": {
          "description": "`metadata.generation` of the last spec that gave the current\nproposal. The operator advances it when it computes a new\nproposal.",
          "format": "int64",
          "nullable": true,
          "type": "integer"
        },
        "optimizationResult": {
          "description": "Summary of the proposal that the operator computed last.",
          "nullable": true,
          "properties": {
            "goals": {
              "description": "The goals that the rebalancer applied after the selection.",
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "leaderMovements": {
              "default": 0,
              "description": "Number of leadership changes in the proposal.",
              "format": "int32",
              "type": "integer"
            },
            "maxLeadersAfter": {
              "default": 0,
              "description": "Max partitions led by any one broker after the proposal applies.",
              "format": "int32",
              "type": "integer"
            },
            "maxLeadersBefore": {
              "default": 0,
              "description": "Max partitions led by any one broker before the proposal applies.",
              "format": "int32",
              "type": "integer"
            },
            "maxReplicasAfter": {
              "default": 0,
              "description": "Max replicas on any one broker after the proposal applies.",
              "format": "int32",
              "type": "integer"
            },
            "maxReplicasBefore": {
              "default": 0,
              "description": "Max replicas on any one broker before the proposal applies.",
              "format": "int32",
              "type": "integer"
            },
            "replicaMovements": {
              "default": 0,
              "description": "Number of partition replica reassignments in the proposal.",
              "format": "int32",
              "type": "integer"
            }
          },
          "type": "object"
        },
        "sessionId": {
          "description": "Proposal id that the rebalancer assigned. The operator stores it,\nso that the `approve`, `stop`, and poll operations reach the same\nproposal in every reconcile.",
          "nullable": true,
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "spec"
  ],
  "title": "KafkaRebalance",
  "type": "object"
}

spec

spec object Required 6 fields

Example: View JSON example

{ "authorizationSecretRef": { "name": "my-cluster-rebalancer-auth", "key": "token" } }
Default No schema default: Not declared

authorizationSecretRef object | null Optional 2 fields

Bearer credential for removeBrokers, read from a Secret in this resource's namespace. When omitted, the operator derives <cluster>-rebalancer-auth / token from the krabka.io/cluster label. The token is never written to status.

Example: View JSON example

{ "name": "my-cluster-rebalancer-auth", "key": "token" }
Default Runtime / omission: Derived from the krabka.io/cluster label: <cluster>-rebalancer-auth, key token.

key string Required

Key within the Secret's data map.

Example: "token"
Default Runtime / omission: None for an explicit Secret reference.

name string Required

Kubernetes Secret name.

Example: "my-cluster-rebalancer-auth"
Default Runtime / omission: None for an explicit Secret reference.

brokers array Optional 1 field

Broker ids targeted by removeBrokers or addBrokers.

Example: View JSON example

[ 3, 4 ]
Default Runtime / omission: [] (no targeted brokers). Set broker IDs for removeBrokers or addBrokers.

[] integer (int32) Array item

Example: 3
Default No independent default: Defined by the parent

endpoint string | null Optional

Connect-RPC base URL of the krabka-rebalancer service, for example http://my-cluster-rebalancer.kafka.svc:9300. When this field is absent, the operator derives http://<cluster>-rebalancer.<namespace>.svc.cluster.local:9300 from the krabka.io/cluster label.

Example: "http://my-cluster-rebalancer.kafka.svc.cluster.local:9300"
Default Runtime / omission: http://<cluster>-rebalancer.<namespace>.svc.cluster.local:9300, using krabka.io/cluster.

goals array | null Optional 1 field

Optimization goals to apply, by name, for example RackAware and ReplicaDistribution. When this field is absent or empty, the rebalancer uses its full default goal registry in priority order.

Example: View JSON example

[ "RackAware", "ReplicaDistribution" ]
Default Runtime / omission: Absent or empty: use the rebalancer's full default goal registry in priority order.

[] string Array item

Example: "RackAware"
Default No independent default: Defined by the parent

mode string Optional

Proposal scope. The operator always sends this explicitly to the rebalancer, including the default full mode.

Example: "removeBrokers"
Default Schema default: "full"

Allowed values"full""removeBrokers""addBrokers"

throttleBytesPerSec integer | null (int64) Optional

Replication throttle in bytes per second while the proposal executes. This is KIP-73. When this field is absent, the rebalancer uses its own --default-throttle-bytes-per-sec.

Example: 10000000
Default Runtime / omission: Use the rebalancer service's configured --default-throttle-bytes-per-sec value.

Validation and schema details

Minimum: 1

status

status object | null Optional 4 fields

Example: View JSON example

{ "conditions": [ { "lastTransitionTime": "2026-10-05T12:00:00Z", "message": "Rebalance proposal is ready for approval.", "reason": "ProposalReady", "status": "True", "type": "ProposalReady" } ] }
Default No schema default: Not declared

conditions array Optional 1 field

Kubernetes-style condition list. The type of the active condition holds the rebalance state. It is one of PendingProposal, ProposalReady, Rebalancing, Ready, NotReady, and Stopped.

Example: View JSON example

[ { "lastTransitionTime": "2026-10-05T12:00:00Z", "message": "Rebalance proposal is ready for approval.", "reason": "ProposalReady", "status": "True", "type": "ProposalReady" } ]
Default Schema default: []

[] object Array item 5 fields

Example: View JSON example

{ "lastTransitionTime": "2026-10-05T12:00:00Z", "message": "Rebalance proposal is ready for approval.", "reason": "ProposalReady", "status": "True", "type": "ProposalReady" }
Default No schema default: Not declared

lastTransitionTime string Required

RFC3339 timestamp.

Example: "2026-10-05T12:00:00Z"
Default No schema default: Not declared

message string Required

Human-readable message.

Example: "Rebalance proposal is ready for approval."
Default No schema default: Not declared

reason string Required

CamelCase machine reason.

Example: "ProposalReady"
Default No schema default: Not declared

status string Required

True, False, or Unknown.

Example: "True"
Default No schema default: Not declared

type string Required

For example, Ready.

Example: "ProposalReady"
Default No schema default: Not declared

observedGeneration integer | null (int64) Optional

metadata.generation of the last spec that gave the current proposal. The operator advances it when it computes a new proposal.

Example: 1
Default No schema default: Not declared

optimizationResult object | null Optional 7 fields

Summary of the proposal that the operator computed last.

Example: View JSON example

{ "goals": [ "RackAware", "ReplicaDistribution" ] }
Default No schema default: Not declared

goals array Optional 1 field

The goals that the rebalancer applied after the selection.

Example: View JSON example

[ "RackAware", "ReplicaDistribution" ]
Default No schema default: Not declared

[] string Array item

Example: "ReplicaDistribution"
Default No schema default: Not declared

leaderMovements integer (int32) Optional

Number of leadership changes in the proposal.

Example: 6
Default Schema default: 0

maxLeadersAfter integer (int32) Optional

Max partitions led by any one broker after the proposal applies.

Example: 8
Default Schema default: 0

maxLeadersBefore integer (int32) Optional

Max partitions led by any one broker before the proposal applies.

Example: 12
Default Schema default: 0

maxReplicasAfter integer (int32) Optional

Max replicas on any one broker after the proposal applies.

Example: 16
Default Schema default: 0

maxReplicasBefore integer (int32) Optional

Max replicas on any one broker before the proposal applies.

Example: 24
Default Schema default: 0

replicaMovements integer (int32) Optional

Number of partition replica reassignments in the proposal.

Example: 12
Default Schema default: 0

sessionId string | null Optional

Proposal id that the rebalancer assigned. The operator stores it, so that the approve, stop, and poll operations reach the same proposal in every reconcile.

Example: "019bbdb3-fec4-7780-9978-8805004f5d96"
Default No schema default: Not declared

Resource schema

Resource schema object Resource schema

Auto-generated derived type for KafkaRebalanceSpec via CustomResource

Example: View JSON example

{ "apiVersion": "krabka.io/v1alpha1", "kind": "KafkaRebalance", "metadata": { "name": "example", "namespace": "default", "labels": { "krabka.io/cluster": "my-cluster" } }, "spec": { "authorizationSecretRef": { "name": "my-cluster-rebalancer-auth", "key": "token" } } }
Default No resource default: None