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" ]