
Sigma CLI: Build and Deploy your Sigma projects with ease
SLAppForge Sigma is a purposely-built IDE for developing and deploying serverless applications on AWS and GCP. As you may be already aware, when you develop a project using Sigma, it provides the capability to build and deploy your project via the Sigma IDE itself without any external tools. While this being very convenient and useful, in some situations it is required to build and/or deploy projects without the Sigma IDE. For example, if you are setting up a CI/CD workflow on GitHub, you may need to configure it to build and deploy your project for certain commits, tags, etc.
To cater to this requirement, we have recently introduced a command-line toolkit named Sigma CLI, which can be used to build and/or deploy your existing Sigma projects. This toolkit is available as an NPM module at the NPM registry, which can be installed as a global module as shown below.
This toolkit only supports AWS based deployments at the moment. GCP based deployments will be supported in the future.
Installing Sigma CLI
Prerequisites
The following should be installed and available in the system where this toolkit is to be used.
- NodeJS (version 10 or newer) – Currently installed
node
version can be checked using the commandnode -v
- NPM – Currently installed
npm
version can be checked using the below commandnpm -v
In case NodeJS and NPM are not installed, you can follow this guide to install them on your system.
Installation
If the above prerequisites are met, Sigma CLI can be installed as a global node module using the below command.
npm install slappforge-sigma-cli -g
Once installed, the sigma
command will be available system-wide.
Building a Sigma project
Sigma CLI can be used to build a Sigma created project on a local file system. For that first clone your Sigma project into a local file system location. Then navigate to the project location via a terminal or command prompt and execute the following Sigma build command to build your project.
sigma aws build
This operation will carry out the following tasks.
- Validate the project to verify that it is a valid Sigma project
- If your project has NPM dependencies, run a
npm install
to download those dependencies. - If your project has PIP dependencies, run a
pip install
to download those dependencies. - Create a Lambda deployable zip archive containing your project files and dependencies and persist it into the local file system.
The name of the above-mentioned deployment package (zip archive) is of the format build_<Project Name>_<Project Version>_<Build timestamp>.zip
. For example, if your project name is MyProject, the version is 1.0.0, and the build was run on 2020-Aug-21 at 10:00 UTC, the deployment package name will be build_MyProject_1.0.0_1598004000000.zip
.
By default, the above-mentioned deployment package (zip archive) will be created in the sigma-builds
subdirectory within the project root directory. If you need to persist it into a different directory, you can pass the --buildDir
option to the above command with the desired output directory as below.
sigma aws build --buildDir myBuildOutputs
Uploading the deployment package to S3
To use the deployment package for a Lambda function, deployment frameworks such as AWS CloudFormation (which is used by Sigma and Sigma CLI) require the deployment package to be present in an S3 location. You can use the Sigma CLI build command itself to perform this S3 upload automatically after the deployment package is generated locally.
For that, you need to provide a set of additional options to the above build command. First of all, you will need to provide the following S3 location related options.
--s3Bucket
– The name of the S3 bucket to upload the generated deployment package. S3 upload will be attempted only if this option is provided with the command.--s3Prefix
– If you need to upload the deployment package under a specific parent prefix within the above bucket, you can provide it with this option. This option is not mandatory.
Then you need to provide the credentials to be used for uploading the deployment package to the above S3 location. For that please refer to the Providing AWS Credentials to CLI operations section below.
Then the full build command will look like below.
sigma aws build --s3Bucket my-deployment-packages --s3Prefix MyProjectPackages --awsProfile aws-dev
Deploying a Sigma project
Sigma CLI can be used to deploy your project to an AWS account. This deployment operation has 2 main modes.
Since
aws deploy
command requires access to the AWS account for deployment tasks, you need to provide the credentials to any variant of this command. Please refer to the Providing AWS Credentials to CLI operations section below on providing AWS credentials.
Deployment with Build
In this mode, the project building tasks as mentioned in the previous section will be performed first and then it will be followed with the deployment tasks. Since uploading the deployment package into an S3 bucket is mandatory in this mode, you must provide the --s3Bucket
option to this command. Also, you can use the other customization options mentioned in the build
command such as --buildDir
and --s3Prefix
with aws deploy
command as well.
sigma aws deploy --s3Bucket my-deployment-packages --awsProfile aws-dev
Deployment without Build
In this mode, you need to provide the S3 URL of an existing deployment package with the option --depPackage
. Then only the deployment tasks will be carried out using the provided deployment package for Lambda deployments.
sigma aws deploy --depPackage s3://my-deployment-packages/MyProjectPackages/build_MyProject_1.0.0_1598004000000.zip --awsProfile aws-dev
In both the above modes, the deployment step involves the following tasks.
- Checks the existence of a CloudFormation stack with the same name.
By default, the stack name is of the format<Project Name>-<Project Version>-Stack
. For example, if your project name is MyProject and the version is 1.0.0, the stack name will beMyProject-1-0-0-Stack
. If you need to provide a custom name for the stack, you can provide it with the--stackName
option. (This can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphabetic character and can’t be longer than 128 characters.) - If a stack with the same name already exists, uses
UPDATE
mode for the deployment, or usesCREATE
mode otherwise. - Creates a CloudFormation Change Set with the deployment changes. Then displays the changes list on the console and prompts for the user approval for executing the changeset.
- If the user has provided the consent, execute the changeset while displaying the event logs on the console in near real-time.
- Once the deployment is completed, displays the deployment status along with the deployment outputs.
Providing CloudFormation Template Parameters
If your project CloudFormation template contains any Template Parameters, their values can be provided to the deploy command with 2 approaches.
The first approach is to define the parameter name-value pairs in the command itself using the --templateParam
option. If you have more than one parameter, you can specify this option multiple times.
sigma aws deploy --s3Bucket my-deployment-packages --awsProfile aws-dev --templateParam parameter1:value1 --templateParam parameter2:value2
The second approach is to include the parameter keys and values as a JSON object in a JSON file and provide the location of the file using the --templateParamFile
option.
sigma aws deploy --s3Bucket my-deployment-packages --awsProfile aws-dev --templateParamFile .~/.configs/deployment-params.json
In case parameter values are provided using both approaches, the value provided through the file will be overridden by the value provided as --templateParam
, if the key is the same.
Sigma IDE by default define 2 parameters in the generated CloudFormation template as
lambdaCodeBucketParameter
andlambdaCodeKeyParameter
, to specify the S3 bucket and the key of the deployment package. You don’t need to provide values for these 2 parameters as CLI will internally provide them during the deployment.
Other supported options of deploy
--autoDepMode
– By default, the deployment step lists the change list on the console and prompts for the user approval before executing them. If this option is provided astrue
, change list will be executed without waiting for user approval. This is normally useful for automated deployments such as CI/CD pipelines.--deleteUnrecoverable
– If the stack is in an unrecoverable (non-updatable) state, the deployment will generally fail. In such a case, if this option is provided astrue
, CLI will delete the existing stack and retry the deployment.
Providing AWS Credentials to CLI operations
Some of the CLI operations require access to your AWS account for tasks such as uploading the deployment package to S3 or deploying your project via CloudFormation. For that either you can provide an AWS access-secret key-pair or you can provide the name of an AWS Named Profile configured on your system.
Providing Access Key and Secret Key
An AWS Access Key and a Secret Key can be provided via the following options to
aws build
andaws deploy
commands.
--awsKey
– AWS access key with necessary access permissions--awsSecret
– AWS secret key associated with the above access keyProviding a Named Profile
Alternatively, the name of an AWS AWS Named Profile configured on your system can be provided via the following option to
aws build
andaws deploy
commands.
--awsProfile
– AWS profile with necessary access permissionsIn case both key and profile options are provided, only the profile option will be used. In case non of them are provided, CLI will attempt AWS access under the assumption that a
default
profile has been configured on the system.