Skip to main content

Fundamental Platform: AWS Setup Guide

Version 1.0

Target Audience: DevOps Engineers / AWS Administrators

Purpose: This document provides step-by-step instructions for deploying the Fundamental platform into your own AWS environment.

1. Prerequisites & Account Access​

Before beginning the installation via the Command Line Interface, ensure you have the following access levels and resources ready.

A. AWS Account Permissions​

To successfully deploy the CloudFormation stacks, the AWS user or role running the deployment must have extensive permissions. During testing, it was confirmed that standard power-user permissions may be insufficient due to the creation of IAM roles and nested stacks.

Required Access:

  • AdministratorAccess (Recommended for setup): The deploying user should ideally have Admin access to ensure all nested stacks, IAM roles, and security groups can be created without interruption.
  • Specific Capabilities:
    • cloudformation:* (Ability to create and manage stacks)
    • iam:* (Ability to create Roles and Instance Profiles)
    • ec2:* (Ability to launch instances, create Security Groups, etc.)
    • s3:* (Read access to Fundamental templates)

B. Networking Requirements​

The Fundamental platform deploys into its own new VPC, but it requires an existing "Consumer" environment to act as the client. You must have:

  • A Consumer VPC ID: An existing VPC where your client applications (or the test client) will reside.
  • A Consumer Subnet ID: A subnet within that VPC with outbound internet access (to download packages) and connectivity to the Fundamental endpoint.
Critical Note

Ensure you have the full Subnet ID (e.g., must start with subnet-12345...).

C. Technical Setup​

  • AWS CLI: Installed and configured with the credentials of the Admin user mentioned above.
  • SSH Key Pair: An existing .pem key pair in the target region to access the client instance.

2. Environment Configuration​

Open your terminal and configure your target deployment region. The examples below use us-east-1 (North Virginia), which was validated during engineering tests.

# Set your target region
export REGION=us-east-1

3. Deployment Configuration​

Create Parameters File​

Create a file named params.json in your working directory. This file maps your existing network resources to the Fundamental deployment.

Important

You must replace <your-vpc-id> and <your-subnet-id> with your actual AWS Resource IDs.

[
  { "ParameterKey": "DeploymentName", "ParameterValue": "fundamental" },
  { "ParameterKey": "ConsumerVpc1Id", "ParameterValue": "<your-vpc-id>" },
  { "ParameterKey": "ConsumerVpc1SubnetIds", "ParameterValue": "<your-subnet-id>" }
]
Troubleshooting Tip

Ensure your ConsumerVpc1SubnetIds value explicitly includes the subnet- prefix. During validation, missing this prefix caused deployment failures.

4. Deploy CloudFormation Stack​

Execute the following command to initiate the deployment. This will pull the root template from the Fundamental S3 bucket.

aws cloudformation create-stack \
  --stack-name fundamental \
  --template-url https://fundamental-ec2-cfn-templates.s3.us-west-1.amazonaws.com/0.1.0/templates/root-template.yaml \
  --parameters file://params.json \
  --capabilities CAPABILITY_NAMED_IAM \
  --region $REGION

Deployment Time: Approximately 20-40 minutes.

5. Validate Deployment​

Once the wait time has passed, verify that all resources are healthy and running.

A. Check Stack Status​

Ensure the root stack reports CREATE_COMPLETE.

aws cloudformation describe-stacks \
  --stack-name fundamental \
  --region $REGION \
  --query 'Stacks[0].StackStatus' \
  --output text

B. Verify Nested Stacks​

Fundamental uses nested stacks. Ensure all 14 substacks are healthy.

aws cloudformation describe-stack-resources \
  --stack-name fundamental \
  --region $REGION \
  --query 'StackResources[?ResourceType==`AWS::CloudFormation::Stack`].ResourceStatus' \
  --output text | tr '\t' '\n' | sort | uniq -c

C. Verify EC2 Instances​

You should see 3 specific instances running: api, controller, and triton.

aws ec2 describe-instances \
  --region $REGION \
  --filters "Name=tag:DeploymentName,Values=fundamental" "Name=instance-state-name,Values=running" \
  --query 'length(Reservations[*].Instances[*])' \
  --output text

6. Client Access Setup​

To interact with the platform, we will set up a Client EC2 instance in your consumer VPC.

A. Grant S3 Access for Client SDK​

We need to attach a policy to the API execution role to allow the client to download the necessary Python SDK wheels.

aws iam put-role-policy \
  --role-name fundamental-$REGION-api-execute-role \
  --policy-name fundamental-client-sdk-access \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::fundamental-ec2-encrypted-models-images/fundamental_client-*"
    }]
  }'

B. Launch Client Instance​

This script finds the latest Amazon Linux 2023 AMI, creates a security group, and launches an EC2 instance in your subnet.

info

Replace the placeholders:

  • <your-vpc-id>
  • <your-subnet-id>
  • <your-key-pair>
# 1. Get latest AMI
export AMI_ID=$(aws ssm get-parameter \
  --name /aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 \
  --region $REGION \
  --query 'Parameter.Value' --output text)

# 2. Create Security Group
export CLIENT_SG=$(aws ec2 create-security-group \
  --region $REGION \
  --group-name fundamental-client-sg \
  --description "Fundamental client access" \
  --vpc-id <your-vpc-id> \
  --query 'GroupId' --output text)

# 3. Authorize Traffic
aws ec2 authorize-security-group-ingress \
  --region $REGION \
  --group-id $CLIENT_SG \
  --protocol -1 --cidr 0.0.0.0/0

# 4. Run Instance
export INSTANCE_ID=$(aws ec2 run-instances \
  --image-id $AMI_ID \
  --instance-type t3.large \
  --subnet-id <your-subnet-id> \
  --security-group-ids $CLIENT_SG \
  --iam-instance-profile Name=fundamental-$REGION-api-execute-profile \
  --key-name <your-key-pair> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=fundamental-client}]' \
  --region $REGION \
  --query 'Instances[0].InstanceId' --output text)

# 5. Wait for Initialization
aws ec2 wait instance-running --instance-ids $INSTANCE_ID --region $REGION

export CLIENT_IP=$(aws ec2 describe-instances \
  --instance-ids $INSTANCE_ID \
  --region $REGION \
  --query 'Reservations[0].Instances[0].PublicIpAddress' --output text)

echo "Client Instance Ready at: $CLIENT_IP"

7. Configuration & Testing​

A. Retrieve API Endpoint​

You will need this URL to configure the Python client.

export API_URL=$(aws cloudformation describe-stacks \
  --stack-name fundamental \
  --region $REGION \
  --query 'Stacks[0].Outputs[?OutputKey==`RestApiEndpoint`].OutputValue' --output text)

echo "API Endpoint: $API_URL"

B. Connect to Client​

SSH into your newly created client machine.

ssh -i "<your-key.pem>" ec2-user@$CLIENT_IP

C. Install SDK & Run Test​

Once inside the client instance, copy and paste the following block to create a setup script. This script installs dependencies, downloads the proprietary Fundamental SDK, and runs a basic training/inference job.

sudo cat << 'SCRIPT' > setup_and_test.sh
#!/bin/bash
set -e

# --- CONFIGURATION REQUIRED ---
export REGION="us-east-1"              # Ensure this matches your deployment region
export API_URL="<PASTE_API_URL_HERE>"  # Paste the URL retrieved in Step 7A
# ------------------------------

echo "Installing System Dependencies..."
sudo dnf update -y && sudo dnf install python3.11 python3.11-pip -y

echo "Downloading Fundamental SDK..."
aws s3 cp s3://fundamental-ec2-encrypted-models-images/fundamental_client-0.1.9-py3-none-any.whl \
  fundamental_client-0.1.9-py3-none-any.whl

pip3.11 install fundamental_client-0.1.9-py3-none-any.whl[ec2]

echo "Creating Python Test Script..."
cat << EOF > client.py
import numpy as np
import pandas as pd
import fundamental
from fundamental import FTMClassifier, FundamentalEC2Client

# Initialize Client
fundamental.set_client(FundamentalEC2Client(aws_region="$REGION", api_url="$API_URL"))
model = FTMClassifier(mode="speed")

print("Training Model...")
# Simple XOR-like pattern
model.fit(X=pd.DataFrame(np.array([[1], [0]])), y=pd.Series(np.array([0, 1])))
print(f"Trained model ID: {model.trained_model_id_}")

print("Running Prediction...")
preds = model.predict(pd.DataFrame(np.array([[1], [0]])))
print(f"Predictions: {preds}")
EOF

echo "Running Test..."
python3.11 client.py
SCRIPT

D. Execute Test​

  1. Open the script you just created: nano setup_and_test.sh
  2. Manually paste your API_URL (from step 7A) into the variable at the top of the file.
  3. Save and exit.
  4. Run the test:
chmod +x setup_and_test.sh && ./setup_and_test.sh

Success Criteria:

You should see output indicating a Trained model ID followed by a prediction array (e.g., [0, 1]).