Skip to content

Latest commit

 

History

History
111 lines (69 loc) · 6.48 KB

deployment.md

File metadata and controls

111 lines (69 loc) · 6.48 KB
Raw

Deployment

Deployments Steps

Before attempting an upgrade, read release notes and migration notes to verify changes.

Prerequisites

Install tools

Ensure that all development and deployment prerequisites are installed on your deployment machine. This is a one-time setup to configure an environment for development and/or deployment.

AWS CLI 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. Create Named profile for IAM credential: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html

Backup and migrate existing data

If migrating from an existing to a more recent CDF release, the following items should be considered as a prerequisite:

  • Take manual snapshots if you wish to retain the data of your Neptune database
  • Migrate existing DynamoDB table data using the dynamodb-migrator tool

Refer to the migration document for more detailed and step-by-step instructions on migration between major changes!

Other Prerequisites

  • S3 Bucket for CDF resources
  • S3 Bucket for CloudFormation resources (can be the same as above)
  • Chosen REST API authentication mechanism (see below)

Configure REST API authentication

Due to the myriad number of ways authentication may be configured for REST APIS's, CDF has taken the approach of externalizing the REST API security as CloudFormation template snippets which can be used as is, or modified to suit specific customer needs.

The provided authentication options are as follows:

Authentication Type Cloudformation Template Snippet Name
No authentication cfn-apiGateway-noAuth.yaml
API Key cfn-apiGateway-apiKeyAuth.yaml
IAM cfn-apiGateway-iamAuth.yaml
Lambda request authorizer cfn-apiGateway-lambdaRequestAuth.yaml
Lambda token authorizer cfn-apiGateway-lambdaTokenAuth.yaml
Private API gateway cfn-apiGateway-privateApi.yaml

The template snippets are located at {aws-connected-device-framework}/source/infrastructure/cloudformation/snippets/, which are uploaded to an S3 bucket as part of the aws-connected-device-framework deployment script.

The name of the specific CloudFormation template snippet to define which authentication mechanism to use, including the no authentication (cfn-apiGateway-noAuth.yaml) template snippet if none is required, must be provided to the installer module as part of the deployment.

If you need to customize the authentication configuration, the recommendation is to copy one of the provided ones as a base, customize as required, then upload it to the configured S3 bucket as part of your deployment script.

If an authentication mechanism is applied to the CDF REST API's, a security perimeter comes into effect around all the core CDF modules. A caller's credentials are validated upon the first entry point into the security boundary for a given request, with all following internal module to module calls for the same request bypassing additional authentication checks. This is made possible by the provided clients for each of the REST API's (see {aws-connected-device-framework}/source/packages/libraries/clients/) that the core CDF modules use for inter-module communication. They can be configured to call their associated REST API by invoking API Gateway, thus requiring to be authorized, or instead invoking the corresponding CDF core's lambda directly thus bypassing any authentication checks. These clients may be reused within your own custom modules to expand the CDF security perimeter to include your custom modules too.

Deploying the project

Deploying from pre-bundled releases

Each github release comes with a pre-bundled release artifact that can be used to simplify the deployment.

Download the latest release tar files from here

Run below step in the folder where you downloaded the tar file:

mkdir aws-connected-device-framework
tar -xvf aws-connected-device-framework.tar -C aws-connected-device-framework
cd aws-connected-device-framework/source
aws-connected-device-framework> rush update

You can now skip to the Deploying step

Deploying from source

Alternatively you can choose to clone the source code to build and bundle them yourself.

All the commands below should be run inside the source folder

aws-connected-device-framework> cd source

Bundling

To build and bundle the modules, run the following command:

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

Deploying

After all the artifacts are bundled, you can use the installer module to deploy the required DF modules.

> cdf-cli deploy <environment> <region>

Additional Information

Existing VPC

If you're not specifying any existing networking information (Vpc Id, Subnets, etc) as part of the deploy step, a new VPC and necessary networking resources will be created, detailed information of the networking resources can be found here

Customer provided KMS Key

KMS will be created with the default key policy, this default key policy has one policy statement that gives the AWS account (root user) that owns the CMK full access to the CMK and enables IAM policies in the account to allow access to the CMK.

This will allow IAM policies to control access to the CMK, below is the explanation from the documentation

Every CMK must have a key policy. You can also use IAM policies to control access to a CMK, but only if the key policy allows it. If the key policy doesn't allow it, IAM policies that attempt to control access to a CMK are ineffective.

To allow IAM policies to control access to a CMK, the key policy must include a policy statement that gives the AWS account full access to the CMK, like the following one. For more information, see Managing access to AWS KMS CMKs.