Browse files

Initial commit of documentation sources

  • Loading branch information...
mweagle committed Nov 29, 2018
1 parent 7b23e61 commit 5f5bee341f2a821bcbe288e0c8932fe43b09e41a
Showing 733 changed files with 355,797 additions and 0 deletions.
@@ -0,0 +1,44 @@
baseURL = "/"
languageCode = "en-US"
defaultContentLanguage = "en"
title = "Sparta Documentation"
theme = "hugo-theme-learn"
metaDataFormat = "yaml"
defaultContentLanguageInSubdir= true
publishDir = "../docs"

editURL = ""
description = "Sparta - AWS Lambda Microservices"
author = "Matt Weagle"
showVisitedLinks = false
disableBreadcrumb = false
disableNextPrev = false
themeVariant = "sparta"
ordersectionsby = "weight"

home = [ "HTML", "RSS", "JSON"]

title = "Sparta - AWS Lambda Microservices"
weight = 1
languageName = "English"

name = "<i class='fab fa-fw fa-github'></i> Github repo"
identifier = "ds"
url = ""
weight = 10

name = "<i class='fas fa-fw fa-camera'></i> Showcases"
url = ""
weight = 11

name = "<i class='fas fa-fw fa-signal'></i> Release History"
url = ""
weight = 12
No changes.
@@ -0,0 +1,3 @@
![Sparta](/images/SpartaLogoNoDomain.png "Sparta")

@@ -0,0 +1,215 @@
date: 2016-03-08T21:07:13+01:00
type: index
weight: 0

<br />

![Sparta](/images/SpartaLogoNoDomain.png "Sparta")

# Self-deploying *go* microservices for [AWS Lambda](

Sparta is a framework that transforms a standard *go* application into a self-deploying AWS Lambda powered service. All configuration and infrastructure requirements are expressed as go types - no JSON or YAML needed!

# Sample Application

## 1. Definition

// File: application.go
package main
import (
sparta ""
// Hello world event handler
func helloWorld() (string, error) {
return "Hello World 🌏", nil
// Main
func main() {
var lambdaFunctions []*sparta.LambdaAWSInfo
lambdaFn := sparta.HandleAWSLambda("Hello world test",
lambdaFunctions = append(lambdaFunctions, lambdaFn)
// Delegate to Sparta
"Simple Sparta application that creates a single AWS Lambda function",

## 2. Deployment

$ go run main.go provision --s3Bucket $MY_S3_BUCKET
[0000] INFO ════════════════════════════════════════════════
[0000] INFO ╔═╗┌─┐┌─┐┬─┐┌┬┐┌─┐ Version : 1.1.1
[0000] INFO ╚═╗├─┘├─┤├┬┘ │ ├─┤ SHA : beb5700
[0000] INFO ╚═╝┴ ┴ ┴┴└─ ┴ ┴ ┴ Go : go1.10
[0000] INFO ════════════════════════════════════════════════
[0000] INFO Service: SpartaHelloWorld LinkFlags= Option=provision UTC=2018-05-25T04:36:50Z
[0000] INFO ════════════════════════════════════════════════
[0000] INFO Using `git` SHA for StampedBuildID Command=git rev-parse HEAD SHA=7ee3e1bc52f15c4a636e05061eaec7b748db22a9
[0000] INFO Provisioning service BuildID=7ee3e1bc52f15c4a636e05061eaec7b748db22a9 CodePipelineTrigger= InPlaceUpdates=false NOOP=false Tags=
[0000] INFO Verifying IAM Lambda execution roles
[0000] INFO IAM roles verified Count=1
[0000] INFO Checking S3 versioning Bucket=MY_S3_BUCKET VersioningEnabled=true
[0000] INFO Checking S3 region Bucket=MY_S3_BUCKET Region=us-west-2
[0000] INFO Running `go generate`
[0000] INFO Compiling binary Name=Sparta.lambda.amd64
[0001] INFO Creating code ZIP archive for upload TempName=./.sparta/
[0001] INFO Lambda code archive size Size=13 MB
[0001] INFO Uploading local file to S3 Bucket=MY_S3_BUCKET Key=SpartaHelloWorld/ Path=./.sparta/ Size=13 MB
[0011] INFO Uploading local file to S3 Bucket=MY_S3_BUCKET Key=SpartaHelloWorld/SpartaHelloWorld-cftemplate.json Path=./.sparta/SpartaHelloWorld-cftemplate.json Size=2.2 kB
[0011] INFO Creating stack StackID=arn:aws:cloudformation:us-west-2:123412341234:stack/SpartaHelloWorld/44b426d0-5fd5-11e8-90cd-503f20f2ad82
[0039] INFO CloudFormation Metrics ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
[0039] INFO Operation duration Duration=24.49s Resource=SpartaHelloWorld Type=AWS::CloudFormation::Stack
[0039] INFO Operation duration Duration=15.02s Resource=IAMRolebc3b888fab1664f42799785a6d9a3bb76ea63798 Type=AWS::IAM::Role
[0039] INFO Operation duration Duration=2.90s Resource=HelloworldtestLambdaa4a9e95c84255c65c284ce95dd7d3c45776c1a68 Type=AWS::Lambda::Function
[0039] INFO Stack provisioned CreationTime=2018-05-25 04:37:02.099 +0000 UTC StackId=arn:aws:cloudformation:us-west-2:123412341234:stack/SpartaHelloWorld/44b426d0-5fd5-11e8-90cd-503f20f2ad82 StackName=SpartaHelloWorld
[0039] INFO ════════════════════════════════════════════════
[0039] INFO SpartaHelloWorld Summary
[0039] INFO ════════════════════════════════════════════════
[0039] INFO Verifying IAM roles Duration (s)=0
[0039] INFO Verifying AWS preconditions Duration (s)=0
[0039] INFO Creating code bundle Duration (s)=1
[0039] INFO Uploading code Duration (s)=10
[0039] INFO Ensuring CloudFormation stack Duration (s)=28
[0039] INFO Total elapsed time Duration (s)=39

## 3. Invoke

![Console GUI](/images/invoke.jpg "Invoke")

<hr />

# Features

<table style="width:90%">
<!-- Row 1 -->
<td style="width:50%">
<p>Use a <b>go</b> monorepo to define and your microservice's:
<li>Application logic</li>
<li>AWS infrastructure</li>
<li>Operational metrics</li>
<li>Alert conditions</li>
<li>Security policies</li>
<td style="width:50%">
<h2>Complete AWS Ecosystem</h2>
<p>Sparta enables your lambda-based service to seamlessly integrate with the entire set of AWS lambda <a href="">event sources</a> such as:
<li>CloudWatch Events</li>
<li>CloudWatch Logs</li>
Additionally, your service may provision any other <a href="">CloudFormation</a> supported resource and even your own <a href="">CustomResources</a>.
<!-- Row 2 -->
<td style="width:50%">
<p>Define <a href="">IAM Roles</a> with limited privileges to minimize your service's attack surface. Both string literal and ARN expressions are supported in order to reference dynamically created resources. Sparta treats <a href="">POLA</a> and <a href="">#SecOps</a> as first-class goals.
<td style="width:50%">
<p>A service may provision dynamic AWS infrastructure, and <a href="">discover</a>, at lambda execution time, the dependent resources' AWS-assigned outputs (<code>Ref</code> &amp; <code>Fn::Att</code>). Eliminate hardcoded <i>Magic ARNs</i> from your codebase and move towards <a href="">immutable infrastructure</a></p>
<!-- Row 3 -->
<td style="width:50%">
<h2>API Gateway</h2>
<p>Make your service HTTPS accessible by binding it to an <a href="">API Gateway</a> REST API during provisioning. As part of API Gateway creation, Sparta includes <a href="">API Gateway Mapping Templates</a> with all request data, including user-defined whitelisted parameters, so that you can focus on your core application logic.</p>
<td style="width:50%">
<h2>Static Sites</h2>
<p>Include a <a href="">CORS-enabled</a> <a href="">S3-backed site</a> with your service. S3-backed sites include API Gateway discovery information for turnkey deployment.</p>

<hr />
<a href="" rel="Sparta Arch">![Sparta Overview](/images/sparta_overview.png)</a>

Sparta relies on [CloudFormation]( to deploy and update your application. For resources that CloudFormation does not yet support, it uses [Lambda-backed Custom Resources]( so that all service updates support both update and rollback semantics. Sparta's automatically generated CloudFormation resources use content-based logical IDs whenever possible to preserve [service availability]( and minimize resource churn during updates.

# Getting Started

To get started using Sparta, begin with the [Overview](/overview).

# Administration
- Problems? Please open an [issue]( in GitHub.

<br />
<img src="/images/GopherInclusion.png" alt="Eveyone Welcome" height="256">
<h6>Courtesy of <a href="">gophers</a>
<br />

# Questions?

Get in touch via:

- <i class="fas fas-twitter">&nbsp; @mweagle</i>
- <i class="fas fas-slack">&nbsp; Gophers: <a href="">@mweagle</a></i>
- [Signup page](
- <i class="fas fas-slack">&nbsp; Serverless: <a href="">@mweagle</a></i>
- [Signup page](

## Related Projects
- [go-cloudcondensor](
- Define AWS CloudFormation templates in `go`
- [go-cloudformation](
- `go` types for CloudFormation resources
- [ssm-cache](
- Lightweight cache for [Systems Manager Paramter Store]( values

## Other resources
* [Build an S3 website with API Gateway and AWS Lambda for Go using Sparta](
* [AWS blog post announcing Go support](
* [Sparta - A Go framework for AWS Lambda](
* Other libraries & frameworks:
* [Serverless](
* [PAWS](
* [Apex](
* [lambda_proc](
* [go-lambda](
* [go-lambda (GRPC)](
* Supported AWS Lambda [programming models](
* [Serverless Code Blog](
* [AWS Serverless Multi-Tier Architectures Whitepaper](
* [Lambda limits](
* [The Twelve Days of Lambda](
* [CloudCraft]( is a great tool for AWS architecture diagrams
@@ -0,0 +1,112 @@
date: 2018-01-22 21:49:38
title: CLI Options
weight: 15
alwaysopen: false

Sparta applications delegate `func main()` responsibilities to one of Sparta's Main entrypoints ([Main](, [MainEx]( This provides each application with some standard command line options as shown below:

$ go run main.go --help
Simple Sparta application that demonstrates core functionality
main [command]
Available Commands:
delete Delete service
describe Describe service
execute Start the application and begin handling events
explore Interactively explore a provisioned service
help Help about any command
profile Interactively examine service pprof output
provision Provision service
status Produce a report for a provisioned service
version Display version information
-f, --format string Log format [text, json] (default "text")
-h, --help help for main
--ldflags string Go linker string definition flags (
-l, --level string Log level [panic, fatal, error, warn, info, debug] (default "info")
--nocolor Boolean flag to suppress colorized TTY output
-n, --noop Dry-run behavior only (do not perform mutations)
-t, --tags string Optional build tags for conditional compilation
-z, --timestamps Include UTC timestamp log line prefix
Use "main [command] --help" for more information about a command.

It's also possible to add [custom flags](/reference/application/custom_flags) and/or [custom commands](/reference/application/custom_commands) to extend your application's behavior.

These command line options are briefly described in the following sections. For the most up to date information, use the `--help` subcommand option.

# Standard Commands

## Delete

This simply deletes the stack (if present). Attempting to delete a non-empty stack is not treated as an error.

## Describe

The `describe` command line option produces an HTML summary (see [graph.html](/images/overview/graph.html) for an example) of your Sparta service.

The report also includes the automatically generated CloudFormation template which can be helpful when diagnosing provisioning errors.

## Execute

This command is used when the cross compiled binary is provisioned in AWS lambda. It is not (typically) applicable to the local development workflow.

## Explore

The `explore` option creates a terminal GUI that supports interactive exploration of lambda functions deployed to AWS. This ui recursively searches for all _*.json_ files in the source tree to populate the set of eligible events that can be submitted.

![Explore](/images/explore.jpg "Explore")

## Profile

The `profile` command line option enters an interactive session where a previously profiled application can be locally visualized using snapshots posted to S3 and provided to a local [pprof ui](

## Provision

The `provision` option is the subcommand most likely to be used during development. It provisions the Sparta application to AWS Lambda.

## Status

The `status` option queries AWS for the current stack status
and produces an optionally account-id redacted report. Stack
outputs, tags, and other metadata are included in the status report:

$ go run main.go status --redact
INFO[0000] ════════════════════════════════════════════════
INFO[0000] ╔═╗╔═╗╔═╗╦═╗╔╦╗╔═╗ Version : 1.5.0
INFO[0000] ╚═╗╠═╝╠═╣╠╦╝ ║ ╠═╣ SHA : 8f199e1
INFO[0000] ╚═╝╩ ╩ ╩╩╚═ ╩ ╩ ╩ Go : go1.11.1
INFO[0000] ════════════════════════════════════════════════
INFO[0000] Service: MyHelloWorldStack-mweagle LinkFlags= Option=status UTC="2018-10-14T12:28:18Z"
INFO[0000] ════════════════════════════════════════════════
INFO[0001] StackId Id="arn:aws:cloudformation:us-west-2:************:stack/MyHelloWorldStack-mweagle/5817dff0-c5f1-11e8-b43a-503ac9841a99"
INFO[0001] Stack status State=UPDATE_COMPLETE
INFO[0001] Created Time="2018-10-02 03:14:59.127 +0000 UTC"
INFO[0001] Last Update Time="2018-10-06 14:20:40.267 +0000 UTC"
INFO[0001] Tag io:gosparta:buildId=7ee3e1bc52f15c4a636e05061eaec7b748db22a9

## Version

The `version` option is a diagnostic command that prints the version of the Sparta framework embedded in the application.

$ go run main.go version
INFO[0000] ════════════════════════════════════════════════
INFO[0000] ╔═╗╔═╗╔═╗╦═╗╔╦╗╔═╗ Version : 1.5.0
INFO[0000] ╚═╗╠═╝╠═╣╠╦╝ ║ ╠═╣ SHA : 8f199e1
INFO[0000] ╚═╝╩ ╩ ╩╩╚═ ╩ ╩ ╩ Go : go1.11.1
INFO[0000] ════════════════════════════════════════════════
INFO[0000] Service: MyHelloWorldStack-mweagle LinkFlags= Option=version UTC="2018-10-14T12:27:36Z"
INFO[0000] ════════════════════════════════════════════════
@@ -0,0 +1,18 @@
date: 2018-01-22 21:49:38
title: Credits
description: Sparta contributors
weight: 10000

## Thanks! 🎉🙏

- **Kyle Anderson**
- [James Brook](
- [Ryan Brown](
- [sdbeard](
- [Scott Raine](
- [Nick Scheiblauer](
- [Paul Seiffert](
- [Thom Shutt](
- [Patrick Steger](
Oops, something went wrong.

0 comments on commit 5f5bee3

Please sign in to comment.