Resource lifecycle

Understand how Blueprints manages resource state during deployments, and how to configure deletion policies, ownership actions, and deployment dependencies.

When you run blueprints deploy, Blueprints compares your blueprint against the current state of your stack and determines what needs to change. Each change (creating, updating, or removing a resource) is an action. The full set of actions for a deploy is an operation.

Operations move through four states:

• Queued: Accepted, waiting to run.
• In progress: Actions are executing. Resources are created, updated, or destroyed in dependency order.
• Completed: All actions succeeded. Your stack matches the blueprint.
• Failed: One or more actions failed. Blueprints rolls back all completed actions in reverse order and restores your stack to its previous state.

Operations are transactional: either your stack fully reflects the new blueprint, or it is restored to what it was before.

You can follow progress in real time with blueprints deploy, which streams logs by default. To review a past operation, run blueprints logs.

• First deployment: Creates all resources in the blueprint.
• Redeploy with changes: Creates new resources, updates changed ones, and removes resources no longer in the blueprint.
• Remove a resource: Destroys that resource, unless a deletion policy prevents it.
• Run blueprints destroy: Destroys the stack and most managed resources; resources with a retain policy are detached rather than destroyed.

The lifecycle property is available on every resource type. It controls what happens to a resource when the stack is deployed, updated, or destroyed.

• deletionPolicy: Controls what happens when the resource is removed from the blueprint or the stack is destroyed. Defaults to allow; datasets and projects default to retain.
• ownershipAction: Controls the ownership relationship between a resource and the stack.
• dependsOn: Declares that this resource must be deployed after another resource in the same blueprint.

Controls what happens to a resource when you remove it from the blueprint or destroy the stack.

The resource is destroyed when removed from the blueprint or when you run blueprints destroy. This is the global default for most resource types.

Datasets and projects are an exception: they default to retain. Set deletionPolicy: 'allow' explicitly if you want them destroyed on removal.

defineRobotToken({
  name: 'ci-robot',
  label: 'CI Robot',
  memberships: [{
    resourceType: 'project',
    resourceId: 'your-project-id',
    roleNames: ['editor'],
  }],
  lifecycle: {
    deletionPolicy: 'allow',
  },
})

The resource is detached when the stack is destroyed and continues to exist independently. Removing it from the blueprint will cause the deployment to fail until you either restore it or set the policy to allow.

Robot tokens and other credentials are good candidates for retain since losing them can break dependent systems.

defineRobotToken({
  name: 'deploy-robot',
  label: 'Deploy Robot',
  memberships: [{
    resourceType: 'project',
    resourceId: 'your-project-id',
    roleNames: ['editor'],
  }],
  lifecycle: {
    deletionPolicy: 'retain',
  },
})

The resource is not updated, removed, destroyed, or detached by Blueprints while this policy is set. Any attempt causes the deployment to fail. To release a protected resource, first change deletionPolicy to allow or retain, deploy, then use detach.

Use protect during initial rollout to prevent accidental changes to critical resources. Remove it when you are ready to manage the resource normally.

defineRobotToken({
  name: 'deploy-robot',
  label: 'Deploy Robot',
  memberships: [{
    resourceType: 'project',
    resourceId: 'your-project-id',
    roleNames: ['editor'],
  }],
  lifecycle: {
    deletionPolicy: 'protect',
  },
})

❌ Don't use protect on a resource you expect to update regularly. Every deploy will fail until you remove the policy.

The resource is destroyed and recreated on every deployment rather than updated in place. Use replace when a resource does not support in-place updates or when you want a guaranteed clean state on each deployment.

defineDocumentWebhook({
  name: 'content-sync',
  url: 'https://api.example.com/webhook',
  on: ['create', 'update'],
  lifecycle: {
    deletionPolicy: 'replace',
  },
})

Some resource types override the global default. Datasets and projects have a default deletion policy of retain, not allow. Removing a dataset or project from a blueprint will fail unless you explicitly set deletionPolicy: 'allow'.

defineDataset({
  name: 'staging',
  datasetName: 'staging',
  lifecycle: {
    deletionPolicy: 'allow',
  },
})

Controls the ownership relationship between a resource and the stack. Use attach to take over an existing resource, detach to release one without destroying it, or reference to read values from a resource in another stack.

Use dependsOn to declare that one or more resources must be fully deployed before another. The values must start with $.resources. followed by the name of the resource to deploy first.

defineDocumentFunction({
  name: 'on-publish',
  src: 'functions/on-publish',
  event: {
    on: ['create'],
    filter: "_type == 'article'",
  },
  lifecycle: {
    dependsOn: ['$.resources.production-dataset'],
  },
})

If a resource already references another resource in its parameters using a $.resources.* path, Blueprints creates the deployment dependency automatically. You only need dependsOn when there is no such parameter reference and you still need to control the order.