Skip to content

Commit c57208a

Browse files
author
RoseHJM
committed
New ARM/Bicep instructions
1 parent d5301e1 commit c57208a

File tree

3 files changed

+219
-118
lines changed

3 files changed

+219
-118
lines changed

‎articles/deployment-environments/how-to-configure-custom-runner.md

Lines changed: 0 additions & 117 deletions
This file was deleted.

‎articles/deployment-environments/how-to-configure-extensibility-custom-runner.md

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
---
2+
title: ADE extensibility model for custom ARM and Bicep images
3+
titleSuffix: Azure Deployment Environments
4+
description: Learn how to use the ADE extensibility model to build and utilize custom ARM and Bicep images within your environment definitions for deployment environments.
5+
ms.service: deployment-environments
6+
author: RoseHJM
7+
ms.author: rosemalcolm
8+
ms.date: 03/27/2024
9+
ms.topic: how-to
10+
11+
#customer intent: As a developer, I want to learn how to build and utilize custom images within my environment definitions for deployment environments.
12+
---
13+
14+
# Custom image support in Azure Deployment Environments
15+
16+
In this article, you learn how to build and utilize custom images within your environment definitions for deployments in Azure Deployment Environments (ADE).
17+
18+
ADE uses an extensibility model to enable you to create custom images to use in your environment definitions. By using the extensibility model, you can create your own custom images, and store them in a container registry like the [Microsoft Artifact Registry](https://mcr.microsoft.com/)(also known as the Microsoft Container Registry). You can then reference these images in your environment definitions to deploy your environments.
19+
20+
The ADE team provides a selection of images to get you started, including a core image, and an Azure Resource Manager (ARM)/Bicep image. You can access these sample images in the [Runner-Images](https://github.com/Azure/deployment-environments/tree/custom-runner-private-preview/Runner-Images) folder.
21+
22+
The ADE CLI is a tool that allows you to build custom images by using ADE base images. You can use the ADE CLI to customize your deployments and deletions to fit your workflow. The ADE CLI is preinstalled on the sample images. To learn more about the ADE CLI, see the [CLI Custom Runner Image reference](./reference-deployment-environment-cli.md).
23+
24+
## Prerequisites
25+
26+
- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
27+
28+
## Create and build a Docker image
29+
30+
In this example, you learn how to build a Docker image to utilize ADE deployments and access the ADE CLI, basing your image off of one of the ADE authored images.
31+
32+
### FROM statement
33+
34+
Include a FROM statement within a created DockerFile for your new image pointing to a sample image hosted on Microsoft Artifact Registry.
35+
36+
Here's an example FROM statement, referencing the sample core image:
37+
38+
```docker
39+
FROM mcr.microsoft.com/deployment-environments/runners/core:latest
40+
```
41+
42+
This statement pulls the most recently published core image, and makes it a basis for your custom image.
43+
44+
### Install Bicep in a Dockerfile
45+
46+
You can install the Bicep package with the Azure CLI by using the RUN statement, as shown in the following example:
47+
48+
```azure cli
49+
RUN az bicep install
50+
```
51+
52+
The ADE sample images are based on the Azure CLI image, and have the ADE CLI and JQ packages preinstalled. You can learn more about the [Azure CLI](/cli/azure/), and the [JQ package](https://devdocs.io/jq/).
53+
54+
To install any more packages you need within your image, use the RUN statement.
55+
56+
### Execute operation shell scripts
57+
58+
Within the sample images, operations are determined and executed based on the operation name. Currently, the two operation names supported are *deploy* and *delete*.
59+
60+
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/custom-runner-private-preview/Runner-Images/ARM-Bicep) image.
61+
62+
To ensure these shell scripts are executable, add the following lines to your Dockerfile:
63+
64+
```docker
65+
COPY scripts/* /scripts/
66+
RUN find /scripts/ -type f -iname "*.sh" -exec dos2unix '{}' '+'
67+
RUN find /scripts/ -type f -iname "*.sh" -exec chmod +x {} \;
68+
```
69+
70+
### Author operation shell scripts to deploy ARM or Bicep templates
71+
To ensure you can successfully deploy ARM or Bicep infrastructure through ADE, you must:
72+
- Convert ADE parameters to ARM-acceptable parameters
73+
- Resolve linked templates if they're used in the deployment
74+
- Use privileged managed identity to perform the deployment
75+
76+
During the core image's entrypoint, any parameters set for the current environment are stored under the variable `$ADE_OPERATION_PARAMETERS`. In order to convert them to ARM-acceptable parameters, you can run the following command using JQ:
77+
```bash
78+
# format the parameters as arm parameters
79+
deploymentParameters=$(echo "$ADE_OPERATION_PARAMETERS" | jq --compact-output '{ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", "contentVersion": "1.0.0.0", "parameters": (to_entries | if length == 0 then {} else (map( { (.key): { "value": .value } } ) | add) end) }' )
80+
```
81+
82+
Next, to resolve any linked templates used within an ARM JSON-based template, you can decompile the main template file, which resolves all the local infrastructure files used into many Bicep modules. Then, rebuild those modules back into a single ARM template with the linked templates embedded into the main ARM template as nested templates. This step is only necessary during the deployment operation. The main template file can be specified using the `$ADE_TEMPLATE_FILE` set during the core image's entrypoint, and you should reset this variable with the recompiled template file. See the following example:
83+
```bash
84+
hasRelativePath=$( cat $ADE_TEMPLATE_FILE | jq '[.. | objects | select(has("templateLink") and (.templateLink | has("relativePath")))] | any' )
85+
86+
if [ "$hasRelativePath" = "true" ]; then
87+
echo "Resolving linked ARM templates"
88+
89+
bicepTemplate="${ADE_TEMPLATE_FILE/.json/.bicep}"
90+
generatedTemplate="${ADE_TEMPLATE_FILE/.json/.generated.json}"
91+
92+
az bicep decompile --file "$ADE_TEMPLATE_FILE"
93+
az bicep build --file "$bicepTemplate" --outfile "$generatedTemplate"
94+
95+
# Correctly reassign ADE_TEMPLATE_FILE without the $ prefix during assignment
96+
ADE_TEMPLATE_FILE="$generatedTemplate"
97+
fi
98+
```
99+
To provide the permissions a deployment requires to execute the deployment and deletion of resources within the subscription, use the privileged managed identity associated with the ADE project environment type. If your deployment needs special permissions to complete, such as particular roles, assign those roles to the project environment type's identity. Sometimes, the managed identity isn't immediately available when entering the container; you can retry until the login is successful.
100+
```bash
101+
echo "Signing into Azure using MSI"
102+
while true; do
103+
# managed identity isn't available immediately
104+
# we need to do retry after a short nap
105+
az login --identity --allow-no-subscriptions --only-show-errors --output none && {
106+
echo "Successfully signed into Azure"
107+
break
108+
} || sleep 5
109+
done
110+
```
111+
112+
To begin deployment of the ARM or Bicep templates, run the `az deployment group create` command. When running this command inside the container, choose a deployment name that doesn't override any past deployments, and use the `--no-prompt true` and `--only-show-errors` flags to ensure the deployment doesn't fail on any warnings or stall on waiting for user input, as shown in the following example:
113+
114+
```bash
115+
deploymentName=$(date +"%Y-%m-%d-%H%M%S")
116+
az deployment group create --subscription $ADE_SUBSCRIPTION_ID \
117+
--resource-group "$ADE_RESOURCE_GROUP_NAME" \
118+
--name "$deploymentName" \
119+
--no-prompt true --no-wait \
120+
--template-file "$ADE_TEMPLATE_FILE" \
121+
--parameters "$deploymentParameters" \
122+
--only-show-errors
123+
```
124+
125+
To delete an environment, perform a Complete-mode deployment and provide an empty ARM template, which removes all resources within the specified ADE resource group, as shown in the following example:
126+
```bash
127+
deploymentName=$(date +"%Y-%m-%d-%H%M%S")
128+
az deployment group create --resource-group "$ADE_RESOURCE_GROUP_NAME" \
129+
--name "$deploymentName" \
130+
--no-prompt true --no-wait --mode Complete \
131+
--only-show-errors \
132+
--template-file "$DIR/empty.json"
133+
```
134+
135+
You can check the provisioning state and details by running the below commands. ADE uses some special functions to read and provide additional context based on the provisioning details, which you can find in the [Runner-Images](https://github.com/Azure/deployment-environments/tree/custom-runner-private-preview/Runner-Images) folder. A simple implementation could be as follows:
136+
```bash
137+
if [ $? -eq 0 ]; then # deployment successfully created
138+
while true; do
139+
140+
sleep 1
141+
142+
ProvisioningState=$(az deployment group show --resource-group "$ADE_RESOURCE_GROUP_NAME" --name "$deploymentName" --query "properties.provisioningState" -o tsv)
143+
ProvisioningDetails=$(az deployment operation group list --resource-group "$ADE_RESOURCE_GROUP_NAME" --name "$deploymentName")
144+
145+
echo "$ProvisioningDetails"
146+
147+
if [[ "CANCELED|FAILED|SUCCEEDED" == *"${ProvisioningState^^}"* ]]; then
148+
149+
echo -e "\nDeployment $deploymentName: $ProvisioningState"
150+
151+
if [[ "CANCELED|FAILED" == *"${ProvisioningState^^}"* ]]; then
152+
exit 11
153+
else
154+
break
155+
fi
156+
fi
157+
done
158+
fi
159+
```
160+
161+
Finally, to view the outputs of your deployment and pass them to ADE to make them accessible via the Azure CLI, you can run the following commands:
162+
```bash
163+
deploymentOutput=$(az deployment group show -g "$ADE_RESOURCE_GROUP_NAME" -n "$deploymentName" --query properties.outputs)
164+
if [ -z "$deploymentOutput" ]; then
165+
deploymentOutput="{}"
166+
fi
167+
echo "{\"outputs\": $deploymentOutput}" > $ADE_OUTPUTS
168+
```
169+
170+
171+
### Build the image
172+
173+
Before you build the image to be pushed to your registry, ensure the [Docker Engine is installed](https://docs.docker.com/desktop/) on your computer. Then, navigate to the directory of your Dockerfile, and run the following command:
174+
175+
```docker
176+
docker build . -t {YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}
177+
```
178+
179+
For example, if you want to save your image under a repository within your registry named `customImage`, and upload with the tag version of `1.0.0`, you would run:
180+
181+
```docker
182+
docker build . -t {YOUR_REGISTRY}.azurecr.io/customImage:1.0.0
183+
```
184+
185+
## Push the Docker image to a registry
186+
187+
In order to use custom images, you need to set up a publicly accessible image registry with anonymous image pull enabled. This way, Azure Deployment Environments can access your custom image to execute in our container.
188+
189+
Azure Container Registry is an Azure offering that stores container images and similar artifacts.
190+
191+
To create a registry, which can be done through the Azure CLI, the Azure portal, PowerShell commands, and more, follow one of the [quickstarts](/azure/container-registry/container-registry-get-started-azure-cli).
192+
193+
To set up your registry to have anonymous image pull enabled, run the following commands in the Azure CLI:
194+
195+
```azurecli
196+
az login
197+
az acr login -n {YOUR_REGISTRY}
198+
az acr update -n {YOUR_REGISTRY} --public-network-enabled true
199+
az acr update -n {YOUR_REGISTRY} --anonymous-pull-enabled true
200+
```
201+
202+
When you're ready to push your image to your registry, run the following command:
203+
204+
```docker
205+
docker push {YOUR_REGISTRY}.azurecr.io/{YOUR_IMAGE_LOCATION}:{YOUR_TAG}
206+
```
207+
208+
## Connect the image to your environment definition
209+
210+
When authoring environment definitions to use your custom image in their deployment, edit the `runner` property on the manifest file (environment.yaml or manifest.yaml).
211+
212+
```yaml
213+
runner: "{YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}"
214+
```
215+
216+
## Related content
217+
218+
- [ADE CLI Custom Runner Image reference](./reference-deployment-environment-cli.md)

‎articles/deployment-environments/toc.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ items:
6161
- name: Create environments with Azure Developer CLI (AZD)
6262
href: how-to-create-environment-with-azure-developer.md
6363
- name: ADE extensibility model for custom images
64-
href: how-to-configure-custom-runner.md
64+
href: how-to-configure-extensibility-custom-runner.md
6565
displayName: custom image, custom runner, extensibility
6666
- name: Manage environments in the developer portal
6767
href: how-to-manage-environments.md

0 commit comments

Comments
 (0)