Deploy Interceptor
Deploys an Interceptor on Gateway.- Managed with: API, CLI, UI, TF
metadata.scope
is optional (default empty).metadata.scope.[vCluster | group | username]
combine with each other to define the targeting- Check the dedicated Interceptor targeting section
spec.pluginClass
is mandatory. Has to be a valid Interceptor class name.spec.priority
is mandatoryspec.config
is a valid config for thepluginClass
Interceptor targeting
You can activate your Interceptor only in specific scenarios. Use the table below to configure Targeting settings.Use case | metadata.scope.vcluster | metadata.scope.group | metadata.scope.username |
---|---|---|---|
Global Interceptor (Including Virtual Clusters) | Set to null | Set to null | Set to null |
Global Interceptor (Excluding Virtual Clusters) | Empty | Empty | Empty |
Username targeting | Empty | Empty | Set |
Group targeting | Empty | Set | Empty |
Virtual Cluster targeting | Set | Empty | Empty |
Virtual Cluster + Username targeting | Set | Empty | Set |
Virtual Cluster + Group targeting | Set | Set | Empty |
The order of precedence from highest (overrides all others) to lowest (most easily overridden) is:
- ServiceAccount
- Group
- VirtualCluster
- Global
Examples
GatewayServiceAccount
When using Oauth, mTLS or delegated backing Kafka authentication,GatewayServiceAccount
is generally optional.
- Managed with: API, CLI, TF
GATEWAY_SECURITY | LOCAL GatewayServiceAccount | EXTERNAL GatewayServiceAccount |
---|---|---|
PLAINTEXT | 🚫 | 🚫 |
SSL | 🚫 | only if mTls |
SASL_PLAINTEXT | ✅ | only if OAuth configured |
SASL_SSL | ✅ | only if OAuth configured |
DELEGATED_SASL_PLAINTEXT | 🚫 | ✅ |
DELEGATED_SASL_SSL | 🚫 | ✅ |
- creating local service accounts
- renaming service accounts for easier clarity when using Interceptors
- attaching service accounts to Virtual Clusters
- When
spec.type
isEXTERNAL
:spec.externalNames
must be a non-empty list of external names. Each name must be unique across all declared GatewayServiceAccount.- we currently only support a list of one element.
- When
spec.type
isEXTERNAL
:- During Client connection, the authenticated user will be checked against the list of
externalNames
to decide which GatewayServiceAccount it is.
- During Client connection, the authenticated user will be checked against the list of
- When
spec.type
isLOCAL
:- Access to
/gateway/v2/tokens
endpoint to generate a password for this service account - Switching a GatewayServiceAccount
spec.type
fromLOCAL
toEXTERNAL
does not invalidate previously emitted tokens. They will keep on working for their TTL.
- Access to
GatewayGroup
Gateway group lets you add multiple users in the same GatewayGroup for easier Interceptor targeting capabilities.spec.members[].name
is mandatory.- Currently, the username needs to refer to an existing GatewayServiceAccount otherwise it will fail. This is a known issue that we’ll address in a further release.
spec.members[].vCluster
is optional. It has to refer to an existing Virtual Cluster. When not using Virtual Clusters, don’t set this attribute.
- All members of the group will be affected by Interceptors deployed with this group’s scope.
ConcentrationRule
Concentration Rules allow you to define patterns where topic creation won’t generate a physical topic, but will instead use our topic concentration feature.metadata.vCluster
is optional. Must refer to an existing Virtual Cluster. When not using Virtual Clusters, don’t set this attribute.spec.physicalTopics.delete
is mandatory. Has to be a valid topic name with acleanup.policy
set todelete
.spec.physicalTopics.compact
is optional. Has ti be a valid topic name with acleanup.policy
set tocompact
.spec.physicalTopics.deleteCompact
is optional. Has to be a valid topic name with acleanup.policy
set todelete,compact
.spec.autoManaged
is optional, default isfalse
.spec.offsetCorrectness
is optional, default isfalse
.
- Once the Concentration Rule is deployed, topics created with a name matching the
spec.pattern
will not be created as real Kafka topics but as concentrated topics instead. - Depending on the topic’s
cleanup.policy
, the topic’s data will be stored in one of the configured physical topics. - If a topic creation request is made with a
cleanup.policy
that isn’t configured in the ConcentrationRule, topic creation will fail. - It is not possible to update
cleanup.policy
of a concentrated topic. - If
spec.autoManaged
is set totrue
, the underlying physical topics and configurations will be automatically created and/or extended to honour the topics configurations. - If
spec.offsetCorrectness
is set totrue
, Gateway will maintain a list of offsets for each of the concentrated topic records.- This allows for a proper calculation of message count and consumer group lag.
- There are some limitations with offset correctness.
- If
spec.offsetCorrectness
is set tofalse
, Gateway will report the offsets of the backing topic records.
If a ConcentrationRule spec changes, it will not affect previously created concentrated topics, it will only affect the topics created after the change.
VirtualCluster
A Virtual Cluster allows you to isolate one or more service accounts within a logical cluster. Any topic or consumer group created within a Virtual Cluster will be accessible only to that specific Virtual Cluster.- Managed with: API, CLI
metadata.name
must be a valid topic prefix as all vcluster topics and consumer groups will be created on the physical kafka cluster with this as the prefix (they will appear on the vcluster without the prefix).spec.aclEnabled
is optional (defaultfalse
). When unset orfalse
,- there are no authorization checks for clients connecting to the vcluster. Clients are free to perform any operation on resources within the vcluster
- The fields
acls
andsuperUsers
cannot be set
spec.type
must be eitherStandard
orPartner
(default if not set isStandard
)
spec.aclEnabled
when it is set to true
ACLs configurable via Kafka
When a vcluster is configured to have ACLs set via Kafka (aclMode: KAFKA_API
) an administrator can connect to the vcluster as any service account named in the superUsers
list and fully manage the ACLs of other service accounts within the vcluster using the Kafka Admin API. This is the same way you would manage a real Kafka Cluster.
- when
spec.aclMode
is set toKAFKA_API
(default ifaclEnabled: true
)- it cannot be changed
acls
cannot be setspec.superUsers
must be set
spec.superUsers
is the list of usernames for which the associated service accounts in this virtual cluster can bypass ACLs.- Specified usernames are not created automatically. You still need to create the associated gateway service accounts on the vcluster for them to work.
ACLs configurable via REST
Managing ACLs with the Kafka Admin API is extremely powerful, but can also be cumbersome. For some use-cases it is desirable to configure everything using the REST api instead.- when
spec.aclMode
is set toREST_API
- it cannot be changed
spec.acls
must be setspec.superUsers
cannot be set
spec.acls
is the complete list of ACL bindings for the vcluster and allows (nearly) any valid Kafka API ACL binding (inc*
wildcards) to be set. For a complete list of valid ACL bindings checkout the Open API schema.
We do not allow the
aclMode
to be changed once it is set because KAFKA_API
and REST_API
have incompatible mutation processes (KAFKA_API
mode changes are cumulative whereas REST_API
mode changes are idempotent).