Setup¶
This guide walks you through the initial setup of easy-db-lab, including AWS credentials configuration, IAM policies, and AMI creation.
Overview¶
The setup-profile command handles all initial configuration interactively. It will:
- Collect your email and AWS credentials
- Validate your AWS access
- Create necessary AWS resources (key pair, IAM roles, Packer VPC)
- Build or validate the required AMI
Prerequisites¶
Before running setup:
- AWS Account: An AWS account with appropriate permissions (see IAM Policies below)
- Java 21+: Required to run easy-db-lab
- Docker: Required only if building custom AMIs
Step 1: Run Setup Profile¶
Run the interactive setup:
easy-db-lab setup-profile
Or use the shorter alias:
easy-db-lab setup
The setup wizard will prompt you for:
| Prompt | Description | Default |
|---|---|---|
| Used to tag AWS resources for ownership | (required) | |
| AWS Region | Region for your clusters | us-west-2 |
| AWS Access Key | Your AWS access key ID | (required) |
| AWS Secret Key | Your AWS secret access key | (required) |
| AxonOps Org | Optional: AxonOps organization name | (skip) |
| AxonOps Key | Optional: AxonOps API key | (skip) |
| AWS Profile | Optional: Named AWS profile | (skip) |
What Gets Created¶
During setup, the following AWS resources are created:
- EC2 Key Pair: For SSH access to instances
- IAM Role: For instance permissions (
easy-db-lab-instance-role) - Packer VPC: Infrastructure for building AMIs
- AMI (if needed): Takes 10-15 minutes to build
Configuration Location¶
Your profile is saved to:
~/.easy-db-lab/profiles/default/settings.yaml
Tip
Use a different profile by setting EASY_CASS_LAB_PROFILE environment variable before running setup.
Step 2: Getting IAM Policies¶
If you need to request permissions from your AWS administrator, use the show-iam-policies command to display the required policies with your account ID populated:
easy-db-lab show-iam-policies
This displays three policies:
| Policy | Purpose |
|---|---|
| EC2 | Create/manage EC2 instances, VPCs, security groups |
| IAM | Create instance roles and profiles |
| EMR | Create Spark clusters (optional) |
Filter by Policy Name¶
To show a specific policy:
easy-db-lab show-iam-policies ec2 # Show EC2 policy only
easy-db-lab show-iam-policies iam # Show IAM policy only
easy-db-lab show-iam-policies emr # Show EMR policy only
Recommended IAM Setup¶
For teams with multiple users, we recommend creating managed policies attached to an IAM group:
- Create an IAM group (e.g., "EasyDBLabUsers")
- Create three managed policies from the JSON output
- Attach all policies to the group
- Add users to the group
Warning
Inline policies have a 5,120 byte limit which may not fit all three policies. Use managed policies instead.
Step 3: Build Custom AMI (Optional)¶
If setup couldn't find a valid AMI for your architecture, or if you want to customize the base image, build one manually:
easy-db-lab build-image
Build Options¶
| Option | Description | Default |
|---|---|---|
--arch |
CPU architecture (AMD64 or ARM64) | AMD64 |
--region |
AWS region for the AMI | (from profile) |
Examples¶
# Build AMD64 AMI (default)
easy-db-lab build-image
# Build ARM64 AMI for Graviton instances
easy-db-lab build-image --arch ARM64
# Build in specific region
easy-db-lab build-image --region eu-west-1
Note
Building an AMI takes approximately 10-15 minutes. Docker must be installed and running.
Environment Variables¶
| Variable | Description | Default |
|---|---|---|
EASY_DB_LAB_USER_DIR |
Override configuration directory | ~/.easy-db-lab |
EASY_CASS_LAB_PROFILE |
Use a named profile | default |
EASY_CASS_LAB_INSTANCE_TYPE |
Default instance type for init |
r3.2xlarge |
EASY_CASS_LAB_STRESS_INSTANCE_TYPE |
Default stress instance type | c7i.2xlarge |
EASY_CASS_LAB_AMI |
Override AMI ID | (auto-detected) |
Verify Installation¶
After setup completes, verify by running:
easy-db-lab
You should see the help output with available commands.
Next Steps¶
Once setup is complete, follow the Tutorial to create your first cluster.