Plan Flowcore deployments and environment promotion

A Flowcore production rollout has three independently deployable parts: Flowcore resources, the application that publishes or consumes events, and the Data Pathway that delivers events. Keeping those parts separate makes releases easier to review and failures easier to locate.

This guide explains how to move a working service through development, staging, and production without mixing credentials, silently changing contracts, or switching delivery modes by accident.

Separate platform, delivery, and application changes

A managed or dedicated Flowcore installation determines who operates the platform. A managed or virtual Data Pathway determines where event delivery runs. Your application deployment determines how the producer, transform endpoint, and projections are released. These choices are related, but one does not imply another.

For example, an application running in your own Kubernetes cluster can use managed Flowcore and a managed Data Pathway. Flowcore operates event storage and delivery workers, while your team operates the application endpoint and its database. A different service may run a virtual pump in-process and therefore own checkpoint storage, scaling, and recovery as well.

Write these decisions into deployment configuration instead of inferring them from NODE_ENV. Production should never switch from virtual to managed delivery only because an environment variable was omitted.

Keep environments isolated

Development, staging, and production need independent credentials and resource scopes. A development key must not be able to publish to production, inspect production history, or administer production pathways.

Use distinct CLI profiles, secret-manager paths, API keys, pathway assignments, and monitoring views. Separate tenants when you require a hard governance boundary; otherwise use clearly isolated resources and policies within the approved tenant model. In either case, the active environment should be obvious from the configuration and logs.

A production service should fail at startup when its tenant, API key, data core, or transform secret is missing. Falling back to development credentials hides configuration errors and can send events to the wrong environment.

Promote Flowcore resources with manifests

Flowcore v2 resources should be defined in versioned YAML and promoted through review. Keep data cores, flow types, event types, Data Pathways, and IAM resources close enough that reviewers can understand their relationships, while retaining separate files where ownership requires it.

Run a diff before every apply. The diff is where you catch an unexpected delete, a broader FRN, a changed endpoint, or disabled delete protection. A small YAML change can affect security or replayability, so production applies should run through protected automation with a dedicated identity rather than a developer's personal token.

A practical promotion sequence is development apply, staging verification, and then production apply from the same reviewed revision. Environment-specific overlays should contain identifiers and capacity settings, not divergent copies of the entire resource model.

Release additive contract changes first

Event history is immutable, so application releases must preserve the meaning of existing event types. If a payload changes incompatibly, introduce a new event-type version such as order.placed.1. Deploy consumers that understand the new version before producers begin emitting it.

For additive changes, deploy in this order:

1. Apply the new Flowcore resource or contract definition.
2. Deploy consumers that can process it.
3. Deploy producers that emit it.
4. Observe delivery and projection freshness before removing old code.

This is one of the few places where a numbered sequence is useful: reversing the order can produce valid events that no running consumer understands.

Choose the production delivery model explicitly

Managed Data Pathways are the usual production default when your service exposes a stable HTTP endpoint. Flowcore operates worker assignment, capacity, retries, and delivery position. Your service authenticates the request and handles the event.

A virtual pathway is appropriate when the application must own delivery in-process. That choice also makes your team responsible for durable checkpoints, leader coordination across replicas, graceful shutdown, replay controls, and pump-specific health signals. A process heartbeat alone is not enough; the pump can stop advancing while the application continues serving requests.

Whichever model you choose, record it in the service's operational documentation together with its tenant, data core, subscriptions, endpoint, and owner.

Separate provisioning from runtime access

Automatic provisioning is convenient in development but gives the application broader permissions than ordinary processing requires. In production, use a bootstrap job or manifest pipeline to create shared resources, then run the application with a narrower key.

A producer normally needs permission to ingest selected event types. A managed transform endpoint needs to validate delivery and update its own projection. Neither usually needs tenant administration, IAM mutation, resource deletion, or unrestricted event-history access.

Calling provision() with a narrow runtime key can fail with a 403 when Pathways attempts to update resources. That failure is a sign to clarify ownership, not a reason to grant the application administrator access.

Configure the application for operations

A production service needs a health endpoint, structured logging, graceful shutdown, and secrets injected at runtime. Its startup log should identify the environment, tenant, data core, delivery mode, and application version without printing credentials.

For a managed pathway, configure the exact subscribed event types and a reachable transform endpoint. Do not subscribe a service to events it publishes unless the loop is intentional. Protect the endpoint with TLS, network controls where available, and the secret expected by PathwayRouter.

For Kubernetes, readiness should indicate whether the service can receive work. Liveness should detect a process that cannot recover without restart. Pump progress and projection freshness belong in metrics or a deeper diagnostic check rather than a shallow endpoint that always returns 200.

Rotate credentials without interrupting delivery

Use an overlap period for API keys and transform secrets. Create the replacement, store it as a new secret version, deploy consumers, and verify successful requests from every replica before revoking the old value.

Managed pathway secret rotation requires coordination between the pathway configuration and the endpoint. If the endpoint can temporarily accept both values, update it first, change the pathway second, and remove the old secret after delivery is confirmed. Never place key values in manifests, images, event metadata, or routine logs.

Verify the complete event path

A healthy pod does not prove a healthy Flowcore deployment. Publish a representative event and follow it through ingestion, pathway delivery, handler completion, and projection update. Check that expected authorization succeeds and that unrelated access still fails.

For new flow types or virtual pumps, verify the initial checkpoint before the first production event is emitted. Some cold-start configurations begin near the current time when no state exists, which can skip events created before the pump started.

Record the deployed manifest revision, application version, verification event ID, and operator. That evidence gives the next incident responder a known-good point.

Continue with Operate Data Pathways in production for delivery health, retries, capacity, and recovery.