Advanced Installation of SaaS Shield CMK for Amazon S3

The Getting Started instructions will guide you through installing an initial instance of the product in AWS. These instructions are meant to help you proceed with setting up an environment that is more appropriate for your production application.

Per-Region Installation

Like S3 buckets, CloudFormation stacks are created in a single region. If you have buckets owned by a single account in multiple regions, you should use that account and install SaaS Shield CMK for Amazon S3 in each region; the S3 proxy does not allow cross region access of buckets, with the exception of copying an object from a bucket in one region to a bucket in another.

You need to choose a unique domain name for the new instance, so that requests are routed to the appropriate instance of the product. You can create the stacks in each region using the same templates. Stack names are not required to be unique across regions, so you can use the same stack name in each region, if you prefer. We do recommend that instead of using the same TSP Configuration file for each region, you log into the Configuration Broker and create a new Tenant Security Proxy (TSP) for the installation in each region. When you download the deployment files, the TSP Config file contains new values, including new secret keys for encryption and signing. There is not a problem using the same TSP configuration for stacks in multiple regions, but generating a new configuration gives you additional revocation and audit flexibility. The deployment template is identical for each new TSP, so you can create a stack using that template as often as desired.

Multiple Installations in One Region

You can install SaaS Shield CMK for Amazon S3 multiple times in a single region using the same AWS account. A possible use case might be configuring a dev test environment and a separate QA environment. Simply use the correct account in the Configuration Broker to create a TSP and download the deployment files, then use those files to create separate stacks in CloudFormation. As with the other installations, you need to choose a separate DNS domain for for each installation and update your DNS server appropriately, but you can run the instances in the same AWS region with no issues.

Customizing the Installation

We generated the CloudFormation deployment template with the goal of making it easy to create an instance of SaaS Shield CMK for Amazon S3 for testing. To simplify the installation, we minimized the number of available choices and configuration options. After you have worked with the test system and are ready to move toward a production installation, you will probably want to make different choices in your configuration. Some likely adjustments include replacing the test bucket and the test user to access that bucket with the actual buckets and users you will want for production.

Although you could configure an entire installation manually in AWS, we recommend that you use CloudFormation to manage each installation; CloudFormation provides an easy way to upgrade the containers running the S3 proxy and the TSP, gets the networking configured correctly, sets up a CloudWatch log group, and simplifies other essential tasks. To modify the installation, edit the deployment template before using it to create the CloudFormation stack. For instance, you can remove the stanzas labeled S3TargetBucket and S3User if you want to use buckets and users that you already have configured in AWS.

Note, however, that the S3AccessKey in the deployment references the user, so if you remove the S3User, you need to update the UserName in the S3AccessKey properties with the name of the user you want to use for S3 access. Likewise, when the task is created to run the S3 proxy, it sets the S3_CONFIG_BUCKET environment variable to the name of the S3TargetBucket, so you will need to edit that value and specify the name of the bucket where the S3 proxy will create or load its tenant mapping configuration.

If you do modify the CloudFormation template, we recommend keeping the template that we provided as well, ideally in a version control system that can track the changes. As we release updates to the product that change the templates, you will need to identify and merge the changes into your customized templates.

Remember to update the tenant mapping file to match the tenants you will be using with the installation.

Removing Installations

If you have installed a stack and want to remove it, you should follow these steps.

1. Remove the contents of the test bucket associated with the deployment stack. The bucket contains at least the tenant mapping file, and because it is not empty, CloudFormation cannot remove the bucket. Go to the stack in the CloudFormation console, open the Resources tab, and find the entry with logical ID S3TargetBucket.
2. Click the link to open the S3 console for the bucket, and delete its contents. You can leave the bucket; CloudFormation can now remove it, since it is empty.
3. Close the tab for the S3 console, and return to the CloudFormation tab. Find the resource with logical ID S3DNSZone.
4. Click the link to open the Route 53 console for the DNS zone. Delete the record with type CNAME. Now CloudFormation will be able to remove the DNS Zone.
5. Close the tab for the Route 53 console, and return to the CloudFormation tab. Click the Delete button at the top to remove the CloudFormation stack and all the resources that it manages.