Connecting clients

Learn how to discover connection details to connect your clients to your Event Streams instance.

Obtaining the bootstrap address

Use one of the following methods to obtain the bootstrap address for your connection to your Event Streams instance, choosing the listener type appropriate for your client. More information on configuring listener types can be found in the configuring Kafka access section.

Using the CLI

  1. Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.

  2. To find the type and address of the Kafka bootstrap host for each listener, run the following command:

    kubectl get eventstreams <instance-name> -o=jsonpath='{range .status.kafkaListeners[*]}{.type} {.bootstrapServers}{"\n"}{end}'

    Where <instance-name> is the name of your Event Streams instance.

Note: If using an external Kafka listener on the OpenShift Container Platform, the OpenShift route is an HTTPS address, and the port in use is 443.

Using the Event Streams UI

  1. Log in to the Event Streams UI from a supported web browser (see how to determine the login URL for your Event Streams UI).
  2. Click the Connect to this cluster tile.

  3. Go to the Kafka listener and credentials section, and select the listener from the list.

    • Click the External tab for applications connecting from outside of the Kubernetes cluster.
    • Click the Internal tab for applications connecting from inside the Kubernetes cluster.

    Note: The list reflects the listeners configured in spec.strimziOverrides.kafka.listeners. For example, you will have external listeners displayed if you have any listeners configured with a type of route or ingress. If spec.strimziOverrides.kafka.listeners is empty for your instance (not configured), then no address is displayed here.

Using the Event Streams CLI

Note: You can only use the Event Streams CLI to retrieve the address if your Event Streams instance has at least one external listener configured in spec.strimziOverrides.kafka.listeners.

  1. Install the Event Streams CLI plugin if not already installed.

  2. Initialize the Event Streams CLI by following the instructions in logging in. Make note of the Event Streams bootstrap address value. This is the Kafka bootstrap address that your application will use.

    Note: If you have multiple listeners defined in spec.strimziOverrides.kafka.listeners, only the external listener is displayed. If you only have internal listeners defined, nothing is displayed.

Using the OpenShift Container Platform web console

  1. Log in to the OpenShift Container Platform web console using your login credentials.
  2. Expand the Operators dropdown and select Installed Operators to open the Installed Operators page.
  3. Expand the Project dropdown and select the project the instance is installed in. Click the operator called IBM Event Streams managing the project.
  4. Select the Event Streams tab and search the Name column for the installed instance and click it.
  5. Select the YAML tab.
  6. Scroll down and look for status.kafkaListeners.
  7. The kafkaListeners field will contain one or more listeners each with a bootstrapServers property. Find the type of listener you want to connect to and use the bootstrapServers value from the entry.

Note: If using an external Kafka listener, the OpenShift route is an HTTPS address, and the port in use is 443.

Securing the connection

To connect client applications to a secured Event Streams, you must obtain the following:

  • A copy of the server-side public certificate to add to your client-side trusted certificates.
  • SCRAM-SHA-512 (username and password) or Mutual TLS (user certificates) Kafka credentials.

Obtaining the server-side public certificate from the CLI

To extract the server-side public certificate to a ca.p12 file, run the following command:

kubectl get secret <cluster_name>-cluster-ca-cert -o jsonpath='{.data.ca\.p12}' | base64 -d > ca.p12

Where <instance-name> is the name of your Event Streams instance.

To extract the password for the certificate to a ca.password file, run the following command:

kubectl get secret <cluster_name>-cluster-ca-cert -o jsonpath='{.data.ca\.password}' | base64 -d > ca.password

Note: If a PEM certificate is required, run the following command to extract the certificate to a ca.crt file:

kubectl get secret <cluster_name>-cluster-ca-cert -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt

Obtaining the server-side public certificate from the Event Streams UI

  1. Log in to the Event Streams UI from a supported web browser (see how to determine the login URL for your Event Streams UI).
  2. Click Connect to this cluster on the right.
  3. From the Certificates section, download the server certificate. If you are using a Java client, use the PKCS12 certificate, remembering to copy the truststore password presented during download. Otherwise, use the PEM certificate.

Obtaining the server-side public certificate from the Event Streams CLI

  1. Install the Event Streams CLI plugin if not already installed.

  2. Initialize the Event Streams CLI by following the instructions in logging in.

  3. Use the certificates command to download the cluster’s public certificate in the required format:

    kubectl es certificates --format p12

    The truststore password will be displayed in the output for the command. The following example has a truststore password of mypassword:

    $ kubectl es certificates --format p12

Trustore password is mypassword
Certificate successfully written to /es-cert.p12.
OK

    Note: You can optionally change the format to download a PEM Certificate if required.

Obtaining the server-side public certificate from the OpenShift Container Platform web console

  1. Log in to the OpenShift Container Platform web console using your login credentials.
  2. Expand the Operators dropdown and select Installed Operators to open the Installed Operators page.
  3. Expand the Project dropdown and select the project the instance is installed in. Click the operator called IBM Event Streams managing the project.
  4. Select the Event Streams tab and search the Name column for the installed instance and click it.
  5. Select the Resources tab.
  6. To filter only secrets, deselect all resource types with the exception of Secret.
  7. Locate and select the <instance-name>-cluster-ca-cert secret. Where <instance-name> is the name of your Event Streams instance.
  8. In the Secret Overview panel scroll down to the Data section. Then, click the copy button to transfer the ca.p12 certificate to the clipboard. The password can be found under ca.password.

Note: For a PEM certificate, click the copy button for ca.crt instead.

Generating or Retrieving Client Credentials

See the assigning access to applications section to learn how to create new application credentials or retrieve existing credentials.

Configuring your SCRAM client

Add the truststore certificate details and the SCRAM credentials to your Kafka client application to set up a secure connection from your application to your Event Streams instance.

You can configure a Java application as follows:

Properties properties = new Properties();
properties.put(CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG, "<bootstrap-address>");
properties.put(CommonClientConfigs.SECURITY_PROTOCOL_CONFIG, "SASL_SSL");
properties.put(SslConfigs.SSL_PROTOCOL_CONFIG, "TLSv1.2");
properties.put(SslConfigs.SSL_TRUSTSTORE_LOCATION_CONFIG, "<certs.p12-file-location>");
properties.put(SslConfigs.SSL_TRUSTSTORE_PASSWORD_CONFIG, "<truststore-password>");
properties.put(SaslConfigs.SASL_MECHANISM, "SCRAM-SHA-512");
properties.put(SaslConfigs.SASL_JAAS_CONFIG, "org.apache.kafka.common.security.scram.ScramLoginModule required "
    + "username=\"<scram-username>\" password=\"<scram-password>\";");
Property Placeholder Description
<bootstrap-address> Bootstrap servers address
<certs.p12-file-location> Path to your truststore certificate. This must be a fully qualified path. As this is a Java application, the PKCS12 certificate is used.
<truststore-password> Truststore password.
<scram-username> SCRAM username.
<scram-password> SCRAM password.

Configuring your Mutual TLS client

Add the truststore and keystore certificate details to your Kafka client application to set up a secure connection from your application to your Event Streams instance.

You can configure a Java application as follows:

Properties properties = new Properties();
properties.put(CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG, "<bootstrap-address>");
properties.put(CommonClientConfigs.SECURITY_PROTOCOL_CONFIG, "SSL");
properties.put(SslConfigs.SSL_PROTOCOL_CONFIG, "TLSv1.2");
properties.put(SslConfigs.SSL_TRUSTSTORE_LOCATION_CONFIG, "<certs.p12-file-location>");
properties.put(SslConfigs.SSL_TRUSTSTORE_PASSWORD_CONFIG, "<truststore-password>");
properties.put(SslConfigs.SSL_KEYSTORE_LOCATION_CONFIG, "<user.p12-file-location>");
properties.put(SslConfigs.SSL_KEYSTORE_PASSWORD_CONFIG, "<user.p12-password>");
Property Placeholder Description
<bootstrap-address> Bootstrap servers address.
<certs.p12-file-location> Path to your truststore certificate. This must be a fully qualified path. As this is a Java application, the PKCS12 certificate is used.
<truststore-password> Truststore password.
<user.p12-file-location> Path to user.p12 keystore file from credentials zip archive.
<user.p12-password> The user.p12 keystore password found in the user.password file in the credentials zip archive.

Configuring your OAuth client

Add the truststore certificate details and the OAuth credentials to your Kafka client application to set up a secure connection from your application to your Event Streams instance.

You can configure a Java application as follows:

Properties properties = new Properties();
properties.put(CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG, "<bootstrap-address>");
properties.put(CommonClientConfigs.SECURITY_PROTOCOL_CONFIG, "SASL_SSL");
properties.put(SslConfigs.SSL_PROTOCOL_CONFIG, "TLSv1.2");
properties.put(SslConfigs.SSL_TRUSTSTORE_LOCATION_CONFIG, "<certs.p12-file-location>");
properties.put(SslConfigs.SSL_TRUSTSTORE_PASSWORD_CONFIG, "<truststore-password>");
properties.put(SaslConfigs.SASL_MECHANISM, "OAUTHBEARER");
properties.put(SaslConfigs.SASL_JAAS_CONFIG, "org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required "
 + "oauth.ssl.truststore.location=\"<oauth-server-certs.p12-file-location>\" "
 + "oauth.ssl.truststore.type=PKCS12 "
 + "oauth.ssl.truststore.password=\"<oauth-server-truststore-password>\" "
 + "oauth.client.id=\"<oauth-clientid>\" "
 + "oauth.client.secret=\"<oauth-client-password>\" "
 + "oauth.token.endpoint.uri=\"<oauth-authentication-token-endpoint>\";");
Property Placeholder Description
<bootstrap-address> Bootstrap servers address.
<certs.p12-file-location> Path to your truststore certificate. This must be a fully qualified path. As this is a Java application, the PKCS12 certificate is used.
<truststore-password> Truststore password.
<oauth-server-certs.p12-file-location> Path to the OAuth server truststore certificate. This must be a fully qualified path. As this is a Java application, the PKCS12 certificate is used.
<oauth-server-truststore-password> OAuth server truststore password.
<oauth-clientid> OAuth client ID.
<oauth-client-secret> OAuth client ID password.
<oauth-authentication-token-endpoint> The URI of the OAuth server token endpoint.

Obtaining Java code samples from the Event Streams UI

For a Java application, you can copy the connection code snippet from the Event Streams UI by doing the following:

  1. Log in to the Event Streams UI from a supported web browser (see how to determine the login URL for your Event Streams UI).
  2. Click the Connect to this cluster tile.
  3. Click the Sample code tab.
  4. Copy the snippet from the Sample connection code section into your Java Kafka client application. Uncomment the relevant sections and replace the property placeholders with the values from the relevant table for SCRAM or Mutual TLS.