From cc494be21dbd278a14d44ef50dc22d9cfbfc69de Mon Sep 17 00:00:00 2001
From: Marcus Robinson <marrobi@microsoft.com>
Date: Tue, 30 Jul 2024 13:56:58 +0100
Subject: [PATCH 1/4] Add `DEPLOY_MODE` variable to deployment scripts and
 documentation

* **.github/workflows/deploy_tre.yml**
  - Add an input for `DEPLOY_MODE` in the workflow
  - Pass the `DEPLOY_MODE` input to the deployment script

* **docs/tre-admins/setup-instructions/workflows.md**
  - Add instructions on using the `DEPLOY_MODE` variable for 'plan' mode deployments via the GitHub UI

* **devops/scripts/terraform_wrapper.sh**
  - Add a check for the `DEPLOY_MODE` variable
  - Execute `terraform plan` without applying if `DEPLOY_MODE` is set to 'plan'
  - Log the plan output to a file

* **docs/tre-admins/setup-instructions/manual-deployment.md**
  - Add instructions on using the `DEPLOY_MODE` variable for 'plan' mode deployments
  - Include examples of setting the `DEPLOY_MODE` variable to 'plan' and 'apply'
---
 .github/workflows/deploy_tre.yml              |  6 ++++++
 devops/scripts/terraform_wrapper.sh           | 20 +++++++++++++++++--
 .../setup-instructions/manual-deployment.md   | 16 +++++++++++++++
 .../setup-instructions/workflows.md           | 10 ++++++++++
 4 files changed, 50 insertions(+), 2 deletions(-)
 mode change 100755 => 100644 devops/scripts/terraform_wrapper.sh

diff --git a/.github/workflows/deploy_tre.yml b/.github/workflows/deploy_tre.yml
index bddea6979f..9557ea256e 100644
--- a/.github/workflows/deploy_tre.yml
+++ b/.github/workflows/deploy_tre.yml
@@ -16,6 +16,11 @@ on:  # yamllint disable-line rule:truthy
         type: environment
         default: CICD
         required: true
+      DEPLOY_MODE:
+        description: The deployment mode to use (plan or apply)
+        type: string
+        default: apply
+        required: true
 
 # This will prevent multiple runs of this entire workflow.
 # We should NOT cancel in progress runs as that can destabilize the environment.
@@ -38,6 +43,7 @@ jobs:
       environmentName: ${{ github.event.inputs.environment || 'CICD' }}
       E2E_TESTS_NUMBER_PROCESSES: 1
       DEVCONTAINER_TAG: 'latest'
+      DEPLOY_MODE: ${{ github.event.inputs.DEPLOY_MODE }}
     secrets:
       AAD_TENANT_ID: ${{ secrets.AAD_TENANT_ID }}
       ACR_NAME: ${{ secrets.ACR_NAME }}
diff --git a/devops/scripts/terraform_wrapper.sh b/devops/scripts/terraform_wrapper.sh
old mode 100755
new mode 100644
index efa02a8078..121ddc8a20
--- a/devops/scripts/terraform_wrapper.sh
+++ b/devops/scripts/terraform_wrapper.sh
@@ -5,7 +5,7 @@ set -e
 function usage() {
     cat <<USAGE
 
-    Usage: $0 [-g | --mgmt-resource-group-name ]  [-s | --mgmt-storage-account-name] [-n | --state-container-name] [-k | --key] [-c | --cmd] [-l | --logfile]
+    Usage: $0 [-g | --mgmt-resource-group-name ]  [-s | --mgmt-storage-account-name] [-n | --state-container-name] [-k | --key] [-c | --cmd] [-l | --logfile] [-d | --deploy-mode]
 
     Options:
         -g, --mgmt-resource-group-name      Management resource group name
@@ -14,6 +14,7 @@ function usage() {
         -k, --key                           Key
         -c, --cmd                           Command to execute
         -l, --logfile                       Log file to write output to
+        -d, --deploy-mode                   Deployment mode (plan or apply)
 USAGE
     exit 1
 }
@@ -49,6 +50,10 @@ while [ "$1" != "" ]; do
         shift
         tf_logfile=$1
         ;;
+    -d | --deploy-mode)
+        shift
+        deploy_mode=$1
+        ;;
     *)
         usage
         ;;
@@ -91,6 +96,11 @@ if [[ -z ${tf_logfile+x} ]]; then
     echo -e "No logfile provided, using ${tf_logfile}\n"
 fi
 
+if [[ -z ${deploy_mode+x} ]]; then
+    deploy_mode="apply"
+    echo -e "No deploy mode provided, using ${deploy_mode}\n"
+fi
+
 terraform init -input=false -backend=true -reconfigure \
     -backend-config="resource_group_name=${mgmt_resource_group_name}" \
     -backend-config="storage_account_name=${mgmt_storage_account_name}" \
@@ -103,6 +113,10 @@ do
     RUN_COMMAND=0
     TF_CMD="$tf_command"
 
+    if [ "$deploy_mode" == "plan" ]; then
+        TF_CMD="terraform plan -out=tfplan && terraform show -json tfplan > plan_output.json"
+    fi
+
     script -c "$TF_CMD" "$tf_logfile"
 
     # upload the log file?
@@ -127,4 +141,6 @@ do
     fi
 done
 
-
+if [ "$deploy_mode" == "plan" ]; then
+    echo "Terraform plan output saved to plan_output.json"
+fi
diff --git a/docs/tre-admins/setup-instructions/manual-deployment.md b/docs/tre-admins/setup-instructions/manual-deployment.md
index af62ee17e7..ab84799374 100644
--- a/docs/tre-admins/setup-instructions/manual-deployment.md
+++ b/docs/tre-admins/setup-instructions/manual-deployment.md
@@ -71,6 +71,22 @@ Open your browser and navigate to the `/api/docs` route of the API:  `https://<a
 
 ![Swagger UI](../../assets/quickstart_swaggerui.png)
 
+## Using the `DEPLOY_MODE` variable
+
+To use the `DEPLOY_MODE` variable, follow these steps:
+
+1. Set the `DEPLOY_MODE` variable to either `plan` or `apply` depending on your desired deployment mode.
+2. Run the deployment command with the `DEPLOY_MODE` variable set.
+
+Example:
+
+```bash
+export DEPLOY_MODE=plan
+make all
+```
+
+When `DEPLOY_MODE` is set to `plan`, the deployment script will execute the terraform plan without applying it, allowing you to review the changes before deciding to apply them. When `DEPLOY_MODE` is set to `apply`, the deployment script will execute the terraform plan and apply the changes automatically.
+
 ## Next steps
 
 * [Configure Shared Services](configuring-shared-services.md)
diff --git a/docs/tre-admins/setup-instructions/workflows.md b/docs/tre-admins/setup-instructions/workflows.md
index 37dfb97dc1..e3a97800ee 100644
--- a/docs/tre-admins/setup-instructions/workflows.md
+++ b/docs/tre-admins/setup-instructions/workflows.md
@@ -151,3 +151,13 @@ Configure variables used in the deployment workflow:
 ### Deploy the TRE using the workflow
 
 With all the repository secrets set, you can trigger a workflow run by pushing to develop/main of your fork, or by dispatching the workflow manually.
+
+To use the `DEPLOY_MODE` variable, follow these steps:
+
+1. Go to the "Actions" tab of your GitHub repository.
+2. Select the `deploy_tre.yml` workflow from the list of workflows.
+3. Click on the "Run workflow" button.
+4. In the "DEPLOY_MODE" input field, enter either `plan` or `apply` depending on your desired deployment mode.
+5. Click on the "Run workflow" button to start the deployment.
+
+When `DEPLOY_MODE` is set to `plan`, the workflow will execute the terraform plan without applying it, allowing you to review the changes before deciding to apply them. When `DEPLOY_MODE` is set to `apply`, the workflow will execute the terraform plan and apply the changes automatically.

From e226c0dc06d3b9255131987dae99b27284bad327 Mon Sep 17 00:00:00 2001
From: Marcus Robinson <marrobi@microsoft.com>
Date: Wed, 31 Jul 2024 13:01:38 +0100
Subject: [PATCH 2/4] Support plan mode deployment

Related to #4029

Add support for 'plan' mode deployments to evaluate the terraform plan before applying it.

* **devops/scripts/terraform_wrapper.sh**
  - Add a check for the `DEPLOY_MODE` variable.
  - Execute `terraform plan` without applying if `DEPLOY_MODE` is set to 'plan'.
  - Log the plan output to a file.

* **docs/tre-admins/setup-instructions/manual-deployment.md**
  - Add instructions on using the `DEPLOY_MODE` variable for 'plan' mode deployments.
  - Include examples of setting the `DEPLOY_MODE` variable to 'plan' and 'apply'.

* **.github/workflows/deploy_tre.yml**
  - Add an input for `DEPLOY_MODE` in the workflow.
  - Pass the `DEPLOY_MODE` input to the deployment script.

* **docs/tre-admins/setup-instructions/workflows.md**
  - Add instructions on using the `DEPLOY_MODE` variable for 'plan' mode deployments via the GitHub UI.
  - Include examples of setting the `DEPLOY_MODE` variable to 'plan' and 'apply'.

---

For more details, open the [Copilot Workspace session](https://copilot-workspace.githubnext.com/microsoft/AzureTRE/issues/4029?shareId=XXXX-XXXX-XXXX-XXXX).
---
 .github/workflows/deploy_tre.yml              |  6 ++++
 devops/scripts/terraform_wrapper.sh           |  6 ++--
 .../setup-instructions/manual-deployment.md   | 34 +++++++++++++++++++
 .../setup-instructions/workflows.md           | 33 ++++++++++++++++++
 4 files changed, 77 insertions(+), 2 deletions(-)
 mode change 100755 => 100644 devops/scripts/terraform_wrapper.sh

diff --git a/.github/workflows/deploy_tre.yml b/.github/workflows/deploy_tre.yml
index bddea6979f..9557ea256e 100644
--- a/.github/workflows/deploy_tre.yml
+++ b/.github/workflows/deploy_tre.yml
@@ -16,6 +16,11 @@ on:  # yamllint disable-line rule:truthy
         type: environment
         default: CICD
         required: true
+      DEPLOY_MODE:
+        description: The deployment mode to use (plan or apply)
+        type: string
+        default: apply
+        required: true
 
 # This will prevent multiple runs of this entire workflow.
 # We should NOT cancel in progress runs as that can destabilize the environment.
@@ -38,6 +43,7 @@ jobs:
       environmentName: ${{ github.event.inputs.environment || 'CICD' }}
       E2E_TESTS_NUMBER_PROCESSES: 1
       DEVCONTAINER_TAG: 'latest'
+      DEPLOY_MODE: ${{ github.event.inputs.DEPLOY_MODE }}
     secrets:
       AAD_TENANT_ID: ${{ secrets.AAD_TENANT_ID }}
       ACR_NAME: ${{ secrets.ACR_NAME }}
diff --git a/devops/scripts/terraform_wrapper.sh b/devops/scripts/terraform_wrapper.sh
old mode 100755
new mode 100644
index efa02a8078..35d6643ed9
--- a/devops/scripts/terraform_wrapper.sh
+++ b/devops/scripts/terraform_wrapper.sh
@@ -97,6 +97,10 @@ terraform init -input=false -backend=true -reconfigure \
     -backend-config="container_name=${container_name}" \
     -backend-config="key=${key}"
 
+if [[ ${DEPLOY_MODE} == "plan" ]]; then
+    tf_command="terraform plan -out=tfplan && terraform show -json tfplan > plan_output.json"
+fi
+
 RUN_COMMAND=1
 while [ $RUN_COMMAND = 1 ]
 do
@@ -126,5 +130,3 @@ do
         exit 1
     fi
 done
-
-
diff --git a/docs/tre-admins/setup-instructions/manual-deployment.md b/docs/tre-admins/setup-instructions/manual-deployment.md
index af62ee17e7..da083b3837 100644
--- a/docs/tre-admins/setup-instructions/manual-deployment.md
+++ b/docs/tre-admins/setup-instructions/manual-deployment.md
@@ -71,6 +71,40 @@ Open your browser and navigate to the `/api/docs` route of the API:  `https://<a
 
 ![Swagger UI](../../assets/quickstart_swaggerui.png)
 
+## Using the DEPLOY_MODE variable
+
+The `DEPLOY_MODE` variable allows you to control whether the deployment runs in 'plan' mode or 'apply' mode. In 'plan' mode, the terraform plan is generated and can be reviewed before applying. In 'apply' mode, the terraform plan is applied directly.
+
+### Setting the DEPLOY_MODE variable
+
+To set the `DEPLOY_MODE` variable, use the following commands:
+
+```bash
+export DEPLOY_MODE=plan
+```
+
+or
+
+```bash
+export DEPLOY_MODE=apply
+```
+
+### Example usage
+
+To run the deployment in 'plan' mode:
+
+```bash
+export DEPLOY_MODE=plan
+make all
+```
+
+To run the deployment in 'apply' mode:
+
+```bash
+export DEPLOY_MODE=apply
+make all
+```
+
 ## Next steps
 
 * [Configure Shared Services](configuring-shared-services.md)
diff --git a/docs/tre-admins/setup-instructions/workflows.md b/docs/tre-admins/setup-instructions/workflows.md
index 37dfb97dc1..6d2d30a8e9 100644
--- a/docs/tre-admins/setup-instructions/workflows.md
+++ b/docs/tre-admins/setup-instructions/workflows.md
@@ -147,6 +147,39 @@ Configure variables used in the deployment workflow:
 | `ENABLE_SWAGGER` | Optional. Determines whether the Swagger interface for the API will be available. Default value is `false`. |
 | `FIREWALL_SKU` | Optional. The SKU of the Azure Firewall instance. Default value is `Standard`. Allowed values [`Basic`, `Standard`, `Premium`]. See [Azure Firewall SKU feature comparison](https://learn.microsoft.com/en-us/azure/firewall/choose-firewall-sku). |
 
+### Using the DEPLOY_MODE variable
+
+The `DEPLOY_MODE` variable allows you to control whether the deployment runs in 'plan' mode or 'apply' mode. In 'plan' mode, the terraform plan is generated and can be reviewed before applying. In 'apply' mode, the terraform plan is applied directly.
+
+### Setting the DEPLOY_MODE variable
+
+To set the `DEPLOY_MODE` variable, use the following commands:
+
+```bash
+export DEPLOY_MODE=plan
+```
+
+or
+
+```bash
+export DEPLOY_MODE=apply
+```
+
+### Example usage
+
+To run the deployment in 'plan' mode:
+
+```bash
+export DEPLOY_MODE=plan
+make all
+```
+
+To run the deployment in 'apply' mode:
+
+```bash
+export DEPLOY_MODE=apply
+make all
+```
 
 ### Deploy the TRE using the workflow
 

From 0390321c566aa7074e693228af824c65df8ad4db Mon Sep 17 00:00:00 2001
From: Marcus Robinson <marrobi@microsoft.com>
Date: Fri, 15 Nov 2024 11:16:52 +0000
Subject: [PATCH 3/4] Refactor DEPLOY_MODE documentation for clarity and
 conciseness

---
 .../setup-instructions/manual-deployment.md   | 46 -------------------
 .../setup-instructions/workflows.md           | 45 +-----------------
 docs/tre-admins/upgrading-tre.md              | 18 ++++++++
 3 files changed, 19 insertions(+), 90 deletions(-)

diff --git a/docs/tre-admins/setup-instructions/manual-deployment.md b/docs/tre-admins/setup-instructions/manual-deployment.md
index ece30eac0f..af62ee17e7 100644
--- a/docs/tre-admins/setup-instructions/manual-deployment.md
+++ b/docs/tre-admins/setup-instructions/manual-deployment.md
@@ -71,52 +71,6 @@ Open your browser and navigate to the `/api/docs` route of the API:  `https://<a
 
 ![Swagger UI](../../assets/quickstart_swaggerui.png)
 
-
-## Using the DEPLOY_MODE variable
-
-The `DEPLOY_MODE` variable allows you to control whether the deployment runs in 'plan' mode or 'apply' mode. In 'plan' mode, the terraform plan is generated and can be reviewed before applying. In 'apply' mode, the terraform plan is applied directly.
-
-### Setting the DEPLOY_MODE variable
-
-To set the `DEPLOY_MODE` variable, use the following commands:
-
-```bash
-export DEPLOY_MODE=plan
-```
-
-or
-
-```bash
-export DEPLOY_MODE=apply
-```
-
-### Example usage
-
-To run the deployment in 'plan' mode:
-=======
-## Using the `DEPLOY_MODE` variable
-
-To use the `DEPLOY_MODE` variable, follow these steps:
-
-1. Set the `DEPLOY_MODE` variable to either `plan` or `apply` depending on your desired deployment mode.
-2. Run the deployment command with the `DEPLOY_MODE` variable set.
-
-Example:
-```bash
-export DEPLOY_MODE=plan
-make all
-```
-
-To run the deployment in 'apply' mode:
-
-```bash
-export DEPLOY_MODE=apply
-make all
-```
-=======
-When `DEPLOY_MODE` is set to `plan`, the deployment script will execute the terraform plan without applying it, allowing you to review the changes before deciding to apply them. When `DEPLOY_MODE` is set to `apply`, the deployment script will execute the terraform plan and apply the changes automatically.
-
-
 ## Next steps
 
 * [Configure Shared Services](configuring-shared-services.md)
diff --git a/docs/tre-admins/setup-instructions/workflows.md b/docs/tre-admins/setup-instructions/workflows.md
index e9e41e0dc3..d914e465b5 100644
--- a/docs/tre-admins/setup-instructions/workflows.md
+++ b/docs/tre-admins/setup-instructions/workflows.md
@@ -147,51 +147,8 @@ Configure variables used in the deployment workflow:
 | `ENABLE_SWAGGER` | Optional. Determines whether the Swagger interface for the API will be available. Default value is `false`. |
 | `FIREWALL_SKU` | Optional. The SKU of the Azure Firewall instance. Default value is `Standard`. Allowed values [`Basic`, `Standard`, `Premium`]. See [Azure Firewall SKU feature comparison](https://learn.microsoft.com/en-us/azure/firewall/choose-firewall-sku). |
 | `APP_GATEWAY_SKU` | Optional. The SKU of the Application Gateway. Default value is `Standard_v2`. Allowed values [`Standard_v2`, `WAF_v2`] |
-
-### Using the DEPLOY_MODE variable
-
-The `DEPLOY_MODE` variable allows you to control whether the deployment runs in 'plan' mode or 'apply' mode. In 'plan' mode, the terraform plan is generated and can be reviewed before applying. In 'apply' mode, the terraform plan is applied directly.
-
-### Setting the DEPLOY_MODE variable
-
-To set the `DEPLOY_MODE` variable, use the following commands:
-
-```bash
-export DEPLOY_MODE=plan
-```
-
-or
-
-```bash
-export DEPLOY_MODE=apply
-```
-
-### Example usage
-
-To run the deployment in 'plan' mode:
-
-```bash
-export DEPLOY_MODE=plan
-make all
-```
-
-To run the deployment in 'apply' mode:
-
-```bash
-export DEPLOY_MODE=apply
-make all
-```
+| `DEPLOY_MODE` | Optional. Control whether the terraform operations run in `plan` mode or `apply` mode. Defaults to `apply` |
 
 ### Deploy the TRE using the workflow
 
 With all the repository secrets set, you can trigger a workflow run by pushing to develop/main of your fork, or by dispatching the workflow manually.
-
-To use the `DEPLOY_MODE` variable, follow these steps:
-
-1. Go to the "Actions" tab of your GitHub repository.
-2. Select the `deploy_tre.yml` workflow from the list of workflows.
-3. Click on the "Run workflow" button.
-4. In the "DEPLOY_MODE" input field, enter either `plan` or `apply` depending on your desired deployment mode.
-5. Click on the "Run workflow" button to start the deployment.
-
-When `DEPLOY_MODE` is set to `plan`, the workflow will execute the terraform plan without applying it, allowing you to review the changes before deciding to apply them. When `DEPLOY_MODE` is set to `apply`, the workflow will execute the terraform plan and apply the changes automatically.
diff --git a/docs/tre-admins/upgrading-tre.md b/docs/tre-admins/upgrading-tre.md
index ca56c57bcf..5e454575e2 100644
--- a/docs/tre-admins/upgrading-tre.md
+++ b/docs/tre-admins/upgrading-tre.md
@@ -42,3 +42,21 @@ If you wish to deploy the Azure TRE from a forked repository you can change the
 - `"OSS_REPO": "myorg/AzureTRE"` (to point to fork of the Azure TRE in your GitHub organisation)
 
 When changing `OSS_REPO` ensure the `OSS_VERSION` variable refers to a GitHub ref on the repository fork.
+
+## Check infrastructure changes using a Terraform plan
+
+The `DEPLOY_MODE` variable allows you to control whether the deployment runs in 'plan' mode or 'apply' mode. In 'plan' mode, the terraform plan is generated and can be reviewed before applying. In 'apply' mode, the terraform plan is applied directly. This can be useful when evaluating an updgrade and don't want to make any actual changes to the deployed infrastructure.
+
+### Setting the DEPLOY_MODE variable
+
+To set the `DEPLOY_MODE` variable, use the following commands:
+
+```bash
+export DEPLOY_MODE=plan
+```
+
+### Example usage
+```bash
+export DEPLOY_MODE=plan
+make core
+```

From a05ec96ba80e01af4d8ad7eb4d788013dd55dc97 Mon Sep 17 00:00:00 2001
From: Marcus Robinson <marrobi@microsoft.com>
Date: Fri, 15 Nov 2024 11:19:20 +0000
Subject: [PATCH 4/4] Update CHANGELOG.md

---
 CHANGELOG.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 236f0e2055..859acf3fa8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,9 +7,10 @@ FEATURES:
 
 ENHANCEMENTS:
 * Key Vaults should use RBAC instead of access policies for access control ([#4000](https://github.com/microsoft/AzureTRE/issues/4000))
-* Split log entries with [Log chunk X of Y] for better readability. ([[#3992](https://github.com/microsoft/AzureTRE/issues/3992)
+* Split log entries with [Log chunk X of Y] for better readability. ([#3992](https://github.com/microsoft/AzureTRE/issues/3992))
 * Expose APP_SERVICE_SKU build variable to allow enablement of App Gateway WAF ([#4111](https://github.com/microsoft/AzureTRE/pull/4111))
 * Update Terraform to use Azure AD authentication rather than storage account keys ([#4103](https://github.com/microsoft/AzureTRE/issues/4103))
+* Add DEPLOY_MODE environemtn variable to enable Terraform plan ([#4047](https://github.com/microsoft/AzureTRE/pull/4047))
 
 BUG FIXES:
 - Update KeyVault references in API to use the version so Terraform cascades the update ([#4112](https://github.com/microsoft/AzureTRE/pull/4112))