channels

Creates, updates, deletes, gets or lists a channels resource.

Overview

Name	channels
Type	Resource
Id	aws.kafka.channels

Fields

The following fields are returned by SELECT queries:

describe_channel

Name	Datatype	Description
channel_arn	string	The Amazon Resource Name (ARN) that uniquely identifies the channel.
channel_name	string	The name of the channel.
cluster_operation_arn	string	The Amazon Resource Name (ARN) of the in-flight cluster operation. Returned only while the channel is in CREATING, UPDATING, or DELETING.
creation_time	string (date-time)	The time when the channel was created.
destination_type	string	The type of destination configured for the channel. (ICEBERG, S3)
encryption_configuration	object	The AWS KMS encryption configuration applied to data at rest.
iceberg_destination_configuration	object	Configuration of an Apache Iceberg destination for a channel.
logging_info	object	Configuration for the destinations to which the channel publishes operational logs.
s3_destination_configuration	object	Configuration of an Amazon S3 destination for a channel.
state_info	object	Additional context for the current channel state, populated when the channel is in FAILED.
status	string	The current lifecycle state of the channel. (CREATING, ACTIVE, UPDATING, DELETING, FAILED, SUSPENDING, SUSPENDED)
tags	object	The tags attached to the channel.
topic_configuration_list	array	The list of topic configurations for the channel.

list_channels

Name	Datatype	Description
channels	array	The list of channels in the cluster.
next_token	string	If the response from ListChannels is truncated, this token is included. Send it as the nextToken parameter on a subsequent ListChannels call to retrieve the next page.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_channel	select	channel_arn, cluster_arn, region		Returns the current configuration and state of a channel.
list_channels	select	cluster_arn, region	maxResults, nextToken, topicNameFilter	Returns the list of channels in a cluster.
create_channel	insert	cluster_arn, region, ChannelName, TopicConfigurationList		Creates a Channel that streams records from an Amazon MSK Express cluster topic to Amazon S3 or Apache Iceberg.
update_channel	update	channel_arn, cluster_arn, region		Updates the destination configuration of an existing channel. Exactly one of icebergDestinationUpdate or s3DestinationUpdate must be supplied.
delete_channel	delete	channel_arn, cluster_arn, region		Deletes the channel specified by channelArn from the cluster specified by clusterArn. The channel transitions through DELETING and is removed when the asynchronous delete completes.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
channel_arn	string	The Amazon Resource Name (ARN) that uniquely identifies the channel.
cluster_arn	string	The Amazon Resource Name (ARN) that uniquely identifies the cluster.
region	string	AWS region (default: us-east-1)
maxResults	integer	Maximum number of channels to return in a single response.
nextToken	string	If the response of ListChannels is truncated, it returns a nextToken in the response. This nextToken should be sent in the subsequent request to ListChannels.
topicNameFilter	string	Filters results to channels whose topic name matches the specified value.

SELECT examples

describe_channel

Returns the current configuration and state of a channel.

SELECT
channel_arn,
channel_name,
cluster_operation_arn,
creation_time,
destination_type,
encryption_configuration,
iceberg_destination_configuration,
logging_info,
s3_destination_configuration,
state_info,
status,
tags,
topic_configuration_list
FROM aws.kafka.channels
WHERE channel_arn = '{{ channel_arn }}' -- required
AND cluster_arn = '{{ cluster_arn }}' -- required
AND region = '{{ region }}' -- required
;

list_channels

Returns the list of channels in a cluster.

SELECT
channels,
next_token
FROM aws.kafka.channels
WHERE cluster_arn = '{{ cluster_arn }}' -- required
AND region = '{{ region }}' -- required
AND maxResults = '{{ maxResults }}'
AND nextToken = '{{ nextToken }}'
AND topicNameFilter = '{{ topicNameFilter }}'
;

INSERT examples

create_channel

Creates a Channel that streams records from an Amazon MSK Express cluster topic to Amazon S3 or Apache Iceberg.

INSERT INTO aws.kafka.channels (
ChannelName,
EncryptionConfiguration,
IcebergDestinationConfiguration,
S3DestinationConfiguration,
Tags,
TopicConfigurationList,
LoggingInfo,
cluster_arn,
region
)
SELECT 
'{{ ChannelName }}' /* required */,
'{{ EncryptionConfiguration }}',
'{{ IcebergDestinationConfiguration }}',
'{{ S3DestinationConfiguration }}',
'{{ Tags }}',
'{{ TopicConfigurationList }}' /* required */,
'{{ LoggingInfo }}',
'{{ cluster_arn }}',
'{{ region }}'
RETURNING
channel_arn,
cluster_operation_arn
;

Manifest

# Description fields are for documentation purposes
- name: channels
props:
  - name: cluster_arn
    value: "{{ cluster_arn }}"
    description: Required parameter for the channels resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the channels resource.
  - name: ChannelName
    value: "{{ ChannelName }}"
  - name: EncryptionConfiguration
    description: |
      The AWS KMS encryption configuration applied to data at rest.
    value:
      KmsKeyArn: "{{ KmsKeyArn }}"
  - name: IcebergDestinationConfiguration
    description: |
      Configuration of an Apache Iceberg destination for a channel.
    value:
      AppendOnly: {{ AppendOnly }}
      Catalog:
        CatalogArn: "{{ CatalogArn }}"
        WarehouseLocation: "{{ WarehouseLocation }}"
      DataFreshnessInSeconds: {{ DataFreshnessInSeconds }}
      DeadLetterQueueS3:
        BucketArn: "{{ BucketArn }}"
        ErrorOutputPrefix: "{{ ErrorOutputPrefix }}"
        ExpectedBucketOwner: "{{ ExpectedBucketOwner }}"
      DestinationTableList:
        - DestinationDatabaseName: "{{ DestinationDatabaseName }}"
          DestinationTableName: "{{ DestinationTableName }}"
          PartitionSpec:
            PartitionStrategy: "{{ PartitionStrategy }}"
            SourceList:
              - SourceName: "{{ SourceName }}"
      SchemaEvolution:
        EnableSchemaEvolution: {{ EnableSchemaEvolution }}
      ServiceExecutionRoleArn: "{{ ServiceExecutionRoleArn }}"
      TableCreation:
        EnableTableCreation: {{ EnableTableCreation }}
      CompressionType: "{{ CompressionType }}"
  - name: S3DestinationConfiguration
    description: |
      Configuration of an Amazon S3 destination for a channel.
    value:
      DataFreshnessInSeconds: {{ DataFreshnessInSeconds }}
      DeadLetterQueueS3:
        BucketArn: "{{ BucketArn }}"
        ErrorOutputPrefix: "{{ ErrorOutputPrefix }}"
        ExpectedBucketOwner: "{{ ExpectedBucketOwner }}"
      ServiceExecutionRoleArn: "{{ ServiceExecutionRoleArn }}"
      Storage:
        BucketArn: "{{ BucketArn }}"
        CompressionType: "{{ CompressionType }}"
        OutputPrefix: "{{ OutputPrefix }}"
        OutputKeyTemplate: "{{ OutputKeyTemplate }}"
        StorageClass: "{{ StorageClass }}"
        ExpectedBucketOwner: "{{ ExpectedBucketOwner }}"
  - name: Tags
    value: "{{ Tags }}"
  - name: TopicConfigurationList
    value:
      - RecordConverter:
          ValueConverter: "{{ ValueConverter }}"
        RecordSchema:
          GsrArn: "{{ GsrArn }}"
        TopicArn: "{{ TopicArn }}"
  - name: LoggingInfo
    description: |
      Configuration for the destinations to which the channel publishes operational logs.
    value:
      CloudWatchLogs:
        Enabled: {{ Enabled }}
        LogGroup: "{{ LogGroup }}"
      Firehose:
        DeliveryStream: "{{ DeliveryStream }}"
        Enabled: {{ Enabled }}
      S3:
        Bucket: "{{ Bucket }}"
        Enabled: {{ Enabled }}
        Prefix: "{{ Prefix }}"

UPDATE examples

update_channel

Updates the destination configuration of an existing channel. Exactly one of icebergDestinationUpdate or s3DestinationUpdate must be supplied.

UPDATE aws.kafka.channels
SET 
IcebergDestinationUpdate = '{{ IcebergDestinationUpdate }}',
S3DestinationUpdate = '{{ S3DestinationUpdate }}'
WHERE 
channel_arn = '{{ channel_arn }}' --required
AND cluster_arn = '{{ cluster_arn }}' --required
AND region = '{{ region }}' --required
RETURNING
channel_arn,
cluster_operation_arn;

DELETE examples

delete_channel

Deletes the channel specified by channelArn from the cluster specified by clusterArn. The channel transitions through DELETING and is removed when the asynchronous delete completes.

DELETE FROM aws.kafka.channels
WHERE channel_arn = '{{ channel_arn }}' --required
AND cluster_arn = '{{ cluster_arn }}' --required
AND region = '{{ region }}' --required
;