Prerequisites: IAM Role Setup
Use attached IAM roles for secure, key-free authentication on EC2 instances. This eliminates the need to manage access keys. References: IAM roles for EC2 | IAM best practices | Using instance profilesCreate IAM Role
- Go to IAM Console → Roles
- Click Create role
- Select trusted entity type: AWS service → EC2
- Attach policies as needed:
- For RDS IAM authentication - see RDS/Aurora section
- For Secrets Manager access - see AWS Secrets Manager section
- Name the role:
bytebase-role
Attach IAM Role to EC2
New EC2 Instance:- Launch instance in EC2 Console
- In Advanced details → IAM instance profile: Select
bytebase-role
- Select instance → Actions → Security → Modify IAM role
- Select
bytebase-role
→ Update IAM role
Alternative: IAM User with Access Keys
Use only when running Bytebase outside AWS. See why to use IAM roles instead of access keys.
- Create an IAM user with required policies
- Generate access keys
- Set environment variables:
RDS/Aurora with IAM Authentication
Prerequisites: IAM role with RDS connect permissions.
Step 1: Configure RDS/Aurora Instance
- In RDS Console, modify your instance
- Enable IAM database authentication under Database authentication options
- Save changes (SSL is enabled by default)
Step 2: Grant Database Connect Permission
Add this policy to your IAM role to allow RDS IAM authentication:REGION
, ACCOUNT_ID
, and DB_RESOURCE_ID
with your values. Find DB_RESOURCE_ID in RDS console → Configuration tab. For easier setup, you can use wildcards: arn:aws:rds-db:*:*:dbuser:*/*
Reference: IAM policy examples
Step 3: Create Database User
MySQL/Aurora MySQL:Step 4: Connect from Bytebase
- Click New Instance in Bytebase
- Configure connection:
- Host: Your RDS endpoint
- Port: 3306 (MySQL) or 5432 (PostgreSQL)
- Username:
bytebase
- Authentication: Select
AWS RDS IAM
- Test and save the connection
AWS Secrets Manager
Store database passwords securely in AWS Secrets Manager instead of Bytebase.Prerequisites: IAM role with Secrets Manager permissions.
Step 1: Grant Secrets Manager Access
Add this policy to your IAM role to read secrets:REGION
, ACCOUNT_ID
, and SECRET_NAME
with your values. For easier setup, you can use wildcards: arn:aws:secretsmanager:*:*:secret:*
Reference: Secrets Manager IAM permissions
Step 2: Create Secret
- Go to AWS Secrets Manager Console
- Click Store a new secret
- Select Other type of secret
- Add key/value pair: Key =
DB_PASSWORD
, Value = your password - Name the secret (e.g.,
bytebase-db-password
) - Complete creation and note the ARN
Step 3: Configure in Bytebase
- In your database instance settings, find the password field
- Click the key icon to use external secret
- Select AWS Secrets Manager
- Enter:
- Secret Name: Your secret name from Step 2
- Secret Key:
DB_PASSWORD
- Test connection and save
Database-Specific Configuration
For specific database types running on AWS, see their configuration guides:- PostgreSQL on RDS
- Aurora PostgreSQL
- Aurora MySQL
Best Practices
- Use IAM Roles over Access Keys: Always prefer IAM roles when running on EC2
- Enable SSL/TLS: All AWS database services support encrypted connections
- Use Secrets Manager: Centralize password management with automatic rotation
- Follow Least Privilege: Grant only necessary permissions to IAM roles
- Monitor Access: Use CloudTrail to audit database access patterns
Troubleshooting
Connection Timeout
- Verify security group rules allow traffic on database port
- Check VPC routing and subnet configuration
- Ensure database is publicly accessible or use VPN/bastion host
IAM Authentication Failed
- Verify IAM role has correct
rds-db:connect
permissions - Check database user was created with correct authentication method
- Ensure SSL is enabled for the connection
Secrets Manager Access Denied
- Verify IAM role has
secretsmanager:GetSecretValue
permission - Check secret ARN matches the policy resource
- Ensure secret exists in the correct region