Sample Service - Details

The Overview walked through a simple “Hello World” example. In this section we’ll cover how Sparta works in preparation for moving on to more advanced use. Most development will use the provision command line argument, so this section will outline exactly what that entails.

Provisioning Flow

The provisioning workflow is defined in provision.go, with a singular goal of encapsulating all AWS mutations into a CloudFormation template. Where CloudFormation does not support a given service, Sparta injects Lambda-backed Custom Resources into the template definition.

At a high level, provisioning uses the flow below. We’ll dive a bit deeper into each stage in the following sections.

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] cgoCompile[CGO Docker Compile for AWS AMI] class compile,cgoCompile stdOp; postBuild[WorkflowHook - PostBuild] class postBuild userHook; nodeJSProxyShims[Create NodeJS-Go HTTP Proxies] pythonJSProxyShims[Create Python-CGO HTTP Proxies] package[ZIP archive] class nodeJSProxyShims,pythonJSProxyShims,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 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.

Verify Static IAM Roles

The HandleAWSLambda function accepts either a string or a sparta.IAMRoleDefinition value type. In the event that a string is passed, this function verifies that the IAM role exists and builds up a cache of IAM role information that can be shared and referenced during template generation. Specifically, a pre-existing IAM Role ARN is cached to minimize AWS calls during template generation.

Compile

The next step is to cross compile the application to a binary that can be executed on an AWS Lambda instance. The compile flags are:

  • TAGS: -tags lambdabinary
  • ENVIRONMENT: GOOS=linux GOARCH=amd64

The binary is built in the current directory with a .lambda.amd64 suffix.

Package

The end result of the package phase is a ZIP archive containing everything needed to deploy your service. This includes the NodeJS proxy entries that forward AWS Lambda requests to your go binary HTTP-based handler. It also includes core google-protobuf to handle de/serializing events to your application. You can see these additional resources being included if you enable --level debug verbosity on the command line.

Upload Archive To S3

Uploads the archive to S3. There’s not much else to see here.

Generate CloudFormation Template

Once the archive is uploaded and the S3 Item key is available, the CloudFormation template is generated by marshaling the sparta.LambdaAWSInfo objects into CloudFormation JSON representations.

The AWS Lambda marshaling is automatically handled. This is also the point at which the optional TemplateDecorator functions are called to annocate the automatically generated template with additional resources.

Upload CloudFormation Template to S3

Uploads the template to S3 to maximize template size. There’s not much else to see here.

Create/Update Stack

Finally, the provisioning workflow determines whether the Sparta serviceName exists and either creates or updates as appropriate.

Next Steps

Now that we’ve covered how Sparta handles provisioning your stack, we’re ready to expand functionality to leverge more of the AWS ecosystem in the next section.