rhoas-cli-getting-started-kafka

Creating Kafka resources by using the OpenShift Application Services CLI

With the 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:

• Create a Kafka instance

• Create a service account

• Create a Kafka topic

• Use rhoas to manage your Kafka instances, service accounts, and Kafka topics

• Generate configurations for a Kafka instance

Prerequisites

• You’ve a command-line terminal application.

• You’ve a registered OpenShift cluster.

• You’ve installed the rhoas CLI. For more information, see Installing the rhoas CLI.

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’re logged in to rhoas.

Procedure

1. On the command line, create a Kafka instance.

   Creating a Kafka instance

   $ rhoas kafka create

2. Type my-kafka for your instance name.

3. When prompted to select a cluster, use the arrows on your keyboard to select your OpenShift cluster and press Enter to provision your Kafka instance.

4. When prompted to select an instance size, use the arrows on your keyboard to select 1 or 2 streaming units, and press Enter.

   A streaming unit determines the default maximum capacity of a Kafka instance. An instance with a larger size can handle higher loads and process more events, has more storage, and can handle more clients and connections.

   The CLI displays information about the created instance including billing model, cloud provider, cluster ID of the cluster the instance is provisioned on, and instance type.

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

   Note

   Alternatively, to provision a Kafka instance by specifying the Kafka name and cluster ID, enter the following command: rhoas kafka create --name my-kafka --cluster-id <CLUSTER_ID>. Replace <CLUSTER_ID> with your cluster ID. Using this command creates an instance with the default value size of 1 streaming unit.

5. Verify the details and ready status of a Kafka instance.

   Verifying the Kafka instance

   $ rhoas context status kafka

   Note	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"

   Note	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.

Note	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

   Note	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

• CLI command reference (rhoas)