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 iam[Verify Static IAM Roles] preBuild[WorkflowHook - PreBuild] style preBuild fill:#61B6EB,stroke:#000,stroke-width:4px; compile[Cross Compile for AWS AMI] cgoCompile[CGO Docker Compile for AWS AMI] postBuild[WorkflowHook - PostBuild] style postBuild fill:#61B6EB,stroke:#000,stroke-width:4px; nodeJSProxyShims[Create NodeJS-Go HTTP Proxies] pythonJSProxyShims[Create Python-CGO HTTP Proxies] package[ZIP archive] userArchive[WorkflowHook - Archive] style userArchive fill:#61B6EB,stroke:#000,stroke-width:4px; upload[Upload Archive to S3] packageAssets[Conditionally ZIP S3 Site Assets] uploadAssets[Upload S3 Assets] preMarshall[WorkflowHook - PreMarshall] style preMarshall fill:#61B6EB,stroke:#000,stroke-width:4px; generate[Marshal to CloudFormation] decorate[Call Lambda Decorators - Dynamic AWS Resources] serviceDecorator[Service Decorator] style serviceDecorator fill:#61B6EB,stroke:#000,stroke-width:4px; postMarshall[WorkflowHook - PostMarshall] style postMarshall fill:#61B6EB,stroke:#000,stroke-width:4px; uploadTemplate[Upload Template to S3] updateStack[Create/Update Stack] inplaceUpdates[In-place λ code updates] wait[Wait for Complete/Failure Result] iam-->preBuild preBuild-->|go|compile preBuild-->|cgo|cgoCompile compile-->postBuild cgoCompile-->postBuild postBuild-->|go|nodeJSProxyShims nodeJSProxyShims-->package nodeJSProxyShims-->packageAssets postBuild-->|cgo|pythonJSProxyShims pythonJSProxyShims-->package pythonJSProxyShims-->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