feat: Decide on Secrets Placement for Terraform (#702)

Co-authored-by: Erik Osterman (CEO @ Cloud Posse) <[email protected]>

Author: milldr

docs/layers/project/design-decisions/decide-on-secrets-management-placement.mdx

@@ -0,0 +1,55 @@
+---
+title: "Decide on Secrets Placement for Terraform"
+sidebar_label: "Secrets Placement"
+sidebar_position: 5
+refarch_id: REFARCH-81
+description: "Decide where to store secrets used by Terraform"
+---
+import Intro from '@site/src/components/Intro';
+
+<Intro>
+We need to decide where to store secrets used by Terraform. We have two options: store secrets in each account or store them in a centralized account.
+</Intro>
+
+## Context
+
+Often we need to integrate with third-party services or internal services that require API keys or other secrets. We need to decide where to store these secrets so that Terraform can access them. There are two reasonable options for storing secrets in our AWS account architecture. We need to decide which one to use.
+
+### Option 1: Store Secrets in each account
+
+The first option is to store the credential in the same account as the resource. For example, API keys scoped to `dev` would live in `plat-dev`.
+
+#### Pros
+
+- Accounts can easily access their given credentials
+- IAM level boundaries are enforced between accounts
+
+#### Cons
+
+- Secret administrators need to access many accounts to create those secrets
+- There is no centralized management for all secrets out there
+
+### Option 2: Store Credentials in a Centralized Account
+
+The second option is to store the credentials in a centralized account, such as `corp` or `auto`. Now you would need to share those credentials with each account, for example with [AWS RAM](https://aws.amazon.com/ram/).
+
+#### Pros
+
+- Centralized secrets management
+- Secret administrators have a single place to manage secrets
+- Once shared, resources in a given account still access their given secrets from their own account. They do not need to reach out to another account
+
+#### Cons
+
+- Complexity with AWS RAM
+- Secret administrators must be careful to share secrets with the correct accounts
+- You need to decide what account to use as the centralized management account. We could deploy `corp` if you'd like for this or reuse `auto`.
+
+## Decision
+
+We will use AWS SSM Parameter Store for all platform-level secrets used by `infrastructure` and `terraform`.
+
+## Related
+
+- [Decide on Secrets Strategy for Terraform](/layers/project/design-decisions/decide-on-secrets-management-strategy-for-terraform/)
+

docs/layers/project/design-decisions/decide-on-secrets-management-strategy-for-terraform.mdx

@@ -3,13 +3,13 @@ title: "Decide on Secrets Management Strategy for Terraform"
 sidebar_label: "Secrets Management"
 sidebar_position: 5
 refarch_id: REFARCH-81
-description: "Decide where to manage secrets used by Terraform"
+description: "Decide how to manage secrets used by Terraform"
 ---
 import Intro from '@site/src/components/Intro';
 import KeyPoints from '@site/src/components/KeyPoints';
 
 <Intro>
-Deciding where to store secrets is crucial for securing both platform integration and application data when using Terraform. The appropriate secret store depends on the stack layer and must account for situations where other infrastructure might not yet be in place (e.g. Vault, Kubernetes, etc).
+Deciding how to store secrets is crucial for securing both platform integration and application data when using Terraform. The appropriate secret store depends on the stack layer and must account for situations where other infrastructure might not yet be in place (e.g. Vault, Kubernetes, etc).
 </Intro>
 
 We need to decide where secrets will be kept. We’ll need to be able to securely store platform integration secrets (e.g. master keys for RDS, HashiCorp Vault unseal keys, etc) as well as application secrets (any secure customer data).
@@ -20,10 +20,13 @@ like ASM/SSM is required.
 - e.g. Vault deployed as helm chart in each tenant environment using KMS keys for automatic unsealing (this chart
   already exists)
 
-- SSM Parameter Store + KMS for all platform-level secrets used by `infrastructure` and `terraform`
+- SSM Parameter Store + KMS for all platform-level secrets used by `infrastructure` and Terraform
 
-- AWS Secrets Manager supports automatic key rotation which almost nothing other than RDS supports and requires
-  applications to be modified in order to use it to the full extent.
+- AWS Secrets Manager supports automatic key rotation which almost nothing other than RDS supports and requires applications to be modified in order to use it to the full extent.
+
+## Recommendation
+
+We will use AWS SSM Parameter Store for all platform-level secrets used by `infrastructure` and Terraform.
 
 ## Related