Test build 09

Author: RoseHJM

articles/deployment-environments/how-to-configure-extensibility-model-custom-image.md

@@ -73,15 +73,14 @@ Creating a custom container image allows you to customize your deployments to fi
 
 After you complete the image customization, you can build the image and push it to your container registry by using a script provided by Microsoft to automate the process.
 
-[!INCLUDE [custom-image-create](includes/custom-image-create.md)]
+[!INCLUDE [custom-image-create-arm](includes/custom-image-create-arm.md)]
 
 ### Build a container image with a script
 
 Rather than building your custom image and pushing it to a container registry yourself, you can use a script to build and push it to a specified container registry. 
 
 [!INCLUDE [custom-image-script](includes/custom-image-script.md)]
 
-
 ### [Create a custom image manually](#tab/custom-manual/)
 ### Create a custom container image manually
 
@@ -108,6 +107,135 @@ docker build . -t {YOUR_REGISTRY}.azurecr.io/customImage:1.0.0
 
 ::: zone-end
 
+::: zone pivot="terraform"
+## Use container images with ADE
+
+You can take one of the following approaches to use container images with ADE:
+- **Create a container image leveraging a GitHub workflow:** To start with, you can use the published GitHub workflow from the Leveraging ADE's Extensibility Model With Terraform repository.
+- **Create a custom container image:** You can create a workflow that creates a Terraform specific image customized with all the software, settings, and configuration that you need.
+ 
+
+## Create a container image leveraging a GitHub workflow
+Creating a custom container image allows you to customize your deployments to fit your requirements. You can create custom images based on the ADE standard images.
+
+After you complete the image customization, you must build the image and push it to your container registry.
+
+You can build and push the image manually, or use a script provided by Microsoft to automate the process.
+
+The published GitHub Action helps to build and push an image to an Azure Container Registry (ACR). You can reference a provided ACR image link within an environment definition in ADE to deploy or delete an environment with the provided image.
+
+To create an image configured for ADE, follow these steps:
+1. Create a custom image based on a GitHub workflow.
+1. Install desired packages.
+1. Configure operation shell scripts.
+1. Create operation shell scripts that use the Terraform CLI. 
+
+**1. Create a custom image based on a GitHub workflow**
+
+Use the [published repository](https://github.com/Azure/ade-extensibility-model-terraform/blob/main/README.md#azure-deployment-environments---leveraging-ades-extensibility-model-with-terraform) to take advantage of the GitHub workflow. The repository contains ADE-compatible sample image components, including a Dockerfile and shell scripts for deploying and deleting environments using Terraform IaC templates. This sample code helps you create your own container image. 
+
+
+**2. Install required packages**
+In this step, you install any packages you require in your image, including Terraform. You can install the Terraform CLI to an executable location so that it can be used in your deployment and deletion scripts. 
+
+Here's an example of that process, installing version 1.7.5 of the Terraform CLI:
+
+```azure cli
+RUN wget -O terraform.zip https://releases.hashicorp.com/terraform/1.7.5/terraform_1.7.5_linux_amd64.zip
+RUN unzip terraform.zip && rm terraform.zip
+RUN mv terraform /usr/bin/terraform
+```
+
+> [!Tip]
+> You can get the download URL for your preferred version of the Terraform CLI from [Hashicorp releases](https://aka.ms/deployment-environments/terraform-cli-zip).
+
+
+**3. Configure operation shell scripts**
+
+Within the standard images, operations are determined and executed based on the operation name. Currently, the two operation names supported are *deploy* and *delete*.
+
+To set up your custom image to utilize this structure, specify a folder at the level of your Dockerfile named *scripts*, and specify two files, *deploy.sh*, and *delete.sh*. The deploy shell script runs when your environment is created or redeployed, and the delete shell script runs when your environment is deleted. You can see examples of shell scripts in the repository under the [Runner-Images folder for the ARM-Bicep](https://github.com/Azure/deployment-environments/tree/main/Runner-Images/ARM-Bicep) image.
+
+To ensure these shell scripts are executable, add the following lines to your Dockerfile:
+
+```docker
+COPY scripts/* /scripts/
+RUN find /scripts/ -type f -iname "*.sh" -exec dos2unix '{}' '+'
+RUN find /scripts/ -type f -iname "*.sh" -exec chmod +x {} \;
+```
+
+**4. Create operation shell scripts that use the Terraform CLI**
+
+There are three steps to deploy infrastructure via Terraform: 
+1. `terraform init` - initializes the Terraform CLI to perform actions within the working directory
+1. `terraform plan` - develops a plan based on the incoming Terraform infrastructure files and variables, and any existing state files, and develops steps needed to create or update infrastructure specified in the *.tf* files
+1. `terraform apply` - applies the plan to create new or update existing infrastructure in Azure
+
+During the core image's entrypoint, any existing state files are pulled into the container and the directory saved under the environment variable ```$ADE_STORAGE```. Additionally, any parameters set for the current environment stored under the variable ```$ADE_OPERATION_PARAMETERS```. In order to access the existing state file, and set your variables within a *.tfvars.json* file, run the following commands:
+```bash
+EnvironmentState="$ADE_STORAGE/environment.tfstate"
+EnvironmentPlan="/environment.tfplan"
+EnvironmentVars="/environment.tfvars.json"
+
+echo "$ADE_OPERATION_PARAMETERS" > $EnvironmentVars
+```
+
+Additionally, to utilize ADE privileges to deploy infrastructure inside your subscription, your script needs to use the Managed Service Identity (MSI) when provisioning infrastructure by using the Terraform AzureRM provider. If your deployment needs special permissions to complete your deployment, such as particular roles, assign those permissions to the project environment type's identity that is being used for your environment deployment. ADE sets the relevant environment variables, such as the client, tenant, and subscription IDs within the core image's entrypoint, so run the following commands to ensure the provider uses the ADE MSI:
+```bash
+export ARM_USE_MSI=true
+export ARM_CLIENT_ID=$ADE_CLIENT_ID
+export ARM_TENANT_ID=$ADE_TENANT_ID
+export ARM_SUBSCRIPTION_ID=$ADE_SUBSCRIPTION_ID
+```
+
+If you have other variables to reference within your template that aren't specified in your environment's parameters, set environment variables using the prefix *TF_VAR*. A list of provided ADE environment variables is provided [Azure Deployment Environment CLI variables reference](./reference-deployment-environment-variables.md). An example of those commands could be;
+```bash
+export TF_VAR_resource_group_name=$ADE_RESOURCE_GROUP_NAME
+export TF_VAR_ade_env_name=$ADE_ENVIRONMENT_NAME
+export TF_VAR_env_name=$ADE_ENVIRONMENT_NAME
+export TF_VAR_ade_subscription=$ADE_SUBSCRIPTION_ID
+export TF_VAR_ade_location=$ADE_ENVIRONMENT_LOCATION
+export TF_VAR_ade_environment_type=$ADE_ENVIRONMENT_TYPE
+```
+
+Now, you can run the steps listed previously to initialize the Terraform CLI, generate a plan for provisioning infrastructure, and apply a plan during your deployment script:
+```bash
+terraform init
+terraform plan -no-color -compact-warnings -refresh=true -lock=true -state=$EnvironmentState -out=$EnvironmentPlan -var-file="$EnvironmentVars"
+terraform apply -no-color -compact-warnings -auto-approve -lock=true -state=$EnvironmentState $EnvironmentPlan
+```
+
+During your deletion script, you can add the `destroy` flag to your plan generation to delete the existing resources, as shown in the following example:
+```bash
+terraform init
+terraform plan -no-color -compact-warnings -destroy -refresh=true -lock=true -state=$EnvironmentState -out=$EnvironmentPlan -var-file="$EnvironmentVars"
+terraform apply -no-color -compact-warnings -auto-approve -lock=true -state=$EnvironmentState $EnvironmentPlan
+```
+
+Finally, to make the outputs of your deployment uploaded and accessible when accessing your environment via the Azure CLI, transform the output object from Terraform to the ADE-specified format through the JQ package. Set the value to the $ADE_OUTPUTS environment variable, as shown in the following example:
+```bash
+tfOutputs=$(terraform output -state=$EnvironmentState -json)
+# Convert Terraform output format to ADE format.
+tfOutputs=$(jq 'walk(if type == "object" then 
+            if .type == "bool" then .type = "boolean" 
+            elif .type == "list" then .type = "array" 
+            elif .type == "map" then .type = "object" 
+            elif .type == "set" then .type = "array" 
+            elif (.type | type) == "array" then 
+                if .type[0] == "tuple" then .type = "array" 
+                elif .type[0] == "object" then .type = "object" 
+                elif .type[0] == "set" then .type = "array" 
+                else . 
+                end 
+            else . 
+            end 
+        else . 
+        end)' <<< "$tfOutputs")
+
+echo "{\"outputs\": $tfOutputs}" > $ADE_OUTPUTS
+```
+::: zone-end
+
 
 ## Make the custom image available to ADE