KafkaOffsetReset CRD

The KafkaOffsetReset custom resource resets consumer group offsets on a Kafka cluster.

Full Specification

apiVersion: kafka.oso.sh/v1alpha1
kind: KafkaOffsetReset
metadata:
  name: offset-reset
  namespace: kafka-backup
spec:
  kafkaCluster:
    bootstrapServers:
      - kafka-0.kafka.svc:9092
      - kafka-1.kafka.svc:9092
    securityProtocol: SASL_SSL
    caSecret:                                    # optional: separate CA secret (e.g. Strimzi)
      name: cluster-ca-cert
      caKey: ca.crt
    tlsSecret:
      name: kafka-tls
      caKey: ca.crt
    saslSecret:
      name: kafka-credentials
      mechanism: SCRAM-SHA-512
    connection:
      connectionsPerBroker: 4

  consumerGroups:
    - order-processor
    - payment-handler

  topics:
    - orders
    - payments

  resetStrategy: to-timestamp
  resetTimestamp: 1713009600000
  resetOffset: null

  parallelism: 50
  dryRun: false
  continueOnError: false
  snapshotBeforeReset: true

  offsetMappingRef:
    restoreName: production-restore
    path: /tmp/offset-mapping.json
    pvcName: restore-workspace

Spec Fields

kafkaCluster

Field	Type	Required	Description
bootstrapServers	[]string	Yes	Kafka broker addresses
securityProtocol	string	No	PLAINTEXT, SSL, SASL_PLAINTEXT, or SASL_SSL
tlsSecret	object	No	TLS certificate secret reference
caSecret	object	No	Separate CA certificate secret (e.g. Strimzi cluster CA). Overrides caKey in tlsSecret when both are set
saslSecret	object	No	SASL credentials secret reference
connection	object	No	Kafka TCP connection tuning, including connectionsPerBroker

resetStrategy

Value	Description
to-earliest	Reset to earliest available offset
to-latest	Reset to latest offset
to-timestamp	Reset to the first offset at or after resetTimestamp
to-offset	Reset to resetOffset
from-mapping	Reset using an offset mapping from a restore operation

Options

Field	Type	Default	Description
consumerGroups	[]string	Required	Consumer groups to reset
topics	[]string	[]	Topics to reset; empty resets all topics for the group
resetTimestamp	int	unset	Epoch milliseconds for to-timestamp
resetOffset	int	unset	Target offset for to-offset
parallelism	int	50	Bulk reset parallelism
dryRun	bool	false	Validate without committing offsets
continueOnError	bool	false	Continue if one group fails
snapshotBeforeReset	bool	true	Create a rollback snapshot first
offsetMappingRef	object	unset	Restore offset mapping reference for from-mapping

Examples

Reset to Earliest

apiVersion: kafka.oso.sh/v1alpha1
kind: KafkaOffsetReset
metadata:
  name: reset-to-earliest
spec:
  kafkaCluster:
    bootstrapServers:
      - kafka:9092
  consumerGroups:
    - my-consumer-group
  resetStrategy: to-earliest

Reset to a Timestamp

apiVersion: kafka.oso.sh/v1alpha1
kind: KafkaOffsetReset
metadata:
  name: reset-to-timestamp
spec:
  kafkaCluster:
    bootstrapServers:
      - kafka:9092
  consumerGroups:
    - order-processor
  topics:
    - orders
  resetStrategy: to-timestamp
  resetTimestamp: 1713009600000
  snapshotBeforeReset: true

Reset From Restore Mapping

apiVersion: kafka.oso.sh/v1alpha1
kind: KafkaOffsetReset
metadata:
  name: reset-from-restore
spec:
  kafkaCluster:
    bootstrapServers:
      - kafka:9092
  consumerGroups:
    - order-processor
  resetStrategy: from-mapping
  offsetMappingRef:
    restoreName: production-restore

Status

status:
  phase: Completed
  groupsTotal: 2
  groupsReset: 2
  groupsFailed: 0
  snapshotId: "offset-reset-20260413"
  snapshotPath: "/tmp/offset-reset-20260413.json"