Permalink
Browse files

Update docs

  • Loading branch information...
mweagle committed Dec 1, 2018
1 parent e39592b commit f1c795982da37c9565f1843a79e956462a794d4e
Showing with 299 additions and 250 deletions.
  1. +1 −2 docs_source/content/cli_options/_index.md
  2. +2 −3 docs_source/content/{overview/_index.md → concepts.md}
  3. +1 −1 docs_source/content/reference/_index.md
  4. +2 −2 docs_source/content/reference/apigateway/_index.md
  5. 0 docs_source/content/reference/{ → apigateway}/s3Site.md
  6. +3 −7 docs_source/content/reference/application/_index.md
  7. 0 docs_source/content/reference/{ → application}/custom_lambda_resources.md
  8. +0 −1 docs_source/content/reference/{ → application}/custom_resources.md
  9. +57 −57 docs_source/content/reference/application/environments.md
  10. +0 −13 docs_source/content/reference/cicd.md
  11. +77 −6 docs_source/content/reference/decorators/_index.md
  12. +5 −3 docs_source/content/reference/decorators/codedeployserviceupdate.md
  13. +6 −6 docs_source/content/reference/{ → decorators}/dynamic_infrastructure.md
  14. +1 −1 docs_source/content/reference/decorators/lambda_versioning.md
  15. +1 −1 docs_source/content/reference/docker.md
  16. +1 −2 docs_source/content/reference/eventsources/_index.md
  17. +1 −1 docs_source/content/reference/{ → eventsources}/archetypes/_index.md
  18. 0 docs_source/content/reference/{ → eventsources}/archetypes/cloudwatch.md
  19. 0 docs_source/content/reference/{ → eventsources}/archetypes/dynamodb.md
  20. 0 docs_source/content/reference/{ → eventsources}/archetypes/kinesis.md
  21. 0 docs_source/content/reference/{ → eventsources}/archetypes/rest.md
  22. 0 docs_source/content/reference/{ → eventsources}/archetypes/s3.md
  23. 0 docs_source/content/reference/{ → eventsources}/archetypes/sns.md
  24. +1 −1 docs_source/content/reference/eventsources/cloudformation.md
  25. +1 −2 docs_source/content/reference/eventsources/cognito.md
  26. +9 −5 docs_source/content/reference/interceptors/_index.md
  27. +17 −0 docs_source/content/reference/interceptors/xray_interceptor.md
  28. +0 −50 docs_source/content/reference/magefile.md
  29. +10 −0 docs_source/content/reference/operations/_index.md
  30. +9 −0 docs_source/content/reference/operations/cicd.md
  31. +2 −2 docs_source/content/reference/{ → operations}/deployment_strategies.md
  32. +68 −0 docs_source/content/reference/operations/magefile.md
  33. +10 −0 docs_source/content/reference/operations/metrics_publisher.md
  34. +1 −1 docs_source/content/reference/{ → operations}/profiling.md
  35. +1 −1 docs_source/content/reference/step_functions.md
  36. +4 −2 docs_source/content/reference/{local_testing.md → testing/_index.md}
  37. +0 −74 docs_source/content/reference/workflow_hooks.md
  38. +7 −5 docs_source/content/sample_service/_index.md
  39. +1 −1 docs_source/layouts/partials/logo.html
@@ -7,7 +7,7 @@ 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
```shell
$ go run main.go --help
Simple Sparta application that demonstrates core functionality
@@ -36,7 +36,6 @@ Flags:
-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.
@@ -1,12 +1,11 @@
---
date: 2018-01-22 21:49:38
title: Overview
description: Sparta overview
title: Concepts
description: Core Sparta Concepts
weight: 10
alwaysopen: false
---


This is a brief overview of Sparta's core concepts. Additional information regarding specific features is available from the menu.

# Terms and Concepts
@@ -2,5 +2,5 @@
date: 2018-01-22 21:49:38
title: Reference
weight: 100
alwaysopen: true
alwaysopen: false
---
@@ -1,9 +1,9 @@
---
date: 2016-03-09T19:56:50+01:00
title:
pre: "<b>API Gateway</b>&nbsp;<i class='fas fa-fw fa-globe'></i>"
pre: "<i class='fas fa-fw fa-globe'></i>&nbsp;<b>API Gateway</b>"
alwaysopen: false
weight: 190
weight: 110
---

## Examples
@@ -1,17 +1,13 @@
---
date: 2016-03-09T19:56:50+01:00
title:
pre: "<b>Application Customization</b>&nbsp;<i class='fas fa-fw fa-cog'></i>"
pre: "<i class='fas fa-fw fa-cog'></i>&nbsp;<b>Application Customization</b>"
alwaysopen: false
weight: 300
weight: 140
---

Sparta-based applications use the [Cobra](https://github.com/spf13/cobra) package to expose a rich set of command line options. This section describes:

* [Default options](/cli_options)
* [Adding flags](/reference/application/custom_flags)
* [Adding commands](/reference/application/custom_commands)
* [Managing Environments](/reference/application/environments)
* [Workflow Hooks](/reference/application/workflow_hooks)
{{% children %}}

Adding custom flags or commands is typically a prerequisite to supporting [alternative topologies](/reference/alternative_topologies).
@@ -21,7 +21,6 @@ Defining a custom resource is a two stage process, depending on whether your app
1. *Optional* - The template decorator that binds your CustomResource's [data results](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-responses.html) to the owning `LambdaAWSInfo` caller.
1. *Optional* - A call from your standard Lambda's function body to discover the CustomResource outputs via `sparta.Discover()`.


### Custom Resource Functioon

A Custom Resource Function is a standard AWS Lambda Go function type that
@@ -6,9 +6,9 @@ weight: 10

It's common for a single Sparta application to target multiple *environments*. For example:

* Development
* Staging
* Production
* Development
* Staging
* Production

Each environment is largely similar, but the application may need slightly different configuration in each context.

@@ -20,26 +20,27 @@ This example will work through the [SpartaConfig](https://github.com/mweagle/Spa

To start with, create the _default_ configuration. This is the configuration that Sparta uses when provisioning your Stack and defines the environment configuration contract.

```golang
```go
// +build !staging,!production
// file: environments/default.go
package environments
import (
"fmt"
"github.com/Sirupsen/logrus"
"github.com/aws/aws-sdk-go/aws/session"
gocf "github.com/crewjam/go-cloudformation"
sparta "github.com/mweagle/Sparta"
"fmt"
"github.com/Sirupsen/logrus"
"github.com/aws/aws-sdk-go/aws/session"
gocf "github.com/crewjam/go-cloudformation"
sparta "github.com/mweagle/Sparta"
)
// Name is the default configuration
const Name = ""
```

The important part is the set of excluded tags at the top of the file:

```golang
```go
// +build !staging,!production
```

@@ -49,18 +50,17 @@ This ensures that the configuration is only eligible for compilation when Sparta

The next steps are to define the environment-specific configuration files:


```golang
```go
// +build staging
// file: environments/staging.go
package environments
import (
"github.com/Sirupsen/logrus"
"github.com/aws/aws-sdk-go/aws/session"
gocf "github.com/crewjam/go-cloudformation"
sparta "github.com/mweagle/Sparta"
"github.com/Sirupsen/logrus"
"github.com/aws/aws-sdk-go/aws/session"
gocf "github.com/crewjam/go-cloudformation"
sparta "github.com/mweagle/Sparta"
)
// Name is the production configuration
@@ -69,17 +69,17 @@ const Name = "staging"
```


```golang
```go
// +build production
// file: environments/production.go
package environments
import (
"github.com/Sirupsen/logrus"
"github.com/aws/aws-sdk-go/aws/session"
gocf "github.com/crewjam/go-cloudformation"
sparta "github.com/mweagle/Sparta"
"github.com/Sirupsen/logrus"
"github.com/aws/aws-sdk-go/aws/session"
gocf "github.com/crewjam/go-cloudformation"
sparta "github.com/mweagle/Sparta"
)
// Name is the production configuration
@@ -95,7 +95,7 @@ The `serviceName` argument supplied to [sparta.Main](https://godoc.org/github.co

The `serviceName` can be specialized by using the `buildTags` in the service name definition as in:

```golang
```go
fmt.Sprintf("SpartaHelloWorld-%s", sparta.OptionsGlobal.BuildTags),
```

@@ -109,53 +109,53 @@ The final requirement is to add the environment name as a Stack Output. To annot

The _main.go_ source file registers the workflow hook via:

```golang
```go
hooks := &sparta.WorkflowHooks{
Context: map[string]interface{}{},
ServiceDecorator: environments.ServiceDecoratorHook(sparta.OptionsGlobal.BuildTags),
Context: map[string]interface{}{},
ServiceDecorator: environments.ServiceDecoratorHook(sparta.OptionsGlobal.BuildTags),
}
```

Both _environments/staging.go_ and _environments/production.go_ define the same hook function:

```golang
```go
func ServiceDecoratorHook(buildTags string) sparta.ServiceDecoratorHook {
return func(context map[string]interface{},
serviceName string,
template *gocf.Template,
S3Bucket string,
buildID string,
awsSession *session.Session,
noop bool,
logger *logrus.Logger) error {
template.Outputs["Environment"] = &gocf.Output{
Description: "Sparta Config target environment",
Value: Name,
}
return nil
}
return func(context map[string]interface{},
serviceName string,
template *gocf.Template,
S3Bucket string,
buildID string,
awsSession *session.Session,
noop bool,
logger *logrus.Logger) error {
template.Outputs["Environment"] = &gocf.Output{
Description: "Sparta Config target environment",
Value: Name,
}
return nil
}
}
```

The _environments/default.go_ definition is slightly different. The "default" environment isn't one that our service should actually deploy to. It simply exists to make the initial Sparta build (the one that cross compiles the AWS Lambda binary) compile. Build tags are applied to the *AWS Lambda* compiled binary that Sparta generates.

To prevent users from accidentally deploying to the "default" environment, the `BuildTags` are validated in the hook definition:

```golang
```go
func ServiceDecoratorHook(buildTags string) sparta.ServiceDecoratorHook {
return func(context map[string]interface{},
serviceName string,
template *gocf.Template,
S3Bucket string,
buildID string,
awsSession *session.Session,
noop bool,
logger *logrus.Logger) error {
if len(buildTags) <= 0 {
return fmt.Errorf("Please provide a --tags value for environment target")
}
return nil
}
return func(context map[string]interface{},
serviceName string,
template *gocf.Template,
S3Bucket string,
buildID string,
awsSession *session.Session,
noop bool,
logger *logrus.Logger) error {
if len(buildTags) <= 0 {
return fmt.Errorf("Please provide a --tags value for environment target")
}
return nil
}
}
```

@@ -165,11 +165,11 @@ Putting everything together, the `SpartaConfig` service can deploy to either env

**staging**

go run main.go provision --level info --s3Bucket $(S3_BUCKET) --noop --tags staging
go run main.go provision --level info --s3Bucket $(S3_BUCKET) --noop --tags staging

**production**

go run main.go provision --level info --s3Bucket $(S3_BUCKET) --noop --tags production
go run main.go provision --level info --s3Bucket $(S3_BUCKET) --noop --tags production

Attempting to deploy to "default" generates an error:

@@ -210,4 +210,4 @@ exit status 1

- Call [ParseOptions](https://godoc.org/github.com/mweagle/Sparta#ParseOptions) to initialize `sparta.OptionsGlobal.BuildTags` field for use in a service name definition.
- An alternative approach is to define a custom [ArchiveHook](https://godoc.org/github.com/mweagle/Sparta#ArchiveHook) and inject custom configuration into the ZIP archive. This data is available at `Path.Join(env.LAMBDA_TASK_ROOT, ZIP_ARCHIVE_PATH)`
- See [discfg](https://github.com/tmaiaroto/discfg), [etcd](https://github.com/coreos/etcd), [Consul](https://www.consul.io/) (among others) for alternative, more dynamic discovery services.
- See [discfg](https://github.com/tmaiaroto/discfg), [etcd](https://github.com/coreos/etcd), [Consul](https://www.consul.io/) (among others) for alternative, more dynamic discovery services.

This file was deleted.

Oops, something went wrong.
@@ -1,12 +1,83 @@
---
date: 2018-01-22 21:49:38
date: 2018-12-01 06:18:10
title:
pre: "<b>Decorators</b>&nbsp;<i class='fas fa-fw fa-paint-brush'></i>"
alwaysopen: false
weight: 190
pre: "<i class='fas fa-fw fa-paint-brush'></i>&nbsp;<b>Build Time Decorators</b>"
chapter: false
weight: 120
---

Sparta uses [decorators](https://godoc.org/github.com/mweagle/Sparta/decorator) to annotate the CloudFormation template with
Sparta uses build-time [decorators](https://godoc.org/github.com/mweagle/Sparta/decorator) to annotate the CloudFormation template with
additional functionality.

Decorators at different phases in the provisioning workflow. The following set of decorators are available.
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](https://godoc.org/github.com/mweagle/Sparta#WorkflowHooks) structure. These hooks are called at specific points in the _provision_ lifecycle and support augmenting the standard pipeline:

{{< spartaflow >}}

The following sections describe the 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](https://godoc.org/github.com/mweagle/Sparta#WorkflowHook) signature:

```go
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:

```go
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:

```go
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](https://godoc.org/github.com/mweagle/Sparta#WorkflowHooks) structure with 1 or more hook functions and call [sparta.MainEx](https://godoc.org/github.com/mweagle/Sparta#MainEx).

## Available Decorators

{{% children %}}

### Notes

- Workflow hooks can be used to support [Dockerizing](https://github.com/mweagle/SpartaDocker) your application
- You may need to add [custom CLI commands](/reference/application/custom_commands) to fully support Docker
- Enable `--level debug` for detailed workflow hook debugging information
Oops, something went wrong.

0 comments on commit f1c7959

Please sign in to comment.