github.com/mweagle/Sparta@v1.15.0/docs_source/content/reference/faq.md (about)

     1  ---
     2  date: 2016-03-09T19:56:50+01:00
     3  title: FAQ
     4  weight: 1000
     5  ---
     6  
     7  ## CloudFormation
     8  
     9  ### How do I create dynamic resource ARNs?
    10  
    11  Linking AWS resources together often requires creating dynamic ARN
    12  references. This can be achieved by using [cloudformation.Join](https://godoc.org/github.com/mweagle/go-cloudformation#Join) expressions.
    13  
    14  For instance:
    15  
    16  ```go
    17  import (
    18      gocf "github.com/mweagle/go-cloudformation"
    19  )
    20  
    21  s3SiteBucketAllKeysResourceValue := gocf.Join("",
    22      gocf.String("arn:aws:s3:::"),
    23      gocf.Ref(s3BucketResourceName),
    24      gocf.String("/*"))
    25  ```
    26  
    27  ```go
    28  import (
    29  	gocf "github.com/mweagle/go-cloudformation"
    30  )
    31  
    32   AuthorizerURI: gocf.Join("",
    33                          gocf.String("arn:aws:apigateway:"),
    34                          gocf.Ref("AWS::Region").String(),
    35                          gocf.String(":lambda:path/2015-03-31/functions/"),
    36                          gocf.GetAtt(myAWSLambdaInfo.LogicalResourceName(), "Arn"),
    37                          gocf.String("/invocations")),
    38  ```
    39  
    40  See the CloudFormation [Fn::GetAtt](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html) docs for the set of attributes created by each
    41  resource. CloudFormation [pseudo-parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/pseudo-parameter-reference.html) can be included in dynamic expresssions via [gocf.Ref](https://godoc.org/github.com/mweagle/go-cloudformation#Ref) expressions. For instance:
    42  
    43  ```go
    44  gocf.Ref("AWS::Region")
    45  gocf.Ref("AWS::AccountId")
    46  gocf.Ref("AWS::StackId")
    47  gocf.Ref("AWS::StackName")
    48  ```
    49  
    50  ## Development
    51  
    52  
    53  ### How do I configure AWS SDK settings?
    54  
    55  Sparta relies on standard AWS SDK configuration settings. See the [official documentation](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html) for more information.
    56  
    57  During development, configuration is typically done through environment variables:
    58  
    59    - `AWS_ACCESS_KEY_ID`
    60    - `AWS_SECRET_ACCESS_KEY`
    61    - `AWS_REGION`
    62  
    63  ### What are the *Minimum* IAM Privileges for Sparta developers?
    64  
    65  The absolute minimum set of privileges an account needs is the following [IAM Policy](https://awspolicygen.s3.amazonaws.com/policygen.html):
    66  
    67  ```json
    68  {
    69      "Version": "2012-10-17",
    70      "Statement": [
    71          {
    72              "Sid": "Stmt1505975332000",
    73              "Effect": "Allow",
    74              "Action": [
    75                  "cloudformation:DescribeStacks",
    76                  "cloudformation:CreateStack",
    77                  "cloudformation:CreateChangeSet",
    78                  "cloudformation:DescribeChangeSet",
    79                  "cloudformation:ExecuteChangeSet",
    80                  "cloudformation:DeleteChangeSet",
    81                  "cloudformation:DeleteStack",
    82                  "iam:GetRole",
    83                  "iam:DeleteRole",
    84                  "iam:DeleteRolePolicy",
    85                  "iam:PutRolePolicy"
    86              ],
    87              "Resource": [
    88                  "*"
    89              ]
    90          },
    91          {
    92              "Sid": "Stmt1505975332000",
    93              "Effect": "Allow",
    94              "Action": [
    95                  "s3:PutObject",
    96                  "s3:GetBucketVersioning",
    97                  "s3:DeleteObject"
    98              ],
    99              "Resource": [
   100                  "arn:aws:s3:::PROVISION_TARGET_BUCKETNAME"
   101              ]
   102          }
   103      ]
   104  }
   105  ```
   106  
   107  This set of privileges should be sufficient to deploy a Sparta application similar to [SpartaHelloWorld](https://github.com/mweagle/SpartaHelloWorld). Additional privileges may be required to enable different datasources.
   108  
   109  You can view the exact set of AWS API calls by enabling `--level debug` log verbosity. This log level includes all AWS API calls starting with release [0.20.0](https://github.com/mweagle/Sparta/blob/master/CHANGES.md#v0200).
   110  
   111  ### What are the minimum IAM privileges to provision a Sparta app and API Gateway
   112  
   113  Your AWS user must have the following privileges. Ensure to update the `YOUR_S3_BUCKETNAME_HERE` value with your own S3 bucket name.
   114  
   115  ```json
   116  {
   117      "Version": "2012-10-17",
   118      "Statement": [
   119          {
   120              "Sid": "VisualEditor0",
   121              "Effect": "Allow",
   122              "Action": [
   123                  "cloudformation:CreateChangeSet",
   124                  "cloudformation:DeleteChangeSet",
   125                  "cloudformation:DescribeStacks",
   126                  "cloudformation:DescribeStackEvents",
   127                  "cloudformation:CreateStack",
   128                  "cloudformation:DeleteStack",
   129                  "cloudformation:DescribeChangeSet",
   130                  "cloudformation:ExecuteChangeSet",
   131                  "iam:GetRole",
   132                  "iam:DeleteRole",
   133                  "iam:CreateRole",
   134                  "iam:PutRolePolicy",
   135                  "iam:PassRole",
   136                  "iam:DeleteRolePolicy",
   137                  "lambda:CreateFunction",
   138                  "lambda:GetFunction",
   139                  "lambda:GetFunctionConfiguration",
   140                  "lambda:AddPermission",
   141                  "lambda:DeleteFunction",
   142                  "lambda:RemovePermission"
   143              ],
   144              "Resource": "*"
   145          },
   146          {
   147              "Sid": "VisualEditor1",
   148              "Effect": "Allow",
   149              "Action": [
   150                  "apigateway:DELETE",
   151                  "apigateway:PUT",
   152                  "apigateway:PATCH",
   153                  "apigateway:POST",
   154                  "apigateway:GET",
   155                  "s3:PutObject",
   156                  "s3:GetObject",
   157                  "s3:GetBucketVersioning",
   158                  "s3:DeleteObject"
   159              ],
   160              "Resource": [
   161                  "arn:aws:apigateway:*::*",
   162                  "arn:aws:s3:::<YOUR_S3_BUCKETNAME_HERE>"
   163                  "arn:aws:s3:::<YOUR_S3_BUCKETNAME_HERE>/*"
   164              ]
   165          }
   166      ]
   167  }
   168  ```
   169  
   170  
   171  ### What flags are defined during AWS AMI compilation?
   172  
   173  * **TAGS**:         `-tags lambdabinary`
   174  * **ENVIRONMENT**:  `GOOS=linux GOARCH=amd64`
   175  
   176  ### What working directory should I use?
   177  
   178  Your working directory should be the root of your Sparta application.  Eg, use
   179  
   180  ```go
   181  go run main.go provision --level info --s3Bucket $S3_BUCKET
   182  ```
   183  
   184  rather than
   185  
   186  ```go
   187  go run ./some/child/path/main.go provision --level info --s3Bucket $S3_BUCKET
   188  ```
   189  
   190  See [GitHub](https://github.com/mweagle/Sparta/issues/29) for more details.
   191  
   192  ### How can I make `provision` faster?
   193  
   194  Starting with Sparta [v0.11.2](https://github.com/mweagle/Sparta/blob/master/CHANGES.md#v0112), you can supply an optional
   195  _--inplace_ argument to the `provision` command. If this is set when provisioning updates to an existing stack,
   196  your Sparta application will verify that the *only* updates to the CloudFormation stack are code-level updates. If
   197  only code updates are detected, your Sparta application will parallelize [UpdateFunctionCode](http://docs.aws.amazon.com/sdk-for-go/api/service/lambda/#Lambda.UpdateFunctionCode) API calls directly to update the
   198  application code.
   199  
   200  Whether _--inplace_ is valid is based on evaluating the [ChangeSet](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html) results of the
   201  requested update operation.
   202  
   203  *NOTE*: The _inplace_ argument implies that your service state is not reflected in CloudFormation.
   204  
   205  ## Event Sources - SES
   206  <hr />
   207  
   208  ### Where does the _SpartaRuleSet_ come from?
   209  
   210  SES only permits a single [active receipt rule](http://docs.aws.amazon.com/ses/latest/APIReference/API_SetActiveReceiptRuleSet.html).  Additionally, it's possible that multiple Sparta-based services are handing different SES recipients.
   211  
   212  All Sparta-based services share the _SpartaRuleSet_ SES ruleset, and uniquely identify their Rules by including the current servicename as part of the SES [ReceiptRule](http://docs.aws.amazon.com/ses/latest/APIReference/API_CreateReceiptRule.html).
   213  
   214  ### Why does `provision` not always enable the _SpartaRuleSet_?
   215  
   216  Initial _SpartaRuleSet_ will make it the active ruleset, but Sparta assumes that manual updates made outside of the context of the framework were done with good reason and doesn't attempt to override the user setting.
   217  
   218  ## Operations
   219  <hr />
   220  
   221  ### How can I provision a service dashboard?
   222  
   223  Sparta [v0.13.0](https://github.com/mweagle/Sparta/blob/master/CHANGES.md#v0130) adds support for the provisioning of a
   224  CloudWatch Dashboard that's dynamically created based on your service's topology. The dashboard
   225  is attached to the standard Sparta workflow via a [WorkflowHook](https://godoc.org/github.com/mweagle/Sparta#WorkflowHook) as in:
   226  
   227  ```go
   228  // Setup the DashboardDecorator lambda hook
   229  workflowHooks := &sparta.WorkflowHooks{
   230  	ServiceDecorator: sparta.DashboardDecorator(lambdaFunctions, 60),
   231  }
   232  ```
   233  
   234  See the [SpartaXRay](https://github.com/mweagle/SpartaXRay) project for a complete example of provisioning a dashboard as below:
   235  
   236  ![CloudWatchDashboard](/images/faq/CloudWatchDashboard.jpg)
   237  
   238  ### How can I monitor my Lambda function?
   239  
   240  If you plan on using your Lambdas in production, you'll probably want to be made aware of any excessive errors.
   241  
   242  You can easily do this by adding a CloudWatch alarm to your Lambda, in the decorator method.
   243  
   244  This example will push a notification to an SNS topic, and you can configure whatever action is appropriate from there.
   245  
   246  ```go
   247  func lambdaDecorator(serviceName string,
   248  	lambdaResourceName string,
   249  	lambdaResource gocf.LambdaFunction,
   250  	resourceMetadata map[string]interface{},
   251  	S3Bucket string,
   252  	S3Key string,
   253  	buildID string,
   254  	cfTemplate *gocf.Template,
   255  	context map[string]interface{},
   256  	logger *logrus.Logger) error {
   257  
   258  	// setup CloudWatch alarm
   259  	var alarmDimensions gocf.CloudWatchMetricDimensionList
   260  	alarmDimension := gocf.CloudWatchMetricDimension{Name: gocf.String("FunctionName"), Value: gocf.Ref(lambdaResourceName).String()}
   261  	alarmDimensions = []gocf.CloudWatchMetricDimension{alarmDimension}
   262  
   263  	lambdaErrorsAlarm := &gocf.CloudWatchAlarm{
   264  		ActionsEnabled:     gocf.Bool(true),
   265  		AlarmActions:       gocf.StringList(gocf.String("arn:aws:sns:us-east-1:123456789:SNSToNotifyMe")),
   266  		AlarmName:          gocf.String("LambdaErrorAlarm"),
   267  		ComparisonOperator: gocf.String("GreaterThanOrEqualToThreshold"),
   268  		Dimensions:         &alarmDimensions,
   269  		EvaluationPeriods:  gocf.String("1"),
   270  		Period:             gocf.String("300"),
   271  		MetricName:         gocf.String("Errors"),
   272  		Namespace:          gocf.String("AWS/Lambda"),
   273  		Statistic:          gocf.String("Sum"),
   274  		Threshold:          gocf.String("3.0"),
   275  		Unit:               gocf.String("Count"),
   276  	}
   277  	cfTemplate.AddResource("LambdaErrorAlaram", lambdaErrorsAlarm)
   278  
   279  	return nil
   280  }
   281  ```
   282  
   283  
   284  ### Where can I view my function's `*logger` output?
   285  
   286  Each lambda function includes privileges to write to [CloudWatch Logs](https://console.aws.amazon.com/cloudwatch/home).  The `*logrus.logger` output is written (with a brief delay) to a lambda-specific log group.
   287  
   288  The CloudWatch log group name includes a sanitized version of your **go** function name & owning service name.
   289  
   290  ### Where can I view Sparta's golang spawn metrics?
   291  
   292  Visit the [CloudWatch Metrics](https://aws.amazon.com/cloudwatch/) AWS console page and select the `Sparta/{SERVICE_NAME}` namespace:
   293  
   294  ![CloudWatch](/images/faq/CloudWatch_Management_Console.jpg)
   295  
   296  Sparta publishes two counters:
   297  
   298    * `ProcessSpawned`: A new **go** process was spawned to handle requests
   299    * `ProcessReused`: An existing **go** process was used to handle requests.  See also the discussion on AWS Lambda [container reuse](https://aws.amazon.com/blogs/compute/container-reuse-in-lambda/).
   300  
   301  ### How can I include additional AWS resources as part of my Sparta application?
   302  
   303  Define a [TemplateDecorator](https://godoc.org/github.com/mweagle/Sparta#TemplateDecorator) function and annotate the `*gocf.Template` with additional AWS resources.
   304  
   305  For more flexibility, use a [WorkflowHook](https://godoc.org/github.com/mweagle/Sparta#WorkflowHooks).
   306  
   307  ### How can I provide environment variables to lambda functions?
   308  
   309  Sparta uses conditional compilation rather than environment variables. See [Managing Environments](/reference/application/environments/) for more information.
   310  
   311  ### Does Sparta support Versioning & Aliasing?
   312  
   313  Yes.
   314  
   315  Define a [TemplateDecorator](https://godoc.org/github.com/mweagle/Sparta#TemplateDecorator) function and annotate the `*gocf.Template` with an [AutoIncrementingLambdaVersionInfo](https://godoc.org/github.com/mweagle/Sparta/aws/cloudformation#AutoIncrementingLambdaVersionInfo) resource. During each `provision` operation, the `AutoIncrementingLambdaVersionInfo` resource will dynamically update the CloudFormation template with a new version.
   316  
   317  ```go
   318  autoIncrementingInfo, autoIncrementingInfoErr := spartaCF.AddAutoIncrementingLambdaVersionResource(serviceName,
   319    lambdaResourceName,
   320    cfTemplate,
   321    logger)
   322  ```
   323  
   324  You can also move the "alias pointer" by referencing one or more of the versions available in the returned struct. For example, to set the alias pointer to the most recent version:
   325  
   326  ```go
   327  // Add an alias to the version we're publishing as part of this `provision` operation
   328  aliasResourceName := sparta.CloudFormationResourceName("Alias", lambdaResourceName)
   329  aliasResource := &gocf.LambdaAlias{
   330      Name:            gocf.String("MostRecentVersion"),
   331      FunctionName:    gocf.Ref(lambdaResourceName).String(),
   332      FunctionVersion: gocf.GetAtt(autoIncrementingInfo.CurrentVersionResourceName, "Version").String(),
   333  }
   334  cfTemplate.AddResource(aliasResourceName, aliasResource)
   335  ```
   336  
   337  ### How do I forward additional metrics?
   338  
   339  Sparta-deployed AWS Lambda functions always operate with CloudWatch Metrics `putMetric` privileges.  Your lambda code can call `putMetric` with application-specific data.
   340  
   341  ### How do I setup alerts on additional metrics?
   342  
   343  Define a [TemplateDecorator](https://godoc.org/github.com/mweagle/Sparta#TemplateDecorator) function and annotate the `*gocf.Template` with the needed [AWS::CloudWatch::Alarm](https://godoc.org/github.com/crewjam/go-cloudformation#CloudWatchAlarm) values.  Use [CloudFormationResourceName(prefix, ...parts)](https://godoc.org/github.com/mweagle/Sparta#CloudFormationResourceName) to help generate unique resource names.
   344  
   345  ### How can I determine the outputs available in sparta.Discover() for dynamic AWS resources?
   346  
   347  The list of registered output provider types is defined by `cloudformationTypeMapDiscoveryOutputs` in [cloudformation_resources.go](https://github.com/mweagle/Sparta/blob/master/cloudformation_resources.go).  See the [CloudFormation Resource Types Reference](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html) for information on interpreting the values.
   348  
   349  ## Future