Apache NiFi and Amazon Kinesis integration

Connect Apache NiFi to Amazon Kinesis Data Streams or Firehose with the supported NiFi processors, and plan checkpointing, IAM and ordering before the flow goes live. Learn when NiFi is the right consumer.

On this page

Apache NiFi and Amazon Kinesis integration: what the processors do

Choose the processor by direction first. When Kinesis data must enter a NiFi flow, use ConsumeKinesis, which reads records from an Amazon Kinesis Data Stream and stores its read position in a DynamoDB table so that consumption resumes after a NiFi restart. When NiFi must send records out, use PutKinesisStream for a Kinesis Data Stream, which needs the stream name, or PutKinesisFirehose for a Kinesis Data Firehose delivery stream, which needs the delivery stream name. The two writers are not interchangeable: a stream is read by consumers you operate, while a Firehose delivery stream is a managed path that delivers to its configured destination. Confirm the exact properties in the current component documentation for your NiFi 2 release, since property names and defaults can change between bundle versions. The ConsumeKinesis documentation is the reference for its checkpoint and shard settings.

The checkpoint table is the part teams most often underestimate. ConsumeKinesis depends on DynamoDB for state, so the AWS identity used by the NiFi AWS controller service needs permissions on that table as well as on the stream, and the table must exist in the region you expect. Plan who creates and owns that table, how it is named per consumer group, and what happens if two NiFi clusters read the same stream with the same checkpoint name. Ordering is a design constraint, not a tuning detail: the processor reads parent and child shards concurrently after a split or merge, so records from one partition key may arrive out of sequence. If downstream logic depends on order, decide before the build whether to sort or key the data downstream, or whether NiFi is the right consumer at all.

Decide whether NiFi is the right consumer before writing flows. NiFi fits when Kinesis data needs routing, parsing, enrichment or delivery to systems outside AWS, and when the team already operates NiFi clusters. It is a weaker fit when a single AWS-native service can do the job without an extra runtime to patch and secure. Ask your team to document the expected record volume per shard, the acceptable delay after a restart, the handling of duplicates during checkpoint replay, and the IAM policy each processor will use. Confirm these answers with your AWS account team and NiFi administrators before the flow is designed, because they determine the checkpoint layout and the failure paths you need to test.

What you need before building the Kinesis flows

Most Kinesis problems in NiFi start before the first processor is placed: the runtime, the AWS resources and the identities that touch them. Work through these cards with your AWS and platform teams so that the stream, the checkpoint table and the NiFi nodes are ready together.

NiFi 2 on a Java 21 runtime

Plan the Kinesis flows on NiFi 2 rather than 1.x, because the 1.x line cannot be maintained further and new work should not start there. The NiFi administration guide lists Java 21 as the minimum runtime, so confirm the JVM on every node before installing the AWS processor bundle. Check the exact NiFi 2 minor release you intend to run against the ConsumeKinesis documentation.

Streams and delivery streams

Identify each Kinesis Data Stream that ConsumeKinesis will read and each stream or Firehose delivery stream that PutKinesisStream or PutKinesisFirehose will write to. PutKinesisStream needs the stream name, and PutKinesisFirehose needs the delivery stream name, so record both in your flow parameters. Confirm the AWS Region and account for each resource with the data owners before anyone creates them.

DynamoDB checkpoint table

ConsumeKinesis stores its checkpoints in DynamoDB so that consumption resumes after a restart. Ask the AWS team to create the checkpoint table in the same account and Region as the stream, and decide who owns its capacity mode, backups and deletion. Do not share one checkpoint table between unrelated consumers, because they will overwrite each other's progress.

IAM principals and least privilege

Create a dedicated IAM role or user for each NiFi consumer and writer, and grant it access only to the streams, delivery streams and checkpoint table it uses. Read and write permissions should sit on separate principals where possible. Confirm the exact IAM actions for each processor against the component documentation, since the required set differs between reading, writing and checkpointing.

Credentials in NiFi

Decide how NiFi obtains AWS credentials for the Kinesis processors, preferring instance or workload roles over long-lived access keys stored in flows. Keep any secret material in NiFi's sensitive value handling, not in flow JSON or Git-versioned parameter files. Record who can view and change the AWS controller service, since that access is effectively access to the stream.

Network paths to AWS endpoints

Every NiFi node that runs a Kinesis processor must reach the regional Kinesis, DynamoDB and, for Firehose, delivery endpoints over HTTPS. Check egress rules, proxies, DNS resolution and any VPC endpoints from each node, not only from a bastion. Test the paths from every node in the cluster, because a single node with a blocked route will fail its share of the work.

How to configure ConsumeKinesis and the Kinesis writers

This sequence takes a team from empty AWS accounts to a NiFi flow that reads a Kinesis stream with checkpointing, writes to a stream, and delivers to a Firehose delivery stream, with a check at each stage.

  1. Create the AWS resources first

    Your AWS administrator creates the Kinesis Data Stream that NiFi will read, the stream or delivery stream it will write to, and the DynamoDB table that ConsumeKinesis uses for checkpoints. Decide the stream shard count, the Region and the table naming convention before anything is configured in NiFi, because the processor properties refer to these names directly. Confirm the resources exist and are active in the console or with the AWS CLI, and record the ARNs and names in your configuration worksheet. The step is done when every name the flow will reference is visible in the target Region and account.

  2. Grant IAM permissions to the NiFi host

    Create an IAM role or user for NiFi with only the actions its processors need: reading the stream and its shards, reading and writing the checkpoint table in DynamoDB, writing to the target stream, and writing to the delivery stream. Scope each statement to the specific resource ARNs. Confirm the exact action list against the ConsumeKinesis, PutKinesisStream and PutKinesisFirehose component documentation for your NiFi version, since the required permissions depend on how each processor is configured. The step is done when the policy simulator or a test call from the NiFi host succeeds for each action and fails for an unrelated resource.

  3. Configure the AWS credentials controller service

    Add the AWS credentials provider controller service at the root or process group level, choosing an instance profile, a role assumption or static keys according to your security policy. Prefer instance or workload identity where the NiFi hosts support it, and keep any static keys in NiFi's sensitive value handling. Set the Region, then enable the service and confirm it reports as valid. Reference this single service from every Kinesis processor so credentials are managed in one place. The step is done when the service is enabled and a processor using it reports no authentication error on its first validation.

  4. Set the stream and checkpoint table on ConsumeKinesis

    Place a ConsumeKinesis processor on the canvas and set the Kinesis stream name, the credentials service and the DynamoDB checkpoint table name. Keep the checkpoint table dedicated to this consumer, because checkpoints from different consumers must not share state. Review the record reader and writer choices and the output strategy so downstream processors receive records in the form they expect. Start the processor for a short period with a test producer writing to the stream. The step is done when the processor reports records received and the checkpoint table contains an item for the consumer after records are processed.

  5. Verify checkpoint resumption after a restart

    Stop the ConsumeKinesis processor, write a known set of test records to the stream while it is stopped, and then restart it. Compare the records received after restart with the records you sent so that you can see whether processing resumed from the stored checkpoint without replaying everything or skipping records. Inspect the checkpoint table in DynamoDB to confirm the sequence position advanced. Record the result, because a checkpoint that is not advancing will cause duplicates or gaps after a NiFi restart. The step is done when the restart test produces the expected count and the checkpoint item has changed.

  6. Configure PutKinesisStream with the stream name

    Add a PutKinesisStream processor, set the target stream name and the same credentials controller service, and connect it to an upstream path that carries the records to publish. Choose the record handling and partition key approach that matches how your consumers will order and group the data. Send a small batch of FlowFiles through the processor. Check the success relationship receives the FlowFiles and that the failure relationship is wired to a handling path rather than left unconnected. The step is done when a consumer reading the target stream outside NiFi sees the test records with the expected keys.

  7. Configure PutKinesisFirehose with the delivery stream name

    Add a PutKinesisFirehose processor, set the delivery stream name and the credentials controller service, and route a test set of FlowFiles to it. Firehose delivers to its own configured destination, so confirm the delivery stream's destination and buffering settings in AWS before judging the result, since delivery is not immediate. Keep the record format consistent with what the destination expects. Check the success and failure relationships as you did for the stream writer. The step is done when the test records appear at the Firehose destination, such as the configured storage location, within the delivery behavior you confirmed in AWS.

  8. Test each path and reconcile record counts

    Run a controlled test that sends a known number of records through the producer, the ConsumeKinesis path, the PutKinesisStream path and the PutKinesisFirehose path, then compare counts at each hop. Use provenance in NiFi to trace FlowFiles and identify any that went to failure, and review the CloudWatch metrics for the stream and delivery stream for throttling or errors. Document the expected and observed counts in your test record. The step is done when the counts reconcile at every hop, all failure relationships are either empty or handled, and the test is repeated after any configuration change.

How stream fields and FlowFile attributes map

This table compares how Kinesis record data, partition keys, sequence numbers and shard identifiers appear in a NiFi FlowFile, and how NiFi record fields feed the partition key on PutKinesisStream or the record payload on PutKinesisFirehose. Read each row as a design question to answer before you build the flow. Attribute names are the ones to confirm in the ConsumeKinesis and put processor documentation for your NiFi version.

Stream elementWhere it lands in NiFiWhat to confirm before building
Record data (payload)FlowFile content, read through a record reader or kept as raw bytesWhether the consumer emits one FlowFile per record or batches records, and the reader schema that matches the payload
Partition keyA FlowFile attribute set by ConsumeKinesis, carried through to downstream routingThe exact attribute name in the ConsumeKinesis documentation, and whether it survives record-level splitting
Sequence numberA FlowFile attribute that identifies the record position within its shardWhether the attribute is exposed in your NiFi version, and that you do not use it as a global ordering key across shards
Shard identifierA FlowFile attribute that identifies the source shard for the recordHow parent and child shards appear after a split or merge, since reads from both can run concurrently
NiFi record field to PutKinesisStream partition keySet the partition key property on PutKinesisStream from a record field or expressionWhich field has enough cardinality to spread load across shards, and that the same key always sends related records to the same shard
NiFi record field to PutKinesisFirehose recordThe FlowFile content is sent as the record, so the record writer defines the output shapeWhether the delivery stream expects a specific format, and that the record writer output matches the destination schema
Stream name and delivery stream nameConfigured on PutKinesisStream (stream name) and PutKinesisFirehose (delivery stream name)That the names resolve in the target AWS account and Region, and that parameters are used per environment

Why ordering breaks across shard splits and merges

Kinesis keeps order within a shard, but shard splits and merges create parent and child shards that ConsumeKinesis reads at the same time. The cards below cover what that means for downstream consumers and how to design around it before the flow goes live.

Concurrent parent and child reads

When a shard splits or merges, ConsumeKinesis reads the parent and child shards concurrently rather than draining the parent first. Records from one original key can therefore arrive interleaved, even though each shard is ordered on its own. Test a split on a non-production stream before you rely on order at the sink, and confirm the behavior against the processor documentation for your NiFi version.

Impact on order-dependent consumers

Consumers that apply updates as they arrive, such as a ledger, a balance calculation or a state machine, can end up applying an older change after a newer one. The error may not show up as a failure, so it can pass unnoticed into reports. Identify which downstream tables or APIs assume strict sequence before you choose a consumer design.

Idempotent writes at the sink

Design each write so that replaying or reordering it gives the same final state. Use a stable business key and a version or timestamp column, and write with upsert logic that only overwrites when the incoming version is newer. This approach works with PutDatabaseRecord and similar sinks, and it also protects against duplicates after a restart from checkpoint.

Sequence-aware sinks

Where a sink must keep order, store the Kinesis sequence number with each record and reject or hold writes that arrive behind the stored value. Ask the sink owner whether it can enforce this check, and document how late records are handled, for example by routing them to a review queue instead of silently discarding them.

When another consumer fits better

If the business needs strict order across a stream that is split or merged often, NiFi may be the wrong consumer for that path. Compare it with a consumer that manages shard ordering in its own model, and confirm that choice against your throughput, replay and operations requirements. Keep NiFi for enrichment, routing and delivery where ordering is enforced downstream.

When NiFi is the right consumer for Kinesis data

NiFi fits best when one Kinesis stream feeds many destinations and each destination needs its own filtering, format conversion or enrichment. A flow can read a stream once, split records by attribute, convert formats with record readers and writers, and deliver to object storage, a database, a search index and a SIEM from the same flow. Provenance records what happened to each FlowFile, which helps when a downstream team asks where a record went.

  • Single read, many outputs: One ConsumeKinesis group can serve several destinations, instead of each team running its own consumer code.
  • Attribute-based routing: RouteOnAttribute or record-based routing sends subsets of data to different sinks without custom code.
  • Format conversion: Record readers and writers handle JSON, Avro and other formats between the stream and the destination.
  • Provenance trail: Per-record lineage supports investigations and reprocessing questions from audit and operations teams.
  • Operator visibility: Queues, back pressure and processor status are visible in the UI without separate dashboards.

Before committing, confirm which PutKinesisStream or PutKinesisFirehose targets your flow needs and test sustained throughput with your own record sizes and shard count.

Securing the Kinesis integration with least-privilege IAM

The Kinesis integration touches three AWS resources and several NiFi components, and each one needs its own access boundary. The cards below cover how to scope IAM to the exact streams, delivery streams and checkpoint table, how NiFi stores and uses credentials, and how to protect data in transit and at rest inside NiFi.

Scope IAM to named resources

Write the consumer and producer policies against the specific stream ARNs, the specific Firehose delivery stream and the DynamoDB checkpoint table that the flow uses. Avoid wildcard resources in production. ConsumeKinesis needs read access to the stream and read and write access to its checkpoint table, while PutKinesisStream and PutKinesisFirehose need only write actions on their target. Review each policy against the processor properties, since a typo in a stream name fails quietly into a different permission scope.

Separate consumer and producer roles

Give the flow that reads from Kinesis a different IAM role from the flow that writes to Firehose or Kinesis. A single role with both read and write rights on every stream makes a compromised processor a route to tamper with upstream data. Keep the checkpoint table in the consumer role only, so that no producer path can reset or rewrite reading positions.

Prefer roles over long-lived keys

Where NiFi runs on EC2, EKS or another AWS compute service, use an instance profile, pod identity or assumed role instead of stored access keys. Temporary credentials expire and do not sit in flow definitions or backups. If static keys are unavoidable, record who owns them, rotate them on a fixed schedule and confirm that the AWS credentials provider service used by the processors supports your chosen method.

Control credential handling in controller services

Put AWS credentials only in the controller service that the Kinesis processors reference, not in individual processor properties. Restrict who can view or change that controller service, and confirm that it is enabled only where the flow needs it. Parameter contexts can hold the role or key references, but the values themselves should come from a secrets source managed outside the flow.

Protect sensitive values and editing rights

NiFi encrypts sensitive property values with the sensitive properties key, so back up that key separately from the flow definition and restrict access to it. Use NiFi's policies to limit who can view, modify or operate each process group, since editing a processor that writes to Kinesis is an action that changes production data. Review these policies whenever team membership changes.

Encrypt data in transit and confirm endpoints

The AWS SDK calls use HTTPS by default, but confirm that any VPC endpoints, proxies or custom endpoint URLs you configure also use TLS and that the NiFi cluster to Kinesis path does not leave the network boundary you intend. Enable TLS on NiFi's own web and cluster communication, and check the server certificate chain on any proxy used for outbound traffic. Ask your AWS account team or network owner which endpoint policies apply.

Common Kinesis failures in NiFi and how to fix them

This table lists the failures teams most often hit when running ConsumeKinesis and PutKinesisStream or PutKinesisFirehose, with the cause and fix for each. Read it as a triage checklist: match the symptom to the cause, then confirm the fix in a non-production stream before changing live flows. The main takeaway is that most failures trace to names, IAM scope, network reachability or assumptions about ordering and delivery.

FailureLikely causeFix
Records reprocessed after a restartThe IAM role cannot read or write the DynamoDB checkpoint table, so ConsumeKinesis cannot save its position and restarts from an earlier pointGrant the processor's role read and write access to the checkpoint table, confirm the table name matches the processor configuration, and check the processor logs for DynamoDB access errors
Duplicate records after restartsCheckpoints are saved only at intervals, so records read after the last checkpoint are delivered again when the processor resumesDesign downstream steps to be idempotent, using a stable record key for deduplication, and test a forced restart in a non-production flow to measure the overlap
Processor cannot find the streamThe stream name in ConsumeKinesis or PutKinesisStream does not match the stream in the target account or RegionConfirm the exact stream name and Region in the AWS console for the account the processor's credentials target, then correct the processor property
Firehose writes fail or go nowhereThe delivery stream name given to PutKinesisFirehose is wrong, or the stream is in another account or RegionUse the exact delivery stream name, verify it exists in the same Region as the processor, and check the failure relationship for the error returned
Access denied errorsThe IAM policy lacks Kinesis, Firehose or DynamoDB actions for the stream, delivery stream or checkpoint table, or the credential provider resolves to a different identity than expectedReview the effective identity used by the AWS credentials controller service, then add only the required actions scoped to the named resources and retest
Cluster nodes cannot reach AWSOutbound network rules, proxies or DNS on some nodes block the Kinesis, Firehose or DynamoDB endpoints, so only part of the cluster failsTest connectivity from every node to the regional endpoints, align proxy and firewall rules across nodes, and confirm the configured Region matches the endpoints you can reach
Out-of-order records after shard splits or mergesConsumeKinesis reads parent and child shards concurrently, so records from one key can arrive out of sequence after a split or mergeDo not rely on arrival order across a split or merge. Use the record's own timestamp or sequence data to reorder downstream, or route ordering-sensitive records to a consumer that enforces order
Ordering assumptions break in PutKinesisStream outputParallel or retried sends can change the order in which records reach the stream when concurrent tasks are usedChoose partition keys deliberately, reduce concurrency where order matters, and document which downstream consumers depend on order

Questions buyers ask about Kinesis and NiFi

Does NiFi add a license cost to a Kinesis integration?

No license fee applies to Apache NiFi itself. It is an Apache Software Foundation project released under the Apache License 2.0, and the project offers no paid edition. The costs you will see are the infrastructure to run NiFi, the AWS charges for Kinesis Data Streams, Firehose, DynamoDB checkpoint tables and CloudWatch, and the labor to design and build the flows. AWS usage is billed by AWS and is separate from NiFi. Ask any partner to show these components as separate lines in a quote, and ask which of them recur monthly and which are one-time build effort.

How long does a Kinesis and NiFi build take?

The duration depends on scope, not on the NiFi package itself. The main drivers are the number of streams and delivery targets, whether you need both reading and writing, how many record formats must be parsed, how much checkpoint and error handling you need, and how many AWS accounts and IAM roles must be approved. A single consume-and-deliver flow for one stream is a much smaller job than a multi-account design with failover and monitoring. Most engagements are fixed-scope, so the written scope should state the timeline and the milestones. Ask for those dates in the proposal rather than accepting an open-ended estimate.

What must our team supply before the build starts?

You need to supply the AWS accounts and regions in scope, the Kinesis streams or Firehose delivery streams with their names, and a clear list of record formats and consumers. Your cloud or security team must approve the IAM policies that let NiFi read and write the streams and manage the DynamoDB checkpoint table. Also provide a network path from the NiFi nodes to AWS endpoints, the credential method you allow (for example, an instance role or a managed secret), and an owner for the DynamoDB table and its capacity settings. Confirm the approval lead time with your IAM governance process early, because it often sets the start date.

Can our internal team build this without a partner?

Yes, an internal team with NiFi and AWS experience can build the integration alone. The processors are documented in the NiFi components documentation, and the work follows a known sequence: credentials, checkpointing, flow design, error handling and monitoring. The gaps usually appear in ordering design, IAM scoping, and testing shard splits or consumer restarts, which need deliberate planning. Ask whether your team has run a NiFi cluster in production, has tested AWS IAM least-privilege policies, and has a rehearsal plan for restarts. If any answer is no, a fixed-scope review or build can cover those areas while your team keeps ownership.

Does NiFi keep Kinesis records in order?

Not across a shard split or merge. ConsumeKinesis reads parent and child shards concurrently after a reshard, so records from the same partition key can interleave during that window. Within a single shard, records are generally processed in sequence, but a cluster with several consumers and FlowFile processing adds its own reordering risk. If your workload depends on strict per-key order, design the consumer to tolerate out-of-order arrival, use sequence numbers or event timestamps to reorder downstream, or choose a design that avoids resharding during business-critical windows. Confirm the exact behavior your use case needs before committing to NiFi.

When is NiFi the right consumer for Kinesis data?

NiFi fits when Kinesis data must be routed, enriched, converted or delivered to several systems, and when operators need a visual flow with provenance and retry handling. It is a weaker fit when you need a single lightweight consumer with strict ordering, very low latency per record, or a purpose-built stream processing job. Compare the options by listing the transformations, the number of destinations, the ordering requirement, and the team that will run the pipeline. If the work is mostly moving data from one stream to one store, a simpler consumer may be enough. If it is a hub for many formats and targets, NiFi is often a better fit.

What does ongoing operation of this integration involve?

Ongoing work covers monitoring the consumer lag and the DynamoDB checkpoint table, reviewing IAM permissions when streams change, handling reshards, and keeping NiFi itself patched and on a supported version. Most of these tasks recur, so ask whether the quote includes operational handover or a support retainer. DeployOpen offers ongoing support, upgrades and continuous testing as retainers, which can cover these tasks after the build. Ask which alerts you will receive, who responds to them, and how restarts are tested before they happen in production.

How do we confirm the integration is secure before go-live?

Confirm three areas before go-live: the IAM policy scope, the credential handling in NiFi, and the controls on the flow itself. The IAM policy should grant only the stream, delivery stream and checkpoint table actions the flow needs, and it should be reviewed by your security team. Credentials should come from a managed source rather than from flow files. On the NiFi side, check authentication, TLS and authorization settings as described in the NiFi administration guide. DeployOpen can run security testing on the resulting system, but the approval of the design remains with your team.

How DeployOpen scopes and delivers this integration

DeployOpen scopes this integration as a fixed-scope engagement, with the scope, deliverables and timeline agreed in writing before any work starts. For a Kinesis integration, that written scope should name each stream and delivery stream in use, the direction of each flow (ConsumeKinesis, PutKinesisStream or PutKinesisFirehose), the AWS account and Region that own the resources, the DynamoDB table that holds checkpoints, and the IAM roles NiFi will assume. Naming these items up front keeps the permission review, the checkpoint design and the test plan tied to the same list. Ask for the written scope to state what is excluded, such as changes to producers upstream of Kinesis or work on consumers outside NiFi, so both sides agree on where the integration ends.

The deliverables typically cover the flow definitions, the controller service configuration, the IAM policy documents, the checkpoint table settings, the test evidence for restart and shard-change behavior, and the runbook your operators will use. Because the flows are versioned in Git through NiFi's registry clients, the delivered flows can be reviewed and promoted through your own change process. Confirm with DeployOpen how the handover will work, including who receives the source, who holds the AWS access used during build, and how that access is removed at the end of the engagement.

Many teams also want help after go-live, such as reviewing shard counts as traffic grows, updating NiFi when new 2.x releases ship, or rerunning permission and failure tests after AWS changes. These needs are covered by optional retainers for ongoing support, upgrades and continuous testing. Ask for retainer terms in writing, including response expectations and what is included, so the support model is clear before the build is complete.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.