Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions docs/modules/kafka/pages/usage-guide/management-access.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ spec:
authentication:
userProvided:
tls:
secretClassName: kafka-client-auth-secret # <2>
secretName: kafka-agent-credential # <2>
controllers:
roleGroups:
default:
Expand All @@ -54,21 +54,29 @@ spec:
replicas: 3
----
<1> Deploys the agent. Setting it to `false` removes the agent again.
<2> The SecretClass that provisions the client certificate of the agent, here the same SecretClass that the brokers use to verify client certificates, see xref:usage-guide/security.adoc[Security].
<2> A Secret with a client certificate issued for the agent.
The certificate must be signed by the CA that the brokers use to verify client certificates, that is the CA of the `clientCertSecretClass` of the AuthenticationClass, see xref:usage-guide/security.adoc[Security].

The agent supports the following authentication methods:

`anonymous: {}`:: The agent connects without a client certificate.
This is only possible if the cluster does not require client authentication.
`tls.secretClassName`:: A client certificate provisioned by the xref:secret-operator:index.adoc[Secret Operator] from the given SecretClass.
`tls.secretName`:: A static Secret holding the client certificate in the keys `tls.crt` and `tls.key` (PEM), for example a Secret of type `kubernetes.io/tls`.
If the CA is managed by the Secret Operator, take its xref:secret-operator:secretclass.adoc#ca-rotation[rotation] into account.

WARNING: `tls.secretClassName` is currently only recommended for test and development environments.
The Secret Operator issues all certificates of a SecretClass with the same generic subject `CN=generated certificate for pod`, so Kafka cannot distinguish the agent from other clients of the same SecretClass.
Permissions granted to the agent then apply to all of these clients.
For production, use `tls.secretName` with a certificate whose subject is unique to the agent.

The agent verifies the brokers with the CA of the SecretClass used by the client listener, that is `spec.clusterConfig.tls.serverSecretClass` or the `clientCertSecretClass` of the TLS AuthenticationClass.

== Authorization

The principal of the agent must be allowed to manage topics in Kafka.
The principal is derived from the subject of the client certificate.
The principal is derived from the subject of the client certificate, for example `User:CN=kafka-agent`.
Make sure that no other client uses this principal, as it would be granted the permissions of the agent as well.
The agent needs the following permissions:

[cols="2,3", options="header"]
Expand All @@ -87,6 +95,9 @@ The agent needs the following permissions:
NOTE: Without `DESCRIBE_CONFIGS`, Kafka still creates a topic, but the agent cannot observe it.
The KafkaTopic then reports `KafkaRejected`.

Kafka only authorizes the agent, not the users of KafkaTopics.
Who is allowed to manage topics is therefore decided by the Kubernetes permissions on KafkaTopics, see xref:usage-guide/topics.adoc[Topics].

== Network

The agent connects to the headless Services of the broker role groups, which resolve to the broker Pods.
Expand Down