# 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. ```shell 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 ```shell 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: ```shell > cdf-cli deploy -b -p ``` | 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///`, `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 | ```shell > cdf-cli deploy -c -b -p ``` 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 | ```shell > cdf-cli package -b -p ``` 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 -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](../../../infrastructure/cloudformation/cfn-eventbus.yaml) | None | None | | | `VPC` | [cfn-networking.template](../../../infrastructure/cloudformation/cfn-networking.yaml) | None | None | You can use existing VPC and not use the one provided by this repository | | `OpenSSL Lambda Layer` | [cfn-openssl-layer.template](../../../infrastructure/lambdaLayers/openssl/infrastructure/cfn-openssl-layer.yml) | None | None | | | `Deployment Helper` | [cfn-deployment-helper.template](../../libraries/core/deployment-helper/infrastructure/cfn-deployment-helper.yaml) | None | None | | | `Deployment Helper VPC` | [cfn-deployment-helper-vpc.template](../../libraries/core/deployment-helper/infrastructure/cfn-deployment-helper-vpc.yaml) | `VPC` | None | This deployment helper lambda can queries resources inside VPC (e.g. NeptuneDB version) | | `Auth (by Device Cert)` | [cfn-auth-devicecert.template](../auth-devicecert/infrastructure/cfn-auth-devicecert.yaml) | `KMS`
`OpenSSL Lambda Layer` | None | | | `Greengrass 2 Installer Config Generators` | [cfn-greengrass2-installer-config-generators.template](../greengrass2-installer-config-generators/infrastructure/cfn-greengrass2-installer-config-generators.yml) | `Deployment Helper` | None | | | `Asset Library Neptune` | [cfn-neptune.template](../assetlibrary/infrastructure/cfn-neptune.yaml) | `VPC`
`Deployment Helper VPC` | None | This stack is required if you're running `Asset Library` in **full** mode | | `Asset Library Service` | [cfn-assetlibrary.template](../assetlibrary/infrastructure/cfn-assetLibrary.yaml) | `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](../assetlibraryhistory/infrastructure/cfn-assetLibraryHistory.yml) | `KMS`
`Asset Library Service` | `VPC` | `VPC` is only needed when you need to run API Gateway in **private** mode | | `Bulk Certificates` | [cfn-bulkcerts.template](../bulkcerts/infrastructure/cfn-bulkcerts.yml) | `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](../device-patcher/infrastructure/cfn-device-patcher.yml) | `KMS` | `VPC` | `VPC` is only needed when you need to run API Gateway in **private** mode | | `Events Processor` | [cfn-eventsProcessor.template](../events-processor/infrastructure/cfn-eventsProcessor.yml) | `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](../events-alerts/infrastructure/cfn-eventsAlerts.yml) | `KMS`
`Events Processor` | `VPC` | `VPC` is only needed when you need to run API Gateway in **private** mode | | `Provisioning` | [cfn-provisioning.template](../provisioning/infrastructure/cfn-provisioning.yml) | `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](../assetlibrary-export/infrastructure/cfn-assetlibrary-export.yaml) | `KMS`
`Asset Library [Neptune]` | `VPC` | `VPC` is only needed when you need to run API Gateway in **private** mode | | `Certificate Activator` | [cfn-certificateactivator.template](../certificateactivator/infrastructure/cfn-certificateactivator.yml) | `KMS`
`Asset Library Service`
`Provisioning`
`OpenSSL Lambda Layer`
| None | | | `Commands` | [cfn-commands.template](../commands/infrastructure/cfn-commands.yml) | `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](../command-and-control/infrastructure/cfn-command-and-control.yml) | `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](../device-monitoring/infrastructure/cfn-device-monitoring.yml) | `Asset Library Service` | None | | | `Simulation Launcher` | [cfn-simulation-launcher.template](../simulation-launcher/infrastructure/cfn-simulation-launcher.yaml) | `VPC`
`Deployment Helper` | None | | | `Simuation Manager` | [cfn-simulation-manager.template](../simulation-manager/infrastructure/cfn-simulation-manager.yml) | `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](../greengrass2-provisioning/infrastructure/cfn-greengrass2-provisioning.yml) | `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](../certificatevendor/infrastructure/cfn-certificatevendor.yml) | `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 | ```shell > cdf-cli delete ``` ### Generating Postman environment file This retrieves the urls for all the CDF modules that expose a REST API endpoint and prints out an [environment](https://learning.postman.com/docs/sending-requests/managing-environments/#creating-environments) json file that can be imported into [Postman](https://www.postman.com/product/rest-client/). | Argument | Description | | ------------- | --------------------------- | | `name` | name of Postman environment | | `environment` | the environment to deploy | | `region` | the region to deploy into | ```shell > cdf-cli postman ``` ### 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) | ```shell > cdf-cli cloud-to-env ``` 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.