Workflow Hooks

Introduction

While Sparta tries to provide workflows common across service lifecycles, it may be the case that an application requires additional functionality or runtime resources.

To support this, Sparta allows you to customize the build pipeline via WorkflowHooks structure. These hooks are called at specific points in the provision lifecycle and support augmenting the standard pipeline:

graph TD classDef stdOp fill:#FFF,stroke:#A00,stroke-width:2px; classDef userHook fill:#B5B2A1,stroke:#A00,stroke-width:2px,stroke-dasharray: 5, 5; iam[Verify Static IAM Roles] class iam stdOp; preBuild[WorkflowHook - PreBuild] class preBuild userHook; compile[Cross Compile for AWS AMI] postBuild[WorkflowHook - PostBuild] class postBuild userHook; package[ZIP archive] class package stdOp; userArchive[WorkflowHook - Archive] class userArchive userHook; upload[Upload Archive to S3] packageAssets[Conditionally ZIP S3 Site Assets] uploadAssets[Upload S3 Assets] class upload,packageAssets,uploadAssets stdOp; preMarshall[WorkflowHook - PreMarshall] class preMarshall userHook; generate[Marshal to CloudFormation] class generate stdOp; decorate[Call Lambda Decorators - Dynamic AWS Resources] class decorate stdOp; serviceDecorator[Service Decorator] class serviceDecorator userHook; postMarshall[WorkflowHook - PostMarshall] class postMarshall stdOp; uploadTemplate[Upload Template to S3] updateStack[Create/Update Stack] inplaceUpdates[In-place λ code updates] wait[Wait for Complete/Failure Result] class uploadTemplate,updateStack,inplaceUpdates,wait stdOp; iam-->preBuild preBuild-->|go|compile compile-->postBuild postBuild-->package package-->packageAssets package-->userArchive userArchive-->upload packageAssets-->uploadAssets uploadAssets-->generate upload-->generate generate-->preMarshall preMarshall-->decorate decorate-->serviceDecorator serviceDecorator-->postMarshall postMarshall-->uploadTemplate uploadTemplate-->|standard|updateStack uploadTemplate-->|inplace|inplaceUpdates updateStack-->wait
This diagram is rendered with Mermaid. Please open an issue if it doesn't render properly.

The following sections describe the three types of WorkflowHooks available. All hooks accept a context map[string]interface{} as their first parameter. Sparta treats this as an opaque property bag that enables hooks to communicate state.

WorkflowHook Types

Builder Hooks

BuilderHooks share the WorkflowHook signature:

type WorkflowHook func(context map[string]interface{},
	serviceName string,
	S3Bucket string,
	buildID string,
	awsSession *session.Session,
	noop bool,
	logger *logrus.Logger) error

These functions include:

  • PreBuild
  • PostBuild
  • PreMarshall
  • PostMarshall

Archive Hook

The ArchiveHook allows a service to add custom resources to the ZIP archive and have the signature:

type ArchiveHook func(context map[string]interface{},
    serviceName string,
    zipWriter *zip.Writer,
    awsSession *session.Session,
    noop bool,
    logger *logrus.Logger) error

This function is called after Sparta has written the standard resources to the *zip.Writer stream.

Rollback Hook

The RollbackHook is called iff the provision operation fails and has the signature:

type RollbackHook func(context map[string]interface{},
    serviceName string,
    awsSession *session.Session,
    noop bool,
    logger *logrus.Logger)

Using WorkflowHooks

To use the Workflow Hooks feature, initialize a WorkflowHooks structure with 1 or more hook functions and call sparta.MainEx.

Notes

  • Workflow hooks can be used to support Dockerizing your application
  • Enable --level debug for detailed workflow hook debugging information