github.com/mweagle/Sparta@v1.15.0/docs_source/content/concepts/_index.md (about)

     1  ---
     2  date: 2018-01-22 21:49:38
     3  title: Concepts
     4  description: Core Sparta Concepts
     5  weight: 20
     6  alwaysopen: false
     7  ---
     8  
     9  This is a brief overview of Sparta's core concepts. Additional information regarding specific features is available from the menu.
    10  
    11  # Terms and Concepts
    12  
    13  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).
    14  
    15  ## Service Name
    16  
    17  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)
    18  
    19  ```go
    20  stackName := "MyUniqueServiceName"
    21  sparta.Main(stackName,
    22    "Simple Sparta application",
    23    myLambdaFunctions,
    24    nil,
    25    nil)
    26  ```
    27  
    28  ## Lambda Function
    29  
    30  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:
    31  
    32  - `func ()`
    33  - `func () error`
    34  - `func (TIn), error`
    35  - `func () (TOut, error)`
    36  - `func (context.Context) error`
    37  - `func (context.Context, TIn) error`
    38  - `func (context.Context) (TOut, error)`
    39  - `func (context.Context, TIn) (TOut, error)`
    40  
    41  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:
    42  
    43  {{< highlight text >}}
    44  ERRO[0000] Lambda function (Hello World) has invalid returns: handler
    45  returns a single value, but it does not implement error exit status 1
    46  {{< /highlight >}}
    47  
    48  ## Privileges
    49  
    50  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.
    51  
    52  ```go
    53  lambdaFn.RoleDefinition.Privileges = append(lambdaFn.RoleDefinition.Privileges,
    54    sparta.IAMRolePrivilege{
    55      Actions:  []string{"s3:GetObject", "s3:HeadObject"},
    56      Resource: "arn:aws:s3:::MyS3Bucket",
    57  })
    58  ```
    59  
    60  ## Permissions
    61  
    62  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.
    63  
    64  ```go
    65  cloudWatchEventsPermission := sparta.CloudWatchEventsPermission{}
    66  cloudWatchEventsPermission.Rules = make(map[string]sparta.CloudWatchEventsRule, 0)
    67  cloudWatchEventsPermission.Rules["Rate5Mins"] = sparta.CloudWatchEventsRule{
    68    ScheduleExpression: "rate(5 minutes)",
    69  }
    70  lambdaFn.Permissions = append(lambdaFn.Permissions, cloudWatchEventsPermission)
    71  ```
    72  
    73  ## Decorators
    74  
    75  Decorators are associated with either [Lambda functions](https://godoc.org/github.com/mweagle/Sparta#TemplateDecoratorHandler) or
    76  the larger service workflow via [WorkflowHooks](https://godoc.org/github.com/mweagle/Sparta#WorkflowHooks). They are user-defined
    77  functions that provide an opportunity for your service to perform secondary actions such as automatically generating a
    78  [CloudFormation Dashboard](https://godoc.org/github.com/mweagle/Sparta/decorator#DashboardDecorator) or automatically publish
    79  an [S3 Artifact](https://godoc.org/github.com/mweagle/Sparta/decorator#S3ArtifactPublisherDecorator) from your service.
    80  
    81  Decorators are applied at `provision` time.
    82  
    83  ## Interceptors
    84  
    85  Interceptors are the runtime analog to Decorators. They are user-defined functions that are executed in the
    86  context of handling an event. They provide an opportunity for you to support cross-cutting concerns such as automatically
    87  registering [XRayTraces](https://godoc.org/github.com/mweagle/Sparta/interceptor#RegisterXRayInterceptor) that can capture
    88  service performance and log messages in the event of an error.
    89  
    90  {{< interceptorflow >}}
    91  
    92  ## Dynamic Resources
    93  
    94  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.
    95  
    96  ```go
    97  snsTopicName := sparta.CloudFormationResourceName("SNSDynamicTopic")
    98  snsTopic := &gocf.SNSTopic{
    99    DisplayName: gocf.String("Sparta Application SNS topic"),
   100  })
   101  lambdaFn, _ := sparta.NewAWSLambda(sparta.LambdaName(echoDynamicSNSEvent),
   102    echoDynamicSNSEvent,
   103    sparta.IAMRoleDefinition{})
   104  
   105  lambdaFn.Permissions = append(lambdaFn.Permissions, sparta.SNSPermission{
   106    BasePermission: sparta.BasePermission{
   107      SourceArn: gocf.Ref(snsTopicName),
   108    },
   109  })
   110  ```
   111  
   112  ## Discovery
   113  
   114  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
   115  entity specifies a [DependsOn](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-dependson.html) relationship.
   116  
   117  ```go
   118  func echoS3DynamicBucketEvent(ctx context.Context,
   119    s3Event awsLambdaEvents.S3Event) (*awsLambdaEvents.S3Event, error) {
   120  
   121    discoveryInfo, discoveryInfoErr := sparta.Discover()
   122    logger.WithFields(logrus.Fields{
   123      "Event":        s3Event,
   124      "Discovery":    discoveryInfo,
   125      "DiscoveryErr": discoveryInfoErr,
   126    }).Info("Event received")
   127  
   128    // Use discoveryInfo to determine the bucket name to which RawMessage should be stored
   129    ...
   130  }
   131  ```
   132  
   133  # Summary
   134  
   135  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.
   136  
   137  {{< spartaflow >}}
   138  
   139  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).
   140  
   141  # Next Steps
   142  
   143  Walk through a starting [Sparta Application](/sample_service/).