Getting started with the rhoas CLI for Red Hat OpenShift Streams for Apache Kafka

Guide
  • Red Hat OpenShift Streams for Apache Kafka 1
  • Updated 11 October 2022
  • Published 19 October 2021

Getting started with the rhoas CLI for Red Hat OpenShift Streams for Apache Kafka

Guide
Red Hat OpenShift Streams for Apache Kafka 1
  • Updated 11 October 2022
  • Published 19 October 2021

With the Red Hat OpenShift Application Services rhoas command-line interface (CLI), you can manage OpenShift Streams for Apache Kafka from a terminal.

As a developer of applications and services, you can use rhoas to create Kafka instances and connect your applications and services to these instances. You can also create Kafka topics to store data for producers and consumers.

This guide describes how to get started quickly by doing the following:

Prerequisites

Creating a Kafka instance

A Kafka instance includes a Kafka cluster, bootstrap server, and other required configurations for connecting to Kafka producer and consumer services.

Prerequisites
  • You are logged in to rhoas.

Procedure
  1. Enter the following command to create a Kafka instance with default values.

    This example creates a Kafka instance called my-kafka.

    Creating a Kafka instance
    $ rhoas kafka create --name my-kafka

    CLI uses service contexts to group service instances against which commands are executed. The created Kafka instance is set automatically in the current context.

    If you do not want to use the default values, enter the following command: rhoas kafka create. You will be prompted to enter the Name, Cloud Provider, and Cloud Region for the Kafka instance.

  2. Verify that the Kafka instance is ready to use.

    Reviewing details of a Kafka instance
    $ rhoas context status kafka

    If you have multiple Kafka instances, you can make the current context switch to a different instance by using the rhoas context set-kafka command.

Creating a service account

To connect your applications or services to a Kafka instance, you must first create a service account with credentials. The credentials are exported to a file on your computer, which you can use to authenticate your application with your Kafka instance.

Prerequisites
  • You’ve created a Kafka instance, and it has a ready status.

Procedure
  1. Create a service account.

    This example creates a service account and saves the credentials in a JSON file.

    Creating a service account
    $ rhoas service-account create --file-format json --short-description="rhoas-service-account"

    When creating a service account, you can choose the file format and location to save the credentials. For more information, see the rhoas service-account create command help.

  2. To verify your service account credentials, view the credentials.json file that you created.

    Example credentials.json file
    {
    	"clientID":"<client-id>",
    	"clientSecret":"<client-secret>",
        "oauthTokenUrl": "https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token"
    }

    You use these credentials and the bootstrap server URL to connect your applications and services to your Kafka instance.

  3. Set the permissions for your service account to access the Kafka instance resources.

    This example allows applications to produce and consume messages from topics starting with a specified prefix that belong to any consumer group. The service account information you input here is the clientID value from the previous step.

    Assigning access permissions to a service account
    $ rhoas kafka acl grant-access --consumer --producer \
        --service-account <client-id> --topic-prefix myapp  --group all

    The permissions you assign depend on whether your application produces or consumes messages.

Creating a Kafka topic

After creating a Kafka instance, you can create Kafka topics to start producing and consuming messages in your services.

Prerequisites
  • You’ve created a Kafka instance, and it has a ready status.

You can use rhoas kafka list and rhoas context set-kafka to switch to a specific Kafka instance.

List Kafka instances
$ rhoas kafka list
Selecting a Kafka instance to use
$ rhoas context set-kafka --name my-kafka
Procedure
  1. Create a Kafka topic with default values.

    This example creates the my-topic Kafka topic.

    Creating a Kafka topic with default values
    $ rhoas kafka topic create --name my-topic

    If you do not want to use the default values, you can specify the number of partitions (--partitions) and message retention time (--retention-ms). For more information, use the command help rhoas kafka topic create -h.

  2. If necessary, you can edit or delete the topic by using the rhoas kafka topic update and rhoas kafka topic delete commands.

Generating configurations for a Kafka instance

After creating a Kafka instance, you can generate a configuration file that your applications can use to connect to your Kafka instance.

Prerequisites
  • You’ve created a Kafka instance, and it has a ready status.

  • The Kafka instance is set in the current context.

  • Your user account and org have quota for creating service accounts.

Procedure
  • Generate a configuration file for the current service context.

    This example generates a JSON file with configurations for the Kafka instance you created.

    Generating a configuration file
    $ rhoas generate-config --type json

Commands for managing Kafka

For more information about the rhoas commands you can use to manage your Kafka instance, use the following command help:

  • rhoas kafka -h for Kafka instances

  • rhoas service-account -h for service accounts

  • rhoas kafka acl -h for access management

  • rhoas kafka topic -h for Kafka topics

Additional resources