diff --git a/public/images/gen2/storage/s3-console-permissions.png b/public/images/gen2/storage/s3-console-permissions.png new file mode 100644 index 00000000000..159cde1cde1 Binary files /dev/null and b/public/images/gen2/storage/s3-console-permissions.png differ diff --git a/src/directory/directory.mjs b/src/directory/directory.mjs index ef3a5e7fbc5..5aab7e295d8 100644 --- a/src/directory/directory.mjs +++ b/src/directory/directory.mjs @@ -332,6 +332,9 @@ export const directory = { { path: 'src/pages/[platform]/build-a-backend/storage/use-aws-sdk/index.mdx' }, + { + path: 'src/pages/[platform]/build-a-backend/storage/use-with-custom-s3/index.mdx' + }, { path: 'src/pages/[platform]/build-a-backend/storage/data-usage/index.mdx' } diff --git a/src/pages/[platform]/build-a-backend/storage/use-with-custom-s3/index.mdx b/src/pages/[platform]/build-a-backend/storage/use-with-custom-s3/index.mdx new file mode 100644 index 00000000000..fdfa9ee9621 --- /dev/null +++ b/src/pages/[platform]/build-a-backend/storage/use-with-custom-s3/index.mdx @@ -0,0 +1,129 @@ +import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; + +export const meta = { + title: 'Use Amplify Storage with any S3 bucket', + description: 'You can use the Amplify Storage APIs against your own S3 bucket in your account.', + platforms: [ + 'javascript', + 'react', + 'react-native', + 'angular', + 'vue', + 'nextjs', + 'swift', + 'android', + 'flutter' + ] +}; + +export const getStaticPaths = async () => { + return getCustomStaticPath(meta.platforms); +}; + +export function getStaticProps(context) { + return { + props: { + platform: context.params.platform, + meta + } + }; +} + +With Amplify Storage APIs, you can use your own S3 buckets instead of the Amplify-created ones. + + + +**Important:** To utilize the storage APIs with an S3 bucket outside of Amplify, you must have Amplify Auth configured in your project. + + + +## Step 1 - Add necessary permissions to the S3 bucket + +For the specific Amazon S3 bucket that you want to use with these APIs, you need to make sure that the associated IAM role has the necessary permissions to read and write data to that bucket. + +To do this, go to **Amazon S3 console** > **Select the S3 bucket** > **Permissions** > **Edit** Bucket Policy. + +![Showing Amplify console showing Storage tab selected](/images/gen2/storage/s3-console-permissions.png) + +The policy will look something like this + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "Statement1", + "Principal": { "AWS": "arn:aws:iam:::role/" }, + "Effect": "Allow", + "Action": [ + "s3:PutObject", + "s3:GetObject", + "s3:DeleteObject", + "s3:ListBucket" + ], + "Resource": [ + "arn:aws:s3:::/*" + ] + } + ] +} +``` +Replace `` with your AWS account ID and `` with the IAM role associated with your Amplify Auth setup. Replace `` with the S3 bucket name. + +You can refer to [Amazon S3's Policies and Permissions documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html) for more ways to customize access to the bucket. + +## Step 2 - Specify S3 bucket in Amplify's backend config + +Next, use the `addOutput` method from the backend definition object to define a custom s3 bucket by specifying the name and region of the bucket in your **amplify/backend.ts** file. + + + +**Important** + +You cannot use both a storage backend configured through Amplify and a custom S3 bucket at the same time. + +If you specify a custom S3 bucket, no sandbox storage resource will be created. The provided custom S3 bucket will be used, even in the sandbox environment. + + + +```javascript + +import { defineBackend } from '@aws-amplify/backend'; +import { auth } from './auth/resource'; +import { data } from './data/resource'; + +const backend = defineBackend({ + auth, + data, +}); + +//highlight-start +backend.addOutput({ + storage: { + aws_region: "", + bucket_name: "" + }, +}); +//highlight-end + +``` + + + +## Step 3 - Import latest amplify_outputs.json file + +To ensure the local **amplify_outputs.json** file is up-to-date, you can run [the npx ampx generate outputs command](/[platform]/reference/cli-commands/#npx-ampx-generate-outputs) or download the latest **amplify_outputs.json** from the Amplify console as shown below. + +![outputs](/images/gen2/getting-started/react/amplify-outputs-download.png) + + + + + +## Step 3 - Import latest amplifyconfiguration.dart file + +To ensure the local **amplifyconfiguration.dart** file is up-to-date, you can run [the npx ampx generate outputs command](/[platform]/reference/cli-commands/#npx-ampx-generate-outputs). + + + +Now that you've configured the necessary permissions, you can start using the storage APIs with your chosen S3 bucket.