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:#1A98E7,stroke:#000,stroke-width:4px; compile[Cross Compile for AWS Linux AMI] postBuild[WorkflowHook - PostBuild] style postBuild fill:#1A98E7,stroke:#000,stroke-width:4px; proxyShims[Create NodeJS-Go HTTP Proxies] package[ZIP archive] userArchive[WorkflowHook - Archive] style userArchive fill:#1A98E7,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:#1A98E7,stroke:#000,stroke-width:4px; generate[Marshal to CloudFormation] decorate[Call Lambda Decorators - Dynamic AWS Resources] serviceDecorator[Service Decorator] style serviceDecorator fill:#1A98E7,stroke:#000,stroke-width:4px; postMarshall[WorkflowHook - PostMarshall] style postMarshall fill:#1A98E7,stroke:#000,stroke-width:4px; uploadTemplate[Upload Template to S3] converge[Create/Update Stack] wait[Wait for Complete/Failure Result] iam-->preBuild preBuild-->compile compile-->postBuild postBuild-->proxyShims proxyShims-->package proxyShims-->packageAssets package-->userArchive userArchive-->upload packageAssets-->uploadAssets uploadAssets-->generate upload-->generate generate-->preMarshall preMarshall-->decorate decorate-->serviceDecorator serviceDecorator-->postMarshall postMarshall-->uploadTemplate uploadTemplate-->converge converge-->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