Skip to content
Draft
21 changes: 21 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,27 @@ jobs:
helm lint charts/kafka-operator --strict --kube-version "$version"
helm template kafka-operator charts/kafka-operator --kube-version "$version" > /dev/null
done
rendered=$(helm template kafka-operator charts/kafka-operator)
if grep -q '^kind: PodMonitor$' <<< "$rendered"; then exit 1; fi
grep -F 'kafka.banzaicloud.io/alert-leader: "true"' <<< "$rendered"
grep -E 'fieldPath: metadata\.name$' <<< "$rendered"
grep -E 'fieldPath: metadata\.uid$' <<< "$rendered"
for proxy in true false; do
for port in 8080 9090; do
args=()
if [ "$port" != 8080 ]; then args+=(--set metricEndpoint.port="$port"); fi
rendered=$(helm template kafka-operator charts/kafka-operator \
--set prometheusMetrics.podMonitor.enabled=true \
--set prometheusMetrics.authProxy.enabled="$proxy" "${args[@]}")
grep -F ' port: metrics' <<< "$rendered"
if grep -q ' scheme: https' <<< "$rendered"; then exit 1; fi
grep -F -- "--metrics-addr=:$port" <<< "$rendered"
grep -F "containerPort: $port" <<< "$rendered"
if [ "$proxy" = true ]; then
grep -F -- "--upstream=http://127.0.0.1:$port/" <<< "$rendered"
fi
done
done
IFS=. read -r major minor _ <<< "$KUBERNETES_MIN_VERSION"
unsupported="${major}.$((minor - 1)).99"
if output=$(helm template kafka-operator charts/kafka-operator --kube-version "$unsupported" 2>&1); then
Expand Down
65 changes: 65 additions & 0 deletions charts/kafka-operator/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,71 @@ The [Koperator](https://github.com/adobe/koperator) is a Kubernetes operator to

CI covers Kubernetes 1.35.0 and 1.37.0. The chart's `kubeVersion` constraint also accepts distribution-specific version suffixes.

## Alert routing, readiness, and election constraints

The chart enables leader election. Only its elected listener publishes
`kafka.banzaicloud.io/alert-leader: "true"`, which the alert Service requires.
Never set this label on Pod templates. Webhook-serving standbys remain ready;
elected replicas require usable alert serving/routing, and enabled webhooks
require local serving readiness. Liveness is independent of Kafka and election.
Upgrades from label-unaware versions have an alert endpoint gap until a new
replica becomes leader; plan alert retries during that handoff.

The chart supplies the operator Pod's `POD_NAMESPACE`, `POD_NAME` and `POD_UID`
through the downward API. Routing uses uncached API reads and UID-checked
updates within that namespace and the exact installation selector:
`control-plane=controller-manager`, `controller-tools.k8s.io=1.0`,
`app.kubernetes.io/component=operator`, and matching
`app.kubernetes.io/name`/`app.kubernetes.io/instance`. Existing chart RBAC grants
Pod get/list/update; custom RBAC must include the operator namespace even when
Kafka is watched elsewhere. Identity/read/write failures fail startup closed.

For local/non-Helm use, absence of **both** `POD_NAME` and `POD_UID` preserves the
legacy listener, including with `POD_NAMESPACE` alone. Partial identity is
rejected. Opting in requires all three inputs, installation labels and matching
Service selector above. `alertManager.enable` controls exposure, not startup.
Observed cancellation closes admission, drains HTTP requests for up to five
seconds and bounds self-label cleanup to two seconds; cleanup failure cannot
keep the listener open. Endpoint updates are asynchronous; stale requests may
fail or receive HTTP 503.

Election identity is unchanged. Replicas must enable election, use byte-identical
raw namespace input and share the election namespace. Nonempty `--namespaces`
wins over `WATCH_NAMESPACE`; order, whitespace and duplicates affect the lock
ID even for equivalent watch sets. Do not normalize inputs during rolling
upgrades. Election namespace defaults to the in-cluster service-account
namespace, not watched namespaces or `POD_NAMESPACE`.
Overlapping watch sets (including all-namespaces overlap), differently spelled
equivalent sets and independent election namespaces are unsupported concurrency
topologies. Use replicas of one installation, not separate releases with
different Service selectors sharing a Lease.

Election and routing labels are not external-action fencing or exactly-once
execution. Pauses/partitions before observed cancellation, admitted work and
ambiguous submissions can outlive routing changes; HTTP draining and conflict
retries do not automatically adopt external operations.

## Metrics compatibility

Raw metrics remain bound to all interfaces over unauthenticated HTTP. The
managed PodMonitor, when enabled, scrapes the `metrics` port directly, including
when the existing auth proxy is enabled. The proxy does not protect this raw
endpoint. Listener, container and proxy-upstream ports follow `metricEndpoint.port`
(default 8080).

Managed TLS/authenticated scraping and its certificate/credential lifecycle are
deferred. This preserves baseline HTTP scraping; it does not secure metrics.
Do not treat the proxy's presence as authentication for the raw endpoint.

## Existing webhook certificate renewal limits

Generated webhook serving certificates last 365 days (CA: 3650 days), without
continuous renewal. A generation-enabled Helm upgrade replaces CA and serving
material, not necessarily without downtime. Renew before expiry and coordinate
the Secret, webhook CA bundle and Pod rollout. With `webhook.certs.generate=false`,
refresh supplied CA/certificate/key through existing values and deployment.
No metrics certificate reuse, issuance or automatic renewal is added.

## Installing the chart

Before installing the chart, you must first install the Koperator CustomResourceDefinition resources.
Expand Down
1 change: 1 addition & 0 deletions charts/kafka-operator/templates/alertmanager-service.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ metadata:
app.kubernetes.io/component: alertmanager
spec:
selector:
kafka.banzaicloud.io/alert-leader: "true"
control-plane: controller-manager
controller-tools.k8s.io: "1.0"
app.kubernetes.io/name: {{ include "kafka-operator.name" . }}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
{{- $metricsPort := (.Values.metricEndpoint).port | default 8080 }}
{{- $tlsCrt := "" }}
{{- $tlsKey := "" }}
{{- $caCrt := "" }}
Expand Down Expand Up @@ -157,7 +158,7 @@ spec:
imagePullPolicy: {{ .Values.prometheusMetrics.authProxy.image.pullPolicy }}
args:
- "--secure-listen-address=0.0.0.0:8443"
- "--upstream=http://127.0.0.1:8080/"
- "--upstream=http://127.0.0.1:{{ $metricsPort }}/"
- "--v=10"
ports:
- containerPort: 8443
Expand Down Expand Up @@ -192,9 +193,7 @@ spec:
{{- if .Values.operator.developmentLogging }}
- --development
{{- end }}
{{- if (.Values.metricEndpoint).port }}
- --metrics-addr=":{{ .Values.metricEndpoint.port }}"
{{- end }}
- --metrics-addr=:{{ $metricsPort }}
{{- if .Values.healthProbes.port }}
- --health-probes-addr=:{{ .Values.healthProbes.port }}
{{- end }}
Expand All @@ -216,6 +215,16 @@ spec:
port: health-probes
path: /readyz
env:
- name: POD_NAME
valueFrom:
fieldRef:
apiVersion: v1
fieldPath: metadata.name
- name: POD_UID
valueFrom:
fieldRef:
apiVersion: v1
fieldPath: metadata.uid
- name: POD_NAMESPACE
valueFrom:
fieldRef:
Expand All @@ -230,7 +239,7 @@ spec:
name: webhook-server
protocol: TCP
{{- end}}
- containerPort: {{ (.Values.metricEndpoint).port | default 8080 }}
- containerPort: {{ $metricsPort }}
name: metrics
protocol: TCP
- containerPort: {{ .Values.alertManager.port }}
Expand Down
Loading