# AWS Kinesis integration

[Kinesis](https://aws.amazon.com/kinesis/) integrations enable you to automatically forward events that occur in Ably to AWS Kinesis streams.

## Create a Kinesis integration 

To create a Kinesis integration in your [dashboard:](https://ably.com/dashboard/any)

1. Login and select the application you wish to integrate with Kinesis.
2. Click the **Integrations** tab.
3. Click the **New Integration Rule** button.
4. Choose Firehose.
5. Choose AWS Kinesis.
6. Configure the Kinesis [settings](#settings).
7. Click **Create**.

You can also create a Kinesis integration using the [Control API](https://ably.com/docs/platform/account/control-api.md).

### Settings 

The following settings are available when creating a Kinesis integration:

| Setting | Description |
| ------- | ----------- |
| AWS Region  | Specifies the AWS region of your Kinesis Stream. |
| Stream Name | Defines the name of the Kinesis Stream to connect to. |
| [AWS authentication scheme](#auth) | Choose the authentication method. Either **AWS credentials** or **ARN of an assumable role**. |
| AWS Credentials | If using AWS credentials, enter the values in `key:value` format. |
| ARN of an assumable role | If using ARN of an assumable role, enter the ARN of the role that Ably can assume to access your Kinesis stream. |
| [Source](https://ably.com/docs/platform/integrations/streaming.md#sources) | Specifies the event types being sent to Kinesis. |
| [Channel filter](https://ably.com/docs/platform/integrations/streaming.md#filter) | Filters the source channels based on a regular expression. |
| Encoding | Specifies the encoding format of messages. Either JSON or MsgPack. |
| [Enveloped](https://ably.com/docs/platform/integrations/streaming.md#enveloped) | Checkbox to set whether messages should be enveloped or not. Enveloped is the default. |
| Partition key | Specifies the [partition key](https://ably.com/docs/messages.md#routing) used to route messages to a Kinesis stream shard. |

## AWS authentication 

Delegate access to your AWS resources by creating an [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) that the Ably AWS account can assume.

This approach follows AWS best practices, as it avoids sharing access keys directly. Specify the role's ARN to grant Ably the necessary permissions in a secure manner.

### Create a Kinesis policy 

The following steps show you how to create a policy for AWS Kinesis.

1. In the IAM console sidebar select **Policies**.
2. Click **Create Policy**.
3. Click the JSON tab and enter the following JSON to configure the policy:

<Code>

#### Json

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadWriteToSingleStream",
      "Effect": "Allow",
      "Action": [
        "kinesis:DescribeLimits",
        "kinesis:DescribeStream",
        "kinesis:GetShardIterator",
        "kinesis:GetRecords",
        "kinesis:ListTagsForStream",
        "kinesis:MergeShards",
        "kinesis:PutRecord",
        "kinesis:PutRecords",
        "kinesis:UpdateShardCount"
      ],
      "Resource": [
        "arn:aws:kinesis:<YOUR_AWS_REGION>:<YOUR_AWS_ACCOUNT>:stream/<YOUR_STREAM_NAME>"
      ]
    }
  ]
}
```
</Code>

<Aside data-type='note'>
You will need to replace `<YOUR_AWS_REGION>`, `<YOUR_AWS_ACCOUNT>` and `<YOUR_STREAM_NAME>` with the AWS region that hosts your Kinesis stream, your AWS account ID, and your Kinesis stream name respectively.
</Aside>

4. Click **Next: Tags**. You don't need to add any tags.
5. Click **Next: Review**.
6. Enter a suitable name for your policy.
7. Click **Create Policy**.

You have created a policy that grants the permissions required to use a Kinesis stream. You must now attach it to the role that you'll specify in your Ably integration rule.

### Create a role 

Create an IAM role as follows:

1. In the AWS IAM console, click **Roles** in the sidebar and then click **Create Role**.
2. For type of trusted entity select **Another AWS account**.
3. For Account ID specify 203461409171. This is the Ably AWS account.
4. Click the **Require external ID checkbox** and then enter an external ID of [`<Your_Ably_Account_ID>.<Your_Ably_app_ID>`](https://ably.com/docs/platform/account/control-api.md#ids).
5. Click **Next: Permissions**.
6. Now select the policy you created earlier to attach to this role. You can type the name of your policy into the **Filter policies** search box.

Then ensure the checkbox for the policy is selected.

7. Click **Next: Tags**.
8. You don't need to add tags so click **Next: Review**.
9. Enter a suitable name for your role.
10. Click **Create Role**.