Using the Karapace REST Proxy

The Karapace Rest Proxy is an add-on which can be enabled when creating an Instaclustr Managed Apache Kafka cluster. Note that enabling any Enterprise Add-On or Enterprise Feature adds 20% to standard costs. If you would like to add the Karapace Rest Proxy to an existing cluster, please contact support.

The Karapace Rest Proxy enables you to integrate an Instaclustr Managed Kafka cluster with any system that can communicate with a simple HTTPS RESTful API.

To create a new Kafka cluster with the Karapace REST Proxy add-on, make sure to enable Karapace REST Proxy under the Enterprise Add-Ons subsection on the Kafka setup page. Please note that the Karapace add-ons on the console show up with the following naming:

  • Karapace Schema Registry is displayed simply as Schema Registry, and
  • Karapace REST Proxy is displayed as REST Proxy.

 

Note: Karapace REST Proxy and Karapace Schema Registry cannot be used together with either Kafka Schema Registry (Old) or Kafka REST Proxy (Old). This is enforced through the console as well our API, and Terraform Provider. For example, on the console, enabling Karapace causes Kafka Schema Registry (Old) as well as Kafka REST Proxy (Old) to be disabled, and vice-versa. If you would like to use schema registry, you do have the option of doing so by enabling Schema Registry add-on. 

Instaclustr offers a fixed number of 3 Karapace Rest Proxy nodes when creating a Kafka cluster by selecting Karapace Rest Proxy, and this number remains the same regardless of the size of the Kafka cluster. 

You can also create a local Karapace Schema Registry on the cluster and choose to integrate the Karapace REST Proxy with the local one. The checkbox will be visible when both the Karapace Schema Registry and Karapace REST Proxy are selected. 

 

Configuring the Karapace Rest Proxy

To start using the Karapace Rest Proxy, you must first open the firewall to your client application IP address. Once your cluster is up and running, go to Firewall Rules and add your IP address to the KARAPACE REST PROXY ALLOWED ADDRESSES.

Connecting to the Karapace Rest Proxy

The Karapace Rest Proxy is hosted in our Instaclustr hosted zone, cnodes.io. You can access the Karapace Rest Proxy by using the subdomain we have created.

Connection information can be retrieved on the Connection Info page for the cluster running the Karapace REST Proxy. This page also includes the username and automatically generated password, plus code samples for testing connectivity to your Karapace REST Proxy servers.

Karapace Rest Proxy access

Up until the introduction of ic_addon_rest_proxy Kafka user, we did not offer the ability to restrict access via ACLs for Karapace Rest Proxy clients. For clusters provisioned prior to this user being available, the Karapace Rest Proxy service connects to your Apache Kafka cluster and has access to all topics stored in the cluster.

After the introduction of the ic_addon_rest_proxy Kafka user, only Kafka clusters that provision or enable Karapace Rest Proxy starting that point onwards will have this user present in Kafka. Clusters that upgrade the bundle or have it already enabled, will not have this user present in the Kafka. For such clusters, contacting support to have the Karapace REST Proxy disabled and re-enabled on their clusters would add in this new user.

This user allows you to manage the ACLs specific for ic_addon_rest_proxy. The presence of this user can be verified by checking the Users list for Kafka.

Using the Karapace Rest Proxy

The Karapace Rest Proxy operates as a RESTful web API, any application that can send and receive HTTPS messages can be configured to operate with the application.

Special attention should be paid to the Content Type headers sent with each request. The same Content Type headers must be sent when setting up and configuring consumer instances and producing Kafka topics, otherwise, the requests may fail or return 404 NOT FOUND.

For more information about what content types are supported, refer to the following documentation: 

https://github.com/aiven/karapace/blob/3.2.0/README.rst

Example:

  • The following examples will illustrate a few basic commands using the CURL command on a Unix based client machine.
  • The consumer instance will be named “my_consumer_instance”
  • The Content Type header used will be application/vnd.kafka.json.v2+json
  1. Listing the topics in a Kafka cluster


  2. Create a consumer instance in the consumer group named ‘consumer1’


*Note: Although Instaclustr provides 3 Karapace Rest Proxy nodes, when creating a consumer instance you will be returned a URL for a specific node IP address, which is decided by Karapace. And then a consumer is created in this particular node, you can only consume messages from this particular node.

This is expected and necessary behaviour, as the consumer instances are stateful and each instance maintains the state independently. Subsequent requests for that consumer instance must be made to the same IP address.

  1. Subscribe consumer instance to the topic “test”


  2. Produce a message to the topic “test”


    Note: producing can be done to any Karapace Rest Proxy node

  3. Consume the produced message


Troubleshooting

Consume Issue

The most common issue for new users is that you receive a 404 NOT FOUND when attempting to consume from your consumer instance.

There can be a few reasons this may occur

Mismatched “Content-Type” headers

Check your Content-Type headers are consistent for each request made to create and configure your consumer instance. Any mismatch on datatype or API version will cause requests to fail.

The consumer instance exists on another Karapace Rest Proxy server

Ensure you are communicating with the correct server. Instaclustr offers 3 Karapace Rest Proxy nodes to produce and consume from, however, a single consumer instance only exists on the server it was created on.

To use this consumer instance, you must keep connecting to the same server by its IP address. To facilitate this pattern, in addition to the ID of the consumer instance, the Karapace Rest Proxy will also return the fully qualified URL your application should use.

The Karapace Rest Proxy application was restarted

While Instaclustr does everything it can to avoid restarting your applications, they may get restarted during general maintenance (this is only performed after coordinating with you) or troubleshooting operations.

To account for both scenarios, you can ensure your client code is robust by attempting to use the existing consumer instance, and if you receive a 404 response, creating a new consumer instance and using that one.

Seek Consumer Offset Failure

Another issue you may encounter is that you get the error message: {“error_code”:40403,”message”:”Unknown topic or partition”}, when trying to seek beginning/end consumer offsets from your consumer instance with following endpoint

You can try to replace calling following endpoint using request body {“topics”: [“your topic”]}

with the endpoint using request body {“partitions”: [{“topic”: “your topic”, “partition”: your-partition}]} as below

Further reading

The example above is a simple illustration of a basic produce/consume workflow.

Instaclustr provides and supports all the available features and operations provided by the Karapace Rest Proxy.

Please consult this GitHub repo for a comprehensive guide to these features.