Contact UsGet started

Managing Apache Kafka® topics

Written by
Updated at January 23, 2025

A Managed Service for Apache Kafka® cluster provides two ways for you to manage topics and partitions (which can be used separately or combined):

Managing topics via Yandex Cloud interfaces

Creating a topic

Prior to creating a topic, calculate the minimum storage size.

  1. In the management console, go to the relevant folder.
  2. In the services list, select Managed Service for Kafka.
  3. Click the cluster name and go to the Topics tab.
  4. Click Create topic.
  5. Under Basic parameters, set the basic parameters of the topic:
    • Topic name (must be unique in the Apache Kafka® cluster).
    • Number of topic partitions.
    • Replication factor. This parameter value should not exceed the number of brokers in the cluster. Minimum value: 1. Maximum value: 3. Default value:
      • For a cluster with one or two brokers: 1.
      • For a cluster with three or more brokers: 3.
  6. Under Topic settings, specify the topic settings.
  7. Click Create.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

To create a topic:

  1. View a description of the CLI create topic command:

    yc managed-kafka topic create --help

  2. Create a topic:

    yc managed-kafka topic create <topic_name> \
  --cluster-name <cluster_name> \
  --partitions <number_of_partitions> \
  --replication-factor <replication_factor>

    If necessary, specify the topic settings here.

  1. Open the current Terraform configuration file with an infrastructure plan.

    For more information about creating this file, see Creating clusters.

  2. Add the yandex_mdb_kafka_topic resource and configure the topic under topic_config if required:

    resource "yandex_mdb_kafka_topic" "<topic_name>" {
  cluster_id         = "<cluster_ID>"
  name               = "<topic_name>"
  partitions         = <number_of_partitions>
  replication_factor = <replication_factor>
  topic_config {
    compression_type = "<compression_type>"
    flush_messages   = <maximum_number_of_messages_in_memory>
    ...
  }
}

  3. Make sure the settings are correct.

    1. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

    2. Run the command:

      terraform validate

      If there are errors in the configuration files, Terraform will point to them.

  4. Confirm updating the resources.

    1. Run the command to view planned changes:

      terraform plan

      If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

    2. If you are happy with the planned changes, apply them:

      1. Run the command:

        terraform apply

      2. Confirm the update of resources.

      3. Wait for the operation to complete.

For more information, see the Terraform provider documentation.

  1. Get an IAM token for API authentication and put it into the environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Use the Topic.create method and send the following request, e.g., via cURL:

    curl \
  --request POST \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --header "Content-Type: application/json" \
  --url 'https://mdb.api.cloud.yandex.net/managed-kafka/v1/clusters/<cluster_ID>/topics' \
  --data '{
            "topicSpec": {
             "name": "<topic_name>",
             "partitions": "<number_of_partitions>",
             "replicationFactor": "<replication_factor>"
          }'

    Where:

    • topicSpec stands for topic settings:

      • name: Topic name.
      • partitions: Number of partitions.
      • replicationFactor: Replication factor.

    You can get the cluster ID with a list of clusters in the folder.

  3. View the server response to make sure the request was successful.

  1. Get an IAM token for API authentication and put it into the environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume the repository contents are stored in the ~/cloudapi/ directory.

  3. Use the TopicService/Create call and send the following request, e.g., via gRPCurl:

    grpcurl \
  -format json \
  -import-path ~/cloudapi/ \
  -import-path ~/cloudapi/third_party/googleapis/ \
  -proto ~/cloudapi/yandex/cloud/mdb/kafka/v1/topic_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d '{
        "cluster_id": "<cluster_ID>",
        "topic_spec": {
             "name": "<topic_name>",
             "partitions": {
               "value": "<number_of_partitions>"
             },
             "replication_factor": {
               "value": "<replication_factor>"
             }
        }
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.kafka.v1.TopicService.Create

    Where:

    • topic_spec stands for topic settings:

      • name: Topic name.
      • partitions: Number of partitions. Provided as an object with the value field.
      • replication_factor: Replication factor. Provided as an object with the value field.

    You can get the cluster ID with a list of clusters in the folder.

  4. View the server response to make sure the request was successful.

Note

While running, Managed Service for Apache Kafka® is able to create service topics. You cannot write user data to such topics.

Updating topic settings

You cannot reduce the number of partitions in Managed Service for Apache Kafka® topics. You cannot create new partitions if there is not enough storage space.

For more information, see Minimum storage size.

  1. In the management console, go to the relevant folder.
  2. In the services list, select Managed Service for Kafka.
  3. Click the name of the cluster you need and select the Topics tab.
  4. Click for the topic you need and select Edit.
  5. Change the basic parameters of the topic:
    • Number of topic partitions.
    • Replication factor. This parameter value should not exceed the number of brokers in the cluster. Minimum value: 1. Maximum value: 3. Default:
      • For a cluster with one or two brokers: 1.
      • For a cluster with three or more brokers: 3.
  6. Change additional topic settings.
  7. Click Save.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

To update topic settings:

  1. View a description of the CLI update topic command:

    yc managed-kafka topic update --help

  2. Change topic settings:

    yc managed-kafka topic update <topic_name> \
  --cluster-name <cluster_name> \
  --partitions <number_of_partitions> \
  --replication-factor <replication_factor>

  1. Open the current Terraform configuration file with an infrastructure plan.

    For more information about creating this file, see Creating clusters.

  2. Edit the parameter values in the yandex_mdb_kafka_topic resource description:

    resource "yandex_mdb_kafka_topic" "<topic_name>" {
  cluster_id         = "<cluster_ID>"
  name               = "<topic_name>"
  partitions         = <number_of_partitions>
  replication_factor = <replication_factor>
  topic_config {
    compression_type = "<compression_type>"
    flush_messages   = <maximum_number_of_messages_in_memory>
    ...
  }
}

  3. Make sure the settings are correct.

    1. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

    2. Run the command:

      terraform validate

      If there are errors in the configuration files, Terraform will point to them.

  4. Confirm updating the resources.

    1. Run the command to view planned changes:

      terraform plan

      If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

    2. If you are happy with the planned changes, apply them:

      1. Run the command:

        terraform apply

      2. Confirm the update of resources.

      3. Wait for the operation to complete.

For more information, see the Terraform provider documentation.

  1. Get an IAM token for API authentication and put it into the environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Use the Topic.update method and send the following request, e.g., via cURL:

    Warning

    The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the updateMask parameter as a single comma-separated string.

    curl \
  --request PATCH \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --header "Content-Type: application/json" \
  --url 'https://mdb.api.cloud.yandex.net/managed-kafka/v1/clusters/<cluster_ID>/topics/<topic_name>' \
  --data '{
            "clusterId": "<cluster_ID>",
            "updateMask": "topicSpec.partitions,topicSpec.replicationFactor,topicSpec.topicConfig_2_8.<setting_1>,...,topicSpec.topicConfig_2_8.<setting_N>,topicSpec.topicConfig_3.<setting_1>,...,topicSpec.topicConfig_3.<setting_N>",
            "topicSpec": {
              "partitions": "<number_of_partitions>",
              "replicationFactor": "<replication_factor>",
              "topicConfig_2_8": {
                "<setting_1_for_Apache Kafka®_2.8_topic>": "<value_1>",
                "<setting_2_for_Apache Kafka®_2.8_topic>": "<value_2>",
                ...
                "<setting_N_for_Apache Kafka®_2.8_topic>": "<value_N>"
              },
              "topicConfig_3": {
                "<setting_1_for_Apache Kafka®_3.x_topic>": "<value_1>",
                "<setting_2_for_Apache Kafka®_3.x_topic>": "<value_2>",
                ...
                "<setting_N_for_Apache Kafka®_3.x_topic>": "<value_N>"
              }
            } 
          }'

    Where:

    • updateMask: List of parameters to update as a single string, separated by commas.

      In this case, list all the topic settings to update.

    • topic_spec stands for new topic settings:

      • partitions: Number of partitions.

      • replicationFactor: Replication factor.

      • topicConfig_2_8: Preset topic settings for Apache Kafka® 2.8. Use a separate line for each setting; separate them by commas.

      • topicConfig_3: Preset topic settings for Apache Kafka® 3.x. Use a separate line for each setting; separate them by commas.

        See Settings for individual topics for a description and possible values for each setting.

    You can get the cluster ID with a list of clusters in the folder.

  3. View the server response to make sure the request was successful.

  1. Get an IAM token for API authentication and put it into the environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume the repository contents are stored in the ~/cloudapi/ directory.

  3. Use the TopicService/Update call and send the following request, e.g., via gRPCurl:

    Warning

    The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the update_mask parameter as an array of paths[] strings.

    Format for listing settings
    "update_mask": {
    "paths": [
        "<setting_1>",
        "<setting_2>",
        ...
        "<setting_N>"
    ]
}

    grpcurl \
  -format json \
  -import-path ~/cloudapi/ \
  -import-path ~/cloudapi/third_party/googleapis/ \
  -proto ~/cloudapi/yandex/cloud/mdb/kafka/v1/topic_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d '{
        "cluster_id": "<cluster_ID>",
        "topic_name": "<topic_name>",
        "update_mask": {
          "paths": [
            "topic_spec.partitions",
            "topic_spec.replication_factor",
            "topic_spec.topic_config_2_8.<setting_1>",
            ...,
            "topic_spec.topic_config_2_8.<setting_N>",
            "topic_spec.topic_config_3.<setting_1>",
            ...,
            "topic_spec.topic_config_3.<setting_N>"
          ]
        },
        "topic_spec": {
             "partitions": {
               "value": "<number_of_partitions>"
             },
             "replication_factor": {
               "value": "<replication_factor>"
             },
             "topic_сonfig_2_8": {
                "<setting_1_for_Apache Kafka®_2.8_topic>": "<value_1>",
                "<setting_2_for_Apache Kafka®_2.8_topic>": "<value_2>",
                ...
                "<setting_N_for_Apache Kafka®_2.8_topic>": "<value_N>"
              },
              "topic_сonfig_3": {
                "<setting_1_for_Apache Kafka®_3.x_topic>": "<value_1>",
                "<setting_2_for_Apache Kafka®_3.x_topic>": "<value_2>",
                ...
                "<setting_N_for_Apache Kafka®_3.x_topic>": "<value_N>"
              }
        }
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.kafka.v1.TopicService.Update

    Where:

    • update_mask: List of parameters to update as an array of paths[] strings.

      In this case, list all the topic settings to update.

    • topic_spec stands for new topic settings:

      • partitions: Number of partitions. Provided as an object with the value field.

      • replication_factor: Replication factor. Provided as an object with the value field.

      • topic_config_2_8: Topic settings for Apache Kafka® 2.8. Use a separate line for each setting; separate them by commas.

      • topic_config_3: Topic settings for Apache Kafka® 3.x. Use a separate line for each setting; separate them by commas.

        See Settings for individual topics for a description and possible values for each setting.

    You can get the cluster ID with a list of clusters in the folder.

  4. View the server response to make sure the request was successful.

Getting a list of topics in a cluster

  1. In the management console, go to the relevant folder.
  2. In the services list, select Managed Service for Kafka.
  3. Click the cluster name and go to the Topics tab.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

To get a list of topics, run the following command:

yc managed-kafka topic list --cluster-name <cluster_name>

  1. Get an IAM token for API authentication and put it into the environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Use the Topic.list method and send the following request, e.g., via cURL:

    curl \
  --request GET \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --url 'https://mdb.api.cloud.yandex.net/managed-kafka/v1/clusters/<cluster_ID>/topics'

    You can get the cluster ID with a list of clusters in the folder.

  3. View the server response to make sure the request was successful.

  1. Get an IAM token for API authentication and put it into the environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume the repository contents are stored in the ~/cloudapi/ directory.

  3. Use the TopicService/List call and send the following request, e.g., via gRPCurl:

    grpcurl \
  -format json \
  -import-path ~/cloudapi/ \
  -import-path ~/cloudapi/third_party/googleapis/ \
  -proto ~/cloudapi/yandex/cloud/mdb/kafka/v1/topic_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d '{
        "cluster_id": "<cluster_ID>"
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.kafka.v1.TopicService.List

    You can get the cluster ID with a list of clusters in the folder.

  4. View the server response to make sure the request was successful.

Getting detailed information about a topic

  1. In the management console, go to the relevant folder.
  2. In the services list, select Managed Service for Kafka.
  3. Click the cluster name and go to the Topics tab.
  4. Click the topic name.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

To get detailed information about a topic, run the following command:

yc managed-kafka topic get <topic_name> --cluster-name <cluster_name>

  1. Get an IAM token for API authentication and put it into the environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Use the Topic.list method and send the following request, e.g., via cURL:

    curl \
  --request GET \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --url 'https://mdb.api.cloud.yandex.net/managed-kafka/v1/clusters/<cluster_ID>/topics/<topic_name>'

    You can request the cluster ID with a list of clusters in the folder and the topic name with a list of topics in the cluster.

  3. View the server response to make sure the request was successful.

  1. Get an IAM token for API authentication and put it into the environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume the repository contents are stored in the ~/cloudapi/ directory.

  3. Use the TopicService/Get call and send the following request, e.g., via gRPCurl:

    grpcurl \
  -format json \
  -import-path ~/cloudapi/ \
  -import-path ~/cloudapi/third_party/googleapis/ \
  -proto ~/cloudapi/yandex/cloud/mdb/kafka/v1/topic_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d '{
        "cluster_id": "<cluster_ID>",
        "topic_name": "<topic_name>"
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.kafka.v1.TopicService.Get

    You can request the cluster ID with a list of clusters in the folder and the topic name with a list of topics in the cluster.

  4. View the server response to make sure the request was successful.

Importing topics to Terraform

Using import, you can bring the existing cluster topics under Terraform management.

  1. In the Terraform configuration file, specify the topic you want to import:

    resource "yandex_mdb_kafka_topic" "<topic_name>" {}

  2. Run the following command to import the topic:

    terraform import yandex_mdb_kafka_topic.<topic_name> <cluster_ID>:<topic_name>

    To learn more about importing topics, see the Terraform provider documentation.

Deleting a topic

Note

Permissions granted to the user for a topic remain even after the topic is deleted. If, after deleting a topic, you don't revoke the permissions, then, when you create a topic with the same name, the user will have access to it even if you don't explicitly assign them new permissions.

  1. In the management console, go to the relevant folder.
  2. In the services list, select Managed Service for Kafka.
  3. Click the cluster name and go to the Topics tab.
  4. Click for the topic and select Delete topic.
  5. In the window that opens, click Delete.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

To delete a topic:

  1. View a description of the CLI update topic command:

    yc managed-kafka topic delete --help

  2. Delete a topic:

    yc managed-kafka topic delete <topic_name> --cluster-name <cluster_name>

  1. Open the current Terraform configuration file with an infrastructure plan.

    For more information about creating this file, see Creating clusters.

  2. Delete the yandex_mdb_kafka_topic resource with the topic description.

  3. Make sure the settings are correct.

    1. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

    2. Run the command:

      terraform validate

      If there are errors in the configuration files, Terraform will point to them.

  4. Confirm updating the resources.

    1. Run the command to view planned changes:

      terraform plan

      If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

    2. If you are happy with the planned changes, apply them:

      1. Run the command:

        terraform apply

      2. Confirm the update of resources.

      3. Wait for the operation to complete.

For more information, see the Terraform provider documentation.

  1. Get an IAM token for API authentication and put it into the environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Use the Topic.delete method and send the following request, e.g., via cURL:

    curl \
  --request DELETE \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --url 'https://mdb.api.cloud.yandex.net/managed-kafka/v1/clusters/<cluster_ID>/topics/<topic_name>'

    You can request the cluster ID with a list of clusters in the folder and the topic name with a list of topics in the cluster.

  3. View the server response to make sure the request was successful.

  1. Get an IAM token for API authentication and put it into the environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume the repository contents are stored in the ~/cloudapi/ directory.

  3. Use the TopicService/Delete call and send the following request, e.g., via gRPCurl:

    grpcurl \
  -format json \
  -import-path ~/cloudapi/ \
  -import-path ~/cloudapi/third_party/googleapis/ \
  -proto ~/cloudapi/yandex/cloud/mdb/kafka/v1/topic_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d '{
        "cluster_id": "<cluster_ID>",
        "topic_name": "<topic_name>"
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.kafka.v1.TopicService.Delete

    You can request the cluster ID with a list of clusters in the folder and the topic name with a list of topics in the cluster.

  4. View the server response to make sure the request was successful.

Managing topics via the Apache Kafka® Admin API

To manage topics via the Apache Kafka® Admin API:

  1. Create an admin user with the ACCESS_ROLE_ADMIN role in the cluster.
  2. Manage topics on behalf of this user by making requests to the Apache Kafka® Admin API. Review your favorite programming language manual for information on working with the Admin API.

For more information about working with the Admin API and the existing limitations, see Managing topics and partitions and the Apache Kafka® documentation.

Previous
Code snippets
Next
Managing users