Manage Flowcore v2 resource manifests

Flowcore v2 manifests describe platform resources as individual YAML documents. They provide a reviewable infrastructure-as-code workflow for data cores, flow types, event types, IAM, and other supported resource kinds.

A v2 resource follows a Kubernetes-style shape:

apiVersion: data-core.flowcore.io/v1
kind: DataCore
metadata:
  name: commerce
  tenant: acme-production
spec:
  accessControl: private
  deleteProtection: true
  description: Durable commerce event history

The four top-level fields have distinct roles:

• apiVersion selects the Flowcore API group and schema.
• kind identifies the resource type.
• metadata supplies stable identity such as name and tenant.
• spec contains the desired configuration.

Use one document per resource

Separate documents with ---:

apiVersion: data-core.flowcore.io/v1
kind: DataCore
metadata:
  name: commerce
  tenant: acme-production
spec:
  accessControl: private
  deleteProtection: true
  description: Durable commerce event history
 
---
 
apiVersion: data-core.flowcore.io/v1
kind: FlowType
metadata:
  name: order.0
  tenant: acme-production
spec:
  dataCore: commerce
  description: Order lifecycle events
  eventTypes:
    - name: order.placed.0
      description: An order was accepted for processing
    - name: order.cancelled.0
      description: An order was cancelled

References use stable names. The data core must exist before its flow type, but the CLI's v2 registry calculates dependency order when related resources are applied together.

Understand what a resource manifest owns

Data-core manifests own platform-level configuration such as:

• Resource names and parent relationships
• Descriptions
• Public or private access
• Delete protection
• Event type registration
• Sensitive Data configuration where supported

They do not normally define the complete TypeScript payload contract. Field-level runtime schemas belong in application contract code such as Zod definitions.

A manifest can declare order.placed.0; the application schema defines orderId, currency, line items, and validation rules.

Use the current schema

The data-core v2 API group is data-core.flowcore.io/v1. IAM resources use their corresponding current API group, such as iam.flowcore.io/v1.

Validate manifests against the schemas bundled with or supported by the installed CLI. Older guides can lag platform rollout or show legacy shapes.

Do not invent a resource kind because a REST object with a similar name exists. The CLI can only apply kinds registered by its plugins and schemas.

Store manifests in source control

Keep manifests with the application or platform repository that owns them. A reviewed pull request should show:

• The resource identity
• The intended environment
• Security and delete-protection changes
• New event or IAM resources
• Removed declarations
• Environment overlays

Do not embed API keys, bearer tokens, delivery secrets, or private certificates directly in source-controlled YAML.

A resource manifest is desired configuration, not a secret store.

Preview changes with diff

Run diff before apply:

flowcore diff \
  -f resources.yaml \
  --profile acme-production

Diff compares local resources with platform state and surfaces create or update behavior before mutation.

Review unexpected changes rather than accepting them because the file validates. A syntactically valid IAM or access-control change can still be unsafe.

If the diff is empty when you expect changes, verify the profile, tenant, API version, kind, and resource identity.

Apply v2 resources

Apply the reviewed documents with the v2 path:

flowcore apply --v2 \
  -f resources.yaml \
  --profile acme-production

Apply performs schema validation, merges matching resources from multiple inputs, calculates dependency order, shows changes, and requests confirmation unless automation explicitly supplies approval.

Existing resources are updated rather than recreated when identity matches.

Use interactive confirmation for manual production work. In CI, non-interactive approval should be protected by the deployment environment and review process, not exposed on every branch.

Understand identity and updates

The CLI identifies resources by their API registration and metadata, including kind and name. Changing a display description updates a resource. Changing a stable name generally creates a different identity and requires migration of references.

Do not rename a production data core or event resource as if it were a local variable. Names appear in API calls, Pathways registrations, IAM, dashboards, and retained event paths.

Let the CLI order dependencies

V2 API handlers can calculate apply order. Parent resources are created before children, such as:

1. Data core
2. Flow type
3. Nested event types
4. Consumers or resources that reference them

Documents can still be organized for human readability, but do not depend on accidental file order when the resource system has explicit dependencies.

When apply fails on a missing reference, confirm that the referenced resource is included, has the same tenant and name, and uses a supported kind.

Treat deletion separately from apply

Removing a document from Git does not automatically mean the platform resource should be deleted. Apply is not an implicit garbage collector.

To request deletion from a manifest:

flowcore delete \
  -f resources-to-delete.yaml \
  --profile acme-production

The CLI reverses dependency order so children and dependents are removed before parents.

Deletion can remove event history, break replay, invalidate Pathways, and destroy IAM configuration. Keep deletion in a dedicated reviewed change with explicit resource scope.

Respect delete protection

A production data core with deleteProtection: true cannot be deleted.

The safe sequence is:

1. Review and apply a separate change that sets delete protection to false.
2. Confirm producers, consumers, retention, and backups.
3. Prepare a manifest containing only the resources approved for deletion.
4. Run diff or equivalent inspection against the intended profile.
5. Execute delete with explicit approval.
6. Verify asynchronous platform completion and downstream cleanup.

Do not disable protection and delete in an unreviewed one-step automation.

Avoid accidental broad deletion

Before running delete, inspect the exact file content and selected profile. A copied manifest may contain more resources than the operator intended to remove.

Prefer a minimal deletion file rather than passing the complete production manifest and relying on prompts.

Never run deletion automatically because a pull request removed a YAML document unless the organization has designed, reviewed, and audited a reconciliation controller for that behavior.

Use meaningful descriptions

Descriptions support both operators and Pathways provisioning ownership. State the domain purpose rather than repeating the name.

Good:

description: Order lifecycle events used by fulfillment and customer support

Weak:

description: Orders

Descriptions should help a reviewer decide whether the resource belongs in this data core and who may depend on it.

Model sensitive event types carefully

Event type declarations can include Sensitive Data settings when protected fields require platform handling.

- name: customer.email-changed.0
  description: A customer's email address changed
  sensitiveDataEnabled: true
  sensitiveDataMask:
    key: customer-contact
    schema:
      type: object
      properties:
        email:
          type: string

Validate mask schemas in a non-production environment. Sensitive Data configuration does not replace payload minimization, IAM, encryption in transit, or secure logging.

Separate manifest ownership from Pathways ownership

Both v2 manifests and Pathways auto-provisioning can create shared resources.

Choose one owner per resource:

• Manifests own the data core and event registry, while application registrations omit provisioning descriptions.
• Pathways owns resources through descriptions and provision().
• A bootstrap service owns resources through SDK commands.

Mixed ownership can create confusing drift. If responsibilities are split, document exactly which fields each workflow controls.

Diagnose common failures

Schema validation failure

Check apiVersion, kind, required metadata, and the current resource schema. Do not force apply by switching to a legacy command path.

Referenced data core not found

Confirm that the data core document is included or already exists in the selected tenant. Verify exact spelling and profile.

Delete-protection conflict

Apply a reviewed update that disables protection first. Do not bypass the safeguard with another credential.

Unauthorized operation

Confirm the active user and profile, then inspect the required IAM action. Diff, apply, and delete may require different permissions.

Unexpected replacement or duplicate

Check whether metadata identity changed. A renamed resource is not the same object merely because its description is similar.

Continue with Compose environments and migrate legacy manifests.