Introduction

This article describes how to use an Amazon Web Service (AWS) Simple Storage Service (S3) bucket in order to host the CentreStack backend storage for a single CentreStack tenant. In an effort to follow the "principle of least privilege", this configuration will use an AWS Identity and Access Management (IAM) user that is limited to accessing only a single S3 bucket in an AWS account. This IAM account could be thought of as a "service account", for the benefit of the CentreStack service.

Configuration

Create a S3 Bucket

1. Sign into the AWS portal and navigate to the S3 console. 
2. Click the Create bucket button:
   
3. Fill out the fields in the Create bucket UI:
   1. The Bucket name must follow DNS naming conventions and be globally unique. In this example the bucket name "cstack-bes-hadroncloud" was used. It indicates the company (cstack), that's its purpose is backend storage (bes), and the tenant name (hadroncloud). it may be wise to use some sort of bucket naming convention when there are mutiple CentreStack tenants with buckets in the same AWS account.
   2. Select an AWS Region that is in the same region as the CentreStack server if CentreStack is hosted at AWS, or a region that is closest geographically to the CentreStack server if not hosted in AWS.
   3. There is likely no need to copy settings from an existing bucket.
   4. Click the Next button:
      
      
4. In the next panel:
   1. Make sure that Versioning is disabled because CentreStack has it's own versioning built in. It's normally disabled by default.
   2. The other settings should most likely be disabled unless you have a business reason to enable them.
   3. Click the Next button:
      
5. In the next panel,
   1.  Keep the defaults with all options enabled to prevent public access to the bucket.
   2. Click the Next button:
      
6. Review the settings then click the Create bucket button:
   
7. Click the on the bucket name in the S3 console:
   
8. Notice the bucket is currently empty:
   
9. In the AWS portal, navigate to the IAM service.
10. Click the Policies node:
    
11. Click the Create policy button:
    
12. The "Visual editor" is too slow. Click on the JSON tab:
    
13. AWS provides an example of the necessary IAM policy here: 
    https://docs.aws.amazon.com/AmazonS3/latest/dev/example-policies-s3.html#iam-policy-ex0
14. Copy this text from the AWS documentation:
    

    
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "s3:ListAllMyBuckets"
                ],
                "Resource": "arn:aws:s3:::*"
            },
            {
                "Effect": "Allow",
                "Action": [
                    "s3:ListBucket",
                    "s3:GetBucketLocation"
                ],
                "Resource": "arn:aws:s3:::examplebucket"
            },
            {
                "Effect": "Allow",
                "Action": [
                    "s3:PutObject",
                    "s3:PutObjectAcl",
                    "s3:GetObject",
                    "s3:GetObjectAcl",
                    "s3:DeleteObject"
                ],
                "Resource": "arn:aws:s3:::examplebucket/*"
            }
        ]
    }
    

15. Paste it into a text editor like Visual Studio Code and save it as a .json file (it will be easier to read).
16. Search and replace all occurrences of examplebucket with the name of the S3 bucket that was created (in this example cstack-bes-hadroncloud). Note that this is not the name of the IAM user but rather the S3 bucket that the IAM user will be granted access to.
17. Select all of the text in the text editor and paste it into the JSON text box in the IAM console, replacing any text that was automatically generated, then click the Review policy button:
    
18. In the Create policy panel,
    1. Set the Name text box to something descriptive (spaces are not allowed)
    2. Set the Description text box to something that explains what this custom policy is allowing
    3. Click the Create policy button:
       
19. Notice the custom policy is listed:
    
20. Click the Users node:
    
21. Click the Add user button at the top of the console:
    
22. In the Add user panel,
    1. In the User name field provide some text that indicates what the "service account" will be used for:
    2. Enable the Programmatic access option
    3. Disable the AWS Management Console access option as this user will not need access to the AWS console.
    4. Click the Next: Permissions button:
       
23. Click the Attach existing policies directly tab:
    
24. Click on the check box next to the "Customer managed" policy that was recently created then click the Next:Review button:
    
25. Review the user and policy that will be attached to the user then click the Create user button:
    
26. Click the Download .csv button:
    
27. The recommendation is to store the Access key ID and Secret access key in a secure place such as LastPass or similar. These keys are information required to sign into AWS programmatically as this IAM user. 
28. Sign into the CentreStack console as the cluster admin.
29. The tenant backend storage can be configured either when the tenant is created or the backend storage can be migrated from the CentreStack server's local disk after the tenant was created with default settings. This article will demonstrate the steps related to the later but the basic configuration of IAM user credentials (Access Key and Secret Key) are very similar. 
30. In the Dashboard for the cluster admin, click on the tenant whose backend storage will be moved to the S3 bucket then click on the ellipsis icon in the Backend Storage section in the lower right corner of the page, then click on the Migrate to new storage option:
    
31. Enable the Use Cloud Storage as enterprise storage option then click the drop down and select Amazon S3 then click the Continue button
    
32. Paste in the Access Key ID and Secret Access Key from the .csv file that was downloaded from the AWS IAM console. In this way, CentreStack will authenticate to AWS as the IAM user that was created specifically to access the S3 bucket. Leave the Enable Inplace Versioning option enabled, then click the Continue button at the bottom of the page:
    
33. Note that in this panel, the {Create New Bucket} is a drop-down control because the UI allows the user to either create a new S3 bucket, or select an existing bucket. For this case, we will select an existing bucket, so click on the drop down:
    
34. Once the existing S3 bucket is selected from the drop-down the UI will change to reflect the selection, then click the Finish button at the bottom of the page:
    
35. The defaults are most likely sufficient. Click the Continue button to perform the migration:
    
36. The migrate task will be displayed:
    
37. If a large amount of data is being migrated this process could take some time. Click the Refresh button to update the current status. When the task is complete, there will be a green check mark displayed:
    
38. Click the Download log file button:
    
39. View the log in a text editor:
    

    [info]Started:3/21/2018 11:03:26 AM
    [info]Finished:3/21/2018 11:03:27 AM

40. Once you are confident the task is complete, delete the task by clicking the X button:
    
41. If you view the S3 bucket in the AWS portal you will see that it is no longer empty.
42. A process similar to this could be used to create a CentreStack Team Folder that points to an AWS S3 bucket.