Describing an event source

Create an AsyncAPI document to describe details about your Kafka event source.

Creating a document

Add details about a Kafka event source to generate an AsyncAPI document.

An AsyncAPI document describes events produced to a single Kafka cluster. An event source can produce events to multiple topics in a cluster. You can choose to describe each topic in the same AsyncAPI document, or create separate documents for each topic depending on how you want to categorize them.

Note: The following steps take you through the minimum information required for documenting the API of a Kafka event source. Only 1 topic can be documented with this process. You can then edit the document later and describe additional topics your event source is publishing to. For more information, see editing the document.

Each AsyncAPI document also specifies the credentials used to securely connect Event Endpoint Management to your Kafka cluster. See the following section for the recommended permissions to grant to this credential.

To add event source details and generate a document:

Ensure you have a Catalog and linked Developer Portal site, and an Event Gateway service available as described in prerequisites.
Log in to the Event Endpoint Management instance.
In the navigation pane, click Home, and click the Develop APIs and products tile.
Click Add > AsyncAPI (from Kafka topic).
Provide the following details:

API metadata in the Info section:
- Title: Enter a title that uniquely identifies the event source.
  
  Note: The value in the Name field is generated based on the Title.
- Version: Enter a version identifier for your API.
- Summary (optional): Description of the event source. This summary can help application developers understand the context of the event source and decide if they are interested in using the API in their application.
- Description (optional): You can add more detail about your API. The field supports markdown syntax and can be used to provide richer content.
Kafka cluster connection details in the Servers section:
- Bootstrap servers: Enter the host and port of each Kafka broker on your cluster that is used as a bootstrap server by the event source, separated by commas. For example, broker1.com:9092,broker2.com:9092,broker3.com:9092.
  
  Note: In the generated AsyncAPI document, the value provided for the Bootstrap servers address is defined as a Property, and referenced across the document.
Kafka topic details in the Channel section:

Note: In the generated AsyncAPI document, a Kafka topic is described as a Channel.
- Topic name: Enter the name of the topic that the event source is producing events to. This is the topic that application developers will need to configure their applications to consume from.
- Schema for message body in .avsc format (optional): A schema explains the structure of the messages that are produced to the topic by the event source. The schema helps applications process the incoming stream of events. In addition, the schema is referenced in generated code snippets that the portal provides to developers to use in their applications. Add your schema in Apache Avro (.avsc) format.
  
  Important: Only upload the schema definition if your producer is using an Apache Avro schema.
  
  Note: You can later view the uploaded schema details in the AsyncAPI editor in the Message section under Channels > ChannelName > OperationType > message > payload and Channels > ChannelName > OperationType > message > SchemaFormat.
Provide credentials to use when connecting to the Kafka cluster in Cluster connection security section:

Note: If you are using an Event Gateway to control access to your event source, set the credentials and security details in this section. The gateway uses these values to connect to your cluster when handling requests to your API. The details provided here are only used by the Event Gateway and are not exposed to application developers.

Security protocol: Select how the gateway authenticates and connects to your Kafka cluster. This is the same setting as the security.protocol value set for clients that connect to the cluster. Depending on the selection, you are asked for different details.
- PLAINTEXT: No authentication and no transport security. No further details are required. Traffic is not encrypted between the Kafka cluster and the gateway.
- SASL_PLAINTEXT: Choose the SASL mechanism (PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512). Enter the SASL username and password for authentication. No transport security details are required. Traffic is not encrypted between the Kafka cluster and the gateway.
- SASL_SSL: Choose the SASL mechanism (PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512). Enter the SASL username and password for authentication. Transport security is used. All traffic is encrypted between the Kafka cluster and the gateway.
- SSL: No authentication is required. Transport security is used. All traffic is encrypted between the Kafka cluster and the gateway.
  
  Important: Consider the level of permissions you provide to the gateway for accessing your Kafka resources (such as topics and consumer groups) through Access Control Lists (ACLs). You can do this after you define your AsyncAPI as described in controlling access to Kafka resources.
If your Kafka cluster uses SSL to encrypt the traffic, and the Certificate Authority (CA) that issued the certificate is not well known, then you must provide the certificate so that the gateway can trust the connection to the Kafka cluster.

If you are using Event Streams, retrieve the certificate by using the following OpenShift command. The command copies the certificate of the bootstrap server you are connecting to.
```
oc get -n <NAMESPACE> eem <INSTANCE_NAME> -ojsonpath='{range .items[*].status.listeners[?(@.type=="external")]}{"====\n"}{'.bootstrapServers'}:{"\n"}{'.certificates'}{"\n"}{"\n"}{end}'
```
If you are using Strimzi, retrieve the certificate by using the following OpenShift command.
```
oc get -n <NAMESPACE> strimzi <INSTANCE_NAME> -ojsonpath='{range .items[*].status.listeners[?(@.type=="external")]}{"====\n"}{'.bootstrapServers'}:{'.certificates'}{"\n"}{"\n"}{end}'
```
The certificate is the output that begins with -----BEGIN CERTIFICATE----- and ends with -----END CERTIFICATE-----

For other Kafka vendors, follow the vendor's instructions for retrieving the certificate.
Click Next.
You can control who has access to your event source by selecting Secure the API using an API Key and Secret. This option is selected by default to turn on authentication and enforcement of product and plan traffic requirements.

This will require client applications that want to consume from the event source to provide an API key and a secret, which can be generated in the Developer Portal by clicking Create a new app and following the steps (for more information, see registering an application).

The API key and secret credentials are used by the Event Gateway Service to validate that your application has access to consume from the event source.

Note: When selected, a security scheme is generated for the API, and communication from the clients connecting to the gateway service requires TLS encryption. If you deselect this option, authentication and traffic enforcement is not provided, and access to your API does not go through a gateway service and is not controlled.

Important: You can further control and restrict access to Kafka resources (such as topics and consumer groups) through the Event Gateway Service by using Access Control Lists (ACLs). You can do this after you define your AsyncAPI as described in controlling access to Kafka resources.
Optional: you can publish to an auto Product and default Catalog by selecting Publish this API. For more information, see publishing.
Click Next. An AsyncAPI document for your Kafka event source is generated.
Click Edit API to either add more details to the AsyncAPI document, or to publish the API straight away to a Developer Portal:
- To add more detail to your AsyncAPI document, make edits as described in editing.
- To publish the API and start socializing it, see the options described in publishing.

Recommended permissions for Event Endpoint Management

Event Endpoint Management uses credentials provided in a published AsyncAPI to allow the Event Gateway Service to securely authenticate itself with your Kafka cluster at runtime as required. These credentials, and the principle (user) they represent, are associated with Kafka Access Control List (ACLs) entries, to define what that principle is authorized to access and what actions it can perform on your cluster.

To enable self-service access to your Kafka topics, the Event Gateway Service only requires the ability to Read your published topics. In addition, all consumer groups specified by a client that uses this credential require Read access too. No other permissions are required.

Note: The consumer group name defined in your Kafka ACLs can be further restricted after the API is created.

Therefore, it is recommended that the credentials provided to Event Endpoint Management are as restrictive as possible, granting only the required Read access to any topics you want to socialize.

For examples of creating such a credential, including restricting the consumer group ACL further, see the sections about the following Kafka offerings: