GRAX Documentation

The GRAX Documentation Hub

Welcome to the GRAX Documentation hub. You'll find comprehensive guides and walkthroughs to help you start working with GRAX as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

AWS S3 Configuration

Set up your S3 Bucket and provide access as needed. S3, if you choose to go with AWS, will serve as the primary long term storage option for GRAX.

Introduction

If you have decided to use Amazon S3 as your preferred long term storage, you will need to create an S3 bucket and a credential that can only access that bucket. Typically, we name the bucket/policy/user the exact same name. Some customers like to create separate buckets for QA environment vs Production environment. This article has sample steps to do this within AWS management console and should take < 5 minutes to complete.

S3 Bucket Instructions

  1. Login to the AWS Console for your company
  2. Navigate to S3 service
  3. Create S3 Bucket according to AWS documentation
  • Name Example: grax-customerX-uat
  • Follow region selection instructions below

🚧

Choosing a Region

Please choose a region for the bucket that is closest to the region of your heroku app. The heroku config variable that stores the region information will use the value from the 2nd column (Region) in the link below.

For example: Region Name "US East (Ohio)" would use Region "us-east-2" as the configuration variable.

Here is a list of the AWS region names and their related API names:

AWS Regions and Endpoints

Supported Authentication Methods

There are 2 ways to access S3 bucket: using Static Keys, or using IAM Assumed Role.

S3 Access Using Static Keys

🚧

Change the “Resource” value from the example below to point to your bucket name.

  1. Create an IAM Policy
    a. Click create policy
    b. Click tab JSON -
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": "s3:*",
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::grax-customerx-uat",
                "arn:aws:s3:::grax-customerx-uat/*"
            ]
        }
    ]
}

c. Click Review Policy
d. Name: grax-customerX-uat
e. Click Create Policy

  1. Create an IAM user, per AWS Documentation
    a. Click Add User
    b. User Name : grax-customerX-uat
    c. Checkbox – Programmatic Access
    d. Click – Attach existing policies directly
    e. Search - grax-customerX-uat
    f. Click – Next Review
    g. Click – Create User

  2. At the end of the process you will need following information:

  • User: Access key ID
  • User: Secret access key
  • S3 – Region
  • S3 – Bucket Name

S3 Access Using IAM Assume Role

Accessing S3 through IAM Assume Role does not use Static Keys. Instead, the customer provides “Role ARN” and the application generates the temporary credentials using Role ARN to access the customer S3 bucket. This can be done by following the steps below.

Learn more about how AWS supports delegating access across AWS accounts using IAM roles.

Step 1: Create a policy to access the S3 bucket

Login to AWS root user -> IAM -> Policy -> Create policy and copy the below policy.

Ex: SwitchUserBucketPolicy

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": "s3:*",
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::grax-customerx-uat",
                "arn:aws:s3:::grax-customerx-uat/*"
            ]
        }
    ]
}

🚧

Change the “Resource” value from the above example to point to your bucket name.

Step 2: Create a role and attach the above created bucket policy

2.1. Goto IAM -> Roles -> Create Role

2.2. Select Another AWS Account option from create role page

2.3. In Account ID, enter the AWS account ID for GRAX. This will be provided to you during implementation.

2.4. Optionally select the Required External ID checkbox in order to secure using external ID (this is optional). If this option is selected please share the external ID along with Role with GRAX team.

2.5. Click on Next:Permissions button

2.6. Attach the policy created on step 1 (SwitchUser BucketPolicy)

2.7. Click on Next:Tags”-> “Next:Review

2.8. Enter a Role Name (Ex: CrossAcc-359891290464 )

2.9. Enter a Role descriptions and click on Create Role Button

2.10. Copy the Role ARN and share it with GRAX team to create a trust relation between Customer AWS account and GRAX AWS account.

2.11 The GRAX team will create a child account for your organization with a single user which will be used to assume the role you have created. The Access Key ID and Secret Access Key will be provided to you during implementation.

Supported Encryption Configurations

GRAX supports AES:256 and KMS encryption on AWS. Keep in mind that these are optional configuration that may come with additional operational cost

Minimum Required Policy Actions

Please reference the below sample policy to be sure your IAM policy allows at minimum, the below actions, otherwise GRAX may not have sufficient access.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::sample-s3bucket-test"
            ],
            "Effect": "Allow"
        },
        {
            "Action": [
                "s3:DeleteObject",
                "s3:GetObject",
                "s3:PutObject"
            ],
            "Resource": [
                "arn:aws:s3:::sample-s3bucket-test/*"
            ],
            "Effect": "Allow"
        }
    ]
}

Updated 3 months ago

AWS S3 Configuration


Set up your S3 Bucket and provide access as needed. S3, if you choose to go with AWS, will serve as the primary long term storage option for GRAX.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.