LambdaSharp "Geminus" Release (v0.7.0.1) - 2019-09-12

Geminus of Rhodes, was a Greek astronomer and mathematician, who flourished in the 1st century BC. An astronomy work of his, the Introduction to the Phenomena, still survives; it was intended as an introductory astronomy book for students. He also wrote a work on mathematics, of which only fragments quoted by later authors survive. (Wikipedia)

What's New

This release focuses on making it easy to share modules with others and streamlining the creation and upgrading of LambdaSharp deployment tiers. Prior to this release, LambdaSharp modules had to be made available in an S3 bucket for each region used by a deployment tier. In 0.7.0, the LambdaSharp CLI now automatically imports modules and their artifacts into the S3 bucket of the deployment tier, regardless of the origin region. This new behavior also safeguards against disruption should the original LambdaSharp module become unavailable at a later date since a copy is maintained in the deployment bucket. To further enhance deployment consistency, external modules are only imported during the publishing phase. The deployment phase relies entirely on the modules available in the S3 bucket of the deployment tier.

Upgrade Procedure from v0.6.1 to v0.7.0

  1. Ensure all modules are deployed with v0.6.1 or later
  2. Upgrade LambdaSharp CLI to v0.7.0
    1. dotnet tool uninstall -g LambdaSharp.Tool
    2. dotnet tool install -g LambdaSharp.Tool
  3. Upgrade LambdaSharp Deployment Tier (replace Sandbox with the name of the deployment tier to upgrade)
    1. lash init --tier Sandbox --allow-upgrade
  4. Delete the LambdaSharp CLI profile CloudFormation stack if the CLI profile is not used by any other deployment tiers
    1. Locate the LambdaSharp CLI profile stack in the AWS Console (starts with LambdaSharpTool-)
    2. Empty the associated S3 bucket named DeploymentBucket
    3. Delete the CloudFormation stack

BREAKING CHANGES

LambdaSharp Module

  • The Namespace: declaration has been renamed to Group:.
  • Module references in Using: and Nested: declarations now require an origin suffix. For example, LambdaSharp.S3.IO:0.5 must now be written as LambdaSharp.S3.IO:0.5@lambdasharp.

LambdaSharp Core Services

The DefaultSecretKey was removed from LambdaSharp Core Services. While it was convenient, it introduced a hard relationship between the KMS key and the lifecycle of the LambdaSharp Core Services. The better approach is to entrust the account owner with managing the KMS lifecycle. In addition, it was also a monthly recurring cost item, which was unnecessary when not required.

A few Lambda related error messages have been rephrased to make it clearer they related to the execution of Lambda functions.

  • Task timed out after 15.02 seconds is now Lambda timed out after 15.02 seconds
  • Process exited before completing request is now Lambda exited before completing request
  • Process ran out of memory (Max: 128 MB) is now Lambda ran out of memory (Max: 128 MB)
  • Process nearing execution limits (Memory 80.12 %, Duration: 91.23 %) is now Lambda nearing execution limits (Memory 80.12 %, Duration: 91.23 %)

LambdaSharp CLI

  • The lash config command has been removed. Its functionality has been integrated into the lash init command to streamline the setup process, resulting in a single deployment tier stack.
  • The concept of the CLI profile is gone. Therefore the --cli-profile option is no longer supported.
  • With support of resolving LambdaSharp modules from third-party S3 buckets by using the @origin suffix on module names, there is no need to pre-register S3 buckets anymore, which makes the --module-bucket-names obsolete.
  • The deployment tier does not support the SNS topic for CloudFormation updates, which means the --deployment-notifications-topic option is no longer supported.
  • The LambdaSharp CLI will now fail to publish a stable version of a module when the git-sha is prefixed with DIRTY-, which indicate uncommitted local changes. This behavior can be overwritten with --force-publish.
  • The .csproj file generated by lash new function can now dynamically support contributor mode (i.e. using a local LambdaSharp git checkout), which makes the --use-project-reference and --use-nuget-reference obsolete.
  • The options for lash tier coreservices were changed from --enable to --enabled and from --disable to --disabled to make them consistent with the lash init command.

LambdaSharp Assemblies

  • ALambdaFunction.InfoStruct.ModuleOwner has been renamed to ALambdaFunction.InfoStruct.ModuleNamespace
  • ALambdaFunction.DefaultSecretKeyId has been removed
  • The physical ID returned by ALambdaFinalizerFunction is now a constant (Finalizer:Module) instead of being based on the checksum of the original template. The latter proved too risky, because it could accidentally trigger a CloudFormation delete resource event when not expected.

New LambdaSharp CLI Features

Init Command

The lash init command has been redesigned to streamline the setup and configuration of a deployment tier.

Running lash init --quick-start will create a new deployment tier without any prompts. The newly created tier has no LambdaSharp Core Services, which means it sets up quickly and at no monthly cost. In addition, an empty deployment tier name is now supported, which means using the --tier option--or the LAMBDASHARP_TIER environment variable--is now optional.

The deployment tier can be upgraded to use LambdaSharp Core Services by running lash init --core-services enabled. Similarly, a deployment tier can also be downgraded by running lash init --core-services disabled assuming none of the deployed modules rely on them. Otherwise, first run the lash tier coreservices --disabled command.

Build Command

The lash build command has two new options for advanced use cases. First, is the --module-version, which sets the version of the module being compiled. This option makes it possible to tie the module version to an environment variable or otherwise supply it without modifying the module source file. Second, the --module-build-date, which is used to override the default build date of the module. This option is useful to ensure that the generated CloudFormation file is deterministic, which is required for some validation scenarios.

Publish Command

The lash publish command has a new option to override the module origin information using --module-origin. By default, the module origin for a newly published module is the name of the deployment bucket. However, it may be sometimes necessary to publish a new version of a module that originated from somewhere else, such as deploying an urgent fix. With the --module-origin option, it is possible to publish a module into the S3 bucket of the deployment tier, while making it look like it was imported. As a result, all subsequent deployments will resolve their dependencies to this new module. The imported module and its artifacts are annotated with a metadata field (x-amz-meta-lambdasharp-origin) that describes their true origin.

The lash publish command is responsible for uploading the module artifacts to the deployment bucket, as well as importing all dependencies. Modules from a foreign origin can also be imported explicitly by this command.

Using PowerShell/Bash:

lash publish LambdaSharp.S3.Subscriber:0.7.0@lambdasharp

The following text should appear (or similar):

LambdaSharp CLI (v0.7.0) - Publish LambdaSharp module
=> Imported LambdaSharp.S3.Subscriber:0.7.0@lambdasharp

Done (finished: 8/16/2019 10:27:01 AM; duration: 00:00:04.5205374)

To accommodate combining modules from various origins in a single S3 deployment bucket, the structure of the S3 keys had to be revisited. All published/imported modules and their artifacts now have the following prefix {Module::Origin}/{Module::Namespace}/{Module::Name}, which ensures there will never be any conflicts, since S3 bucket names (i.e. the module origin) is guaranteed to be globally unique. The module manifest--which describes the parameters, resource type definitions, dependencies, and artifacts--is located at {Module::Origin}/{Module::Namespace}/{Module::Name}/{Module::Version}. The module artifacts, across all versions, are located at {Origin}/{ModulePrefix}/{ModuleSuffix}/.artifacts/.

Deploy Command

The lash deploy command now takes multiple values for the --xray option. Without any value, the --xray option only enables AWS X-Ray for the root module being deployed. Optionally, AWS X-Ray can also be enabled for the root module and all nested modules using --xray:allmodules.

Additionally, AWS X-Ray is now supported for Lambda functions, AWS SDK calls, public HTTP calls (when using the [ALambdaFunction.HttpClient] property(xref:ALambdaFunction.HttpClient)) and API Gateway endpoints, providing deeper insights into

New Function Command

The lash new function command has been enhanced with types for C# functions. It can now create the scaffolding for functions to handle API Gateway, custom CloudFormation resources, SQS queues, scheduled CloudWatch events, SNS topics, WebSocket, module finalizer, and generic requests by using the --type option. If no type is provided, the LambdaSharp CLI will prompt for one. In addition, the --memory and --timeout options have been added. When omitted, they default to 256 (MB) and 30 (seconds), respectively.

The generated .csproj file was updated to make it easier for contributors to deploy modules with their latest local changes by conditionally referencing the LambdaSharp nuget package or local LambdaSharp project depending on the LAMBDASHARP environment variable. This behavior was achieved by using conditionals in the .csproj file.

<ItemGroup>
<PackageReference Condition="'$(LAMBDASHARP)'==''" Include="LambdaSharp" Version="0.7.0.*"/>
<ProjectReference Condition="'$(LAMBDASHARP)'!=''" Include="$(LAMBDASHARP)/src/LambdaSharp/LambdaSharp.csproj" />
</ItemGroup>

New Bucket Command

The lash new bucket command is used to create a new public S3 bucket configured to require requestors to pay for data transfer. This is the recommended configuration when publicly sharing LambdaSharp modules so the owner of the bucket only pays for the storage and not its access, which could become expensive for a popular module. Once the bucket is created, it can be used with a deployment tier to enable publishing to it.

Using PowerShell/Bash:

lash new bucket my-lambdasharp-bucket

The following text should appear (or similar):

LambdaSharp CLI (v0.7.0) - Create new public S3 bucket for sharing LambdaSharp modules
CREATE_COMPLETE    AWS::CloudFormation::Stack    PublicLambdaSharpBucket-my-lambdasharp-bucket
CREATE_COMPLETE    AWS::S3::Bucket               Bucket
CREATE_COMPLETE    AWS::S3::BucketPolicy         BucketPolicy
=> Stack creation finished
=> Updating S3 Bucket for Requester Pays access

Done (finished: 8/16/2019 10:20:18 AM; duration: 00:00:32.5327433)

Info Command

The lash info command now shows if LambdaSharp Core Services are enabled for the deployment tier. In addition, it will also show how much Lambda storage is used and how much Lambda reserved capacity is used by the AWS account.

Using PowerShell/Bash:

lash info

The following text should appear (or similar):

LambdaSharp CLI (v0.7.0) - Show LambdaSharp information
LambdaSharp Deployment Tier
    Name: Sandbox
    Version: 0.7.0
    Core Services: Enabled
    Deployment S3 Bucket: sandbox-lambdasharp-cor-deploymentbucketresource-kvuimlss8yky
    API Gateway Role: arn:aws:iam::************:role/LambdaSharp-ApiGatewayRole
Git
    Branch: 1.0-DEV
    SHA: e8705be44f02f81f5e7c300205cf6de97248e090
AWS
    Region: us-west-2
    Account Id: ************
    Lambda Storage: 0.52GB of 75GB (0.69%)
    Lambda Reserved Executions: 35 of 1,000 (3.50%)
Tools
    .NET Core CLI Version: 2.2.203
    Git CLI Version: 2.18.0.windows.1
    Amazon.Lambda.Tools: 3.2.3

Done (finished: 8/20/2019 12:27:29 PM; duration: 00:00:04.9603515)

Encrypt Command

The lash encrypt command now has a support for decrypting an encrypted secret before encrypting it by supplying the --decrypt option. This option makes it possible to decrypt an existing secret and re-encrypt it using a different KMS key without having to decrypt it manually first.

New LambdaSharp Assembly Features

  • Added ALambdaFunction.DeploymentBucketName property to read the S3 bucket name used to deploy the Lambda function.
  • Added ALambdaCustomResourceFunction.Abort(string) method to abort the creation or update of a custom resource. Abort() will cause CloudFormation to respond with a failure code and showing the provided message.
  • Added LambdaSharp.CustomResource.Request<TProperties>.StackId property to custom resource request to uniquely identify the CloudFormation stack from which the request originated.
  • The ALambdaFinalizerFunction class now checks confirms the CloudFormation stack is being deleted before triggering the [DeleteDeployment(FinalizerProperties)] method. This change allows a Finalizer to be removed from a module without triggering its delete logic.

Releases

(v0.7.0.1) - 2019-09-12

Fixes

  • Fixed an issue with enabling/disabling core services in a deployment tier.

Updated Documentation

  • Added metadata to HTML pages.