Skip to content

Commit cd19068

Browse files
you-rgbyou-rgb
committed
update README
1 parent d1a3942 commit cd19068

1 file changed

Lines changed: 207 additions & 21 deletions

File tree

‎deployments/aws/README.md‎

Lines changed: 207 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,13 @@ what you should see. By the end, you'll have a fully operational 7-node Infinia
1111
3. **AWS Account**: Ensure you have an AWS account with the necessary permissions.
1212
4. **Terraform**: Install Terraform locally.
1313
5. **AWS CLI**: Install and configure AWS CLI for authentication.
14+
6. **Python 3**: Required for S3 smoke testing and deployment scripts.
1415

1516
## Features
1617
- Deploys Infinia instances using customizable instance types (default: `m7a.2xlarge`).
1718
- Deploys customizable client instances.
19+
- Option to create new VPC and subnets or use existing infrastructure.
20+
- S3 smoke testing capabilities for deployment validation.
1821
- Health checks on port `8111` for instance availability.
1922

2023
## Directory Structure
@@ -29,20 +32,47 @@ infinia-deployment/
2932
```
3033

3134
## Variables
35+
36+
### Core Infrastructure Variables
3237
| Variable | Description | Default |
3338
|-----------------------|--------------------------------------------------|-------------------|
3439
| `infinia_deployment_name` | Deployment name for Infinia resources (4-8 lowercase chars) | - |
3540
| `aws_region` | AWS region for deployment | `us-west-2` |
36-
| `vpc_id` | VPC ID for resource deployment | - |
37-
| `subnet_ids` | List of subnet IDs | - |
38-
| `security_group_id` | Security group ID allowing access to port 8111 | - |
41+
| `key_pair_name` | Name of the AWS key pair for SSH access | - |
42+
43+
### Network Configuration (Choose One Approach)
44+
#### Option 1: Use Existing Infrastructure
45+
| Variable | Description | Default |
46+
|-----------------------|--------------------------------------------------|-------------------|
47+
| `create_vpc` | Set to `false` to use existing VPC | `false` |
48+
| `vpc_id` | Existing VPC ID for resource deployment | - |
49+
| `subnet_ids` | List of existing subnet IDs | - |
50+
| `security_group_id` | Existing security group ID allowing access to port 8111 | - |
51+
52+
#### Option 2: Create New VPC and Subnets
53+
| Variable | Description | Default |
54+
|-----------------------|--------------------------------------------------|-------------------|
55+
| `create_vpc` | Set to `true` to create new VPC | `false` |
56+
| `vpc_cidr` | CIDR block for new VPC | `10.0.0.0/16` |
57+
| `subnet_cidrs` | List of subnet CIDR blocks | `["10.0.1.0/24", "10.0.2.0/24"]` |
58+
59+
### Instance Configuration
60+
| Variable | Description | Default |
61+
|-----------------------|--------------------------------------------------|-------------------|
3962
| `infinia_ami_id` | AMI ID for Infinia instances | - |
4063
| `client_ami_id` | AMI ID for client instances | - |
4164
| `instance_type_infinia` | Instance type for Infinia instances | `m7a.2xlarge` |
4265
| `instance_type_client` | Instance type for client instances | `t3.medium` |
43-
| `num_infinia_instances` | Number of Infinia instances to deploy | `1` |
66+
| `num_infinia_instances` | Number of Infinia instances to deploy | `6` |
4467
| `num_client_instances` | Number of client instances to deploy | `1` |
45-
| `key_pair_name` | Name of the AWS key pair for SSH access | - |
68+
69+
### Storage Configuration
70+
| Variable | Description | Default |
71+
|-----------------------|--------------------------------------------------|-------------------|
72+
| `use_ebs_volumes` | Enable EBS volumes for Infinia storage | `true` |
73+
| `ebs_volumes_per_vm` | Number of EBS volumes per Infinia instance | `4` |
74+
| `ebs_volume_size` | Size of each EBS volume (GB) | `128` |
75+
| `root_device_size` | Size of root device (GB) | `256` |
4676

4777
## Deployment Steps
4878

@@ -138,7 +168,36 @@ You should see:
138168
```bash
139169
Terraform v1.x.x
140170
```
141-
#### Step 1.3: Install Required Tools
171+
#### Step 1.3: Install Python 3 and Dependencies
172+
**On Mac:**
173+
```bash
174+
# Python 3 is usually pre-installed, check version
175+
python3 --version
176+
# If not installed or version is too old (< 3.7), install via Homebrew
177+
brew install python3
178+
```
179+
180+
**On Linux (Ubuntu/Debian):**
181+
```bash
182+
# Install Python 3 and pip
183+
sudo apt update
184+
sudo apt install python3 python3-pip -y
185+
```
186+
187+
**Install Python dependencies:**
188+
```bash
189+
# Install required Python packages
190+
pip3 install boto3 requests
191+
```
192+
193+
Verify Python installation:
194+
```bash
195+
python3 --version
196+
# Should show Python 3.7 or higher
197+
python3 -c "import boto3; print('boto3 installed successfully')"
198+
```
199+
200+
#### Step 1.4: Install Required Tools
142201
Install jq (for JSON parsing)
143202
On Mac:
144203
```bash
@@ -150,7 +209,7 @@ sudo apt install jq -y
150209
# Install curl (usually pre-installed)
151210
which curl || sudo apt install curl -y
152211
```
153-
#### Step 1.4: Configure AWS CLI
212+
#### Step 1.5: Configure AWS CLI
154213
Now configure the AWS CLI with your access keys from **Step 0.4**:
155214
```bash
156215
aws configure
@@ -317,30 +376,88 @@ cat providers.tf
317376
# Should show your bucket name, not ${BUCKET_NAME}
318377
```
319378
320-
### Step 10: Create terraform.tfvars
321-
Now we'll create the main configuration file with all your values.
322-
> **IMPORTANT:** Choose the right AMI variable based on **Step 7**
323-
If you have the Infinia AMI:
379+
### Step 10: Choose Your Network Configuration
380+
381+
You have two options for network setup:
382+
383+
#### Option A: Use Existing VPC (Recommended for existing AWS accounts)
384+
If you followed the previous steps and have existing VPC, subnets, and security groups.
385+
386+
#### Option B: Create New VPC (Recommended for new deployments)
387+
Let Terraform create a new VPC, subnets, and security groups for you.
388+
389+
### Step 10.1: Create terraform.tfvars
390+
391+
**Option A - Using Existing Infrastructure:**
324392
```bash
325393
cat > terraform.tfvars << EOF
394+
# Core configuration
326395
aws_region = "us-west-2"
396+
infinia_deployment_name = "infinia"
397+
key_pair_name = "${KEY_NAME}"
398+
399+
# Use existing infrastructure
400+
create_vpc = false
327401
vpc_id = "${VPC_ID}"
402+
subnet_ids = ["${SUBNET_ID}"]
328403
security_group_id = "${SG_ID}"
329-
key_pair_name = "${KEY_NAME}"
404+
405+
# Instance configuration
330406
infinia_ami_id = "${INFINIA_AMI_ID}"
331-
subnet_ids = ["${SUBNET_ID}"]
407+
client_ami_id = "${INFINIA_AMI_ID}"
332408
infinia_version = "${INFINIA_VERSION}"
333-
enable_public_ip = "true"
334-
root_device_size = 256
335-
num_infinia_instances = "6"
409+
num_infinia_instances = 6
410+
num_client_instances = 1
336411
instance_type_infinia = "m7a.2xlarge"
412+
instance_type_client = "m7a.2xlarge"
413+
414+
# Storage configuration
415+
use_ebs_volumes = true
416+
ebs_volumes_per_vm = 4
337417
ebs_volume_size = 128
338-
infinia_deployment_name = "infinia-prod"
418+
root_device_size = 256
419+
420+
# Other settings
421+
enable_public_ip = true
339422
bucket_name = "${BUCKET_NAME}"
340-
ebs_volumes_per_vm = 4
423+
EOF
424+
```
425+
426+
**Option B - Create New VPC (Simpler setup):**
427+
```bash
428+
cat > terraform.tfvars << EOF
429+
# Core configuration
430+
aws_region = "us-west-2"
431+
infinia_deployment_name = "infinia"
432+
key_pair_name = "${KEY_NAME}"
433+
434+
# Create new VPC and subnets
435+
create_vpc = true
436+
vpc_cidr = "10.0.0.0/16"
437+
subnet_cidrs = ["10.0.1.0/24", "10.0.2.0/24"]
438+
439+
# Instance configuration
440+
infinia_ami_id = "${INFINIA_AMI_ID}"
441+
client_ami_id = "${INFINIA_AMI_ID}"
442+
infinia_version = "${INFINIA_VERSION}"
443+
num_infinia_instances = 6
444+
num_client_instances = 1
445+
instance_type_infinia = "m7a.2xlarge"
446+
instance_type_client = "m7a.2xlarge"
447+
448+
# Storage configuration
341449
use_ebs_volumes = true
450+
ebs_volumes_per_vm = 4
451+
ebs_volume_size = 128
452+
root_device_size = 256
453+
454+
# Other settings
455+
enable_public_ip = false
456+
bucket_name = "${BUCKET_NAME}"
342457
EOF
343458
```
459+
460+
> **Note:** Option B (create_vpc = true) is simpler as it handles all networking automatically. Option A gives you more control but requires pre-existing infrastructure.
344461
Verify all variables were substituted:
345462
```bash
346463
cat terraform.tfvars
@@ -472,15 +589,84 @@ aws ssm get-command-invocation \
472589

473590
You should see all 7 nodes listed with their capacity and status.
474591

475-
### Step 16: Access the Web Interface
592+
### Step 16: Run S3 Smoke Test (Optional but Recommended)
593+
594+
After deployment, verify that the S3 API is working correctly:
595+
596+
```bash
597+
# Run the S3 smoke test
598+
cd ~/Desktop/infinia-cloud-platform-deploy/
599+
python3 scripts/s3_smoke_test_aws.py \
600+
--region "us-west-2" \
601+
--admin-password "${TF_VAR_admin_password}" \
602+
--client-tag-key "Role" --client-tag-value "client" \
603+
--endpoint-port 8111 \
604+
--no-verify-ssl \
605+
--timeout-sec 1800
606+
```
607+
608+
**Expected output on success:**
609+
```
610+
Selected endpoint: https://10.0.x.x:8111
611+
---- Client i-xxxxxxxxx (Success) ----
612+
upload: test-xxxxx.txt to s3://infinia-smoke-xxxxx/test-xxxxx.txt
613+
LIST:test-xxxxx.txt
614+
OK
615+
✅ S3 smoke test passed on all clients
616+
```
617+
618+
**If the test fails:**
619+
- Check that all instances are running: `aws ec2 describe-instances --region us-west-2`
620+
- Verify client instances have the correct tags
621+
- Ensure the Infinia cluster is fully initialized (may take 10-15 minutes after deployment)
622+
623+
### Step 17: Access the Web Interface
476624
Open your browser and navigate to:
477625
https://[REALM_IP]
478626
Login with:
479627
- Username: `realm_admin`
480-
- Password: Your password from **Step 2
628+
- Password: Your password from **Step 2**
629+
630+
## Troubleshooting
631+
632+
### Common Issues
633+
634+
#### S3 Smoke Test Fails
635+
```bash
636+
# Check if Infinia cluster is ready
637+
REALM_INSTANCE=$(terraform output -raw infinia_instance_realm_ids)
638+
aws ssm send-command \
639+
--instance-ids "${REALM_INSTANCE}" \
640+
--document-name "AWS-RunShellScript" \
641+
--parameters "commands=[\"redcli inventory show\"]" \
642+
--region us-west-2
643+
```
644+
645+
#### Python Dependencies Issues
646+
```bash
647+
# Reinstall Python packages
648+
pip3 install --upgrade boto3 requests
649+
650+
# On some systems, use pip instead of pip3
651+
pip install boto3 requests
652+
```
653+
654+
#### Terraform Backend Issues
655+
If you see S3 backend errors:
656+
```bash
657+
# Verify bucket exists
658+
aws s3 ls s3://$BUCKET_NAME
659+
660+
# If bucket doesn't exist, recreate it
661+
aws s3api create-bucket --bucket $BUCKET_NAME --region us-west-2 --create-bucket-configuration LocationConstraint=us-west-2
662+
```
663+
664+
### Log Locations
665+
- **Instance startup logs**: `/var/log/infinia-deployment.log`
666+
- **Terraform logs**: Enable with `export TF_LOG=DEBUG`
481667

482668
## Tear-Down
483-
To destroy everything and start over
669+
To destroy everything and start over:
484670
```bash
485671
terraform destroy --var-file terraform.tfvars --auto-approve
486672
echo "Deleting state bucket: $BUCKET_NAME"

0 commit comments

Comments
 (0)