Apache NiFi and Google Cloud Pub/Sub integration

Connect NiFi to Google Cloud Pub/Sub with ConsumeGCPubSub and PublishGCPubSub, choosing the right processing strategy, batch size and attribute mapping for your throughput needs.

On this page

Connecting NiFi to Google Cloud Pub/Sub with ConsumeGCPubSub and PublishGCPubSub

Use this section when messages in a Google Cloud Pub/Sub subscription need to reach NiFi flows, or when NiFi output needs to land on a Pub/Sub topic. NiFi covers both directions with two processors. ConsumeGCPubSub pulls messages from a subscription you name, and PublishGCPubSub publishes FlowFile content to a topic. The consume side is where most design decisions sit, because it offers three processing strategies: FlowFile, Demarcator and Record. The FlowFile strategy writes each message as its own FlowFile, the Demarcator strategy splits a batch of messages on a delimiter you define, and the Record strategy parses messages with a record reader and writes them through a record writer, which allows format conversion and schema enforcement.

Choose the strategy before you size anything else. Each one changes how many FlowFiles enter the canvas, how much work each downstream processor does, and how the batch size setting behaves. Confirm the message format with the producing team first. The Demarcator strategy only fits when every message can be split cleanly, so check that the producer does not embed the delimiter inside payloads. Confirm the schema owner and how schema changes are announced if you plan to use the Record strategy, because a schema mismatch can route records to failure rather than quietly passing them on.

On the publish side, the content of each FlowFile becomes one message body, and dynamic properties on PublishGCPubSub are sent as message attributes. Agree attribute names with the subscribers before the flow goes live, since downstream filters depend on them. Ask the Google Cloud and NiFi administrators to confirm the service account permissions for the subscription and topic, the project and credential configuration in the controller service, and how acknowledgement failures will be routed. Review the component documentation for ConsumeGCPubSub and PublishGCPubSub for the exact property names in your NiFi version.

What you need in place before the first Pub/Sub flow runs

Most failed first runs trace back to a missing prerequisite rather than a flow design error. The four areas below cover the NiFi runtime, the Google Cloud resources, the credentials and roles, and the network path, and each one should be confirmed before the processors are configured.

NiFi 2 and Java 21 runtime

Run NiFi 2 on Java 21, which the administration guide lists as the minimum runtime. Confirm the exact NiFi 2 release your environment will standardize on, since the downloads page lists the current series and its end-of-support dates. Build and test the flow on the same version and JVM you will run in production, and avoid mixing NiFi 1.x nodes into a cluster that consumes the same subscription during any migration window.

Google Cloud project and Pub/Sub resources

Identify the Google Cloud project that owns the topic and subscription, and confirm whether your team will pull from an existing subscription or create one for NiFi. Agree on subscription ownership early, because a subscription's acknowledgement deadline, retention and dead-letter settings affect how NiFi retries. Ask the platform team who owns the project and how changes to these resources are approved.

Service account credentials and IAM roles

Decide how NiFi authenticates to Google Cloud and which service account it uses. Keep credentials in a controller service rather than in flow parameters in plain text, and use a dedicated service account per flow or environment. Confirm the exact IAM role names needed for subscribing and publishing against the processor documentation, and check them against your organization's least-privilege policy before granting them.

Outbound access from every node

Every cluster node that runs the processors needs outbound network access to Google APIs, not only the primary node. Confirm proxy rules, egress firewall allowlists and DNS resolution from each host, since a node that cannot reach Google will fail its share of pulls silently. Test connectivity from each node before scheduling the processors, and record the egress path for your network security team.

Test subscription and rollback plan

Create a separate test topic and subscription so the first runs do not consume production messages. Define what happens to messages if the flow stops, including whether unacknowledged messages will be redelivered after the acknowledgement deadline. Agree on a rollback path, such as pausing the consuming flow and leaving the subscription untouched, before any production subscription is attached.

How to configure ConsumeGCPubSub and PublishGCPubSub in sequence

This sequence takes a NiFi flow from an authenticated Pub/Sub connection through consuming a subscription and publishing back to a topic, with a check at each stage so faults surface before the flow carries real traffic.

  1. Prepare the Google Cloud project and identities

    A Google Cloud administrator creates or confirms the project, the subscription that NiFi will pull from, the topic that NiFi will publish to, and a service account with only the Pub/Sub roles the flow needs. The NiFi administrator confirms the service account key handling process and where the credential file will be stored on the NiFi nodes. Ask your cloud team to confirm the current role names in Google Cloud documentation, since they are not listed in the researched facts for this page. The step is done when both resources exist, the service account can be seen in the project, and you have a test message ready to send to the subscription.

  2. Create the GCP credentials controller service

    In the NiFi canvas, add a GCP credentials controller service at the root or process group level, supply the service account credential source your security team approved, and enable it. Keep the credential file outside the flow definition so it is not exported with version-controlled flows. Check the controller service state: it should show as enabled with no validation errors. If validation fails, the most common causes are an unreadable key file on one node or a missing project reference, so verify the file exists with the same path on every node in the cluster before moving on.

  3. Configure ConsumeGCPubSub against the subscription

    Add a ConsumeGCPubSub processor and set its controller service, project ID, and subscription name. Leave the processing strategy at its default for the first test, and set a conservative batch size so you can read individual messages in the queue. Confirm that the processor validates and that its scheduling matches your plan for a clustered flow. Check the result by publishing a single test message to the subscription from the Google Cloud console or CLI, then starting the processor and confirming that one FlowFile appears in the success relationship with the message content.

  4. Select the processing strategy for the consumed messages

    Choose the FlowFile, Demarcator, or Record strategy based on the message format. The NiFi documentation says the Demarcator strategy gives the best throughput when the format allows it, and the Record strategy supports format conversion and schema enforcement. Use FlowFile when each message must stay separate with its own attributes. Switch strategies on a test subscription only, then send one sample of each message shape and compare the FlowFile count and content. The step is done when the output matches the downstream expectation for each shape, and malformed records route to a failure path rather than being dropped.

  5. Set the batch size and confirm backpressure

    Set the batch size on ConsumeGCPubSub based on the message size and the downstream processors' capacity, then send a burst of test messages to the subscription. Watch the connection queue counts and the processor's own statistics in the NiFi UI to see whether messages are pulled faster than the flow can clear them. Adjust the batch size and the number of concurrent tasks if queues grow unevenly across nodes. The check is that the queue drains steadily during the burst and that no messages are acknowledged without reaching a terminal relationship. Ask your NiFi team to confirm the throughput limits they expect for the cluster, since the researched facts do not give figures.

  6. Configure PublishGCPubSub with topic and attributes

    Add a PublishGCPubSub processor that reuses the same credentials controller service, then set the project ID and the target topic. Add dynamic properties for each attribute that should travel with the message, using values from FlowFile attributes through the expression language. The documentation states that dynamic properties are sent as message attributes, so name them to match what the subscribers filter on. Connect the consume path to this processor, and send the failure relationship to a retry or error queue rather than back into the same loop.

  7. Verify a published message on a test subscription

    Create a temporary subscription on the target topic, start the publish path, and send a test FlowFile with a known attribute value. Pull from the test subscription and confirm that the message body matches the FlowFile content and that the attributes appear with the expected names and values. Then stop the flow, remove the test subscription, and record the processor settings, the controller service configuration, and the test results in your change record. The sequence is complete when the end-to-end test passes on every node and the failure relationships have been exercised with one deliberately bad message.

Choosing FlowFile, Demarcator or Record processing for consumed messages

The FlowFile strategy writes each Pub/Sub message to its own FlowFile, so the message boundary is preserved exactly as received. It suits messages that are large, self-contained or not line-delimited, such as binary payloads, single JSON documents or files referenced by a message. Because every message becomes one FlowFile, each one carries its own provenance, attributes and retry path, which makes failure isolation simple to reason about.

  • Message boundary: each message maps to one FlowFile, so no splitting or parsing is needed to recover individual messages.
  • Per-message overhead: every FlowFile adds repository writes and processor invocations, which becomes the limiting factor at high message rates.
  • Attribute visibility: Pub/Sub metadata can be read directly from FlowFile attributes for routing without parsing the content.
  • Failure isolation: a bad message fails alone and can be routed to a failure relationship without affecting its neighbors.
  • Downstream fit: pick this when the consumer expects one object per message, for example one file per event.

Before choosing, confirm with the ConsumeGCPubSub component documentation how your NiFi version handles acknowledgement, and load a representative sample of real messages to measure the per-message cost in your environment.

How batch size and run schedule shape Pub/Sub throughput

Throughput from ConsumeGCPubSub is set by three things that interact: how many messages each run takes from the subscription, how often the processor is scheduled to run, and how quickly the downstream path drains the FlowFiles it creates. Raising the batch size without changing the run schedule only helps if the processor is actually running often enough to use the larger batch. Raising either without checking downstream back pressure simply moves the queue from the subscription into NiFi, where the connection queues fill and the processor stops producing output until the backlog clears. Treat the three as one tuning problem, not three independent settings.

Message size changes the arithmetic. Small messages in large batches give the best message rate per run, but the Demarcator strategy only helps when the format allows it, and the Record strategy adds parsing cost per message. Large messages make batch size a memory question for the NiFi nodes, so keep batches small enough that the heap and content repository can absorb a full run. Build a test set from your own topic: capture real message sizes and volumes at peak, then replay them against a non-production subscription at several batch sizes and run schedules. Record messages per second, FlowFile count, queue depth on the downstream connection and any acknowledgement lag. Confirm the current batch limits and recommended settings in the ConsumeGCPubSub component documentation for your NiFi version before you fix any values.

How Pub/Sub message fields map to NiFi attributes and FlowFile content

This table shows where each Pub/Sub message field lands in NiFi when ConsumeGCPubSub reads a subscription, and where publish-side dynamic properties go in PublishGCPubSub. Read each row against the processing strategy you choose, because the strategy decides whether the message body becomes the FlowFile content, a set of records, or demarcated segments. Confirm the ordering and acknowledgement behavior for your subscription before you rely on any mapping.

Pub/Sub fieldNiFi locationProcessing strategy that affects it
Message data (payload)FlowFile content, or records and segments derived from itFlowFile passes the payload through as content; Demarcator splits it on a delimiter; Record parses it with a reader and writer
Message attributes (key-value pairs set by the publisher)FlowFile attributes carried on each FlowFileConfirm that attributes survive the chosen strategy in your flow before building routing logic on them
Message IDIdentifier attribute on the FlowFile for tracing and duplicate checksConfirm the attribute name and whether it is set under each strategy in your NiFi 2 version
Publish timeTimestamp attribute on the FlowFileConfirm whether the publish time is exposed as an attribute and how it compares with event time in your data
Delimiter-separated lines in the payloadOne FlowFile per message, or one FlowFile per delimited segment within a messageDemarcator gives the best throughput when the format allows it, so check that your payload has a reliable delimiter
Structured payload (JSON, Avro or CSV)Record fields inside the FlowFile content, read with a record readerRecord supports format conversion and schema enforcement, so confirm the schema and how malformed messages are routed
PublishGCPubSub dynamic propertiesSet as Pub/Sub message attributes on each published messageDynamic properties are sent as attributes, so keep names and values within what the subscriber expects to filter on
Ordering key and acknowledgement stateNot a standard FlowFile attribute in the mapping; handled by the subscription and flow sessionConfirm ordering guarantees and redelivery behavior for your subscription and cluster layout before the flow goes live

Securing service account keys, network paths and message content

A Pub/Sub flow touches three trust boundaries: the Google Cloud identity that NiFi uses, the network path between NiFi and Google APIs, and the message bodies that land in FlowFiles, provenance and logs. The cards below cover each boundary so the flow owner can confirm controls before the first subscription is pulled in production.

Scope service accounts per subscription

Create one service account per flow or per trust zone rather than sharing a single key across all NiFi flows. Grant the Pub/Sub subscriber role on the specific subscriptions a processor consumes, and the publisher role only on the specific topics a processor writes to. Review whether a consuming flow needs topic-level rights at all. Ask your team to confirm the current IAM role names in Google Cloud documentation before writing the bindings.

Store key material as sensitive properties

Put the service account credential into a controller service that supplies it to ConsumeGCPubSub and PublishGCPubSub, and mark the credential property as sensitive so NiFi encrypts it at rest and masks it in the UI. Avoid pasting JSON keys into processor properties or parameter values that are not marked sensitive. Confirm how your chosen NiFi authentication provider and sensitive properties key are managed in the administration guide.

Restrict who can view processor properties

NiFi authorization policies separate the right to see a component from the right to change it, and the view of sensitive values is a separate permission. Limit view-sensitive-properties rights to the few operators who must troubleshoot credentials, and keep the Pub/Sub processors in a process group that only the flow team can edit. Check the policy inheritance from parent groups, because a broad grant higher up can expose processors you meant to protect.

Encrypt every transport hop

Traffic from NiFi nodes to Google Cloud APIs should use TLS, and the NiFi UI and cluster communication should use TLS as well. Confirm that NiFi is not bound to the loopback interface in production, since that default applies only when no security configuration is provided. Check outbound proxy and firewall rules on every node, because a single node with a missed egress route will fail pulls only on its partition of work.

Limit payloads in provenance and logs

Provenance records FlowFile content and attributes, and a debug log can echo message bodies, so a Pub/Sub message with personal or card data can persist well beyond the flow itself. Decide which fields are sensitive before go-live, route them through an encryption or masking step, and set provenance and log levels for the production flow accordingly. Ask your team to confirm the provenance retention settings for each repository in your environment.

Review message attributes before publishing

PublishGCPubSub sends dynamic properties as message attributes, which are readable by any principal who can pull from the downstream subscription. Treat attributes as data for other consumers: keep secrets, internal hostnames and raw identifiers out of them, and document which attributes each subscriber may read. Review the attribute list whenever a new dynamic property is added to a publishing processor.

Why ConsumeGCPubSub stalls, drops or rejects messages

This table lists the failures teams most often hit when pulling from or publishing to Pub/Sub with NiFi, with the likely cause, the first diagnostic step and the fix for each. Read it as a triage order: confirm the permission and schema symptoms first, then check backlog and redelivery behavior. Causes are drawn from how the processors consume and acknowledge messages, so confirm specifics against your own subscription and topic settings.

FailureLikely causeDiagnostic stepFix
Subscription permission errorsThe NiFi service account lacks subscriber rights on the subscription, or the credentials controller service points at the wrong projectCheck the processor bulletin and NiFi log for authorization errors, then test the same credentials against the subscription outside NiFiGrant the subscriber role on the specific subscription to the service account used by the GCP credentials service, and re-verify the project ID
Record schema mismatch under the Record strategyIncoming JSON or Avro does not match the configured record reader schema, so records fail parsingInspect failure-relationship FlowFiles and compare a sample payload with the schema in the readerCorrect the schema or make the reader tolerant of optional fields, and route parse failures to a dead-letter path for review
Backlog growth when the run schedule lagsPull frequency or batch size is too low for the message rate, so unacknowledged messages accumulate in the subscriptionWatch the subscription backlog and oldest unacknowledged message age in Cloud Monitoring alongside NiFi queue depthShorten the run schedule, raise batch size within what downstream can absorb, and add nodes or concurrent tasks where the flow permits
Duplicate delivery on redeliveryPub/Sub delivers at least once, so a message is redelivered if it is not acknowledged before the ack deadline or the session endsCompare message IDs in provenance for repeated deliveries and check whether downstream writes are idempotentMake downstream writes idempotent using the message ID as a key, and acknowledge only after the FlowFile is safely committed
Publish failures from missing topic IAMThe publishing service account lacks publisher rights on the topic, or the topic name is wrongCheck PublishGCPubSub failure bulletins and confirm the topic path with the project and topic values in the processorGrant the publisher role on the target topic to the service account and correct the project and topic properties
Messages held back in NiFi after pullsDownstream queues are full or back pressure is set low, so consumed messages wait in NiFi while the ack deadline passesCheck connection queue sizes and back pressure thresholds upstream of the downstream processorsRaise back pressure limits to match batch size, speed up the downstream path, and review the processor's acknowledgement timing
Attribute values missing downstreamDynamic properties on PublishGCPubSub were not set, or attribute names contain characters that did not map as expectedInspect the message attributes on a published message and compare with the dynamic propertiesDefine each attribute explicitly as a dynamic property and keep names simple and consistent across flows
Demarcator splits produce unexpected recordsThe delimiter does not match the payload format, or a message body contains the delimiterExamine a sample message containing the delimiter and count FlowFiles produced per messageChoose a delimiter that cannot appear in payloads, or switch to the Record strategy where the format needs structure

How to test the flow before it carries production traffic

Test the flow against a dedicated test topic and a dedicated test subscription before any production subscription is attached. Pub/Sub delivers each message to subscribers that pull from it, so a test subscription on a production topic would compete with live consumers and could take messages away from them. Create a separate topic for PublishGCPubSub tests and a separate subscription for ConsumeGCPubSub tests, both in a project and service account that do not hold production data. Agree with the customer which identities may publish to and pull from these test resources, and confirm that the service account used by the flow has only the Pub/Sub roles the test requires.

Build a sample payload set for each format the flow will handle, including JSON, Avro or any other format the production topic uses, plus deliberately malformed versions of each. Run each sample through ConsumeGCPubSub with the FlowFile, Demarcator and Record processing strategies that the design selects, and compare the output. For the Record strategy, check that the configured record reader and writer produce the expected schema, that numeric and timestamp fields keep their types, and that conversion does not drop fields. For Demarcator, confirm that the delimiter used in the test payloads never appears inside a message body. Check that every expected message attribute reaches the FlowFile and that PublishGCPubSub sends dynamic properties as attributes on the test topic, using the attribute names the downstream consumers read.

Inject failures on purpose. Publish malformed messages, oversized bodies and messages with missing attributes into the test topic, and confirm that the flow routes each one to the failure path rather than stalling the consumer or writing partial records. Then run an end-to-end count: the number of messages published to the test topic should match the number of FlowFiles delivered downstream plus the number routed to failure, with no unexplained gap. Repeat the count after a NiFi restart during a run. Acceptance criteria, including the allowed failure rate, the expected message counts, the throughput target and who signs off, should be agreed in writing with the customer before testing starts, so that a pass or fail result is not decided after the fact.

Questions buyers ask about Pub/Sub integration with NiFi

What drives the cost of a Pub/Sub to NiFi integration?

The main cost driver is how many subscriptions and topics the flow touches, followed by how many distinct message formats and schemas NiFi must parse. Each subscription needs its own consume design, error routing and checks for duplicates and ordering, and each schema adds reader configuration and testing. Security review adds time when credentials, service accounts and data classification need sign-off. One-time costs cover design, build and testing. Recurring costs cover monitoring, flow changes and NiFi upgrades. Ask any partner for a quote that lists subscriptions, formats, schema count and the security review as separate line items.

How long does a Pub/Sub integration take to deliver?

Duration depends on scope more than on the NiFi platform itself. A single subscription with one well-defined format usually takes less effort than several subscriptions that publish mixed schemas, need replay handling or must feed downstream systems. Timelines also move with access approvals in the Google Cloud project, the availability of sample messages and the number of review rounds for the security team. DeployOpen agrees timelines in the written, fixed scope before work starts, so ask for the milestones and the dependencies behind each one.

What must our team provide before the integration starts?

Expect to provide access to the Google Cloud project with rights to view topics and subscriptions, a service account or workload identity approach agreed with your security team, and representative test messages in every format the flow will handle. You also need the NiFi environment where the flow will run, named owners for each downstream system, and a sign-off contact who accepts test results. Confirm with your cloud team which Pub/Sub settings, such as acknowledgement deadlines and retention, they control, because those affect NiFi design.

Can our internal team build this without an outside partner?

Yes, if your team already runs NiFi in production and has engineers comfortable with Google Cloud IAM and Pub/Sub semantics. The processors are documented in the NiFi component reference, and the decisions are the same ones a partner would make: batch size, processing strategy, attribute mapping and error handling. Outside help usually adds value on the first subscription, where design choices set the pattern for the rest. Be honest about gaps in NiFi clustering, Google Cloud security or testing before deciding.

Which message formats change the design the most?

Formats that are line-delimited or easily split into complete messages suit the Demarcator strategy, which the ConsumeGCPubSub documentation describes as giving the best throughput when the format allows it. Structured formats that need type conversion or schema checks suit the Record strategy, which supports format conversion and schema enforcement. Mixed or nested payloads often need more testing because a parser failure can affect every message in a batch. Confirm the format of each topic with its producer before choosing a strategy.

What should a security review cover for this integration?

Review how NiFi authenticates to Google Cloud, who can read or change the consume and publish processors, and where credentials are stored. Check that message content, which may contain personal or regulated data, is handled under your data classification rules, including what is logged and how provenance is retained. NiFi supports several authentication providers for its own users, such as LDAP and OpenID Connect, and that access should be reviewed alongside the Google Cloud permissions. Ask your reviewer to confirm which controls their policy requires.

Does the integration need a NiFi upgrade or a version check first?

Check the NiFi version before design starts. NiFi 1.28 is the last minor release of the 1.x series, and the project encourages users to upgrade to NiFi 2. The current NiFi 2 processors are the ones this integration should target, so confirm that your running version includes the ConsumeGCPubSub and PublishGCPubSub processors you plan to use. If you are still on 1.x, plan the upgrade as its own workstream, because the migration guidance requires moving through NiFi 1.27.0 before 2.0.0. Confirm current versions in the NiFi download page before you commit to a plan.

How DeployOpen scopes, delivers and supports this integration

DeployOpen plans, builds and documents Apache NiFi and Google Cloud Pub/Sub integrations inside your own Google Cloud projects and NiFi clusters. Work starts from a written scope that names the subscriptions, topics, processing strategies and message contracts involved.

How we scope

  • Inventory the subscriptions and topics, their message formats and expected daily volumes with your platform owners
  • Choose the ConsumeGCPubSub and PublishGCPubSub processing strategies per flow, with the reasons written down
  • Agree in writing which attributes, schemas, acknowledgement behavior and failure paths are in scope
  • Engagements are fixed-scope, so deliverables and timelines are confirmed before build work begins

How we build

  • Configure service account credentials through controller services, with least-privilege roles on each subscription and topic
  • Build flows with batch size and demarcator or record settings tested against representative message samples
  • Map message attributes to FlowFile attributes and publish attributes so downstream routing stays predictable
  • Test redelivery, malformed messages and backpressure in a non-production NiFi cluster before go-live

How we hand over

  • Deliver flow documentation covering each processor setting, its reason and the expected message contract
  • Provide runbooks for credential rotation, subscription changes and replay of failed messages
  • Store flow definitions in your own version control, using the NiFi Registry or Git-based clients you choose
  • Train your operators on monitoring queue depth, acknowledgement lag and processor errors in your environment

How we support

  • Offer ongoing support, upgrades and continuous testing as a retainer after handover
  • Review throughput and error trends with your team when message volumes or formats change
  • Plan NiFi version upgrades and re-test Pub/Sub flows against each release before changing production
  • Confirm the processor documentation for your NiFi version with your team before each change

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.