Connecting Storage

There are a couple cases in which you need to connect GRAX to a longterm storage provider:

1. New GRAX installations
2. Changing storage credentials
3. Moving to a different container/bucket/provider

Regardless of need, the storage configuration is always accessed the same way.

Data Loss and Corruption Possible

Never change your connected storage target in production without consulting with the GRAX support team. Changing the storage target after starting data backups risks corruption and/or loss of the entire dataset. For more information about how GRAX stores your data, see here.

Connecting to Supported Storage

The GRAX app currently supports S3, S3-compatible, Azure Blob, and GCP cloud storage containers. The Storage Settings module allows you to choose the desired platform and adjusts the input form to match.

On AWS, GRAX supports the use of credential-less instance roles by entering no access key or secret via the configuration form. For all other configurations or providers, you'll need access to the storage credentials to fill and save the form. After saving, the app takes a minute or two to reboot and reconfigure.

Once successfully connected, the module has a green "connected" indicator.

Special Cases

Using EC2 Instance Role

EC2 instances are deployed with an assigned Instance Role. If your bucket and EC2 Instance/Role are located in the same AWS account, it's beneficial to use this Instance Role as the authentication method for S3 traffic. This allows you to authenticate GRAX with the bucket without a set of static IAM keys ever existing.

To connect to an S3 bucket via the Instance Role, fill in only the "Bucket Name" and "Bucket Region" fields of the storage configuration. The AWS SDK resolves the Instance Role credential provider and connects as long as the role has appropriate access.

Using AWS Assume Role

GRAX supports the use of AWS Assume Role for authentication into secondary accounts. This allows the S3 permissions to be managed in the account that owns the bucket and GRAX to be connected without static keys. The role or user that GRAX is authenticating with locally must be allowed to assume the remote role; this is managed in the account that owns the bucket and assumed role.

To configure the AWS resources for Assume Role with a GRAX-Hosted app, follow the steps below. For non-standard deployments, the process is similar, but GRAX involvement isn't required.

1. Retrieve the Instance Role ARN from GRAX.

   Open a GRAX Support ticket explaining the intention to use Assume Role for a GRAX Hosted app, if necessary. GRAX provides the ARN of an IAM role that must be allowed to assume the IAM role you'll create in the next step.

2. In your AWS account, create the S3 Policy with the template below, replacing {BUCKET_ARN} and {KMS_ARN} as needed. (AWS Documentation)

   NOTE: the KMS permissions and key mentioned in this template are only required if you plan to use KMS to encrypt S3 data differently than the default AES-256. (AWS Documentation)

   JSON

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Action": [
                   "kms:Decrypt",
                   "kms:DescribeKey",
                   "kms:Encrypt",
                   "kms:GenerateDataKey*",
                   "kms:ReEncrypt*"
               ],
               "Resource": "{KMS_ARN}",
               "Effect": "Allow"
           },
           {
               "Action": [
                   "s3:ListBucket"
               ],
               "Resource": "{BUCKET_ARN}",
               "Effect": "Allow"
           },
           {
               "Action": [
                   "s3:DeleteObject",
                   "s3:GetObject",
                   "s3:PutObject"
               ],
               "Resource": "{BUCKET_ARN}/*",
               "Effect": "Allow"
           }
       ]
   }
   

3. In your AWS account, create an IAM Role that trusts the provided Instance Role ARN and attach the policy from the preceding step. (AWS Documentation)

4. Provide the ARN of the role you created in the previous step to GRAX Support. GRAX Engineering creates the necessary IAM resources to allow the instance to assume that role.

5. Enter the "Bucket Name" and "Bucket Region" fields and enable "Use Assume Role" on the storage settings panel. Enter the remote role's ARN into the "Assume Role ARN" field, as well as an external ID if enabled during role creation.

What's Next?

If you've made it here through installing GRAX and connecting to Salesforce, you're now all set to start backing up and harnessing your data. See Auto Backup documentation for more information on getting data backed up to GRAX.