Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

AWS Deployment with CLI

High-Level Architecture Overview

This section provides a conceptual overview of how the BlueRock instance is deployed on AWS EC2 and how its core components interact.

End-to-End Flow

Deployment scripts are executed from a user's desktop or client environment where AWS CLI is configured. The script uses AWS APIs to provision the required AWS Resources and deploy the BlueRock instance.

BlueRock EC2 Architecture Components

Architecture Diagram

BlueRock EC2 Architecture Components

A typical BlueRock Secure MCP Server EC2 deployment consists of the following AWS Resources/Services:

AWS Resources/Services
Description

Virtual Private Cloud (VPC)

Provides an isolated networking environment in AWS where all BlueRock deployment resources are created.

Amazon VPC Gateway

Enables controlled inbound and outbound internet access for resources deployed inside the VPC.

Amazon EC2 (BlueRock Instance)

Runs the BlueRock MCP Server using a hardened BlueRock AMI and hosts all runtime services.

Amazon Elastic Block Store (EBS)

Provides persistent block storage attached to the EC2 instance for operating system and application data.

Amazon S3 (BlueRock Config)

Stores BlueRock configuration files such as config.toml that are retrieved by the BlueRock control plane during runtime.

AWS Identity and Access Management (IAM) Role

Grants the EC2 instance permission to access required AWS services such as Amazon S3 and Amazon CloudWatch.

Amazon CloudWatch Logs

Stores runtime logs and security events generated by the BlueRock MCP Server for analysis and auditing.

User / Administrator

Manages and monitors the BlueRock deployment through AWS services such as CloudWatch and AWS Systems Manager (SSM).

Deployment types

BlueRock EC2 deployments support multiple deployment modes depending on networking and telemetry requirements:

Private

Deploys a single BlueRock EC2 instance into a private subnet, with outbound access via a NAT Gateway and management access enabled through AWS Systems Manager (SSM).

Public

Deploys a single BlueRock EC2 instance into a public subnet, allowing management access through SSH (if configured) and AWS Systems Manager (SSM).

Supported AMI Distributions

BlueRock Secure MCP Server supports the following Linux distributions. Each distribution has a corresponding AMI with a specific kernel version:

Name

Kernel Version

AMI NAME

Amazon Linux 2023

6.12.89

bluerock-release-26-23-1-amzlnx2023-6.12.89

Ubuntu 24.04

6.12.89

bluerock-release-26-23-1-ubuntu2404-6.12.89

notes-sticky

Note:

The AMI name includes the BlueRock release version, Linux distribution, and Kernel version, allowing users to identify compatibility directly from the AMI name

Prerequisites

AWS Requirements

Deployment Workflow Overview

  1. Phase 1: AWS Infrastructure Provisioning (Local Client / AWS CLI)

    1. Create the IAM Role and Instance Profile

      1. Create the Trust Policy

      2. Create the Role

    2. Create the S3 Bucket

      1. Attach AWS Managed Policies

      2. Create and Attach the Custom Policy with Minimal Permissions

      3. Create and Link the Instance Profile

    3. Launch the EC2 Instance

      1. Check Instance Access

        1. SSH Access

        2. SSM Access

  2. Phase 2: BlueRock Instance Setup

    1. Policy Creation and Upload to S3 Bucket

      1. Create Policy

      2. Required Policy Artifacts

      3. Upload Files to S3

    2. OTEL Configuration

    3. BlueRock Instance Configuration

      1. Verify bluerockd operation

  3. Phase 3: Logs in CloudWatch and Troubleshooting

    1. View Logs in AWS CloudWatch

    2. Troubleshooting

      1. Review bluerockd logs

      2. OpenTelemetry Connectivity Verification

      3. Verify BlueRock Kernel Sensor Service

      4. Verify BlueRock Kernel Sensor Logs

      5. Verify Runtime Artifacts (BlueRock Sensor Socket)

      6. Inspect Local OTEL Event Logs

      7. Check otelcol.service logs

Create the IAM Role and Instance Profile

Configure an IAM Role for the EC2 instance with least-privilege permissions tailored to each service requirement:

  • Amazon S3 Access: Grants permissions to upload and download policy configuration files, public keys, digital signatures, and checksum files to and from the target S3 bucket.

  • Amazon CloudWatch Logging: Grants permission to push OTEL log events to CloudWatch Log Streams for central monitoring and visualization.

  • AWS Systems Manager (SSM) Management: Enables core agent capabilities for remote management, administration, and patching of the BlueRock VM instance.

  • Amazon EC2 Read Access: Grants read-only access to query instance metadata, subnets, and security groups required by the BlueRock VM.

Create the Trust Policy

Create a local file named ec2-trust-policy.json :

Create the Role

Execute the following command to create the IAM role:

Expected Command Output:

Create the S3 Bucket

Create a globally unique S3 bucket to store the BlueRock Instance policies:

Attach AWS Managed Policies

Attach the required AWS-managed policies for EC2 read access, CloudWatch telemetry, and Systems Manager (SSM) core agent support:

  • AmazonEC2ReadOnlyAccess: Grants read-only access to query EC2 infrastructure details, subnets, and security groups.

  • CloudWatchAgentServerPolicy: Grants permission to collect and push OTEL telemetry logs to Amazon CloudWatch.

  • AmazonSSMManagedInstanceCore: Enables core agent capabilities for remote instance management and administration via Systems Manager.

Create and Attach the Custom Policy with Minimal Permissions

Create a local file named bluerock-installer-policy.json containing the explicit minimal permissions for S3 policy objects and log stream events:

Execute the commands to create the custom policy and attach it to the role:

Create and Link the Instance Profile

Create the instance profile and link the IAM role:

Expected Command Output:

Launch the EC2 Instance

Launch the EC2 instance using the target AMI and attach the IAM Instance Profile created previously:

notes-sticky

Note:

  • Ensure that the specified --security-group-ids and --subnet-id belong to the same VPC prior to execution.

  • To locate the shared AMI ID in the target account, run:

  • If Subnet or Security Group IDs are already known, skip retrieving infrastructure details; otherwise, run the following CLI commands for your region:

    • Subnets:

    • Security Groups:

Parameter Table:

Parameter
Type
Description

--image-id

Required

Target region Amazon Machine Image (AMI) ID (e.g., ami-<00xxx00xx>).

--instance-type

Required

Hardware configuration size for the EC2 instance (e.g., t3.large).

--key-name

Required

SSH Key Pair identifier created in the target region (e.g., <key-name>)

--security-group-ids

Required

VPC Security Group ID regulating inbound and outbound network access rules (e.g., sg-<00xxx00xx>).

--subnet-id

Required

Specific Subnet and Availability Zone ID where the instance is deployed (e.g., subnet-<00xxx00xx>).

--iam-instance-profile

Required

IAM Instance Profile name granting S3 and CloudWatch access to the instance (e.g., <InstanceProfileName>).

--block-device-mappings

Required

Storage volume configurations specifying a 40GB gp3 root volume.

--tag-specifications

Required

Resource identification tags in key-value format (e.g., Name=<EC2Username>).

--region

Required

Target AWS Region code where infrastructure is hosted (e.g., <region-code>).

--count

Optional

Number of identical instances to launch simultaneously (Default: 1).

--associate-public-ip-address

Optional

Flag to automatically assign a public IP address.

--user-data

Optional

Path to a bootstrapping script executed automatically upon instance boot.

--ebs-optimized

Optional

Flag enabling dedicated EBS throughput for high performance.

--instance-initiated-shutdown-behavior

Optional

Action taken when OS-level shutdown is initiated (stop or terminate).

Check Instance Access

SSH Access (Public Deployment)

Check instance access to confirm SSH connectivity for public deployments by running the appropriate command for the selected AMI:

SSM Access (Private Deployments)

For instances deployed in a private subnet without a public IP address, establish an interactive shell session using AWS Systems Manager (SSM) Session Manager.

Important:

  • The AWS Systems Manager Session Manager plugin must be installed on the local machine.

  • The EC2 instance must have the AmazonSSMManagedInstanceCore policy attached via its IAM Instance Profile.

Connect via AWS CLI

Start a session using the EC2 Instance ID:

Policy Creation and Upload to S3 Bucket

Create Policy

Policy artifacts must be generated, signed, and uploaded to the target Amazon S3 bucket prior to starting or updating the service daemon. The BlueRock instance uses the TREX tool that resides at /opt/bluerock/trex to generate a signed policy blob (.tar), extract the signed files, and verify digital signatures during startup.

For detailed instructions on generating public keys, configuring trex.toml, and building policy templates, refer to the Policy Builder documentation.

Required Policy Package Artifacts

File

Purpose

policy.json

The core JSON policy file containing the defined enforcement rules.

policy.json.sha256

The cryptographic hash file used to verify JSON integrity.

policy.json.sig

The digital signature file used to authenticate the policy file.

dynpol_pubkey.pem

The public key certificate used by the daemon to validate the policy signature.

Upload Policy Files to S3

Copy the policy package artifacts to the configured S3 bucket path:

notes-sticky

Note:

Ensure file names and bucket paths match the target locations specified in the BlueRock Instance Configuration section. The private key used for signing policy files must never be uploaded to S3.

OTEL Configuration

Configure the OTEL Collector to capture runtime telemetry and log events from bluerockd and route them to Amazon CloudWatch Logs for centralized monitoring and auditing. The default configuration file resides at /opt/bluerock/otel with file name otel-config.yaml, includes standard OTLP HTTP receivers and batch processors. Only the exporters section requires modification to establish the target CloudWatch Logs integration.

Locate the OTEL config file:

Modify the exporters block in otel-config.yaml to specify the CloudWatch Log Group, Log Stream, and regional API endpoint:

Configuration Parameters Table

Parameter
Section
Description

exporters.debug.verbosity

Exporter Config

Detail level of debug output generated by the collector (basic, normal, or detailed).

exporters.awscloudwatchlogs.log_group_name

Exporter Config

Target Amazon CloudWatch Log Group name where log events are published.

exporters.awscloudwatchlogs.log_stream_name

Exporter Config

Specific Amazon CloudWatch Log Stream name within the log group.

exporters.awscloudwatchlogs.region

Exporter Config

AWS Region code hosting the CloudWatch Logs endpoint (e.g., <Region>).

exporters.awscloudwatchlogs.endpoint

Exporter Config

Regional CloudWatch Logs API endpoint URL (e.g., https://logs.<Region>.amazonaws.com).

Enable the OTel service:

Start the otel service:

Check the status of the OTel service:

Expected output:

BlueRock Instance Configuration

BlueRock instances have a configuration file bluerockd.toml to define telemetry and policy settings that reside at /etc/bluerock/.

notes-sticky

Note:

The <internal_ip> placeholder specifies the local private IP address of the EC2 instance. This local address is used because the OTEL Collector service otelcol.service runs locally on the BlueRock instance.

Parameter

Type

Description

metrics_timer

Integer

How often (in seconds) the agent pushes its performance metrics (e.g., 1800 = 30 minutes).

state_dir

Path / String

The local directory path where the agent (bluerockd) stores its internal state data.

policy.public_key

S3 Path

The Amazon S3 bucket location of the public key used to validate the policy signature file (.pem format).

policy.poll_period

Integer

How often (in seconds) the agent checks the source location for a new policy version (e.g., 300 = 5 minutes).

policy.source.location

S3 Path

The base Amazon S3 bucket path where the policy-related files are hosted.

policy.source.policy

File Name

The specific JSON file name containing the agent's configuration rules.

policy.source.policy_sig

File Name

The digital signature file used to verify that the core policy JSON file hasn't been tampered with.

policy.source.transport.auth_method

String

The authentication strategy used to access files. Setting it to default utilizes the EC2 instance's attached IAM Role / Instance Profile.

policy.source.transport.region

String

The Amazon Web Services (AWS) region where the storage resources are located (e.g., us-east-1).

policy.engine.augment_events

Boolean

Determines whether the policy engine should enrich or add additional metadata/context to the captured events (true or false).

otlp.file

Path / String

The local file path where OpenTelemetry log events are written.

otlp.http.url

URL

The local or internal HTTP endpoint (usually an OTLP/HTTP receiver or collector) where telemetry data is forwarded.

After editing bluerockd.toml, restart the bluerockd.service:

Verify bluerockd operation

Verify the operational status and log output of the bluerockd service after modifying /etc/bluerock/bluerockd.toml and restarting the service.

Expected output:

Check bluerockd Journal logs

Check bluerockd journal logs to confirm that policy files loaded successfully from the target S3 bucket location:

Expected output:

  • Once the configured policies are loaded:

  • IAM and other credential validation in bluerockd logs:

View Logs in AWS CloudWatch

Check CloudWatch logs:

  1. Navigate to the CloudWatch Console

  1. Go to Log Groups

  1. Find the BlueRock Log Group

  1. Verify:

  • Log entries are present

  • Events originate from the EC2 instance

  • Timestamps align with instance startup activity

Troubleshooting

Execute the following diagnostic checks on the local Amazon EC2 instance to resolve failed event processing or missing Amazon CloudWatch telemetry data.

Review bluerockd Logs

Review the bluerockd logs to identify failed OpenTelemetry (OTEL) event publishes: Bash

Expected error log indicating a failed publish:

OpenTelemetry Connectivity Verification

If the bluerockd logs indicate a connection error to the OpenTelemetry endpoint, verify network reachability to the collector.

Execute the following command from the BlueRock Instance:

Review the command output to determine the next action:

  • Connection established: Investigate the OpenTelemetry collector configuration files to resolve the export failure.

  • Connection failed: Verify the OpenTelemetry endpoint IP address configuration within the /etc/bluerock/bluerockd.toml file.

Verify BlueRock Kernel Sensor Service

Verify the operational status of the BlueRock Kernel Sensor service to ensure the activation of the underlying driver:

Expected Output:

Verify BlueRock Kernel Sensor Logs

Review the BlueRock Kernel Sensor logs:

Expected output:

Runtime Artifacts (BlueRock Sensor Socket)

Confirm the presence of the communication BlueRock Sensor Socket file in the runtime directory:

Expected output:

Local OTEL Event Logs

List the log directory contents to confirm the generation of local OTEL event and metric logs:

Expected output:

OpenTelemetry Collector Logs

Verify the otelcol journal logs to confirm collector initialization and the active exportation of log events to Amazon CloudWatch Logs:

Expected output:Plaintext

PreviousAWS Deployments
NextAWS Deployment Using Terraform Template

Last updated