Sigma CLI: Build and Deploy your Sigma projects with ease

blog  |     |  

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 command node -v
  • NPM – Currently installed npm version can be checked using the below command npm -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 be MyProject-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 uses CREATE 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 and lambdaCodeKeyParameter, 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 as true, 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 as true, 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 and aws deploy commands.

  • --awsKey – AWS access key with necessary access permissions
  • --awsSecret – AWS secret key associated with the above access key

Providing 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 and aws deploy commands.

  • --awsProfile – AWS profile with necessary access permissions

In 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.