Artifact Lifecycle

Configure how Generic artifacts execute during plan, apply, and destroy stages using the lifecycle configuration map.

Prerequisites

• Understanding of Generic artifacts

• Familiarity with deployment lifecycle

Overview

The lifecycle configuration allows Generic artifacts to have different behavior for each deployment stage. You can:

• Override command arguments per stage

• Use different Docker images per stage

• Set stage-specific environment variables

• Skip execution for specific stages

When to Use Lifecycle Configuration

Use Lifecycle Config When:

• You need different command arguments per stage (e.g., tool apply vs tool destroy)

• You want to skip specific stages entirely (e.g., skip destroy for read-only scripts)

• Your tool requires different images per stage

• You need stage-specific environment variables

Use Environment Variable Detection When:

• Your script can handle all stages using the same command

• You want a single, stage-aware script

• Your logic branches based on BRICKS_ACTION environment variable

Lifecycle Configuration

Basic Structure

{
  "native": {
    "type": "generic",
    "image": "default-image:latest",
    "command": ["tool"],
    "args": ["default-action"],
    "lifecycle": {
      "plan": {
        "args": ["plan", "--detailed"]
      },
      "apply": {
        "args": ["apply", "--auto-approve"]
      },
      "destroy": {
        "args": ["destroy", "--force"]
      }
    }
  }
}

Lifecycle Phase Fields

Each phase (plan, apply, destroy) supports:

Field	Type	Description	Default
image	string	Container image for this phase	Inherits from native.image
command	array	Command to execute	Inherits from native.command
args	array	Command arguments	Inherits from native.args
env_vars	object	Environment variables (merged with native)	Inherits from native.env_vars
skip	boolean	Skip execution (only works for plan and destroy)	false

Configuration Inheritance

Lifecycle phase configuration overrides native configuration:

1. If a field is specified in lifecycle phase, it replaces the native value

2. If a field is not specified, it falls back to native configuration

3. Environment variables are merged (lifecycle takes precedence)

4. If skip: true, the container does not execute for that phase

Skipping Stages

Skipping Destroy with Lifecycle Config

The recommended way to skip destroy execution:

{
  "name": "health-check",
  "native": {
    "type": "generic",
    "image": "python:3.11-slim",
    "command": ["python"],
    "args": ["healthcheck.py"],
    "lifecycle": {
      "destroy": {
        "skip": true
      }
    }
  }
}

When destroy runs:

• Container does not execute

• No cleanup operations performed

• State is still removed

• Deployment uninstall completes successfully

Skipping Destroy with Environment Variable

Alternative approach using script logic:

import os
import sys
import json

action = os.environ.get('BRICKS_ACTION')

# Skip destroy operations
if action == 'destroy':
    with open('/workspace/outputs.json', 'w') as f:
        json.dump({'status': 'skipped'}, f)
    sys.exit(0)

# Continue with apply/plan logic

When to skip destroy:

• Health check scripts that only read data

• Monitoring tools that don't create resources

• Read-only operations

• API queries without side effects

Skipping Plan

Some operations don't need plan execution:

{
  "native": {
    "type": "generic",
    "lifecycle": {
      "plan": {
        "skip": true
      }
    }
  }
}

Environment Variables

All Generic artifact executions receive these environment variables:

BRICKS_ACTION

Current deployment stage being executed.

Values:

• plan - Preview/planning phase

• apply - Create/update operation

• destroy - Cleanup/removal operation

Usage:

import os

action = os.environ.get('BRICKS_ACTION')

if action == 'plan':
    validate_configuration()
elif action == 'apply':
    deploy_resources()
elif action == 'destroy':
    cleanup_resources()

BRICKS_STATE

Base64-encoded JSON of current deployment state. Available during all phases.

Structure:

{
  "output": {
    "resource_id": "res-12345",
    "status": "active"
  },
  "input_hash": "abc123..."
}

Usage:

import os
import json
import base64

state_b64 = os.environ.get('BRICKS_STATE')
if state_b64:
    state = json.loads(base64.b64decode(state_b64))
    previous_outputs = state.get('output', {})
    resource_id = previous_outputs.get('resource_id')

BRICKS_JOB_ID

Unique identifier for the current job execution.

Usage:

job_id = os.environ.get('BRICKS_JOB_ID')
print(f"[{job_id}] Starting operation")

Usage Examples

Example 1: Different Arguments Per Stage

For tools that require different CLI arguments:

{
  "name": "infra-tool",
  "native": {
    "type": "generic",
    "image": "custom/tool:latest",
    "command": ["tool"],
    "args": ["apply", "--config", "prod.yaml"],
    "lifecycle": {
      "plan": {
        "args": ["plan", "--config", "prod.yaml", "--detailed"]
      },
      "destroy": {
        "args": ["destroy", "--config", "prod.yaml", "--force"]
      }
    }
  }
}

Execution:

• Plan: tool plan --config prod.yaml --detailed

• Apply: tool apply --config prod.yaml

• Destroy: tool destroy --config prod.yaml --force

Example 2: Environment Variable Detection

For scripts that handle all stages:

bricks.json:

{
  "name": "resource-manager",
  "native": {
    "type": "generic",
    "image": "python:3.11-slim",
    "command": ["python"],
    "args": ["manager.py"]
  }
}

manager.py:

import os
import json
import base64

def create_resource(vars):
    # Create and return resource ID
    return "res-12345"

def delete_resource(resource_id):
    # Delete resource
    pass

def main():
    action = os.environ.get('BRICKS_ACTION')

    if action == 'apply':
        with open('/workspace/vars.json', 'r') as f:
            vars = json.load(f)

        resource_id = create_resource(vars)

        with open('/workspace/outputs.json', 'w') as f:
            json.dump({'resource_id': resource_id}, f)

    elif action == 'destroy':
        state_b64 = os.environ.get('BRICKS_STATE')
        if state_b64:
            state = json.loads(base64.b64decode(state_b64))
            resource_id = state['output'].get('resource_id')
            if resource_id:
                delete_resource(resource_id)

        with open('/workspace/outputs.json', 'w') as f:
            json.dump({'status': 'destroyed'}, f)

if __name__ == "__main__":
    main()

Example 3: Skipping Destroy

For read-only operations:

{
  "name": "api-health-check",
  "native": {
    "type": "generic",
    "image": "curlimages/curl:latest",
    "command": ["sh", "-c"],
    "args": ["curl $API_ENDPOINT/health"],
    "lifecycle": {
      "destroy": {
        "skip": true
      }
    }
  }
}

Example 4: Stage-Specific Environment Variables

{
  "name": "logger",
  "native": {
    "type": "generic",
    "image": "python:3.11-slim",
    "command": ["python"],
    "args": ["app.py"],
    "env_vars": {
      "LOG_LEVEL": "info"
    },
    "lifecycle": {
      "destroy": {
        "env_vars": {
          "LOG_LEVEL": "debug",
          "CLEANUP_MODE": "aggressive"
        }
      }
    }
  }
}

During destroy:

• LOG_LEVEL=debug (overrides native)

• CLEANUP_MODE=aggressive (additional)

Stage Execution Flow

Plan Stage

Default behavior:

• No execution unless lifecycle.plan is configured

• Outputs metadata placeholders

With lifecycle.plan config:

• Executes container with plan-specific configuration

• BRICKS_ACTION=plan

• BRICKS_STATE contains current state

When skipped:

{
  "lifecycle": {
    "plan": {
      "skip": true
    }
  }
}

Apply Stage

Always executes (unless input hash matches existing state).

Configuration:

• Uses lifecycle.apply if specified

• Falls back to native configuration

• BRICKS_ACTION=apply

• BRICKS_STATE contains current state

Note: skip: true on apply is not supported and will be ignored.

Destroy Stage

Executes during uninstall (v1.63.1+).

Configuration:

• Uses lifecycle.destroy if specified

• Falls back to native configuration

• BRICKS_ACTION=destroy

• BRICKS_STATE contains final state before removal

When skipped:

{
  "lifecycle": {
    "destroy": {
      "skip": true
    }
  }
}

Complete Example: Database Migration

bricks.json:

{
  "name": "db-migration",
  "version": "1.0.0",
  "native": {
    "type": "generic",
    "image": "migrate/migrate:latest",
    "command": ["migrate"],
    "args": [
      "-source", "file:///migrations",
      "-database", "postgres://...",
      "up"
    ],
    "lifecycle": {
      "plan": {
        "args": [
          "-source", "file:///migrations",
          "-database", "postgres://...",
          "version"
        ]
      },
      "destroy": {
        "args": [
          "-source", "file:///migrations",
          "-database", "postgres://...",
          "down"
        ]
      }
    }
  },
  "props": {
    "database_url": {
      "type": "string",
      "description": "PostgreSQL connection string"
    }
  }
}

Execution:

• Plan: Check current migration version

• Apply: Run migrations up

• Destroy: Run migrations down

Best Practices

Use Lifecycle Config For:

• Tools with stage-specific CLI syntax

• Skipping unnecessary stages

• Stage-specific Docker images

• Complex multi-tool workflows

Use Environment Detection For:

• Single scripts handling multiple stages

• Simple stage branching logic

• Unified codebases

Always Handle BRICKS_ACTION

Even if you don't use lifecycle config, check BRICKS_ACTION:

action = os.environ.get('BRICKS_ACTION', 'apply')
if action == 'destroy':
    # Handle cleanup
    pass

Write Outputs For All Stages

Always create /workspace/outputs.json, even if empty:

with open('/workspace/outputs.json', 'w') as f:
    json.dump({}, f)

Use BRICKS_STATE During Destroy

Access previous outputs to clean up resources:

if action == 'destroy':
    state = json.loads(base64.b64decode(os.environ.get('BRICKS_STATE')))
    resource_id = state['output'].get('resource_id')

Backward Compatibility

Packages without lifecycle config:

• Work exactly as before

• BRICKS_ACTION is still set

• Can use environment variable detection

Migration:

• No changes required for existing packages

• Add lifecycle config only if needed

• Environment variable detection works in all versions

See also

• Generic Artifact State -- change tracking and execution behavior

• Input/Output Handling -- vars.json and outputs.json contract

• Container Configuration -- image, command, and environment setup