Update documentation to clarify support for multiple AWS accounts and multiple applications

.github/workflows/template-only-cd.yml

@@ -34,7 +34,7 @@ jobs:
 
       - name: Update infra template
         working-directory: project-repo
-        run: ../template-infra/template-only-bin/update-template.sh
+        run: ../template-infra/template-only-bin/update-template.sh app
 
       - name: Push changes to project repo
         working-directory: project-repo

README.md

@@ -2,63 +2,51 @@
 
 ## Overview
 
-This is a template repository to set up foundational infrastructure for your application in AWS. It is part of a collection of interoperable [Platform templates](https://github.com/navapbc/platform).
+This template sets up foundational infrastructure for applications hosted on Amazon Web Services (AWS). It belongs to a collection of interoperable [Platform templates](https://github.com/navapbc/platform).
 
-This template includes setup for:
+This template includes:
 
-* **Team workflows** - templates for pull requests (PRs), architecture decision records (ADRs), and Makefiles.
-* **Account level foundational infrastructure** - infrastructure for terraform backends, including an S3 bucket and DynamoDB table for storing and managing terraform state files.
-* **Application infrastructure** - the infrastructure you need to set up a basic web app, such as a image container repository, load balancer, web service, and database.
-* **CI for infra** - GitHub action that performs infra code checks, including linting, validation, and security compliance checks.
-* **CD / Deployments** - infrastructure for continuous deployment, including: AWS account access for Github actions, scripts for building and publishing release artifacts, and a Github action for automated deployments from the main branch.
-* **Documentation** - technical documentation for the decisions that went into all the defaults that come with the template.
+* **Team workflows** - templates for pull requests (PRs), architecture decision records (ADRs), and Makefiles
+* **Account level foundational infrastructure** - infrastructure for Terraform backends, including an S3 bucket and DynamoDB table for storing and managing Terraform state files
+* **Application infrastructure** - the infrastructure you need to set up a basic web app, including container image repository, load balancer, web service, and database
+* **Continuous integration (CI) for infrastructure** - GitHub action that performs infrastructre code checks, including linting, validation, and security compliance checks
+* **Continous deployment (CD)** - infrastructure for continuous deployment, including AWS account access for Github actions, scripts for building and publishing release artifacts, and a Github action for automated deployments from the main branch
+* **Documentation** - technical documentation for the decisions that went into all the defaults that come with the template
 
-The system architecture will look like this (see [system architecture documentation](/docs/system-architecture.md) for more information):
+By default, the system architecture looks like this (for more information, see [system architecture documentation](/docs/system-architecture.md)):
 ![System architecture](https://lucid.app/publicSegments/view/e5a36152-200d-4d95-888e-4cdbdab80d1b/image.png)
 
 ## Application Requirements
 
-This template assumes that you have an application to deploy. See [application requirements](./template-only-docs/application-requirements.md) for more information on what is needed to use the infrastructure template. If you're using one of the [Platform application templates](https://github.com/navapbc/platform?tab=readme-ov-file#platform-templates), these requirements are already met.
+Applications must meet [these requirements](/template-only-docs/application-requirements.md) to be used with this template. If you're using a [Platform application template](https://github.com/navapbc/platform?tab=readme-ov-file#platform-templates), these requirements are already met.
+
+### Multiple Applications
+
+You can use this template with multiple applications. By default, this template assumes your project has one application named `app`. However, it's straightforward to [add additional applications](/template-only-docs/multiple-applications.md).
 
 ## Installation
 
-To get started using the infrastructure template on your project, run the following command in your project's directory to execute the [download and install script](https://github.com/navapbc/template-infra/tree/main/template-only-bin/download-and-install-template.sh), which clones the template repository, copies the template files to your repository, and removes any files that are only relevant to the template itself:
+This template assumes that you already have an application to deploy.
+
+To install this template to your project, run the following command in your project's root directory:
 
 ```bash
 curl https://raw.githubusercontent.com/navapbc/template-infra/main/template-only-bin/download-and-install-template.sh | bash -s
 ```
 
+The [download and install script](/template-only-bin/download-and-install-template.sh) clones this template repository, copies the template files to your repository, and removes files that are only relevant to the template itself.
+
 Now you're ready to set up the various pieces of your infrastructure.
 
 ## Setup
 
-After downloading and installing the template into your project:
+After downloading and installing this template into your project, take the following steps to complete setup:
 
-1. Follow the steps in [infra/README.md](/infra/README.md) to setup the infrastructure for your application.
-1. After setting up AWS resources, you can [set up GitHub Actions workflows](./template-only-docs/set-up-ci.md).
-1. After configuring GitHub Actions, you can [set up continuous deployment](./template-only-docs/set-up-cd.md).
-1. At any point, [set up your team workflow](./template-only-docs/set-up-team-workflow.md).
+1. Follow the "First time initialization" steps in [infra/README.md](/infra/README.md).
+2. [Set up continuous integration](./template-only-docs/set-up-ci.md).
+3. [Set up continuous deployment](./template-only-docs/set-up-cd.md).
+4. At any point, [set up your team workflow](./template-only-docs/set-up-team-workflow.md).
 
 ## Updates
 
-There are multiple ways to receive template updates on your project. For most updates, you can simply run the [update-template.sh](/template-only-bin/update-template.sh) script
-
-```bash
-curl https://raw.githubusercontent.com/navapbc/template-infra/main/template-only-bin/update-template.sh | bash -s
-```
-
-If the update fails the simplest option may be to re-run the installation script above and manually review the changes.
-
-**Remember:** Make sure to read the release notes in case there are breaking changes you need to address.
-
-### Renamed applications
-
-If you renamed your application from `infra/app` to something else like `infra/foo`, then first rename your app back to `infra/app` before applying the updates e.g.
-
-```bash
-mv foo app
-mv infra/foo infra/app
-curl https://raw.githubusercontent.com/navapbc/template-infra/main/template-only-bin/update-template.sh | bash -s
-mv infra/app infra/foo
-mv app foo
-```
+This template includes a script to update your project to a newer version of the template.  To update your project to a newer version of this template, follow the [update template instructions](/template-only-docs/update-template.md).

docs/infra/database-access-control.md

@@ -5,7 +5,7 @@
 The master user password is managed by Amazon RDS and Secrets Manager. Managing RDS master user passwords with Secrets Manager provides the following security benefits:
 
 * RDS rotates database credentials regularly, without requiring application changes.
-* Secrets Manager secures database credentials from human access and plain text view. The master password is not even in the terraform state file.
+* Secrets Manager secures database credentials from human access and plain text view. The master password is not even in the Terraform state file.
 
 For more information about the benefits, see [Benefits of managing master user passwords with Secrets Manager](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-secrets-manager.html#rds-secrets-manager-benefits).
 

docs/infra/destroy-infrastructure.md

@@ -11,7 +11,7 @@ To destroy everything you'll need to undeploy all the infrastructure in reverse
    $ terraform destroy -var-file=dev.tfvars
    ```
 
-2. Then to destroy the backends, first you'll need to add `force_destroy = true` to the S3 buckets, and update the lifecycle block to set `prevent_destroy = false`. Then run `terraform apply` from within the `infra/accounts` directory. The reason we need to do this is because S3 buckets by default are protected from destruction to avoid loss of data. See [Terraform: Destroy/Replace Buckets](https://medium.com/interleap/terraform-destroy-replace-buckets-cf9d63d0029d) for a more in-depth explanation.
+2. Then to destroy the backends, first you'll need to add `force_destroy = true` to the S3 buckets, and update the lifecycle block to set `prevent_destroy = false`. Then run `terraform apply` from within the `/infra/accounts` directory. The reason we need to do this is because S3 buckets by default are protected from destruction to avoid loss of data. See [Terraform: Destroy/Replace Buckets](https://medium.com/interleap/terraform-destroy-replace-buckets-cf9d63d0029d) for a more in-depth explanation.
 
    ```terraform
    # infra/modules/modules/terraform-backend-s3/main.tf
@@ -46,13 +46,13 @@ To destroy everything you'll need to undeploy all the infrastructure in reverse
    }2
    ```
 
-4. Then run the following from within the `infra/accounts` directory to copy the `tfstate` back to a local `tfstate` file:
+4. Then run the following from within the `/infra/accounts` directory to copy the `tfstate` back to a local `tfstate` file:
 
    ```bash
    terraform init -force-copy
    ```
 
-5. Finally, you can run `terraform destroy` within the `infra/accounts` directory.
+5. Finally, you can run `terraform destroy` within the `/infra/accounts` directory.
 
    ```bash
    terraform destroy

docs/infra/intro-to-terraform.md

@@ -16,7 +16,7 @@ The `terraform destroy` command is a convenient way to destroy all remote object
 
 ⚠️ WARNING! ⚠️ This is a destructive command! As a best practice, it's recommended that you comment out resources in non-development environments rather than running this command. `terraform destroy` should only be used as a way to clean up a development environment. e.g. a developer's workspace after they are done with it.
 
-For more information about terraform commands follow the link below:
+For more information about Terraform commands follow the link below:
 
 - [Basic CLI Features](https://www.terraform.io/cli/commands)
 

docs/infra/making-infra-changes.md

@@ -2,7 +2,7 @@
 
 ## Requirements
 
-First read [Module Architecture](./module-architecture.md) to understand how the terraform modules are structured.
+First read [Module Architecture](./module-architecture.md) to understand how the Terraform modules are structured.
 
 ## Using make targets (recommended)
 
@@ -34,9 +34,9 @@ TF_CLI_ARGS_apply='-input=false -auto-approve' make infra-update-app-service APP
 TF_CLI_ARGS_apply='-var=image_tag=abcdef1' make infra-update-app-service APP_NAME=app ENVIRONMENT=dev
 ```
 
-## Using terraform CLI wrapper scripts
+## Using Terraform CLI wrapper scripts
 
-An alternative to using the Makefile is to directly use the terraform wrapper scripts that the Makefile uses:
+An alternative to using the Makefile is to directly use the Terraform wrapper scripts that the Makefile uses:
 
 ```bash
 project-root$ ./bin/terraform-init.sh app/service dev
@@ -48,7 +48,7 @@ Look in the script files for more details on usage.
 
 ## Using Terraform CLI directly
 
-Finally, if the wrapper scripts don't meet your needs, you can always run `terraform` directly from the root module directory. You may need to do this if you are running terraform commands other than `terraform plan` and `terraform apply`, such as `terraform import`, `terraform taint`, etc. To do this, you'll need to pass in the appropriate `tfvars` and `tfbackend` files to `terraform init` and `terraform apply`. For example, to make changes to the application's service resources in the dev environment, cd to the `infra/app/service` directory and run:
+Finally, if the wrapper scripts don't meet your needs, you can always run `terraform` directly from the root module directory. You may need to do this if you are running Terraform commands other than `terraform plan` and `terraform apply`, such as `terraform import`, `terraform taint`, etc. To do this, you'll need to pass in the appropriate `.tfbackend` files to `terraform init` and `terraform apply`. For example, to make changes to the application's service resources in the dev environment, change to the `/infra/app/service` directory and run:
 
 ```bash
 infra/app/service$ terraform init -backend-config=dev.s3.tfbackend

docs/infra/module-architecture.md

@@ -85,7 +85,7 @@ When deciding which layer to put an infrastructure resource in, follow the follo
 
 * **Consider policy constraints on what resources the project team is authorized to manage:** Different categories of resources may have different requirements on who is allowed to create and manage those resources. Resources that the project team are not allowed to manage directly should not be mixed with resources that the project team needs to manage directly.
 
-* **Consider out-of-band dependencies:** Put infrastructure resources that require steps outside of terraform to be completed configured in layers that are upstream to resources that depend on those completed resources. For example, after creating a database cluster, the database schemas, roles, and privileges need to be configured before they can be used by a downstream service. Therefore database resources should be separate from the service layer so that the database can be configured fully before attempting to create the service layer resources.
+* **Consider out-of-band dependencies:** Put infrastructure resources that require steps outside of Terraform to be completed configured in layers that are upstream to resources that depend on those completed resources. For example, after creating a database cluster, the database schemas, roles, and privileges need to be configured before they can be used by a downstream service. Therefore database resources should be separate from the service layer so that the database can be configured fully before attempting to create the service layer resources.
 
 ## Making changes to infrastructure
 

docs/infra/service-command-execution.md

@@ -6,57 +6,44 @@ The infrastructure supports developer access to a running application's service
 
 ## Prerequisites
 
-* You'll need to have [set up infrastructure tools](./set-up-infrastructure-tools.md), like Terraform, AWS CLI, and AWS authentication
-* You'll need to have set up the [app environments](./set-up-app-env.md)
-* You'll need to have [installed the Session Manager plugin for the AWS CLI](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)
+* You have [set up infrastructure tools](./set-up-infrastructure-tools.md), like Terraform, AWS CLI, and AWS authentication.
+* You are [authenticated into the AWS account](./set-up-infrastructure-tools.md#authenticate-with-aws) you want to configure.
+* You have [set up the application service](./set-up-app-service.md).
+* You have [installed the Session Manager plugin for the AWS CLI](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html).
 
 ## Instructions
 
-### 1. Make sure you're authenticated into the AWS account that the ECS container is running in
-
-This takes effect in whatever account you're authenticated into. To see which account that is, run
-
-```bash
-aws sts get-caller-identity
-```
-
-To see a more human readable account alias instead of the account, run
-
-```bash
-aws iam list-account-aliases
-```
-
-### 2. Enable service execution access
+### 1. Enable service execution access
 
 Within the `app-config` directory (e.g. `infra/<APP_NAME>/app-config`), each environment has its own config file named after the environment. For example, if the application has three environments `dev`, `staging`, and `prod`, it should have corresponding `dev.tf`, `staging.tf`, and `prod.tf` files.
 
 In the environment config file for the environment that you want to enable service access, set `enable_command_execution` to `true`.
 
-### 3. Update the network
+### 2. Update the network
 
-To enable service execution access, the VPC requires an additional VPC endpoint. Update the network by running
+The VPC requires an additional VPC endpoint. To update the network, run:
 
 ```bash
 make infra-update-network NETWORK_NAME=<NETWORK_NAME>
 ```
 
-`ENVIRONMENT` needs to be the name of the network that the application environment is running in.
+`<NETWORK_NAME>` must be the name of the network that the application is running in.
 
-### 4. Update the application service
+### 3. Update the application service
 
-To enable service execution access, some configuration changes need to be applied to the ECS Task Definition. Update the service by running
+To update the ECS Task Definition to allow command execution, run:
 
 ```bash
 make infra-update-app-service APP_NAME=<APP_NAME> ENVIRONMENT=<ENVIRONMENT>
 ```
 
-`APP_NAME` needs to be the name of the application folder within the `infra` folder.
+`<APP_NAME>` must be the name of the application folder within the `/infra` folder.
 
-`ENVIRONMENT` needs to be the name of the environment to update.
+`<ENVIRONMENT>` must be the name of the environment to update.
 
-### 5. Execute commands
+### 4. Execute commands
 
-To create an interactive shell, run
+To create an interactive shell, run:
 
 ```bash
 aws ecs execute-command --cluster <CLUSTER_NAME> \