Permalink
Browse files

Update docs, include placeholders

  • Loading branch information...
mweagle committed Dec 11, 2018
1 parent df4ced2 commit 6fb87087ed9d5d9fbf4d2a12bd3e9dee102cf06f
Showing with 330 additions and 272 deletions.
  1. +0 −151 docs_source/content/concepts.md
  2. +143 −0 docs_source/content/concepts/_index.md
  3. +0 −1 docs_source/content/reference/_index.md
  4. +3 −5 docs_source/content/reference/apigateway/_index.md
  5. +47 −47 docs_source/content/reference/apigateway/user_input.md
  6. +2 −2 docs_source/content/reference/application/_index.md
  7. +3 −3 docs_source/content/reference/{eventsources → }/archetypes/_index.md
  8. 0 docs_source/content/reference/{eventsources → }/archetypes/cloudwatch.md
  9. 0 docs_source/content/reference/{eventsources → }/archetypes/dynamodb.md
  10. 0 docs_source/content/reference/{eventsources → }/archetypes/kinesis.md
  11. 0 docs_source/content/reference/{eventsources → }/archetypes/rest.md
  12. 0 docs_source/content/reference/{eventsources → }/archetypes/s3.md
  13. 0 docs_source/content/reference/{eventsources → }/archetypes/sns.md
  14. +2 −2 docs_source/content/reference/decorators/_index.md
  15. +5 −5 docs_source/content/reference/eventsources/_index.md
  16. +2 −2 docs_source/content/reference/interceptors/_index.md
  17. +2 −2 docs_source/content/reference/operations/_index.md
  18. +1 −1 docs_source/content/reference/{decorators/cloudwatch_alarm.md → operations/cloudwatch_alarms.md}
  19. 0 docs_source/content/reference/{decorators/dashboard.md → operations/cloudwatch_dashboard.md}
  20. 0 ...ntent/reference/{decorators/codedeployserviceupdate.md → operations/codedeploy_service_update.md}
  21. +3 −1 docs_source/content/reference/operations/magefile.md
  22. +1 −6 docs_source/content/reference/operations/metrics_publisher.md
  23. +10 −0 docs_source/content/reference/step/_index.md
  24. +9 −0 docs_source/content/reference/step/batch.md
  25. +9 −0 docs_source/content/reference/step/dynamodb.md
  26. +9 −0 docs_source/content/reference/step/fargate.md
  27. +9 −0 docs_source/content/reference/step/glue.md
  28. +8 −5 docs_source/content/reference/{step_functions.md → step/lambda.md}
  29. +9 −0 docs_source/content/reference/step/sagemaker.md
  30. +9 −0 docs_source/content/reference/step/sns.md
  31. +9 −0 docs_source/content/reference/step/sqs.md
  32. +2 −2 docs_source/content/reference/testing/_index.md
  33. +32 −36 docs_source/content/sample_service/step1.md
  34. +1 −1 docs_source/layouts/shortcodes/spartaflow.html

This file was deleted.

Oops, something went wrong.
@@ -0,0 +1,143 @@
---
date: 2018-01-22 21:49:38
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

At a high level, Sparta transforms a **go** binary's registered lambda functions into a set of independently addressable AWS Lambda functions . Additionally, Sparta provides microservice authors an opportunity to satisfy other requirements such as defining the IAM Roles under which their function will execute in AWS, additional infrastructure requirements, and telemetry and alerting information (via CloudWatch).

## Service Name

Sparta applications are deployed as a single unit, using the **ServiceName** as a stable logical identifier. The **ServiceName** is used as your application's [CloudFormation StackName](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/pseudo-parameter-reference.html)

```go
stackName := "MyUniqueServiceName"
sparta.Main(stackName,
"Simple Sparta application",
myLambdaFunctions,
nil,
nil)
```

## Lambda Function

A Sparta-compatible lambda is a standard [AWS Lambda Go](https://docs.aws.amazon.com/lambda/latest/dg/go-programming-model-handler-types.html/) function. The following function signatures are supported:

* `func ()`
* `func () error`
* `func (TIn), error`
* `func () (TOut, error)`
* `func (context.Context) error`
* `func (context.Context, TIn) error`
* `func (context.Context) (TOut, error)`
* `func (context.Context, TIn) (TOut, error)`

where the `TIn` and `TOut` parameters represent [encoding/json](https://golang.org/pkg/encoding/json) un/marshallable types. Supplying an invalid signature will produce a run time error as in:

{{< highlight text >}}
ERRO[0000] Lambda function (Hello World) has invalid returns: handler
returns a single value, but it does not implement error exit status 1
{{< /highlight >}}

## Privileges

To support accessing other AWS resources in your **go** function, Sparta allows you to define and link [IAM Roles](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) with narrowly defined [sparta.IAMRolePrivilege](https://godoc.org/github.com/mweagle/Sparta#IAMRolePrivilege) values. This allows you to define the _minimal_ set of privileges under which your **go** function will execute. The `Privilege.Resource` field value may also be a [StringExpression](https://godoc.org/github.com/mweagle/go-cloudformation#StringExpr) referencing a dynamically provisioned CloudFormation resource.

```go
lambdaFn.RoleDefinition.Privileges = append(lambdaFn.RoleDefinition.Privileges,
sparta.IAMRolePrivilege{
Actions: []string{"s3:GetObject", "s3:HeadObject"},
Resource: "arn:aws:s3:::MyS3Bucket",
})
```

## Permissions

To configure AWS Lambda [Event Sources](http://docs.aws.amazon.com/lambda/latest/dg/intro-core-components.html), Sparta provides both [sparta.LambdaPermission](https://godoc.org/github.com/mweagle/Sparta#LambdaPermission) and service-specific _Permission_ types like [sparta.CloudWatchEventsPermission](https://godoc.org/github.com/mweagle/Sparta#CloudWatchEventsPermission). The service-specific _Permission_ types automatically register your lambda function with the remote AWS service, using each service's specific API.

```go
cloudWatchEventsPermission := sparta.CloudWatchEventsPermission{}
cloudWatchEventsPermission.Rules = make(map[string]sparta.CloudWatchEventsRule, 0)
cloudWatchEventsPermission.Rules["Rate5Mins"] = sparta.CloudWatchEventsRule{
ScheduleExpression: "rate(5 minutes)",
}
lambdaFn.Permissions = append(lambdaFn.Permissions, cloudWatchEventsPermission)
```

## Decorators

Decorators are associated with either [Lambda functions](https://godoc.org/github.com/mweagle/Sparta#TemplateDecoratorHandler) or
the larger service workflow via [WorkflowHooks](https://godoc.org/github.com/mweagle/Sparta#WorkflowHooks). They are user-defined
functions that provide an opportunity for your service to perform secondary actions such as automatically generating a
[CloudFormation Dashboard](https://godoc.org/github.com/mweagle/Sparta/decorator#DashboardDecorator) or automatically publish
an [S3 Artifact](https://godoc.org/github.com/mweagle/Sparta/decorator#S3ArtifactPublisherDecorator) from your service.

Decorators are applied at `provision` time.

## Interceptors

Interceptors are the runtime analog to Decorators. They are user-defined functions that are executed in the
context of handling an event. They provide an opportunity for you to support cross-cutting concerns such as automatically
registering [XRayTraces](https://godoc.org/github.com/mweagle/Sparta/interceptor#RegisterXRayInterceptor) that can capture
service performance and log messages in the event of an error.

{{< interceptorflow >}}

## Dynamic Resources

Sparta applications can specify other [AWS Resources](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html) (eg, _SNS Topics_) as part of their application. The dynamic resource outputs can be referenced by Sparta lambda functions via [gocf.Ref](https://godoc.org/github.com/mweagle/go-cloudformation#Ref) and [gocf.GetAtt](https://godoc.org/github.com/mweagle/go-cloudformation#GetAtt) functions.

```go
snsTopicName := sparta.CloudFormationResourceName("SNSDynamicTopic")
snsTopic := &gocf.SNSTopic{
DisplayName: gocf.String("Sparta Application SNS topic"),
})
lambdaFn := sparta.HandleAWSLambda(sparta.LambdaName(echoDynamicSNSEvent),
echoDynamicSNSEvent,
sparta.IAMRoleDefinition{})
lambdaFn.Permissions = append(lambdaFn.Permissions, sparta.SNSPermission{
BasePermission: sparta.BasePermission{
SourceArn: gocf.Ref(snsTopicName),
},
})
```

## Discovery

To support Sparta lambda functions discovering dynamically assigned AWS resource values, Sparta provides [sparta.Discover](https://godoc.org/github.com/mweagle/Sparta#Discover). This function returns information about resources that a given
entity specifies a [DependsOn](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-dependson.html) relationship.

```go
func echoS3DynamicBucketEvent(ctx context.Context,
s3Event awsLambdaEvents.S3Event) (*awsLambdaEvents.S3Event, error) {
discoveryInfo, discoveryInfoErr := sparta.Discover()
logger.WithFields(logrus.Fields{
"Event": s3Event,
"Discovery": discoveryInfo,
"DiscoveryErr": discoveryInfoErr,
}).Info("Event received")
// Use discoveryInfo to determine the bucket name to which RawMessage should be stored
...
}
```

# Summary

Given a set of registered Sparta lambda function, a typical `provision` build to create a new service follows this workflow. Items with dashed borders are opt-in user behaviors.

{{< spartaflow >}}

During provisioning, Sparta uses [AWS Lambda-backed Custom Resources](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources-lambda.html) to support operations for which CloudFormation doesn't yet support (eg, [API Gateway](https://aws.amazon.com/api-gateway/) creation).

# Next Steps

Walk through a starting [Sparta Application](/sample_service/).
@@ -2,5 +2,4 @@
date: 2018-01-22 21:49:38
title: Reference
weight: 100
alwaysopen: false
---
@@ -1,13 +1,11 @@
---
date: 2016-03-09T19:56:50+01:00
title:
pre: "<i class='fas fa-fw fa-globe'></i>&nbsp;<b>API Gateway</b>"
title: API Gateway
post: "&nbsp;<i class='fas fa-fw fa-globe'></i>"
alwaysopen: false
weight: 110
weight: 100
---

## Examples

One of the most powerful ways to use AWS Lambda is to make function publicly available over HTTPS. This is accomplished by connecting the AWS Lambda function with the [API Gateway](https://aws.amazon.com/api-gateway/). In this section we'll start with a simple "echo" example and move on to a lambda function that accepts user parameters and returns an expiring S3 URL.

* [Example 1 - Echo Event](/reference/apigateway/echo_event)
Oops, something went wrong.

0 comments on commit 6fb8708

Please sign in to comment.