Permalink
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
enableGitInfo=true
publishDir = "../docs"

[params]
editURL = "https://github.com/mweagle/Sparta/tree/docs/content/"
description = "Sparta - AWS Lambda Microservices"
author = "Matt Weagle"
showVisitedLinks = false
disableBreadcrumb = false
disableNextPrev = false
themeVariant = "sparta"
ordersectionsby = "weight"

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

[Languages]
[Languages.en]
title = "Sparta - AWS Lambda Microservices"
weight = 1
languageName = "English"

[[Languages.en.menu.shortcuts]]
name = "<i class='fab fa-fw fa-github'></i> Github repo"
identifier = "ds"
url = "https://github.com/mweagle/Sparta"
weight = 10

[[Languages.en.menu.shortcuts]]
name = "<i class='fas fa-fw fa-camera'></i> Showcases"
url = "https://github.com/mweagle?utf8=%E2%9C%93&tab=repositories&q=Sparta&type=&language="
weight = 11

[[Languages.en.menu.shortcuts]]
name = "<i class='fas fa-fw fa-signal'></i> Release History"
url = "https://github.com/mweagle/Sparta/blob/master/CHANGES.md"
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
title:
type: index
weight: 0
---

<br />

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

# Self-deploying *go* microservices for [AWS Lambda](https://aws.amazon.com/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

```go
// File: application.go
package main
import (
sparta "github.com/mweagle/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",
helloWorld,
sparta.IAMRoleDefinition{})
lambdaFunctions = append(lambdaFunctions, lambdaFn)
// Delegate to Sparta
sparta.Main("SpartaHelloWorld",
"Simple Sparta application that creates a single AWS Lambda function",
lambdaFunctions,
nil,
nil)
}
```

## 2. Deployment

```shell
$ 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/SpartaHelloWorld-code.zip
[0001] INFO Lambda code archive size Size=13 MB
[0001] INFO Uploading local file to S3 Bucket=MY_S3_BUCKET Key=SpartaHelloWorld/SpartaHelloWorld-code.zip Path=./.sparta/SpartaHelloWorld-code.zip 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 -->
<tr>
<td style="width:50%">
<h2>Unified</h2>
<p>Use a <b>go</b> monorepo to define and your microservice's:
<ul>
<li>Application logic</li>
<li>AWS infrastructure</li>
<li>Operational metrics</li>
<li>Alert conditions</li>
<li>Security policies</li>
</ul>
</td>
<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="http://docs.aws.amazon.com/lambda/latest/dg/intro-core-components.html">event sources</a> such as:
<ul>
<li>DynamoDB</li>
<li>S3</li>
<li>Kinesis</li>
<li>SNS</li>
<li>SES</li>
<li>CloudWatch Events</li>
<li>CloudWatch Logs</li>
</ul>
Additionally, your service may provision any other <a href="http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html">CloudFormation</a> supported resource and even your own <a href="http://gosparta.io/docs/custom_resources">CustomResources</a>.
</p>
</td>
</tr>
<!-- Row 2 -->
<tr>
<td style="width:50%">
<h2>Security</h2>
<p>Define <a href="http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html">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="http://searchsecurity.techtarget.com/definition/principle-of-least-privilege-POLP">POLA</a> and <a href="https://twitter.com/hashtag/secops">#SecOps</a> as first-class goals.
</p>
</td>
<td style="width:50%">
<h2>Discovery</h2>
<p>A service may provision dynamic AWS infrastructure, and <a href="http://gosparta.io/docs/eventsources">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="http://chadfowler.com/2013/06/23/immutable-deployments.html">immutable infrastructure</a></p>
</td>
</tr>
<!-- Row 3 -->
<tr>
<td style="width:50%">
<h2>API Gateway</h2>
<p>Make your service HTTPS accessible by binding it to an <a href="http://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html">API Gateway</a> REST API during provisioning. As part of API Gateway creation, Sparta includes <a href="http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html">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>
<td style="width:50%">
<h2>Static Sites</h2>
<p>Include a <a href="http://docs.aws.amazon.com/AmazonS3/latest/dev/cors.html">CORS-enabled</a> <a href="http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html">S3-backed site</a> with your service. S3-backed sites include API Gateway discovery information for turnkey deployment.</p>
</td>
</tr>
</table>


<hr />
<a href="https://cloudcraft.co/view/8571b3bc-76ef-48c1-8401-0b6ae1d36b4e?key=d44zi4j1pxj00000" rel="Sparta Arch">![Sparta Overview](/images/sparta_overview.png)</a>

Sparta relies on [CloudFormation](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) to deploy and update your application. For resources that CloudFormation does not yet support, it uses [Lambda-backed Custom Resources](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources-lambda.html) 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](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks.html) and minimize resource churn during updates.

# Getting Started

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

# Administration
- Problems? Please open an [issue](https://github.com/mweagle/Sparta/issues/new) in GitHub.

<br />
<img src="/images/GopherInclusion.png" alt="Eveyone Welcome" height="256">
<center>
<h6>Courtesy of <a href="https://github.com/ashleymcnamara/gophers">gophers</a>
</h6>
</center>
<br />


# Questions?

Get in touch via:

- <i class="fas fas-twitter">&nbsp; @mweagle</i>
- <i class="fas fas-slack">&nbsp; Gophers: <a href="https://gophers.slack.com/team/mweagle">@mweagle</a></i>
- [Signup page](https://invite.slack.golangbridge.org/)
- <i class="fas fas-slack">&nbsp; Serverless: <a href="https://serverless-forum.slack.com/team/mweagle">@mweagle</a></i>
- [Signup page](https://wt-serverless-seattle.run.webtask.io/serverless-forum-signup?webtask_no_cache=1)


## Related Projects
- [go-cloudcondensor](https://github.com/mweagle/go-cloudcondenser)
- Define AWS CloudFormation templates in `go`
- [go-cloudformation](https://github.com/mweagle/go-cloudformation)
- `go` types for CloudFormation resources
- [ssm-cache](https://github.com/mweagle/ssm-cache)
- Lightweight cache for [Systems Manager Paramter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) values

## Other resources
* [Build an S3 website with API Gateway and AWS Lambda for Go using Sparta](https://medium.com/@mweagle/go-aws-lambda-building-an-html-website-with-api-gateway-and-lambda-for-go-using-sparta-5e6fe79f63ef)
* [AWS blog post announcing Go support](https://aws.amazon.com/blogs/compute/announcing-go-support-for-aws-lambda/)
* [Sparta - A Go framework for AWS Lambda](https://medium.com/@mweagle/a-go-framework-for-aws-lambda-ab14f0c42cb#.6gtlwe5vg)
* Other libraries & frameworks:
* [Serverless](https://github.com/serverless/serverless)
* [PAWS](https://github.com/braahyan/PAWS)
* [Apex](http://apex.run)
* [lambda_proc](https://github.com/jasonmoo/lambda_proc)
* [go-lambda](https://github.com/xlab/go-lambda)
* [go-lambda (GRPC)](https://github.com/pilwon/go-lambda)
* Supported AWS Lambda [programming models](http://docs.aws.amazon.com/lambda/latest/dg/programming-model-v2.html)
* [Serverless Code Blog](https://serverlesscode.com)
* [AWS Serverless Multi-Tier Architectures Whitepaper](https://d0.awsstatic.com/whitepapers/AWS_Serverless_Multi-Tier_Architectures.pdf)
* [Lambda limits](http://docs.aws.amazon.com/lambda/latest/dg/limits.html)
* [The Twelve Days of Lambda](https://aws.amazon.com/blogs/compute/the-twelve-days-of-lambda/)
* [CloudCraft](http://cloudcraft.co) 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](https://godoc.org/github.com/mweagle/Sparta#Main), [MainEx](https://godoc.org/github.com/mweagle/Sparta#MainEx)). This provides each application with some standard command line options as shown below:

```bash
$ go run main.go --help
Simple Sparta application that demonstrates core functionality
Usage:
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
Flags:
-f, --format string Log format [text, json] (default "text")
-h, --help help for main
--ldflags string Go linker string definition flags (https://golang.org/cmd/link/)
-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](https://rakyll.org/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:

```bash
$ 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.

```bash
$ 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](https://github.com/jbrook)
- [Ryan Brown](https://github.com/ryansb)
- [sdbeard](https://github.com/sdbeard)
- [Scott Raine](https://github.com/nylar)
- [Nick Scheiblauer](https://github.com/turgon)
- [Paul Seiffert](https://github.com/seiffert)
- [Thom Shutt](https://github.com/thomshutt)
- [Patrick Steger](https://github.com/psteger)
Oops, something went wrong.

0 comments on commit 5f5bee3

Please sign in to comment.