Управление топиками Apache Kafka®

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

Чтобы создать топик:

1. Посмотрите описание команды CLI для создания топиков:

   yc managed-kafka topic create --help
   

2. Создайте топик:

   yc managed-kafka topic create <имя_топика> \
     --cluster-name <имя_кластера> \
     --partitions <количество_разделов> \
     --replication-factor <фактор_репликации>
   

   При необходимости здесь же задайте настройки топика.

   Примечание

   Если нужно создать топик, начинающийся с символа _, используйте Admin API Apache Kafka®. Создать такой топик с помощью интерфейсов Yandex Cloud нельзя.

1. Откройте актуальный конфигурационный файл Terraform с планом инфраструктуры.

   О том, как создать такой файл, см. в разделе Создание кластера.

2. Добавьте ресурс yandex_mdb_kafka_topic и, при необходимости, задайте настройки топика в блоке topic_config:

   resource "yandex_mdb_kafka_topic" "<имя_топика>" {
     cluster_id         = "<идентификатор_кластера>"
     name               = "<имя_топика>"
     partitions         = <количество_разделов>
     replication_factor = <фактор_репликации>
     topic_config {
       compression_type = "<тип_сжатия>"
       flush_messages   = <максимальное_число_сообщений_в_памяти>
       ...
     }
   }
   

   Примечание

   Если нужно создать топик, начинающийся с символа _, используйте Admin API Apache Kafka®. Создать такой топик с помощью интерфейсов Yandex Cloud нельзя.

3. Проверьте корректность настроек.

   1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.

   2. Выполните команду:

      terraform validate
      

      Если в файлах конфигурации есть ошибки, Terraform на них укажет.

4. Подтвердите изменение ресурсов.

   1. Выполните команду для просмотра планируемых изменений:

      terraform plan
      

      Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.

   2. Если вас устраивают планируемые изменения, внесите их:

      1. Выполните команду:

         terraform apply
         

      2. Подтвердите изменение ресурсов.

      3. Дождитесь завершения операции.

Подробнее см. в документации провайдера Terraform.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Воспользуйтесь методом Topic.create и выполните запрос, например, с помощью 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/<идентификатор_кластера>/topics' \
     --data '{
               "topicSpec": {
                "name": "<имя_топика>",
                "partitions": "<количество_партиций>",
                "replicationFactor": "<фактор_репликации>"
             }'
   

   Где:

   • topicSpec — настройки топика:

     • name — имя топика.

       Примечание

       Если нужно создать топик, начинающийся с символа _, используйте Admin API Apache Kafka®. Создать такой топик с помощью интерфейсов Yandex Cloud нельзя.

     • partitions – количество разделов.

     • replicationFactor – фактор репликации.

   Идентификатор кластера можно запросить со списком кластеров в каталоге.

3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Клонируйте репозиторий cloudapi:

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

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

3. Воспользуйтесь вызовом TopicService/Create и выполните запрос, например, с помощью 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": "<идентификатор_кластера>",
           "topic_spec": {
                "name": "<имя_топика>",
                "partitions": {
                  "value": "<количество_партиций>"
                },
                "replication_factor": {
                  "value": "<фактор_репликации>"
                }
           }
         }' \
     mdb.api.cloud.yandex.net:443 \
     yandex.cloud.mdb.kafka.v1.TopicService.Create
   

   Где:

   • topic_spec — настройки топика:

     • name — имя топика.

       Примечание

       Если нужно создать топик, начинающийся с символа _, используйте Admin API Apache Kafka®. Создать такой топик с помощью интерфейсов Yandex Cloud нельзя.

     • partitions – количество разделов. Передается в виде объекта с полем value.

     • replication_factor – фактор репликации. Передается в виде объекта с полем value.

   Идентификатор кластера можно запросить со списком кластеров в каталоге.

4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

Чтобы изменить настройки топика:

1. Посмотрите описание команды CLI для изменения топиков:

   yc managed-kafka topic update --help
   

2. Измените настройки топика:

   yc managed-kafka topic update <имя_топика> \
     --cluster-name <имя_кластера> \
     --partitions <количество_разделов> \
     --replication-factor <фактор_репликации>
   

1. Откройте актуальный конфигурационный файл Terraform с планом инфраструктуры.

   О том, как создать такой файл, см. в разделе Создание кластера.

2. Измените значение параметров в описании ресурса yandex_mdb_kafka_topic:

   resource "yandex_mdb_kafka_topic" "<имя_топика>" {
     cluster_id         = "<идентификатор_кластера>"
     name               = "<имя_топика>"
     partitions         = <количество_разделов>
     replication_factor = <фактор_репликации>
     topic_config {
       compression_type = "<тип_сжатия>"
       flush_messages   = <максимальное_число_сообщений_в_памяти>
       ...
     }
   }
   

3. Проверьте корректность настроек.

   1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.

   2. Выполните команду:

      terraform validate
      

      Если в файлах конфигурации есть ошибки, Terraform на них укажет.

4. Подтвердите изменение ресурсов.

   1. Выполните команду для просмотра планируемых изменений:

      terraform plan
      

      Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.

   2. Если вас устраивают планируемые изменения, внесите их:

      1. Выполните команду:

         terraform apply
         

      2. Подтвердите изменение ресурсов.

      3. Дождитесь завершения операции.

Подробнее см. в документации провайдера Terraform.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Воспользуйтесь методом Topic.update и выполните запрос, например, с помощью cURL:

   Важно

   Метод API переопределит все параметры изменяемого объекта, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре updateMask (одной строкой через запятую).

   curl \
     --request PATCH \
     --header "Authorization: Bearer $IAM_TOKEN" \
     --header "Content-Type: application/json" \
     --url 'https://mdb.api.cloud.yandex.net/managed-kafka/v1/clusters/<идентификатор_кластера>/topics/<имя_топика>' \
     --data '{
               "clusterId": "<идентификатор_кластера>",
               "updateMask": "topicSpec.partitions,topicSpec.replicationFactor,topicSpec.topicConfig_2_8.<настройка_1>,...,topicSpec.topicConfig_2_8.<настройка_N>,topicSpec.topicConfig_3.<настройка_1>,...,topicSpec.topicConfig_3.<настройка_N>",
               "topicSpec": {
                 "partitions": "<количество_партиций>",
                 "replicationFactor": "<фактор_репликации>",
                 "topicConfig_3": {
                   "<настройка_1_топика_Apache Kafka®_версии_3.x>": "<значение_1>",
                   "<настройка_2_топика_Apache Kafka®_версии_3.x>": "<значение_2>",
                   ...
                   "<настройка_N_топика_Apache Kafka®_версии_3.x>": "<значение_N>"
                 }
               } 
             }'
   

   Где:

   • updateMask — перечень изменяемых параметров в одну строку через запятую.

     В данном случае перечислите все изменяемые настройки топика.

   • topicSpec — новые настройки топика:

     • partitions – количество разделов.

     • replicationFactor – фактор репликации.

     • topicConfig_3 — набор настроек топика, если используется Apache Kafka® версий 3.x. Укажите каждую настройку на отдельной строке через запятую.

       Описание и возможные значения настроек см. в разделе Настройки отдельных топиков.

   Идентификатор кластера можно запросить со списком кластеров в каталоге.

3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Клонируйте репозиторий cloudapi:

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

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

3. Воспользуйтесь вызовом TopicService/Update и выполните запрос, например, с помощью gRPCurl:

   Важно

   Метод API переопределит все параметры изменяемого объекта, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре update_mask (в виде массива строк paths[]).

   Формат перечисления настроек

   "update_mask": {
       "paths": [
           "<настройка_1>",
           "<настройка_2>",
           ...
           "<настройка_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": "<идентификатор_кластера>",
           "topic_name": "<имя_топика>",
           "update_mask": {
             "paths": [
               "topic_spec.partitions",
               "topic_spec.replication_factor",
               "topic_spec.topic_config_2_8.<настройка_1>",
               ...,
               "topic_spec.topic_config_2_8.<настройка_N>",
               "topic_spec.topic_config_3.<настройка_1>",
               ...,
               "topic_spec.topic_config_3.<настройка_N>"
             ]
           },
           "topic_spec": {
                "partitions": {
                  "value": "<количество_партиций>"
                },
                "replication_factor": {
                  "value": "<фактор_репликации>"
                },
                 "topic_сonfig_3": {
                   "<настройка_1_топика_Apache Kafka®_версии_3.x>": "<значение_1>",
                   "<настройка_2_топика_Apache Kafka®_версии_3.x>": "<значение_2>",
                   ...
                   "<настройка_N_топика_Apache Kafka®_версии_3.x>": "<значение_N>"
                 }
           }
         }' \
     mdb.api.cloud.yandex.net:443 \
     yandex.cloud.mdb.kafka.v1.TopicService.Update
   

   Где:

   • update_mask — перечень изменяемых параметров в виде массива строк paths[].

     В данном случае перечислите все изменяемые настройки топика.

   • topic_spec — новые настройки топика:

     • partitions – количество разделов. Передается в виде объекта с полем value.

     • replication_factor – фактор репликации. Передается в виде объекта с полем value.

     • topic_config_3 — набор настроек топика, если используется Apache Kafka® версий 3.x. Укажите каждую настройку на отдельной строке через запятую.

       Описание и возможные значения настроек см. в разделе Настройки отдельных топиков.

   Идентификатор кластера можно запросить со списком кластеров в каталоге.

4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

Чтобы получить список топиков, выполните следующую команду:

yc managed-kafka topic list --cluster-name <имя_кластера>

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Воспользуйтесь методом Topic.list и выполните запрос, например, с помощью cURL:

   curl \
     --request GET \
     --header "Authorization: Bearer $IAM_TOKEN" \
     --url 'https://mdb.api.cloud.yandex.net/managed-kafka/v1/clusters/<идентификатор_кластера>/topics'
   

   Идентификатор кластера можно запросить со списком кластеров в каталоге.

3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Клонируйте репозиторий cloudapi:

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

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

3. Воспользуйтесь вызовом TopicService/List и выполните запрос, например, с помощью 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": "<идентификатор_кластера>"
         }' \
     mdb.api.cloud.yandex.net:443 \
     yandex.cloud.mdb.kafka.v1.TopicService.List
   

   Идентификатор кластера можно запросить со списком кластеров в каталоге.

4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

Чтобы получить детальную информацию о топике, выполните следующую команду:

yc managed-kafka topic get <имя_топика> --cluster-name <имя_кластера>

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Воспользуйтесь методом Topic.list и выполните запрос, например, с помощью cURL:

   curl \
     --request GET \
     --header "Authorization: Bearer $IAM_TOKEN" \
     --url 'https://mdb.api.cloud.yandex.net/managed-kafka/v1/clusters/<идентификатор_кластера>/topics/<имя_топика>'
   

   Идентификатор кластера можно запросить со списком кластеров в каталоге, а имя топика — со списком топиков в кластере.

3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Клонируйте репозиторий cloudapi:

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

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

3. Воспользуйтесь вызовом TopicService/Get и выполните запрос, например, с помощью 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": "<идентификатор_кластера>",
           "topic_name": "<имя_топика>"
         }' \
     mdb.api.cloud.yandex.net:443 \
     yandex.cloud.mdb.kafka.v1.TopicService.Get
   

   Идентификатор кластера можно запросить со списком кластеров в каталоге, а имя топика — со списком топиков в кластере.

4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

Чтобы удалить топик:

1. Посмотрите описание команды CLI для изменения топиков:

   yc managed-kafka topic delete --help
   

2. Удалите топик:

   yc managed-kafka topic delete <имя_топика> --cluster-name <имя_кластера>
   

1. Откройте актуальный конфигурационный файл Terraform с планом инфраструктуры.

   О том, как создать такой файл, см. в разделе Создание кластера.

2. Удалите ресурс yandex_mdb_kafka_topic с описанием нужного топика.

3. Проверьте корректность настроек.

   1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.

   2. Выполните команду:

      terraform validate
      

      Если в файлах конфигурации есть ошибки, Terraform на них укажет.

4. Подтвердите изменение ресурсов.

   1. Выполните команду для просмотра планируемых изменений:

      terraform plan
      

      Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.

   2. Если вас устраивают планируемые изменения, внесите их:

      1. Выполните команду:

         terraform apply
         

      2. Подтвердите изменение ресурсов.

      3. Дождитесь завершения операции.

Подробнее см. в документации провайдера Terraform.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Воспользуйтесь методом Topic.delete и выполните запрос, например, с помощью cURL:

   curl \
     --request DELETE \
     --header "Authorization: Bearer $IAM_TOKEN" \
     --url 'https://mdb.api.cloud.yandex.net/managed-kafka/v1/clusters/<идентификатор_кластера>/topics/<имя_топика>'
   

   Идентификатор кластера можно запросить со списком кластеров в каталоге, а имя топика — со списком топиков в кластере.

3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Клонируйте репозиторий cloudapi:

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

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

3. Воспользуйтесь вызовом TopicService/Delete и выполните запрос, например, с помощью 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": "<идентификатор_кластера>",
           "topic_name": "<имя_топика>"
         }' \
     mdb.api.cloud.yandex.net:443 \
     yandex.cloud.mdb.kafka.v1.TopicService.Delete
   

   Идентификатор кластера можно запросить со списком кластеров в каталоге, а имя топика — со списком топиков в кластере.

4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.