Skip to content

Commit 03ac0e9

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #272092 from RoseHJM/ade-environment-variables
ADE - ADE CLI variable reference
2 parents b4062d0 + 82f0366 commit 03ac0e9

File tree

2 files changed

+115
-0
lines changed

2 files changed

+115
-0
lines changed

‎articles/deployment-environments/reference-deployment-environment-variables.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
title: ADE CLI variables reference
3+
titleSuffix: Azure Deployment Environments
4+
description: Learn about the variables available for building custom images using the Azure Deployment Environment (ADE) CLI.
5+
ms.service: deployment-environments
6+
author: RoseHJM
7+
ms.author: rosemalcolm
8+
ms.date: 04/12/2024
9+
ms.topic: reference
10+
11+
# Customer intent: As a developer, I want to learn about the variables available for use with the ADE CLI.
12+
---
13+
14+
# Azure Deployment Environment CLI variables reference
15+
16+
Azure Deployment Environments (ADE) sets many variables related to your environment you can reference while authoring custom images. You can use the below variables within the operation scripts (deploy.sh or delete.sh) in order to make your images flexible to the environment they're interacting with.
17+
18+
For files used by ADE within the container, all exist in an ```ade``` subfolder off of the initial directory.
19+
20+
Here's the list of available environment variables:
21+
22+
## ADE_ERROR_LOG
23+
Refers to the file located at `/ade/temp/error.log`. The `error.log` file stores any standard error output that populates an environment's error details in the result of a failed deployment or deletion. The file is used with `ade execute`, which records any standard output and standard error content to an ADE-managed log file. When using the `ade execute` command, redirect standard error logging to this file location using the following command:
24+
25+
```bash
26+
ade execute --operation $ADE_OPERATION_NAME --command "{YOUR_COMMAND}" 2> >(tee -a $ADE_ERROR_LOG)
27+
```
28+
29+
By using this method, you can view the deployment or deletion error within the developer portal. This leads to quicker and more successful debugging iterations when creating your custom image, and quicker diagnosis of the root cause for the failed operation.
30+
31+
## ADE_OUTPUTS
32+
Refers to the file located at `/ade/temp/output.json`. The `output.json` file stores any outputs from an environment's deployment in persistent storage, so that it can be accessed by using the Azure CLI at a later date. When storing the output in a custom image, ensure the output is uploaded to the specified file, as shown in the following example:
33+
```bash
34+
echo "$deploymentOutput" > $ADE_OUTPUTS
35+
```
36+
37+
## ADE_STORAGE
38+
Refers to the directory located at `/ade/storage`. During the core image's entrypoint, ADE pulls down a specially named `storage.zip` file from the environment's storage container and populate this directory, and then at completion of the operation, reuploads the directory as a zip file back to the storage container. If you have files you would like to reference within your custom image on subsequent redeployments, such as state files, place them within this directory.
39+
40+
## ADE_CLIENT_ID
41+
Refers to the object ID of the Managed Service Identity (MSI) of the environment's project environment type. This variable can be used to validate to the Azure CLI for permissions to utilize within the container, such as deployment of infrastructure.
42+
43+
## ADE_TENANT_ID
44+
Refers to the tenant GUID of the environment.
45+
46+
## ADE_SUBSCRIPTION_ID
47+
Refers to the subscription GUID of the environment.
48+
49+
## ADE_TEMPLATE_FILE
50+
Refers to where the main template file specified in the 'templatePath' property in the environment definition lives within the container. This path roughly mirrors the source control of where the catalog, depending on the file path level you connected the catalog at. The file is roughly located at `/ade/repository/{CATALOG_NAME}/{PATH_TO_TEMPLATE_FILE}`. This method is used primarily during the main deployment step as the file referenced to base the deployment off.
51+
52+
Here's an example using the Azure CLI:
53+
```bash
54+
az deployment group create --subscription $ADE_SUBSCRIPTION_ID \
55+
--resource-group "$ADE_RESOURCE_GROUP_NAME" \
56+
--name "$deploymentName" \
57+
--no-prompt true --no-wait \
58+
--template-file "$ADE_TEMPLATE_FILE" \
59+
--parameters "$deploymentParameters" \
60+
--only-show-errors
61+
```
62+
63+
Any further files, such as supporting IaC files or files you would like to use in your custom image, are stored at their relative location to the template file inside the container as they are within the catalog. For example, take the following directory:
64+
```
65+
├───SampleCatalog
66+
├───EnvironmentDefinition1
67+
│ file1.bicep
68+
│ main.bicep
69+
│ environment.yaml
70+
│
71+
└───TestFolder
72+
test1.txt
73+
test2.txt
74+
```
75+
76+
In this case, `$ADE_TEMPLATE_FILE=/ade/repository/SampleCatalog/EnvironmentDefinition1/main.bicep`. Additionally, files such as file1.bicep would be located within the container at `/ade/repository/SampleCatalog/EnvironmentDefinition1/file1.bicep`, and test2.txt would be located at `/ade/repository/SampleCatalog/EnvironmentDefinition1/TestFolder/test2.txt`.
77+
78+
## ADE_ENVIRONMENT_NAME
79+
The name of the environment given at deployment time.
80+
81+
## ADE_ENVIRONMENT_LOCATION
82+
The location where the environment is being deployed. This location is the region of the project.
83+
84+
## ADE_RESOURCE_GROUP_NAME
85+
The name of the resource group created by ADE to deploy your resources to.
86+
87+
## ADE_ENVIRONMENT_TYPE
88+
The name of the project environment type being used to deploy this environment.
89+
90+
## ADE_OPERATION_PARAMETERS
91+
A JSON object of the parameters supplied to deploy the environment. An example of the parameters object follows:
92+
```json
93+
{
94+
"location": "locationInput",
95+
"name": "nameInput",
96+
"sampleObject": {
97+
"sampleProperty": "sampleValue"
98+
},
99+
"sampleArray": [
100+
"sampleArrayValue1",
101+
"sampleArrayValue2"
102+
]
103+
}
104+
```
105+
106+
## ADE_OPERATION_NAME
107+
The type of operation being performed on the environment. Today, this value is either 'deploy' or 'delete'.
108+
109+
## ADE_HTTP__OPERATIONID
110+
The Operation ID assigned to the operation being performed on the environment. The Operation ID is used as validation to use the ADE CLI, and is the main identifier in retrieving logs from past operations.
111+
112+
## ADE_HTTP__DEVCENTERID
113+
The Dev Center ID of the environment. The Dev Center ID is also used as validation to use the ADE CLI.

‎articles/deployment-environments/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,8 @@ items:
9898
- name: Reference
9999
expanded: false
100100
items:
101+
- name: ADE CLI variables
102+
href: reference-deployment-environment-variables.md
101103
- name: Install Azure CLI extension
102104
href: how-to-install-devcenter-cli-extension.md
103105
- name: Azure CLI - devcenter

0 commit comments

Comments
 (0)