> 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/gcp-deployments/gcp-deployment-with-terraform.md).

# GCP Deployment with Terraform

This guide describes how the BlueRock Secure MCP Server is deployed on Google Compute Engine (GCE) using Terraform.

Terraform scripts are executed from a local machine or CI/CD environment with the Google Cloud SDK (gcloud) initialized. The scripts use the Google Cloud APIs to provision the necessary Compute Engine, Networking, and Storage resources.

### Prerequisites

* Google Cloud CLI tools (`gcloud`), for installation refer to the official [Google Cloud CLI installation](https://docs.cloud.google.com/sdk/docs/install-sdk) guide.
* Terraform: Version `1.0` or higher installed, for installation refer to the official [HashiCorp Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli)  guide.
* BlueRock images: BlueRock provides pre-packaged images of BlueRock Ubuntu 2404 Linux Distribution - (Free or Full version), contact [BlueRock support](https://www.bluerock.io/contact) for the images. 

  <table><thead><tr><th width="102">Version</th><th width="141">OS</th><th width="144">Kernel Version</th><th>GCP Image Name</th></tr></thead><tbody><tr><td>Free</td><td>Ubuntu 24.04</td><td>6.12.63</td><td>bluerock-release-26-08-0-ubuntu2404-6.12.63-free</td></tr><tr><td>Full</td><td>Ubuntu 24.04</td><td>6.12.63</td><td>bluerock-release-26-08-0-ubuntu2404-6.12.63</td></tr></tbody></table>

#### BlueRock GCP Architecture Components

A typical deployment on GCP consists of the following resources:

| **GCP Resource/Service** | **Description**                                                             |
| ------------------------ | --------------------------------------------------------------------------- |
| VPC Network              | Provides an isolated virtual network environment in GCP.                    |
| Cloud NAT / Router       | Enables outbound internet access for private instances without a Public IP. |
| Compute Engine (GCE)     | Runs the BlueRock MCP Server using a hardened Ubuntu image.                 |
| Persistent Disk          | Provides persistent block storage attached to the GCE instance.             |
| Cloud Storage (GCS)      | Stores configuration files and certificates for the BlueRock node.          |
| IAM Service Account      | Grants the GCE instance minimal permissions for Logging and Storage.        |
| Cloud Logging            | Collects and monitors system and application logs from the node.            |

### Deployment Types

BlueRock GCP deployments support two primary modes based on networking requirements:

* **Public Deployment**: The instance is assigned a Public IP and is accessible via SSH restricted by a specific CIDR range.
* **Private Deployment:** The instance has no public IP. Access is facilitated through Identity-Aware Proxy (IAP), and outbound connectivity is provided via Cloud NAT.

### Deployment Package Overview

#### Download and Extract Package

Download and extract the BlueRock deployment `bluerock_gcp_deployments_scripts.zip` package in which a sub-package `bluerock-gcp-terraform-26-08.tar.gz` refer to the and extract it on your local environment.

```bash
$ tar -xzf terraform.tar.gz

$ ls 
terraform/
terraform.tar.gz
```

### Directory Structure

The GCP Terraform scripts follow a hierarchical structure to separate full and free versions:

```zsh
gcp/compute/terraform/
├── ubuntu/  # This directory is for Full version 
│   ├── PublicDeployment/       # Full Public IP
        │       ├── main.tf
        │       ├── outputs.tf
        │       ├── terraform.tfvars
        │       ├── terraform.tfvars.example
        │       ├── user_data.sh.tpl
        │       └── variables.tf
│   └── PrivateDeployment/      # Full Private (NAT/IAP)
        │       ├── main.tf
        │       ├── outputs.tf
        │       ├── terraform.tfvars
        │       ├── terraform.tfvars.example
        │       ├── user_data.sh.tpl
        │       └── variables.tf
└── free/  # This directory is for Free version 
    └── ubuntu/
        ├── PublicDeployment/   # Free Public IP
        │       ├── main.tf
        │       ├── outputs.tf
        │       ├── terraform.tfvars
        │       ├── terraform.tfvars.example
        │       ├── user_data.sh.tpl
        │       └── variables.tf
        └── PrivateDeployment/  # Free Private (NAT/IAP)
        │       ├── main.tf
        │       ├── outputs.tf
        │       ├── terraform.tfvars
        │       ├── terraform.tfvars.example
        │       ├── user_data.sh.tpl
        │       └── variables.tf
```

### Parameter Reference

Key variables defined in `variables.tf` that must be configured in your `terraform.tfvars`:

| **Parameter**  | **Description**                       | **Required** | **Example**                                        |
| -------------- | ------------------------------------- | ------------ | -------------------------------------------------- |
| `project_id`   | The unique ID of your GCP project     | Yes          | `project-1234`                                     |
| `region`       | GCP region for resource deployment    | Yes          | `us-central1`                                      |
| `boot_image`   | The name of the BlueRock Ubuntu image | Yes          | `bluerock-release-26-08-0-ubuntu2404-6.12.63-free` |
| `machine_type` | GCE instance type                     | Yes          | `e2-standard-2`                                    |
| `allow_ip`     | User's or Admin's desktop IP Address  | Yes          | `xx.xx.xx.xx/32`                                   |

### `terraform.tfvars` Configuration

By default, the package has `terraform.tfvars.example` file to configure parameters based on requirements and rename it to `terraform.tfvars` for quick onboarding.

### `terraform.tfvars` Parameter Reference

The following parameters are defined in the `terraform.tfvars` file. You must update these values to match your GCP project environment before running the deployment scripts.

<table data-header-hidden><thead><tr><th width="193.12109375"></th><th></th><th width="114.23828125"></th><th width="217.40234375"></th></tr></thead><tbody><tr><td><strong>Parameter</strong></td><td><strong>Description</strong></td><td><strong>Required</strong></td><td><strong>Example / Default Value</strong></td></tr><tr><td><code>project_id</code></td><td>The unique GCP Project ID where resources will be deployed.</td><td>Yes</td><td><code>your-project-id</code></td></tr><tr><td><code>region</code></td><td>The GCP region for the deployment (e.g., <code>us-central1</code>).</td><td>Yes</td><td><code>us-central1</code></td></tr><tr><td><code>zone</code></td><td>The specific availability zone within the region.</td><td>Yes</td><td><code>us-central1-a</code></td></tr><tr><td><code>prefix</code></td><td>A string prefix used for naming all generated GCP resources.</td><td>No</td><td><code>bluerock-free</code></td></tr><tr><td><code>allow_ip</code></td><td>CIDR range allowed for SSH access to the BlueRock node.</td><td>Yes</td><td><code>xx.xx.xx.xx/20</code> (Use some private network of <code>xx.xx.xx.xx/20</code>)</td></tr><tr><td><code>machine_type</code></td><td>The GCE machine type (vCPU/RAM) for the instance.</td><td>Yes</td><td><code>e2-standard-4</code></td></tr><tr><td><code>boot_image</code></td><td>The name of the pre-baked BlueRock Ubuntu OS image.</td><td>Yes</td><td><code>bluerock-release-26-08-0-ubuntu2404-6.12.63-free</code></td></tr><tr><td><code>existing_network</code></td><td>Existing VPC Network name. Leave empty to create a new one.</td><td>Optional</td><td><code>""</code></td></tr><tr><td><code>existing_subnetwork</code></td><td>Existing Subnetwork name. Leave empty to create a new one.</td><td>Optional</td><td><code>""</code></td></tr><tr><td><code>enable_external_otel</code></td><td>Enables the OpenTelemetry collector for external telemetry.</td><td>No</td><td><code>true</code></td></tr><tr><td><code>existing_bucket_name</code></td><td>Existing GCS bucket name to store configuration/logs.</td><td>Optional</td><td><code>""</code></td></tr></tbody></table>

### Configuration Steps for `terraform.tfvars`&#x20;

To prepare your environment for deployment, follow these steps to initialize your variables:

1. Navigate to the appropriate deployment directory. for example:  `gcp/compute/terraform/ubuntu/PublicDeployment/` <br>

2. Copy the example variables file to a live configuration file:

   ```shell
   cp terraform.tfvars.example terraform.tfvars
   ```

3. Edit the `terraform.tfvars` file and provide your specific `project_id` and `boot_image`.

> **Note**:&#x20;
>
> If you are deploying into an existing network, ensure both `existing_network` and `existing_subnetwork` are provided; otherwise, Terraform will attempt to create a new VPC and Subnet.

### Terrform Running the Deployment

1. Navigate to the desired deployment directory (e.g., `PublicDeployment`).
2. Initialize:

   ```yaml
   $ terraform init
   ```
3. Plan:

   ```yaml
   $ terraform plan
   ```
4. Apply:

   ```yaml
   $ terraform apply
   ```

### Post-Deployment Validation

#### Check BlueRock Instance

Verify the VM status and retrieve the IP via the gcloud CLI:

```shell
$ gcloud compute instances list --filter="name~'bluerock*'"
```

#### Verify Services

SSH into the instance and check the BlueRock control plane status:

```shell
$ sudo docker ps # To verigy Docker is running
$ sudo systemctl status uc-docker.service
```

### View Logs in GCP

To view logs In GCP:

1. Log in to your GCP account in a browser navigate to **Compute Engine** > **VM Instances**.
2. Select the required instance.
3. Select **Logging**.<br>

   <figure><img src="/files/WABEUjTOjWnnJTbFE9LV" alt=""><figcaption></figcaption></figure>


---

# 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/gcp-deployments/gcp-deployment-with-terraform.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.