How to implement BlueArch Update Engine in your AWS account (v0.0.5)

Subscribe to the BlueArch Update Engine in AWS Marketplace

  1. Logged in the account you want to deploy the BlueArch Update Engine, open the marketplace product url in your browser;
  2. Click on the Continue to Subscribe button;
  3. Click on the Accept Offer button;
  4. Click on the Continue to Configuration button;
  5. On the Fullfillment Option, select the Deploy StepFunctions State Machine option, select the latest version then click on the Continue to Launch button;
  6. Follow the instructions to deploy the product.

Usage Instructions

Pull the ECR Marketplace Image then push it to your ECR Repository:

ensure you have the following permissions:

- ecr:GetAuthorizationToken
- ecr:BatchCheckLayerAvailability
- ecr:GetDownloadUrlForLayer
- ecr:BatchGetImage
- ecr:CreateRepository
- ecr:PutImage
- ecr:InitiateLayerUpload
- ecr:UploadLayerPart
- ecr:CompleteLayerUpload
  1. Then open CloudShell (recommended) in the desired account/region or a authenticated terminal with the AWS CLI and Docker installed;
  2. Run the following commands to pull the ECR Marketplace Image:
export ACCOUNT_ID=YOUR_ACCOUNT_ID
export CURRENT_REGION=CURRENT_REGION

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com/bluearch-io/bluearch_update_engine

docker pull 709825985650.dkr.ecr.us-east-1.amazonaws.com/bluearch-io/bluearch_update_engine:v0.0.5
  1. Create the BlueArch Update Engine ECR Repository in your account (If you already have it, skip this step):
aws ecr create-repository --repository-name bluearch-io/bluearch_update_engine
  1. Push the ECR Marketplace Image to your ECR Repository:
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $ACCOUNT_ID.dkr.ecr.$CURRENT_REGION.amazonaws.com

docker tag 709825985650.dkr.ecr.us-east-1.amazonaws.com/bluearch-io/bluearch_update_engine:v0.0.5 $ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/bluearch-io/bluearch_update_engine:v0.0.5

docker push $ACCOUNT_ID.dkr.ecr.$CURRENT_REGION.amazonaws.com/bluearch-io/bluearch_update_engine:v0.0.5

Choose one of the following options to deploy the BlueArch Update Engine:

1- Single AWS Account deployment using CloudFormation + Step Functions

  1. Open the Single Account Cloudformation link in your browser;
  2. Fill in the parameters mentioned in the next section and click Next.
  3. Click Next again.
  4. Check the box I acknowledge that AWS CloudFormation might create IAM resources and click Create stack.
  5. Wait for the stack to be created.

2- Organization level deployment (Manager Account) using CloudFormation StackSet + Step Functions

  1. Open the Org Level Cloudformation link in your browser;
  2. If you do not have Trusted Access with AWS Organizations to use service-managed permissions (Doc reference), this banner will appear: Trusted Access with AWS Organizations
  3. Select Activate trusted access. Trusted access is successfully activated when the following banner displays: Trusted Access with AWS Organizations
  4. Fill in the parameters mentioned in the next section and click Next.
  5. Click Next again.
  6. Check the box I acknowledge that AWS CloudFormation might create IAM resources and click Create stack.
  7. Wait for the stack to be created.

CloudFormation Parameters

Organization Parameters

Update Engine General Configuration

Step Functions Configurations

Architectural Diagram

BlueArch Update Engine Architectural Diagram.

Resources Created by the CloudFormation StackSet

Resource Description
S3ReportBucket The S3 Bucket where Update Engine will store its Excel report files.
LambdaRole IAM Role that allows the application to interact with the Update Engine resources inside the current account.
StepFunctionsExecutionRole IAM Role that allows AWS Step Functions to interact with the Lambda Function.
EmailSNSTopic AWS SNS Topic - The application will send the excel report file through this topic everytime it runs all emails inside the EMailList Parameter.
CrossAccountAccessRoleForBlueArch IAM Role that allows the application to assume it and collect the necessary data for the application to work.
BlueArchRoleStackSet CloudFormation Stackset that will deploy the CrossAccountAccessRoleForBlueArch in all accounts inside the organization. More information about StackSets.
DynamoDBTable DynamoDB table that will store AWS resource information’s (id, account, region, resource type) and the SSM SafeLock token.
Lambda Lambda function that will be triggered by the Step Functions State Machine.
SafeLockSSMParameter The SSM Parameter the user will use to put the Safe Lock Token.
UpdateEngineStateMachine The Step Functions State Machine that will orchestrate the application.
CronEventRule The CloudWatch Rule that will trigger the Step Functions State Machine in a weekly basis

AWS price estimation

BlueArch Update Engine Price Estimation.

Click here to check the full details pricing estimations based on the Default values (typical deployment).

The Application

How to start the application

  1. Check your inbox, you should have received an email with the sns topic confirmation link. Click on it to confirm your subscription.
  2. Start the Step Functions State Machine execution by searching for Step Functions in the AWS Console, clicking on it, and then clicking on the bluearch-update-engine state machine. Click on the Start Execution button and then click on the Start Execution button again.
  3. Now you should have received a new email with the Excel report file URL. Click on it to download the file and check the resources that are going to be updated. You should also be able to find the user instruction showing how to unlock the SSM Safe Lock . BlueArch Update Engine Report Email .
  4. Once you have unlocked the SSM Safe Lock, the application will be able to execute all updates that are listed in the Excel report file.

How the Application Works

Update Engine scans the Organization that is set in the CloudFormation Parameters, collect resources details, stores them in DynamoDB Table, processes the collected information, and sends the Excel report file and the SSM SafeLock token to the emails listed in the Email list parameter. Once the SSM SafeLock is unlocked, the application will be able to execute all updates that are listed in the Excel report file.

Table of Steps

Step Description
CleanUp Starts the process by cleaning up the DynamoDB table.
GeneratePayloads Generates payloads containing Account id, Resource type and ids, for individual processing in the next steps.
DistributePayloads Distributes payloads for parallel processing.
ScanAndPersistIndividualPayload Processes individual payloads and stores the results in DynamoDB (Read Only step).
CreateReportAndSendToEmail Creates and emails a excel report file based on stored data, along with the SSM SafeLock token and instructions showing how to use it.
WaitForHumanInteraction Pauses for human interaction or input.
CheckSSMSafeLock Checks a condition or lock in AWS SSM.
Job Complete? Decides the next step based on SSM SafeLock status.
GeneratePayloadsFromDynamo Generates payloads from DynamoDB table for parallel processing.
ExecuteWorkers Map state that will generate payloads based on the DynamoDB items and execute the workers.
ProcessIndividualPayload Processes DynamoDB payloads in parallel.

Step Functions Graph

BlueArch Update Engine StepFunctions Graph.

Customer Information Disclaimer

BlueArch Update Engine data security and privacy are paramount. We want to provide you with a clear understanding of how we handle your customer information:

How to monitor the application

Check the State Machine Execution

  1. Navigate to the AWS Console, search for Step Functions, and click on it.
  2. Look for the bluearch-update-engine state machine.
  3. Click on the state machine name to see the previous executions.
  4. Then click on the execution id to see the execution details.
  5. You can see the execution details, input, output, and logs.
  6. You can also see the state machine graph and the state machine logs.

Checking the Logs

  1. Navigate to the AWS Console, search for Step Functions, and click on it.
  2. Look for the bluearch-update-engine state machine.
  3. Clock the log group link in the state machine details. State Machine Logs

How to remove everything

  1. Empty the S3 bucket created by the CloudFormation StackSet:
    1. Navigate to the AWS Console, search for S3, and click on it.
    2. Click on the bluearchio-update-engine bucket.
    3. Click on the Empty button.
    4. Type permanently delete in the confirmation box and click Empty.
  2. Delete the Cloudformation Stack you created:
    1. Navigate to the AWS Console, search for CloudFormation, and click on it.
    2. Under Stack section, click on the BlueArch Update Engine you’ve created before.
    3. Click on the Delete button.
    4. Wait for the stack to be deleted.

Supported Resources in the Current Version (v0.0.5):

EC2 Instances

EBS