document how to deploy with a LoadBalancer ingress

robobario · robobario · commit 5ed962c83cf4 · 2025-06-26T16:41:14.000+12:00
We need to instruct users on how to enable off-cluster access via SNI.

We are intentionally vague about certificate generation and external DNS
management as these will vary by environment.

Signed-off-by: Robert Young &lt;robeyoun@redhat.com&gt;
diff --git a/docs/assemblies/assembly-operator-deploy-a-proxy-with-in-cluster-plain-ingress.adoc b/docs/assemblies/assembly-operator-deploy-a-proxy-with-in-cluster-plain-ingress.adoc
@@ -5,6 +5,8 @@
 
 [id='assembly-operator-deploy-a-proxy-with-in-cluster-plain-ingress-{context}']
 = Deploying a proxy exposed to Kafka clients on the same Kubernetes Cluster
+:parent-context: {context}
+:context: {parent-context}-in-cluster
 
 [role="_abstract"]
 Deploy a basic proxy instance with a single virtual cluster exposed to Kafka clients on the same Kubernetes cluster.
@@ -36,4 +38,6 @@ include::assembly-operator-configuring-kafkaprotocolfilters.adoc[leveloffset=+3]
 // TODO
 // == Configuring a filter
 //
-// include::../modules/configuring/proc-configuring-filter.adoc[leveloffset=+1]
+// include::../modules/configuring/proc-configuring-filter.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
diff --git a/docs/assemblies/assembly-operator-deploy-a-proxy-with-loadbalancer-ingress.adoc b/docs/assemblies/assembly-operator-deploy-a-proxy-with-loadbalancer-ingress.adoc
@@ -0,0 +1,89 @@
+// file included in the following:
+//
+// assembly-operator-deploy-a-proxy.adoc
+
+
+[id='assembly-operator-deploy-a-proxy-with-loadbalancer-ingress-{context}']
+= Deploying a proxy exposed to Kafka clients outside the Kubernetes Cluster via a LoadBalancer Service
+:parent-context: {context}
+:context: {parent-context}-load-balancer
+
+[role="_abstract"]
+Deploy a basic proxy instance with a single virtual cluster exposed to Kafka clients outside the Kubernetes Cluster via a Kubernetes LoadBalancer Service.
+
+== Prerequisites
+
+* The operator must be installed in the Kubernetes cluster
+* A Kafka cluster to be proxied
+* External DNS under your control
+* <<Addressing Scheme>>
+* <<TLS Certificates for the proxy>>
+
+=== Addressing Scheme
+
+Access to a proxy from outside the Kubernetes Cluster via a LoadBalancer service requires:
+
+* TLS between the client and proxy
+* Specific hostnames to be routed from the client to the LoadBalancer Service (configuring external DNS systems to do this is a user responsibility)
+
+First we must decide on what addresses clients will use to address our virtual Kafka cluster:
+
+* We choose a bootstrap address of `bootstrap.my-cluster.my-proxy.kroxylicious.io`
+* We choose broker addresses:
+** `broker-0.my-cluster.my-proxy.kroxylicious.io`
+** `broker-1.my-cluster.my-proxy.kroxylicious.io`
+** `broker-2.my-cluster.my-proxy.kroxylicious.io`
+
+Where 0, 1 and 2 are the node ids of the proxied brokers.
+
+Later we will configure our DNS to resolve these addresses to the manifested LoadBalancer Service.
+
+=== TLS Certificates for the proxy
+
+We must provision a Kubernetes Secret of type `kubernetes.io/tls` containing a server certificate with Subject Alternate Names containing all the names in our <<Addressing Scheme>>.
+
+This Secret could be provisioned with a technology like https://cert-manager.io/[cert-manager].
+
+For the purposes of this guide we will assume that a Secret named `proxy-server-tls` has been created in the `my-proxy`
+namespace (must be in the same namespace as the KafkaProxy)
+
+== The required resources
+
+include::../modules/configuring/con-kafkaproxy.adoc[leveloffset=+2]
+
+include::../modules/configuring/con-kafkaproxyingress-for-loadbalancer-access.adoc[leveloffset=+2]
+
+include::../modules/configuring/con-kafkaservice-by-bootstrap.adoc[leveloffset=+2]
+
+include::../modules/configuring/con-virtualkafkacluster-tls.adoc[leveloffset=+2]
+// TODO
+// == Deploying the example proxy
+//
+// include::../modules/configuring/proc-deploying-example-proxy.adoc[leveloffset=+1]
+//
+
+// configuring filters
+include::assembly-operator-configuring-kafkaprotocolfilters.adoc[leveloffset=+3]
+
+// TODO
+// == Configuring a filter
+//
+// include::../modules/configuring/proc-configuring-filter.adoc[leveloffset=+1]
+
+== DNS Configuration
+
+After the Proxy has manifested we must configure our external DNS to resolve all the addresses in our <<Addressing Scheme>>
+to resolve to the LoadBalancer address.
+
+A Kubernetes Service `simple-sni` should have been manifested, inspect it to obtain its external address. Depending on your environment,
+this may be an IP address, or a hostname.
+
+Configure your DNS such that all the addresses in the <<Addressing Scheme>> either:
+
+* resolve to the external IP address
+* resolve to the external hostname via a `CNAME` record
+
+Once this is configured and the client can resolve all those addresses, you should be able to connect to the bootstrap
+address which is present in the `status.ingresses` section of the `VirtualKafkaCluster` you have created. The client will
+need to be appropriately configured to connect using TLS and trust the Server certificates.
+ifdef::parent-context[:context: {parent-context}]
diff --git a/docs/assemblies/assembly-operator-deploy-a-proxy.adoc b/docs/assemblies/assembly-operator-deploy-a-proxy.adoc
@@ -5,8 +5,8 @@
 
 [id='assembly-operator-deploying-a-proxy-{context}']
 = Deploying a proxy
-
 [role="_abstract"]
 This section provides a series of guides for deploying a proxy. We will explore different patterns for accessing the proxy.
 
-include::assembly-operator-deploy-a-proxy-with-in-cluster-plain-ingress.adoc[leveloffset=+1]
+include::assembly-operator-deploy-a-proxy-with-in-cluster-plain-ingress.adoc[leveloffset=+1]
+include::assembly-operator-deploy-a-proxy-with-loadbalancer-ingress.adoc[leveloffset=+1]
diff --git a/docs/modules/configuring/con-kafkaproxyingress-for-loadbalancer-access.adoc b/docs/modules/configuring/con-kafkaproxyingress-for-loadbalancer-access.adoc
@@ -0,0 +1,35 @@
+// file included in the following:
+//
+// kroxylicious-operator/assemblies/assembly-operator-deploy-a-proxy.adoc
+
+[id='con-configuring-kafkaproxyingress-loadbalancer-access-{context}']
+= Networking configuration for external access via LoadBalancer Service
+
+A `KafkaProxyIngress` resource defines the networking configuration that allows Kafka clients to connect to a `VirtualKafkaCluster`.
+
+It is uniquely associated with a single `KafkaProxy` instance, but it is not uniquely associated with a `VirtualKafkaCluster`; it can be used by multiple `VirtualKafkaCluster` instances.
+
+This example shows a `KafkaProxyIngress` for exposing virtual clusters to Kafka clients outside that Kubernetes Cluster, via a Kubernetes LoadBalancer Service.
+
+.Example `KafkaProxyIngress` configuration for LoadBalancer access.
+[source,yaml]
+----
+kind: KafkaProxyIngress
+apiVersion: kroxylicious.io/v1alpha1
+metadata:
+  namespace: my-proxy
+  name: load-balancer
+spec:
+  proxyRef: # <1>
+    name: simple
+  loadBalancer: # <2>
+    bootstrapAddress: 'bootstrap.$(virtualClusterName).my-proxy.kroxylicious.io' # <3>
+    advertisedBrokerAddressPattern: 'broker-$(nodeId).$(virtualClusterName).my-proxy.kroxylicious.io' # <4>
+----
+<1> The `proxyRef` names the `KafkaProxy` resource that this ingress is part of. It must be in the same namespace as the `KafkaProxyIngress`.
+<2> This ingress uses `loadBalancer` networking, which connects a Kubernetes `Service` resources with `type: LoadBalancer` to the virtual cluster (this Service may be shared with other clusters).
+<3> The bootstrap address that clients will bootstrap with. Using the optional `$(virtualClusterName)` replacement allows this `KafkaProxyIngress` to be referenced by multiple `VirtualKafkaCluster` resources
+<4> The advertised broker address pattern that clients will connect to when communicating with brokers. Using the optional `$(virtualClusterName)` replacement allows this `KafkaProxyIngress` to be referenced by multiple `VirtualKafkaCluster` resources
+
+NOTE: LoadBalancer ingress requires TLS between the client and Proxy. So each `VirtualKafkaCluster` that references this `KafkaProxyIngress`
+must have `tls` configured alongside the `KafkaProxyIngress` reference.
diff --git a/docs/modules/configuring/con-kafkaproxyingress-for-on-cluster-access.adoc b/docs/modules/configuring/con-kafkaproxyingress-for-on-cluster-access.adoc
@@ -11,7 +11,7 @@ It is uniquely associated with a single `KafkaProxy` instance, but it is not uni
 
 This example shows a `KafkaProxyIngress` for exposing virtual clusters to Kafka clients running in the same Kubernetes cluster as the proxy.
 
-.Example `KafkaProxyIngress` configuration.
+.Example `KafkaProxyIngress` configuration for on cluster access.
 [source,yaml]
 ----
 kind: KafkaProxyIngress
diff --git a/docs/modules/configuring/con-kafkaservice-by-bootstrap.adoc b/docs/modules/configuring/con-kafkaservice-by-bootstrap.adoc
@@ -21,7 +21,7 @@ spec:
   nodeIdRanges: # <2>
     - name: brokers # <3>
       start: 0 # <4>
-      end: 5 # <5>
+      end: 2 # <5>
   # ...
 ----
 <1> The `bootstrapServers` property is a comma-separated list of addresses in `<host>:<port>` format. Including multiple broker addresses helps clients connect when one is unavailable.
diff --git a/docs/modules/configuring/con-virtualkafkacluster-tls.adoc b/docs/modules/configuring/con-virtualkafkacluster-tls.adoc
@@ -0,0 +1,47 @@
+// file included in the following:
+//
+// kroxylicious-operator/assemblies/assembly-operator-deploy-a-proxy.adoc
+
+[id='con-configuring-virtualkafkacluster-{context}']
+= Virtual cluster configuration for LoadBalancer access with TLS
+
+A `VirtualKafkaCluster` resource defines a logical Kafka cluster that is accessible to clients over the network.
+
+The virtual cluster references the following:
+
+* A `KafkaProxy` resource that the proxy is associated with.
+* One or more `KafkaProxyIngress` resources that expose the virtual cluster to Kafka clients.
+* A `KafkaService` resource that defined the backend Kafka cluster.
+* Zero or more `KafkaProtocolFilter` resources that apply filters to the Kafka protocol traffic passing between clients and the backend Kafka cluster.
+
+This example shows a `VirtualKafkaCluster`, exposing it to external Kafka clients via a LoadBalancer Service.
+It uses TLS as the transport protocol (LoadBalancer ingress requires TLS).
+
+.Example `VirtualKafkaCluster` configuration with downstream TLS
+[source,yaml]
+----
+kind: VirtualKafkaCluster
+apiVersion: kroxylicious.io/v1alpha1
+metadata:
+  name: my-cluster
+  namespace: my-proxy
+spec:
+  proxyRef: # <1>
+    name: simple
+  targetKafkaServiceRef: # <2>
+    name: my-cluster
+  ingresses:
+    - ingressRef: # <3>
+        name: load-balancer
+      tls:
+        certificateRef: # <4>
+          name: 'proxy-server-tls'
+          kind: Secret
+----
+<1> The `proxyRef` names the `KafkaProxy` hosting with this virtual cluster.
+  It must be in the same namespace as the `VirtualKafkaCluster`.
+<2> The `KafkaService` that is proxied by the virtual cluster.
+  It must be in the same namespace as the `VirtualKafkaCluster`.
+<3> Ingresses to expose the virtual cluster.
+  Each ingress names a `KafkaProxyIngress` which must be in the same namespace as the `VirtualKafkaCluster`.
+<4> TLS server certificate that the Proxy will use to secure connections on this particular ingress. The `Secret` must be in the same namespace as the `VirtualKafkaCluster`
