Deploy Module

The deploy command is used to deploy a published module.

CloudFormation stacks created by the LambdaSharp CLI have termination protection enabled when deployed with the --protect option. In addition, subsequent updates cannot delete or replace data resources unless the --allow-data-loss option is passed in. This behavior is to reduce the risk of accidental data loss when CloudFormation resources are replaced.

Arguments

The deploy command takes an optional argument. The argument can either be the name of a published module with an optional version constraint, a path to a manifest file, a path to a module definition, or a path to a folder containing a Module.yml file.

If the argument refers to a manifest file, the deploy command invokes publish command to upload the module and its artifacts to the deployment bucket.

If the argument refers to a module definition, the deploy command invokes the build command to compile the module and all its artifacts, followed by the publish command to upload all built artifacts.

Options

--name <NAME>: (optional) Specify an alternative module name for the deployment (default: module name)
--parameters <FILE>: (optional) Specify filename to read module parameters from (default: none)
--allow-data-loss: (optional) Allow CloudFormation resource update operations that could lead to data loss
--protect: (optional) Enable termination protection for the CloudFormation stack
--xray[:<LEVEL>]: (optional) Enable service-call tracing with AWS X-Ray for all resources in module (0=Disabled, 1=RootModule, 2=AllModules; RootModule if LEVEL is omitted)
--force-deploy: (optional) Force module deployment
--prompt-all: (optional) Prompt for all missing parameters values (default: only prompt for missing parameters with no default value)
--no-import: (optional) All module artifacts must exist in deployment tier bucket and cannot be imported
--no-dependency-upgrades: (optional) Do not automatically upgrade shared dependencies
--prompts-as-errors: (optional) Missing parameters cause an error instead of a prompts (use for CI/CD to avoid unattended prompts)
--force-publish: (optional) Publish modules and their artifacts even when no changes were detected
--no-assembly-validation: (optional) Disable validating LambdaSharp assembly references in function project files
--no-dependency-validation: (optional) Disable validating LambdaSharp module dependencies
--configuration|-c <CONFIGURATION>: (optional) Build configuration for function projects (default: "Release")
--git-sha <VALUE>: (optional) Git SHA of most recent git commit (default: invoke git rev-parse HEAD command)
--git-branch <VALUE>: (optional) (optional) Git branch name (default: invoke git rev-parse --abbrev-ref HEAD command)
--output|-o <DIRECTORY>: (optional) Path to output directory (default: bin)
--selector <NAME>: (optional) Selector for resolving conditional compilation choices in module
--cfn-output <FILE>: (optional) Name of generated CloudFormation template file (default: bin/cloudformation.json)
--module-origin <ORIGIN>: (optional) Set alternative module origin when publishing
--module-version <VERSION>: (optional) Override the module version
--module-build-date <DATE>: (optional) Override module build date [yyyyMMddHHmmss]
--from-bucket <BUCKET>: (optional) Use specified S3 bucket to import module from instead of module origin
--force-build: (optional) Always build function packages
--force-refresh: (optional) Always refresh manifests from their origin
--build-policy <FILEPATH>: (optional) Provide build policy document file path
--dryrun[:<LEVEL>]: (optional) Generate output artifacts without deploying (0=everything, 1=cloudformation)
--tier|-T <NAME>: (optional) Name of deployment tier (default: LAMBDASHARP_TIER environment variable)
--aws-profile|-P <NAME>: (optional) Use a specific AWS profile from the AWS credentials file
--aws-region <NAME>: (optional) Use a specific AWS region (default: read from AWS profile)
--verbose|-V[:<LEVEL>]: (optional) Show verbose output (0=Quiet, 1=Normal, 2=Detailed, 3=Exceptions; Normal if LEVEL is omitted)
--no-ansi: (optional) Disable colored ANSI terminal output
--quiet: (optional) Don't show banner or execution time
--no-beep: (optional) Don't emit beep when finished

Examples

Build, publish, and deploy module in current folder

Using PowerShell/Bash:

lash deploy

Output:

LambdaSharp CLI (v0.7.0) - Deploy LambdaSharp module
Readying module for deployment tier 'Sandbox'

Reading module: Module.yml
Compiling: Demo.SlackTodo (v1.0-DEV)
=> Building function SlackCommand [netcoreapp3.1, Release]
=> Module compilation done: bin\cloudformation.json
Publishing module: Demo.SlackTodo
=> Uploading artifact: s3://lambdasharp-bucket-name/lambdasharp-bucket-name/LambdaSharp/Demo.SlackTodo/.artifacts/function_Demo.SlackTodo_SlackCommand_E0F4477DDAFDC152C8B66343657E9425.zip
=> Uploading template: s3://lambdasharp-bucket-name/lambdasharp-bucket-name/LambdaSharp/Demo.SlackTodo/.artifacts/cloudformation_Demo.SlackTodo_939992254E194760372083264D08D795.json
Resolving module reference: Demo.SlackTodo:1.0-DEV@lambdasharp-bucket-name
=> Validating module for deployment tier

Deploying stack: Sandbox-LambdaSharp-Demo-SlackTodo [Demo.SlackTodo:1.0-DEV@lambdasharp-bucket-name]
=> Stack create initiated for Sandbox-LambdaSharp-Demo-SlackTodo [CAPABILITY_IAM]
CREATE_COMPLETE    AWS::CloudFormation::Stack             Sandbox-LambdaSharp-Demo-SlackTodo
CREATE_COMPLETE    AWS::DynamoDB::Table                   TaskTable
CREATE_COMPLETE    AWS::ApiGateway::RestApi               Module::RestApi
...
CREATE_COMPLETE    AWS::Logs::SubscriptionFilter          SlackCommand::LogGroupSubscription
CREATE_COMPLETE    AWS::ApiGateway::Deployment            Module::RestApi::Deployment48BDBB7F2CFECB525DA5E89C8DF7A0E7
CREATE_COMPLETE    AWS::ApiGateway::Stage                 Module::RestApi::Stage
=> Stack create finished
Stack output values:
=> LambdaSharpTier = Sandbox
=> LambdaSharpTool = 0.7.0
=> Module = Demo.SlackTodo:1.0-DEV@lambdasharp-bucket-name
=> ModuleChecksum = 442684F838E5B6717B0EF0E74334062F
=> SlackApiPath: Slack Command URL = https://lr0iaacgoc.execute-api.us-west-2.amazonaws.com/LATEST/slack

Done (finished: 9/5/2019 1:43:03 PM; duration: 00:01:55.6433420)

Deploy a published module

Using PowerShell/Bash:

lash deploy bin/cloudformation.json

Output:

LambdaSharp CLI (v0.7.0) - Deploy LambdaSharp module
Readying module for deployment tier 'Sandbox'

Publishing module: Demo.SlackTodo
=> Uploading artifact: s3://lambdasharp-bucket-name/lambdasharp-bucket-name/LambdaSharp/Demo.SlackTodo/.artifacts/function_Demo.SlackTodo_SlackCommand_E0F4477DDAFDC152C8B66343657E9425.zip
=> Uploading template: s3://lambdasharp-bucket-name/lambdasharp-bucket-name/LambdaSharp/Demo.SlackTodo/.artifacts/cloudformation_Demo.SlackTodo_939992254E194760372083264D08D795.json
Resolving module reference: Demo.SlackTodo:1.0-DEV@lambdasharp-bucket-name
=> Validating module for deployment tier

Deploying stack: Sandbox-LambdaSharp-Demo-SlackTodo [Demo.SlackTodo:1.0-DEV@lambdasharp-bucket-name]
=> Stack create initiated for Sandbox-LambdaSharp-Demo-SlackTodo [CAPABILITY_IAM]
CREATE_COMPLETE    AWS::CloudFormation::Stack             Sandbox-LambdaSharp-Demo-SlackTodo
CREATE_COMPLETE    AWS::DynamoDB::Table                   TaskTable
CREATE_COMPLETE    AWS::ApiGateway::RestApi               Module::RestApi
...
CREATE_COMPLETE    AWS::Logs::SubscriptionFilter          SlackCommand::LogGroupSubscription
CREATE_COMPLETE    AWS::ApiGateway::Deployment            Module::RestApi::Deployment48BDBB7F2CFECB525DA5E89C8DF7A0E7
CREATE_COMPLETE    AWS::ApiGateway::Stage                 Module::RestApi::Stage
=> Stack create finished
Stack output values:
=> LambdaSharpTier = Sandbox
=> LambdaSharpTool = 0.7.0
=> Module = Demo.SlackTodo:1.0-DEV@lambdasharp-bucket-name
=> ModuleChecksum = 442684F838E5B6717B0EF0E74334062F
=> SlackApiPath: Slack Command URL = https://lr0iaacgoc.execute-api.us-west-2.amazonaws.com/LATEST/slack

Done (finished: 9/5/2019 1:43:03 PM; duration: 00:01:55.6433420)

Deploy a module with a parameters file

The deploy command can optionally take a YAML file to specify the parameter values. The YAML file must be a map of key-value pairs, where each key corresponds to a parameter or import name. The value can either be a literal value (string, number, boolean) or a list. Lists are automatically concatenated into a comma-separated string of values.

The Secrets key has some additional special processing rules. Secrets is used to enable a module to use additional managed encryption keys. These can be specified with an account specified key ID or with an account-agnostic key alias. When a key alias is used, the deploy command automatically resolves it to a key ID before using it as a parameter value.

ParameterValue: parameter value
ParameterCommaSeparatedList:
    - first value
    - second value
Secrets:
    - alias/MySecretKey

Using PowerShell/Bash:

lash deploy --parameters params.yml Demo

Use lookup functions in parameter file

The following functions can be used in parameter files to dynamically resolve values during the deploy phase.

!GetConfig

The !GetConfig function takes two arguments: the location of a JSON file and a JSON-path expression. The CLI loads the JSON file and finds the value at the JSON-path expression. The !GetConfig is recommended when there is a central configuration file that is used for deploying multiple modules.

Syntax

!GetConfig [ json-file-path, json-path-expression ]

Parameters

json-file-path: The path to the JSON file, relative to the location of the parameter files.
json-path-expression: A JSON-path expression to locate to desired value in the JSON file. A good description of the syntax and operators can be found in this repository.

!GetEnv

The !GetEnv function reads a system environment variable.

Syntax

!GetEnv environment-variable

Parameters

environment-variable: The name of an environment variable.

!GetParam

The !GetParam function reads a value from the AWS Parameter Store and optionally encrypts it using a KMS key.

Syntax

!GetParam parameter-store-path

-OR-

!GetParam [ parameter-store-path ]

-OR-

!GetParam [ parameter-store-path, encryption-key-id ]

Parameters

parameter-store-path: The path to a value in the AWS Parameter Store.
If the value is stored as a SecureString, it is automatically decrypted when retrieved and passed as plain text, unless an encryption-key-id is provided.
encryption-key-id: The AWS Key Management Service key ARN or alias to use for encrypting the value from the parameter store.

Examples

ApiKey: !GetConfig [ '../global.json', Services.SomeApi.ApiKey ]
ReplyEmail: !GetParam /Company/EmailAddress
Language: !GetEnv LANG

!Ref

The !Ref function reads a built-in variable.

Syntax

!Ref builtin-variable

Parameters

builtin-variable

The name of a built-in variable.

One of:

Deployment::BucketName: S3 Bucket name from which the module is being deployed from.
Deployment::Tier: Deployment tier name. Empty string for default deployment tier.
Deployment::TierLowercase: Deployment tier name in lowercase characters. Empty string for default deployment tier.
Deployment::TierPrefix: Deployment tier prefix used to isolate resources. Empty string for default deployment tier.
Deployment::TierPrefixLowercase: Deployment tier prefix in lowercase characters. Used by resources that require only lowercase characters (e.g. S3 buckets, domain names). Empty string for default deployment tier.

!Sub

The !Sub function substitutes variables in the format string with values from the arguments map or environment variables.

Syntax

!Sub format-string

-OR-

!Sub [ format-string, arguments ]

Parameters

format-string: A string with variables that !Sub substitutes. Write variables as ${MyVariable}. Variable values can come from the arguments map or from environment variables. The arguments map can be omitted if only environment variables are referenced.
arguments: A map of key-value pairs. The value of a key can be a function.

Examples

BucketArn: !Sub
  - "arn:aws:s3:::${Name}"
  - Name: !GetParam [ !Sub "/${STAGE}/bucket-name" ]