<commit_before>// Module included in the following assemblies:
//
// deploying/assembly_deploy-verify.adoc
// getting-started.adoc

[id='setup-external-clients-{context}']
= Setting up access for clients outside of Kubernetes

This procedure shows how to configure client access to a Kafka cluster from outside Kubernetes.

Using the address of the Kafka cluster, you can provide external access to a client on a different Kubernetes namespace or outside Kubernetes entirely.

You configure an external Kafka listener to provide the access.

The following external listener types are supported:

* `route` to use OpenShift `Route` and the default HAProxy router
* `loadbalancer` to use loadbalancer services
* `nodeport` to use ports on Kubernetes nodes
* `ingress` to use Kubernetes _Ingress_ and the {NginxIngressController}

The type chosen depends on your requirements, and your environment and infrastructure.
For example, loadbalancers might not be suitable for certain infrastructure, such as bare metal, where node ports provide a better option.

In this procedure:

. An external listener is configured for the Kafka cluster, with TLS encryption and authentication, and Kafka _simple authorization_ is enabled.
. A `KafkaUser` is created for the client, with TLS authentication and Access Control Lists (ACLs) defined for _simple authorization_.

You can configure your listener to use TLS or SCRAM-SHA-512 authentication,
both of which can be used with TLS encryption.
If you are using an authorization server, you can use token-based link:{BookURLUsing}#assembly-oauth-authentication_str[OAuth 2.0 authentication^] and link:{BookURLUsing}#assembly-oauth-authorization_str[OAuth 2.0 authorization^].
Open Policy Agent (OPA) authorization is also supported as a link:{BookURLUsing}#con-securing-kafka-authorization-str[Kafka authorization] option.

When you configure the `KafkaUser` authentication and authorization mechanisms, ensure they match the equivalent Kafka configuration:

* `KafkaUser.spec.authentication` matches `Kafka.spec.kafka.listeners[*].authentication`
* `KafkaUser.spec.authorization` matches `Kafka.spec.kafka.authorization`

You should have at least one listener supporting the authentication you want to use for the `KafkaUser`.

NOTE: Authentication between Kafka users and Kafka brokers depends on the authentication settings for each.
For example, it is not possible to authenticate a user with TLS if it is not also enabled in the Kafka configuration.

Strimzi operators automate the configuration process:

* The Cluster Operator creates the listeners and sets up the cluster and client certificate authority (CA) certificates to enable authentication within the Kafka cluster.
* The User Operator creates the user representing the client and the security credentials used for client authentication, based on the chosen authentication type.

In this procedure, the certificates generated by the Cluster Operator are used, but you can replace them by link:{BookURLUsing}#installing-your-own-ca-certificates-str[installing your own certificates^].
You can also configure your listener to link:{BookURLUsing}#kafka-listener-certificates-str[use a Kafka listener certificate managed by an external Certificate Authority^].

Certificates are available in PKCS #12 format (.p12) and PEM (.crt) formats.

.Prerequisites

* The Kafka cluster is available for the client
* The Cluster Operator and User Operator are running in the cluster
* A client outside the Kubernetes cluster to connect to the Kafka cluster

.Procedure

. Configure the Kafka cluster with an `external` Kafka listener.
+
* Define the authentication required to access the Kafka broker through the listener
* Enable authorization on the Kafka broker
+
For example:
+
[source,yaml,subs="+quotes,attributes"]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
spec:
  kafka:
    # ...
    listeners: <1>
    - name: external <2>
      port: 9094 <3>
      type: _LISTENER-TYPE_ <4>
      tls: true <5>
      authentication:
        type: tls <6>
      configuration:
        preferredNodePortAddressType: InternalDNS <7>
        _bootstrap and broker service overrides_ <8>
        #...
      authorization: <9>
        type: simple
        superUsers:
          - super-user-name <10>
  # ...
----
<1> Configuration options for enabling external listeners are described in the link:{BookURLUsing}#type-GenericKafkaListener-reference[Generic Kafka listener schema reference^].
<2> Name to identify the listener. Must be unique within the Kafka cluster.
<3> Port number used by the listener inside Kafka. The port number has to be unique within a given Kafka cluster. Allowed port numbers are 9092 and higher with the exception of ports 9404 and 9999, which are already used for Prometheus and JMX. Depending on the listener type, the port number might not be the same as the port number that connects Kafka clients.
<4> External listener type specified as `route`, `loadbalancer`, `nodeport` or `ingress`. An internal listener is specified as `internal`.
<5> Enables TLS encryption on the listener. Default is `false`. TLS encryption is not required for `route` listeners.
<6> Authentication specified as `tls`.
<7> (Optional, for `nodeport` listeners only) Configuration to link:{BookURLUsing}#type-GenericKafkaListenerConfiguration-reference[specify a preference for the first address type used by Strimzi as the node address^].
<8> (Optional) Strimzi automatically determines the addresses to advertise to clients.
The addresses are automatically assigned by Kubernetes.
You can override link:{BookURLUsing}#type-GenericKafkaListenerConfiguration-reference[bootstrap and broker service addresses] if the infrastructure on which you are running Strimzi does not provide the right address.
Validation is not performed on the overrides.
The override configuration differs according to the listener type.
For example, you can override hosts for `route`, DNS names or IP addresses for `loadbalancer`, and node ports for `nodeport`.
<9> Authoization specified as `simple`, which uses the `AclAuthorizer` Kafka plugin.
<10> (Optional) Super users can access all brokers regardless of any access restrictions defined in ACLs.

. Create or update the `Kafka` resource.
+
[source,shell,subs=+quotes]
kubectl apply -f _KAFKA-CONFIG-FILE_
+
The Kafka cluster is configured with a Kafka broker listener using TLS authentication.
+
A service is created for each Kafka broker pod.
+
A service is created to serve as the _bootstrap address_ for connection to the Kafka cluster.
+
A service is also created as the _external bootstrap address_ for external connection to the Kafka cluster using `nodeport` listeners.
+
The cluster CA certificate to verify the identity of the kafka brokers is also created with the same name as the `Kafka` resource.

. Find the bootstrap address and port from the status of the `Kafka` resource.<commit_msg>[DOC] Note for route address length (#3927)<commit_after>// Module included in the following assemblies:
//
// deploying/assembly_deploy-verify.adoc
// getting-started.adoc

[id='setup-external-clients-{context}']
= Setting up access for clients outside of Kubernetes

This procedure shows how to configure client access to a Kafka cluster from outside Kubernetes.

Using the address of the Kafka cluster, you can provide external access to a client on a different Kubernetes namespace or outside Kubernetes entirely.

You configure an external Kafka listener to provide the access.

The following external listener types are supported:

* `route` to use OpenShift `Route` and the default HAProxy router
* `loadbalancer` to use loadbalancer services
* `nodeport` to use ports on Kubernetes nodes
* `ingress` to use Kubernetes _Ingress_ and the {NginxIngressController}

The type chosen depends on your requirements, and your environment and infrastructure.
For example, loadbalancers might not be suitable for certain infrastructure, such as bare metal, where node ports provide a better option.

In this procedure:

. An external listener is configured for the Kafka cluster, with TLS encryption and authentication, and Kafka _simple authorization_ is enabled.
. A `KafkaUser` is created for the client, with TLS authentication and Access Control Lists (ACLs) defined for _simple authorization_.

You can configure your listener to use TLS or SCRAM-SHA-512 authentication,
both of which can be used with TLS encryption.
If you are using an authorization server, you can use token-based link:{BookURLUsing}#assembly-oauth-authentication_str[OAuth 2.0 authentication^] and link:{BookURLUsing}#assembly-oauth-authorization_str[OAuth 2.0 authorization^].
Open Policy Agent (OPA) authorization is also supported as a link:{BookURLUsing}#con-securing-kafka-authorization-str[Kafka authorization] option.

When you configure the `KafkaUser` authentication and authorization mechanisms, ensure they match the equivalent Kafka configuration:

* `KafkaUser.spec.authentication` matches `Kafka.spec.kafka.listeners[*].authentication`
* `KafkaUser.spec.authorization` matches `Kafka.spec.kafka.authorization`

You should have at least one listener supporting the authentication you want to use for the `KafkaUser`.

NOTE: Authentication between Kafka users and Kafka brokers depends on the authentication settings for each.
For example, it is not possible to authenticate a user with TLS if it is not also enabled in the Kafka configuration.

Strimzi operators automate the configuration process:

* The Cluster Operator creates the listeners and sets up the cluster and client certificate authority (CA) certificates to enable authentication within the Kafka cluster.
* The User Operator creates the user representing the client and the security credentials used for client authentication, based on the chosen authentication type.

In this procedure, the certificates generated by the Cluster Operator are used, but you can replace them by link:{BookURLUsing}#installing-your-own-ca-certificates-str[installing your own certificates^].
You can also configure your listener to link:{BookURLUsing}#kafka-listener-certificates-str[use a Kafka listener certificate managed by an external Certificate Authority^].

Certificates are available in PKCS #12 format (.p12) and PEM (.crt) formats.

.Prerequisites

* The Kafka cluster is available for the client
* The Cluster Operator and User Operator are running in the cluster
* A client outside the Kubernetes cluster to connect to the Kafka cluster

.Procedure

. Configure the Kafka cluster with an `external` Kafka listener.
+
* Define the authentication required to access the Kafka broker through the listener
* Enable authorization on the Kafka broker
+
For example:
+
[source,yaml,subs="+quotes,attributes"]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
  namespace: myproject
spec:
  kafka:
    # ...
    listeners: <1>
    - name: external <2>
      port: 9094 <3>
      type: _LISTENER-TYPE_ <4>
      tls: true <5>
      authentication:
        type: tls <6>
      configuration:
        preferredNodePortAddressType: InternalDNS <7>
        _bootstrap and broker service overrides_ <8>
        #...
      authorization: <9>
        type: simple
        superUsers:
          - super-user-name <10>
  # ...
----
<1> Configuration options for enabling external listeners are described in the link:{BookURLUsing}#type-GenericKafkaListener-reference[Generic Kafka listener schema reference^].
<2> Name to identify the listener. Must be unique within the Kafka cluster.
<3> Port number used by the listener inside Kafka. The port number has to be unique within a given Kafka cluster. Allowed port numbers are 9092 and higher with the exception of ports 9404 and 9999, which are already used for Prometheus and JMX. Depending on the listener type, the port number might not be the same as the port number that connects Kafka clients.
<4> External listener type specified as `route`, `loadbalancer`, `nodeport` or `ingress`. An internal listener is specified as `internal`.
<5> Enables TLS encryption on the listener. Default is `false`. TLS encryption is not required for `route` listeners.
<6> Authentication specified as `tls`.
<7> (Optional, for `nodeport` listeners only) Configuration to link:{BookURLUsing}#type-GenericKafkaListenerConfiguration-reference[specify a preference for the first address type used by Strimzi as the node address^].
<8> (Optional) Strimzi automatically determines the addresses to advertise to clients.
The addresses are automatically assigned by Kubernetes.
You can override link:{BookURLUsing}#type-GenericKafkaListenerConfiguration-reference[bootstrap and broker service addresses] if the infrastructure on which you are running Strimzi does not provide the right address.
Validation is not performed on the overrides.
The override configuration differs according to the listener type.
For example, you can override hosts for `route`, DNS names or IP addresses for `loadbalancer`, and node ports for `nodeport`.
<9> Authoization specified as `simple`, which uses the `AclAuthorizer` Kafka plugin.
<10> (Optional) Super users can access all brokers regardless of any access restrictions defined in ACLs.
+
WARNING: An OpenShift Route address comprises the name of the Kafka cluster, the name of the listener, and the name of the namespace it is created in.
For example, `my-cluster-kafka-listener1-bootstrap-myproject` (_CLUSTER-NAME_-kafka-_LISTENER-NAME_-bootstrap-_NAMESPACE_).
If you are using a `route` listener type, be careful that the whole length of the address does not exceed a maximum limit of 63 characters.

. Create or update the `Kafka` resource.
+
[source,shell,subs=+quotes]
kubectl apply -f _KAFKA-CONFIG-FILE_
+
The Kafka cluster is configured with a Kafka broker listener using TLS authentication.
+
A service is created for each Kafka broker pod.
+
A service is created to serve as the _bootstrap address_ for connection to the Kafka cluster.
+
A service is also created as the _external bootstrap address_ for external connection to the Kafka cluster using `nodeport` listeners.
+
The cluster CA certificate to verify the identity of the kafka brokers is also created with the same name as the `Kafka` resource.

. Find the bootstrap address and port from the status of the `Kafka` resource.
{'fraction_non_alphanumeric': 0.06018550805495502, 'fraction_numerical': 0.007322686379803334, 'mean_word_length': 4.803318494536625, 'pattern_counts': {'":': 0, '<': 43, '<?xml version=': 0, '>': 43, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1566662', 'n_tokens_mistral': 3687, 'n_tokens_neox': 3519, 'n_words': 1831}