diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/access-key.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/access-key.webp deleted file mode 100644 index 59ce23ab6..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/access-key.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/app-outside-aws.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/app-outside-aws.webp deleted file mode 100644 index 25e6bf217..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/app-outside-aws.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/attach-policy.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/attach-policy.webp deleted file mode 100644 index 9cbf3ea90..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/attach-policy.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/cloudsql-iam-auth-on.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/cloudsql-iam-auth-on.webp deleted file mode 100644 index 38ae617d4..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/cloudsql-iam-auth-on.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/connect-permission.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/connect-permission.webp deleted file mode 100644 index 9d82b329f..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/connect-permission.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/connection-name.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/connection-name.webp deleted file mode 100644 index 36cb0ff3b..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/connection-name.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/create-pk.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/create-pk.webp deleted file mode 100644 index d524f5a10..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/create-pk.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/create-policy.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/create-policy.webp deleted file mode 100644 index 8f35c404a..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/create-policy.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/create-user.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/create-user.webp deleted file mode 100644 index 74c4d644f..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/create-user.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/db-password-iam.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/db-password-iam.webp deleted file mode 100644 index 5b3f2ec22..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/db-password-iam.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/grant-cloud-sql-admin.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/grant-cloud-sql-admin.webp deleted file mode 100644 index d668b3fea..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/grant-cloud-sql-admin.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/mysql-connection.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/mysql-connection.webp deleted file mode 100644 index cb96fa7b1..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/mysql-connection.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/rds-iam-auth.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/rds-iam-auth.webp deleted file mode 100644 index 4a599e4a9..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/rds-iam-auth.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/retrieve-access-keys.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/retrieve-access-keys.webp deleted file mode 100644 index 1b1f8665b..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/retrieve-access-keys.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/service-account-keys.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/service-account-keys.webp deleted file mode 100644 index 4620e93a5..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/service-account-keys.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/sql-users.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/sql-users.webp deleted file mode 100644 index f3a2b12d6..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/sql-users.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/user-account-type.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/user-account-type.webp deleted file mode 100644 index 736355d52..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/user-account-type.webp and /dev/null differ diff --git a/mintlify/content/docs/get-started/instance/aws-rds-iam/user-added-bytebase.webp b/mintlify/content/docs/get-started/instance/aws-rds-iam/user-added-bytebase.webp deleted file mode 100644 index d584177ba..000000000 Binary files a/mintlify/content/docs/get-started/instance/aws-rds-iam/user-added-bytebase.webp and /dev/null differ diff --git a/mintlify/get-started/instance.mdx b/mintlify/get-started/instance.mdx index bb8709536..a5ae78db4 100644 --- a/mintlify/get-started/instance.mdx +++ b/mintlify/get-started/instance.mdx @@ -145,78 +145,103 @@ Integrate with custom secret managers using your API: ### RDS/Aurora with IAM Authentication -Connect to AWS databases using IAM credentials instead of passwords. - -#### Prerequisites - -Enable IAM authentication when creating your RDS/Aurora instance: - -![IAM authentication option](/content/docs/get-started/instance/aws-rds-iam/db-password-iam.webp) - -#### Setup IAM Policy - -1. Go to **IAM > Policies** and click **Create policy** - ![](/content/docs/get-started/instance/aws-rds-iam/create-policy.webp) - -2. Select `RDS IAM Authentication` for service - ![](/content/docs/get-started/instance/aws-rds-iam/rds-iam-auth.webp) - -3. Select `connect` permission and `specific` as Resources. Check `Any in this account` - ![](/content/docs/get-started/instance/aws-rds-iam/connect-permission.webp) - - - `Any in this account` will mark the resource as `arn:aws:rds-db:*:<>:dbuser:*/*`, which contains 3 `*`: - - 1st *: any regions - - 2nd *: any databases - - 3rd *: any database users +This guide demonstrates the most secure method for IAM authentication using EC2 instance profiles, which eliminates the need to manage access keys. + +For alternative authentication methods such as IAM users with access keys or cross-account access, refer to: +- [AWS RDS IAM Database Authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html) +- [Connecting using IAM authentication from the command line](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Connecting.html) +- [IAM authentication for cross-account access](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.CrossAccount.html) + +#### Step 1: Configure RDS/Aurora Instance + +Enable IAM authentication on your database instance: + +1. **Enable IAM Database Authentication** + - For existing instances: Modify instance → Database authentication → IAM database authentication + - For new instances: Enable "Password and IAM database authentication" during creation + - Reference: [Enabling IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Enabling.html) + +2. **Verify SSL/TLS** + - SSL is enabled by default on RDS (required for IAM auth) + - No additional configuration needed + +#### Step 2: Create IAM Role for EC2 + +1. **Create IAM Policy** + - Go to IAM → Policies → Create policy + - Choose JSON and paste: + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "rds-db:connect", + "Resource": "arn:aws:rds-db:REGION:ACCOUNT_ID:dbuser:DB_INSTANCE_ID/DB_USER" + } + ] + } + ``` + - Replace `REGION`, `ACCOUNT_ID`, `DB_INSTANCE_ID`, and `DB_USER` with your values + - Or use wildcards (*) for broader access + - Name the policy: `rds-iam-auth-policy` + + > **Production Best Practice:** Use specific ARNs instead of wildcards. See [AWS IAM Policy examples](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.IAMPolicy.html). - This will allow RDS connect on behalf of all database users in all databases in your account. - If you want to limit the connection to specific databases, please follow [this doc](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.IAMPolicy.html). - +2. **Create IAM Role** + - Go to IAM → Roles → Create role + - Select trusted entity: `AWS service` → `EC2` + - Attach the `rds-iam-auth-policy` created above + - Name: `bytebase-rds-role` -4. Name it `rds-connect` and create this policy +#### Step 3: Setup EC2 Instance with IAM Role -#### Create IAM User +1. **Attach IAM Role to EC2** + - New instances: Select `bytebase-rds-role` during launch configuration + - Existing instances: EC2 console → Actions → Security → Modify IAM role → Select `bytebase-rds-role` -1. Go to **IAM > Users** and click **Create user**. Name it `rds-connector` - ![](/content/docs/get-started/instance/aws-rds-iam/create-user.webp) +2. **Deploy Bytebase** + - Install Bytebase on your EC2 instance + - No AWS credentials configuration needed - the IAM role provides automatic authentication -2. Choose **Attach policy directly** and select the `rds-connect` policy. Click **Next** and then click **Create user** - ![](/content/docs/get-started/instance/aws-rds-iam/attach-policy.webp) +#### Step 4: Create Database User -3. On the user detail page, click **Create access key** - ![](/content/docs/get-started/instance/aws-rds-iam/access-key.webp) +Connect to your RDS instance and create an IAM-authenticated user: -4. Choose `Application running outside AWS` and click **Next** - ![](/content/docs/get-started/instance/aws-rds-iam/app-outside-aws.webp) +**MySQL/Aurora MySQL:** +```sql +CREATE USER 'bytebase'@'%' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS'; +ALTER USER 'bytebase'@'%' REQUIRE SSL; +GRANT ALL PRIVILEGES ON *.* TO 'bytebase'@'%'; +``` -5. Then you get the **access key** and the **secret access key** - ![](/content/docs/get-started/instance/aws-rds-iam/retrieve-access-keys.webp) +**PostgreSQL/Aurora PostgreSQL:** +```sql +CREATE USER bytebase; +GRANT rds_iam TO bytebase; +-- Grant appropriate database permissions as needed +``` -#### Use IAM Auth in Bytebase +Reference: [MySQL setup](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html#UsingWithRDS.IAMDBAuth.DBAccounts.MySQL) | [PostgreSQL setup](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html#UsingWithRDS.IAMDBAuth.DBAccounts.PostgreSQL) -1. Start Bytebase with AWS IAM credentials by passing the AWS environment variables: +#### Step 5: Connect from Bytebase - ```bash - docker run --init \ - -e AWS_ACCESS_KEY_ID=<> \ - -e AWS_SECRET_ACCESS_KEY=<> \ - -e AWS_REGION=<> \ - ... - ``` +Configure the database connection in Bytebase: -2. Go to RDS instance detail page, you'll find the **endpoint** and **port** - ![](/content/docs/get-started/instance/aws-rds-iam/mysql-connection.webp) +1. Click **New Instance** in Bytebase +2. Enter connection details: + - **Host:** Your RDS endpoint (found in RDS console) + - **Port:** 3306 (MySQL) or 5432 (PostgreSQL) + - **Username:** `bytebase` + - **Authentication:** Select `AWS RDS IAM` -3. Configure instance connection using `AWS RDS IAM`, create the `bytebase` user with `AWSAuthenticationPlugin` and grant permissions: +3. Test and save the connection - ```sql - -- For MySQL/Aurora MySQL - CREATE USER bytebase@'%' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS'; - ALTER USER 'bytebase'@'%' REQUIRE SSL; - ``` +Bytebase automatically handles IAM token generation and refresh using the EC2 instance role. -4. Use the instance endpoint, port and the username `bytebase` to connect the instance + +IAM authentication tokens expire after 15 minutes, but Bytebase automatically refreshes them using the instance profile. Learn more about [IAM database authentication limitations](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html#UsingWithRDS.IAMDBAuth.Limitations). + ### AWS Secrets Manager