> For the complete documentation index, see [llms.txt](https://docs.bluerock.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bluerock.io/deployment-guides/aws-deployments/aws-deployment-with-cloud-formation-template.md).

# AWS Deployment with Cloud Formation Template

### High-Level Architecture Overview

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

#### End-to-End Flow

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

#### BlueRock EC2 Deployment Architecture

#### Architecture Diagram

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FCBxTsMZSokxpmIDxhtTI%2FChatGPT%20Image%20Feb%203%2C%202026%2C%2003_18_20%20PM.png?alt=media&amp;token=e323464a-4711-4a05-9678-3dcc0d692e9e" alt=""><figcaption></figcaption></figure>

#### **BlueRock EC2 Architecture Components**

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

<table data-search="false"><thead><tr><th width="316.65625">AWS Resources/Services</th><th>Description</th></tr></thead><tbody><tr><td><strong>Virtual Private Cloud (VPC)</strong></td><td>Provides an isolated networking environment in AWS where all BlueRock deployment resources are created.</td></tr><tr><td><strong>Amazon VPC Gateway</strong></td><td>Enables controlled inbound and outbound internet access for resources deployed inside the VPC.</td></tr><tr><td><strong>Amazon EC2 (BlueRock Node)</strong></td><td>Runs the BlueRock MCP Server using a hardened BlueRock AMI and hosts all runtime services.</td></tr><tr><td><strong>Amazon Elastic Block Store (EBS)</strong></td><td>Provides persistent block storage attached to the EC2 instance for operating system and application data.</td></tr><tr><td><strong>Amazon S3 (BlueRock Config)</strong></td><td>Stores BlueRock configuration files such as <code>bluerockd.toml</code> that are retrieved by the BlueRock control plane during runtime.</td></tr><tr><td><strong>AWS Identity and Access Management (IAM) Role</strong></td><td>Grants the EC2 instance permission to access required AWS services such as Amazon S3 and Amazon CloudWatch.</td></tr><tr><td><strong>Amazon CloudWatch</strong></td><td>Receives telemetry and monitoring data generated by the BlueRock MCP Server.</td></tr><tr><td><strong>Amazon CloudWatch Logs</strong></td><td>Stores runtime logs and security events generated by the BlueRock MCP Server for analysis and auditing.</td></tr><tr><td><strong>User / Administrator</strong></td><td>Manages and monitors the BlueRock deployment through AWS services such as CloudWatch and AWS Systems Manager (SSM).</td></tr></tbody></table>

***

### Supported AMI Distributions

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

<table data-header-hidden><thead><tr><th width="179.46484375">Name</th><th width="152.1328125">Kernel Version</th><th>AMI Name</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td><strong>Kernel Version</strong></td><td><strong>AMI Name</strong></td></tr><tr><td>Amazon Linux 2023</td><td>6.12.89</td><td>bluerock-release-26-23-1-amzlnx2023-6.12.89</td></tr><tr><td>Ubuntu 24.04</td><td>6.12.89</td><td>bluerock-release-26-23-1-ubuntu2404-6.12.89</td></tr></tbody></table>

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

* Active AWS account
* API key credentials configured in the local environment
* AWS CLI should be installed, and key credentials should be configured

#### Required Packages

The BlueRock Deployment Package for EC2 is provided by BlueRock as part of customer onboarding. This package includes AWS CloudFormation templates required to deploy the BlueRock Secure MCP Server on AWS EC2.

**AWS CLI installation and configuration guide:**\
[AWS-CLI-Installation-Config-Guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)

```shellscript
## AWS CLI uses credentials stored in the following file:
$ ~/.aws/credentials

## If the .aws directory does not exist, create it using:
$ mkdir -p ~/.aws

## Create or edit the credentials file:
$ ~/.aws/credentials

## Add the following entries:
AWS_ACCESS_KEY_ID=[your_access_key]
AWS_SECRET_ACCESS_KEY=[your_secret_key]
AWS_SESSION_TOKEN=[your_session_token]
```

#### Obtaining AWS Access Keys

Access keys can be generated from the AWS Management Console.

1. Navigate to the **AWS Management Console**
2. Open **IAM**
3. Go to **Users**
4. Select your user account
5. Open the **Security credentials** tab
6. Under **Access keys**, choose **Create access key**

Copy the **Access Key ID** and **Secret Access Key** into the credentials file shown above.

#### **AWS Permissions Required**

**User permissions:** The user executing the deployment script requires permissions to create the following AWS resources:

* VPC, Subnets, Internet Gateway, Route Tables
* EC2 instance
* Security Group
* IAM Profile
* S3 bucket

**Note:** The IAM instance profile required for the BlueRock instance is automatically created by the deployment script.&#x20;

***

### Deployment Package Overview

#### Download and Extract Package

Download the BlueRock deployment package (bluerock-cloudformation-ec2) and extract it in your local environment. It contains AWS CloudFormation templates required to deploy the BlueRock Secure MCP Server on AWS EC2.

```shellscript
Download the package:
bluerock_rel25500_deploy_script.tar.gz

Extract the package:
tar -xzf bluerock_rel25500_deploy_script.tar.gz

Verify extraction:
ls -l

Output:
bluerock_rel25500_deploy_script/
```

**Note:**

On macOS, the tar command may display the warning:

```shellscript
tar: Ignoring unknown extended header keyword 'LIBARCHIVE.xattr.com.apple.quarantine'
```

This warning is expected and can be safely ignored.

\
**Directory Structure**

After extracting the CloudFormation deployment package, the directory structure contains AWS CloudFormation templates and parameter files for different EC2 deployment modes.

```
bluerock_rel25500_deploy_script/
└── cloudformation/
    └── ec2/
        ├── README.md
        ├── al2023/
        │   ├── bluerock-bru-aws-ec2-template.yaml
        │   └── parameters.json
        ├── ubuntu2404/
            ├── bluerock-bru-aws-ec2-template.yaml
            └── parameters.json 
```

***

### CloudFormation Deployment

#### Configuration Parameters

The CloudFormation deployment uses a predefined set of parameters to control networking, instance configuration, and telemetry settings.

Parameters can be provided in either of the following ways:

* Through a **JSON parameters file**
* Directly via the **AWS CloudFormation Console**

#### Deployment using AWS Web Console

1. Navigate to the **AWS CloudFormation Console**
2. Click **Create Stack** → With new resources (standard).

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FWlatrJBoDi5WqkKStZgu%2FScreenshot%202026-02-05%20at%202.43.09%E2%80%AFPM.png?alt=media&amp;token=fc13443f-5346-4dc2-bb0e-95f4ccb1d67c" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2F9TnUut93SpsDJMtvLKC4%2F1%20new.tiff?alt=media&amp;token=56117b99-3e75-494d-8eb7-96162745d365" alt=""><figcaption></figcaption></figure>

3. Upload the CloudFormation template

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2Fn5rUdkwlOAYGZ6SWBiwG%2FScreenshot%202026-02-03%20at%205.09.30%E2%80%AFPM.png?alt=media&amp;token=b0f2252c-e459-4d65-8030-874fb8b1bae3" alt=""><figcaption></figcaption></figure>

4. Configure parameters

**Parameters List:**

```shellscript
AllowIp
Public IP address allowed to access the instance via SSH.
Example: 101.0.62.104/32

NodeInstanceType
Instance type used for BlueRock worker node.
Example: t3.xlarge

Prefix
Prefix used for AWS resource names.

SshKeyName
Name of an existing EC2 key pair.

AmiId
AMI ID for the BlueRock Secure MCP Server image.
Example: ami-0251e1dd3708aab50

ExistingVpcId (Optional)
Existing VPC ID for deployment.

ExistingSubnetId (Optional)
Existing subnet ID for deployment.
```

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FNkcIZdUd0FcXp1vigysS%2FScreenshot%202026-02-09%20at%201.05.44%E2%80%AFPM.png?alt=media&amp;token=e7348184-70b1-43e9-ad05-2e88893bcb13" alt=""><figcaption></figcaption></figure>

4. Configure Stack Options

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FFSNtDyLFM08n7vtJMFCX%2FScreenshot%20from%202026-03-09%2017-30-37.png?alt=media&amp;token=a10d8e1b-edb5-4281-a0ed-8f7684ec515a" alt=""><figcaption></figcaption></figure>

4. Review and create stack

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FXkC1Xxfvk9vNiQBDLQoE%2FScreenshot%202026-02-09%20at%201.20.57%E2%80%AFPM.png?alt=media&amp;token=faf897f9-97de-4431-be16-3ccc33ab25e1" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2F1rfEa4wBOD2FVrsLBysf%2FScreenshot%202026-02-09%20at%201.06.46%E2%80%AFPM.png?alt=media&amp;token=a71d4b2e-23cd-4e6e-b73c-dcf99699d019" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FILA9fYH2RFvv8aJsagRX%2FScreenshot%202026-02-09%20at%201.21.06%E2%80%AFPM.png?alt=media&amp;token=77be6fc8-de3a-4389-b0e9-751e876c98d8" alt=""><figcaption></figcaption></figure>

4. Monitor stack events for completion

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FcLv9JcH5fMj2RGRL2BGg%2FScreenshot%202026-02-09%20at%201.09.35%E2%80%AFPM.png?alt=media&amp;token=e55ea7ee-f8b8-49b1-8e03-80d11b4beb56" alt=""><figcaption></figcaption></figure>

***

#### Deployment using AWS CLI

**Step 1:** Navigate to the CloudFormation template directory

```shellscript
Amazon Linux:
cd bluerock-aws-cloudformation-bru-release-26.08.0/ec2/al2023/

Ubuntu:
cd bluerock-aws-cloudformation-bru-release-26.08.0/ec2/ubuntu2404/
```

**Step 2:** Create CloudFormation stack

```shellscript
aws cloudformation create-stack \
  --stack-name bluerock-deployment \
  --template-body file://template.yaml \
  --parameters file://parameters.json \
  --capabilities CAPABILITY_IAM
```

**Step 3:** Monitor stack status.

Wait until the stack status shows **CREATE\_COMPLETE** before proceeding.

```shellscript
aws cloudformation describe-stacks --stack-name bluerock-deployment

Output:
{
  "Stacks": [
    {
      "StackName": "bluerock-deployment",
      "StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/bluerock-deployment/9c8f1e20-1234-11ef-a2c3-0a1b2c3d4e5f",
      "StackStatus": "CREATE_COMPLETE",
      "CreationTime": "2026-02-03T10:42:18.123Z",
      "Description": "BlueRock Secure MCP Server EC2 Deployment",
      "Capabilities": [
        "CAPABILITY_IAM"
      ]
    }
  ]
}

```

***

### Post-Deployment Validation

This section verifies that the BlueRock Secure MCP Server has been deployed successfully and is functioning as expected.

#### Check BlueRock Instance

Check the instance status to confirm that the EC2 instance is running and has a public IP address assigned (for public deployments):

```shellscript
~ $ aws ec2 describe-instances \
    --filters "Name=tag:Name,Values=bluerock*"
{
  "Reservations": [
    {
      "ReservationId": "r-00fc24c1245a2e96c",
      "OwnerId": "077227809213",
      "RequesterId": "043320173835",
      "Groups": [],
      "Instances": [
        {
          "Architecture": "x86_64",
          "BlockDeviceMappings": [
            {
              "DeviceName": "/dev/sda1",
              "Ebs": {
                "AttachTime": "2026-02-09T07:37:36+00:00",
                "DeleteOnTermination": true,
                "Status": "attached",
                "VolumeId": "vol-0929b350547dc3802",
                "EbsCardIndex": 0
              }
            }
          ],
          "ClientToken": "2f7fae10-b724-84df-0dcf-c85aee79c683",
          "EbsOptimized": false,
          "EnaSupport": true,
          "Hypervisor": "xen",
          "IamInstanceProfile": {
            "Arn": "arn:aws:iam::077227809213:instance-profile/bluerock-external-otel-InstanceProfile",
            "Id": "AIPARD6ZC3G673AWVVTM6"
          },
          "NetworkInterfaces": [
            {
              "Association": {
                "IpOwnerId": "amazon",
                "PublicDnsName": "ec2-18-227-161-122.us-east-2.compute.amazonaws.com",
                "PublicIp": "18.227.161.122"
              },
              "Attachment": {
                "AttachTime": "2026-02-09T07:37:35+00:00",
                "AttachmentId": "eni-attach-09c4ad25e1611d5df",
                "DeleteOnTermination": true,
                "DeviceIndex": 0,
                "Status": "attached",
                "NetworkCardIndex": 0
              },
              "Groups": [
                {
                  "GroupId": "sg-053ae813feb64d4f4",
                  "GroupName": "bluerock-external-otel-InstanceSecurityGroup-hzuMqu5i2q7W"
                }
              ],
              "MacAddress": "02:bc:a1:63:78:df",
              "NetworkInterfaceId": "eni-0d8d5fda7c9e7459c",
              "OwnerId": "077227809213",
              "PrivateDnsName": "ip-10-0-1-211.us-east-2.compute.internal",
              "PrivateIpAddress": "10.0.1.211"
            }
          ],
          "State": {
            "Code": 16,
            "Name": "running"
          },
          "Tags": [
            {
              "Key": "Name",
              "Value": "bluerock-external-otel-node"
            }
          ]
        }
      ]
    }
  ]
}

```

#### Check Instance Access

**Option 1: SSH Access** (Public Deployment Only)

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

```shellscript
Amazon Linux:
ssh -i /path/to/key.pem ec2-user@<PUBLIC_IP>

Ubuntu:
ssh -i /path/to/key.pem ubuntu@<PUBLIC_IP>
```

**Option 2: AWS Systems Manager (SSM)**

For Private deployment, where SSH is disabled, connect via AWS SSM.

1. Navigate to EC2 Console
2. Select the BlueRock instance
3. Click **Connect → Session Manager**

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FrFucNteHmzmrZsonwtVN%2FScreenshot%202026-02-09%20at%201.31.11%E2%80%AFPM.png?alt=media&amp;token=625fa3b3-31cb-4200-a79c-fe7e6d06899a" alt=""><figcaption></figcaption></figure>

4. Click **Connect**

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2F143MTCBVB5EDBSN9ElVN%2FScreenshot%202026-02-03%20at%205.27.27%E2%80%AFPM.png?alt=media&amp;token=1118bf69-5639-440b-a1c4-ef92ad0d02f5" alt=""><figcaption></figcaption></figure>

Successful connection confirms:

* SSM agent is running
* IAM instance profile permissions are correct

```shellscript
sh-5.2$ whoami
ssm-user
sh-5.2$
```

### OTEL Event Collection

1. Locate the OTEL config file:

   ```shellscript
   $ cd /opt/bluerock/otel

   $ ls

   otel-config.yaml
   ```
2. Edit the `otel-config.yaml` file based on the requirements.
3. Enable the otel service

   ```shellscript
   $ sudo systemctl enable otelcol.service
   ```
4. Start the otel service

   ```shellscript
   $ sudo systemctl start otelcol.service
   ```
5. Check the status of the otel service

   ```shell
   $ sudo systemctl status otelcol.service --no-pager -l
   ● otelcol.service - OpenTelemetry Collector (Bluerock)
        Loaded: loaded (/etc/systemd/system/otelcol.service; enabled; preset: enabled)
        Active: active (running) since Fri 2026-07-03 03:15:22 UTC; 7h ago
          Docs: https://opentelemetry.io/docs/collector/
      Main PID: 3227 (aws-otel-collec)
         Tasks: 9 (limit: 18800)
        Memory: 19.9M (peak: 21.7M)
           CPU: 19.917s
        CGroup: /system.slice/otelcol.service
                └─3227 /opt/aws/aws-otel-collector/bin/aws-otel-collector --config=/opt/bluerock/otel/otel-config.yaml
   Jul 03 03:15:22 ip-172-31-29-175 run-otelcol.sh[3227]: 2026-07-03T03:15:22.324Z        debug        builders/builders.go:24        Stable component.        {"resource": {"service.instance.id": "27df2ba6-b766-4dc7-9b5b-c80a5956c45c", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "otelcol.signal": "logs"}
   Jul 03 03:15:22 ip-172-31-29-175 run-otelcol.sh[3227]: 2026-07-03T03:15:22.324Z        debug        Logger core does not support injecting component attributes        {"resource": {"service.instance.id": "27df2ba6-b766-4dc7-9b5b-c80a5956c45c", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "otelcol.signal": "logs"}
   ```

### Verify OTEL Events in AWS CloudWatch

**Check CloudWatch logs:**

1. Navigate to **CloudWatch Console**

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FIa8Rqo7hFIN1APJ0nthb%2FScreenshot%202026-02-05%20at%206.17.23%E2%80%AFPM.png?alt=media&amp;token=00fdbad6-9b8a-40fd-b748-52780c5ca33e" alt=""><figcaption></figcaption></figure>

2. Go to **Log Groups**

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FOdfFZRM8iAI2qonyF2eh%2FScreenshot%202026-02-05%20at%206.19.28%E2%80%AFPM.png?alt=media&amp;token=78f1dd5c-76b4-48f4-aadc-e18ed2cf1f6d" alt=""><figcaption></figcaption></figure>

3. Find the BlueRock Log Group

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FANaLhv3rxTk6FexAs3Di%2FScreenshot%202026-02-09%20at%201.35.56%E2%80%AFPM.png?alt=media&amp;token=255142ca-c197-4294-907d-6a50743d9573" alt=""><figcaption></figcaption></figure>

4. **Verify:**

* Log entries are present
* Events originate from the EC2 instance
* Timestamps align with instance startup activity

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FPJ5LTDB3bgYct2ki2Pvp%2FScreenshot%202026-02-09%20at%204.41.24%E2%80%AFPM.png?alt=media&amp;token=afe03dae-75f7-43f9-bc3b-a005a716134d" alt=""><figcaption></figcaption></figure>

Expected logs include runtime events emitted by the BlueRock Secure MCP Server.

For additional information on CloudWatch Logs, see:\
[CloudWatchLogs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bluerock.io/deployment-guides/aws-deployments/aws-deployment-with-cloud-formation-template.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.