README.md

Getting Started

The installer module provides a set of tools for installing and managing CDF modules.

Prerequisites

CDF Module Bundles

Ensure that CDF modules had been built and bundled ready for deployment.

aws-connected-device-framework/source> rush bundle

IAM Credentials

The installer executes a number of aws commands (e.g, aws cloudformation package, aws cloudformation deploy) to upload artifacts and deploy the modules to the target account. Ensure that you have IAM credential with the right policies set up on your shell when running the scripts below.

Building the installer

To build the installer module run this script

aws-connected-device-framework/source> cd packages/services/installer
aws-connected-device-framework/source/packages/services/installer> rushx create:installer

Commands

Note that in all the examples below the command to run the installer is given as cdf-cli. We have had some reports where the cdf-cli command cannot be found after building. The rushx create:installer command is meant to configure the cdf-cli alias but for some unknown reason it does not always create the alias. If you run into this issue, substitue node dist/index.js for cdf-cli to run.

Deploying using the wizard

Start the deployment wizard using the following command:

> cdf-cli deploy <environment> <region> -b <optional-bucket> -p <optional-prefix>

Argument	Description
environment	the environment to deploy
region	the region to deploy into
optional-bucket	optional s3 bucket to store the packaged artifacts
optional-prefix	optional s3 prefix to organize the generated artifacts

The deployment wizard will ask a series of questions to determine which CDF modules need to be deployed based on the selected options. Once you finish the deployment, a configuration file for your deployment state will be stored in ~/aws-connected-device-framework/config/<ACCOUNT_ID>/<REGION>/<ENVIRONMENT>, ENVIRONMENT will be the file name. It is recommended to add these generated configuration files to source control so that others can update the deployment.

Running this command with the flag -d or --dryrun will generate the configuration file without performing the deployment

Deploying using an existing configuration

The installer wizard can be bypassed by providing a pre-existing installer configuration file, the same file generated from the using the installer wizard, as follows:

Argument	Description
environment	the environment to deploy
region	the region to deploy into
deployment-config	location of deployment configuration file generated by deployment wizard
optional-bucket	optional s3 bucket to store the packaged artifacts
optional-prefix	optional s3 prefix to organize the generated artifacts

> cdf-cli deploy <environment> <region> -c <deployment-config> -b <optional-bucket> -p <optional-prefix>

This will deploy all the modules configured in your last deployment wizard run. This type of deployment is recommended for continuous integration and automated deployments.

Packaging

The packaging command will package all the modules that selected and upload both the CloudFormation template files and parameter files to S3 bucket. This is useful in scenarios where CDF needs to be deployed via a CI/CD pipeline.

For example, if you specify cdf-packaging-bucket as the s3 bucket to use, the templates will be uploaded to s3://cdf-packaging-bucket/cloudformation/templates and the parameters file will be uploaded to s3://cdf-packaging-bucket/cloudformation/parameters. It will also upload the list of tagging parameters to s3://cdf-packaging-bucket/cloudformation/tags

The installer will try to pre-populate the parameters file based on your answer and default value in the CloudFormation template, but there are some parameters that are dependent on the output of other stacks, make sure you deploy the stack in the right order (see "Deploying the packaged template manually" below for a suggested ordering).

Packaging using an existing configuration

To package the cloudformation templates, you have to provide installer configuration file generated by the installer as follows:

Argument	Description
deployment-config	location of deployment configuration file generated by deployment wizard
optional-bucket	optional s3 bucket to store the packaged artifacts
optional-prefix	optional s3 prefix to organize the generated artifacts in the s3 bucket

> cdf-cli package <deployment-config> -b <optional-bucket> -p <optional-prefix>

If you specify cdf-production-packaging-bucket as the optional bucket and v1.0.0 as the optional prefix, the templates will be uploaded to s3://cdf-production-packaging-bucket/v1.0.0/templates , parameters will be uploaded to s3://cdf-production-packaging-bucket/v1.0.0/parameters and tags to s3://cdf-production-packaging-bucket/v1.0.0/tags

NOTE: You can generate the configuration file by running the deploy command in dryRun mode as follows: cdf-cli deploy <environment> <region> -d

Deploying the packaged template manually

Below are the details of each module ordered by deployment sequence (for full CDF deployment). If you only want to deploy some modules, locate the module on the table and workbackward from the list of dependencies to figure out which module that needs to be deployed as pre-requisite.

NOTE: The file name in template column refers to the packaged template that is uploaded to S3 as part of the packacing process, but the link will redirect you to the pre-packaged file.

Module	Template	Dependencies	Optional Dependencies	Notes
KMS	None	None	None	If you're not deploying with cdf-cli, you need to create the KMS key manually and pass in the id to the stack that requires KMS
EventBus	cfn-eventbus.template	None	None
VPC	cfn-networking.template	None	None	You can use existing VPC and not use the one provided by this repository
OpenSSL Lambda Layer	cfn-openssl-layer.template	None	None
Deployment Helper	cfn-deployment-helper.template	None	None
Deployment Helper VPC	cfn-deployment-helper-vpc.template	VPC	None	This deployment helper lambda can queries resources inside VPC (e.g. NeptuneDB version)
Auth (by Device Cert)	cfn-auth-devicecert.template	KMS OpenSSL Lambda Layer	None
Greengrass 2 Installer Config Generators	cfn-greengrass2-installer-config-generators.template	Deployment Helper	None
Asset Library Neptune	cfn-neptune.template	VPC Deployment Helper VPC	None	This stack is required if you're running Asset Library in full mode
Asset Library Service	cfn-assetlibrary.template	Deployment Helper (lite) Deployment Helper VPC(full)	VPC Asset Library [Neptune]	If you're deploying Asset Library in in full mode, then VPC, Deployment Helper VPC and Asset Library Neptune is mandatory
Asset Library History	cfn-assetLibraryHistory.template	KMS Asset Library Service	VPC	VPC is only needed when you need to run API Gateway in private mode
Bulk Certificates	cfn-bulkcerts.template	KMS OpenSSL Lambda Layer	VPC	VPC is only needed when you need to run API Gateway in private mode
Device Patcher	cfn-device-patcher.template	KMS	VPC	VPC is only needed when you need to run API Gateway in private mode
Events Processor	cfn-eventsProcessor.template	KMS Deployment Helper	VPC	VPC is only needed when you need to run API Gateway in private mode or if you want to use DAX
Events Alerts	cfn-eventsAlerts.template	KMS Events Processor	VPC	VPC is only needed when you need to run API Gateway in private mode
Provisioning	cfn-provisioning.template	KMS OpenSSL Lambda Layer Deployment Helper	VPC	VPC is only needed when you need to run API Gateway in private mode
Asset Library Export	cfn-assetlibrary-export.template	KMS Asset Library [Neptune]	VPC	VPC is only needed when you need to run API Gateway in private mode
Certificate Activator	cfn-certificateactivator.template	KMS Asset Library Service Provisioning OpenSSL Lambda Layer	None
Commands	cfn-commands.template	KMS Asset Library Service Deployment Helper Provisioning	VPC	VPC is only needed when you need to run API Gateway in private mode
Command And Control	cfn-command-and-control.template	KMS Asset Library Service Deployment Helper Provisioning	VPC	VPC is only needed when you need to run API Gateway in private mode
Device Monitoring	cfn-device-monitoring.template	Asset Library Service	None
Simulation Launcher	cfn-simulation-launcher.template	VPC Deployment Helper	None
Simuation Manager	cfn-simulation-manager.template	KMS Simulation Launcher Deployment Helper Asset Library Service	VPC	VPC is only needed when you need to run API Gateway in private mode
Greengrass V2 Provisioning	cfn-greengrass2-provisioning.template	KMS Greengrass 2 Installer Config Generators Provisioning EventBus	VPC Asset Library Service	Asset Library Service is only needed if you want to perform complex query when selecting devices for components deployment
Certificate Vendor	cfn-certificatevendor.template	KMS Asset Library Service Commands OpenSSL Lambda Layer Deployment Helper

Deleting stacks

This will remove all the stacks that have been created based on a deployment:

Argument	Description
environment	the environment to deploy
region	the region to deploy into

> cdf-cli delete <environment> <region>

Generating Postman environment file

This retrieves the urls for all the CDF modules that expose a REST API endpoint and prints out an environment json file that can be imported into Postman.

Argument	Description
name	name of Postman environment
environment	the environment to deploy
region	the region to deploy into

> cdf-cli postman <name> <environment> <region>

Local development

You can generate the .env file automatically for running modules locally. This is useful when carrying out local development.

Argument	Description
environment	the environment to deploy
region	the region to deploy into
output-folder	the folder to store the generated env file(s)

> cdf-cli generate-local-config <environment> <region> <output-folder>

The .env file for each of the deployed modules will be generated in the output-folder.

Each generated .env file contains instructions on how to start the module locally.