Full AWS APIG stage configuration

[sbkn]

Is there a way to set the settings Enable CloudWatch Logs and Enable Detailed CloudWatch Metrics for the APIG stage? In Cloudformation that would be the params in AWS::ApiGateway::Stage -> MethodSettings.

[HyperBrain]

Currently not, but sounds like a good idea. As the plugin creates a stage resource (and thus has the possibility of complete configuration) an addition and implementation of the feature should be straight forward.

How would you see a possible configuration? I would see it somewhere at function and service level.

[mikelax]

Here is the documentation for the API Gateway Stage MethodSettings.

Is there a way we should default to values (where applicable) from the main serverless.yml file? I agree that it makes sense to be able to set the MethodSettings at either the service or function level.

[HyperBrain]

I inspected the available stage settings and came to the conclusion that the plugin should offer a possibility to configure all of the stage settings instead of only the CW log settings.

To limit possible conflicts with Serverless (in case someone wnats to add this as basic feature to the framework somewhen - I don't really believe in that 😈 ) I'd suggest that the stage setting would reside in an object prefixed with "alias". So the following definition would be possible at the service, function and http event level. Having these 3 locations would let us configure it globally, per function (affecting all endpoints in the function) or only for a specific endpoint. The defaults, if no option is set at all would be the configuration as it currently is in the plugin).

If an option is not explicitly specified in the stage configuration it will be omitted from the CF template. I think that's the expected behavior.

The order of application of multiple configurations would be SVC_LEVEL -> FUNC_LEVEL -> ENDPOINT_LEVEL

The configuration at all locations will then be specified as (YAML):

aliasStage:
  cacheDataEncrypted: Boolean
  cacheTtlInSeconds: Integer
  cachingEnabled: Boolean
  dataTraceEnabled: Boolean
  loggingLevel: String
  metricsEnabled: Boolean
  throttlingBurstLimit: Integer
  throttlingRateLimit: Number

If everyone agrees with this proposal I will implement it exactly that way.

[HyperBrain]

There will be two additional settings that can only be set on the service level:

cacheClusterEnabled: Indicates whether cache clustering is enabled for the stage.
cacheClusterSize: The stage's cache cluster size.

I'll add these for completeness to have any possible stage configuration available

[HyperBrain]

Excerpt from the new README. Explains the exact use of the new feature:

Stage configuration (NEW)

The alias plugin supports configuring the deployed API Gateway stages, exactly as you can do it within the AWS APIG console, e.g. you can configure logging (with or without data/request tracing), setup caching or throttling on your endpoints.

The configuration can be done on a service wide level, function level or method level by adding an aliasStage object either to provider, any function or a http event within a function in your serverless.yml. The configuration is applied hierarchically, where the inner configurations overwrite the outer ones.

HTTP Event -> FUNCTION -> SERVICE

The aliasStage configuration object

All settings are optional, and if not specified will be set to the AWS stage defaults.

aliasStage:
  cacheDataEncrypted: (Boolean)
  cacheTtlInSeconds: (Integer)
  cachingEnabled: (Boolean)
  dataTraceEnabled: (Boolean) - Log full request/response bodies
  loggingLevel: ("OFF", "INFO" or "ERROR")
  metricsEnabled: (Boolean) - Enable detailed CW metrics
  throttlingBurstLimit: (Integer)
  throttlingRateLimit: (Number)

There are two further options that can only be specified on a service level and that affect the whole stage:

aliasStage:
  cacheClusterEnabled: (Boolean)
  cacheClusterSize: (Integer)

For more information see the AWS::APIGateway::Stage or MethodSettings documentation on the AWS website.

Sample serverless.yml (partial):

service: sls-test-project

provider:
  ...
  # Enable detailed error logging on all endpoints
  aliasStage:
    loggingLevel: "ERROR"
    dataTraceEnabled: true
  ...

functions:
  myFunc1:
    ...
    # myFunc1 should generally not log anything
    aliasStage:
      loggingLevel: "OFF"
      dataTraceEnabled: false
    events:
      - http:
          method: GET
          path: /func1
            - http:
                    method: POST
                    path: /func1/create
            - http:
                    method: PATCH
                    path: /func1/update
                    # The update endpoint needs special settings
                    aliasStage:
                      loggingLevel: "INFO"
                      dataTraceEnabled: true
                        throttlingBurstLimit: 200
                        throttlingRateLimit: 100

    myFunc2:
      ...
        # Will inherit the global settings if nothing is set on function level

[HyperBrain]

The feature is available in master now. If someone could give it a try before I release 1.3 it would be great.

I tested it thoroughly with different configuration combinations. I will release 1.3 tomorrow.

[HyperBrain]

Released!