Skip to content

Commit d42bf95

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #258939 from RoseHJM/ade-environment-yaml
ADE - document environment.yaml
2 parents 9a7dcca + 9061951 commit d42bf95

File tree

3 files changed

+150
-12
lines changed

3 files changed

+150
-12
lines changed

‎articles/deployment-environments/concept-environment-yaml.md

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
title: environment.yaml schema
3+
description: Learn how to use environment.yaml to define parameters in your environment definition.
4+
author: RoseHJM
5+
ms.author: rosemalcolm
6+
ms.service: dev-box
7+
ms.topic: concept-article
8+
ms.date: 11/17/2023
9+
10+
#customer intent: As a developer, I want to know which parameters I can assign for parameters in environment.yaml.
11+
12+
---
13+
14+
# Parameters and data types in environment.yaml
15+
16+
ADE environment definitions are infrastructure as code (IaC), written in Bicep or Terraform, stored in repositories. Environment definitions can be modified and adapted for your specific requirements and then used to create a deployment environment on Azure. The environment.yaml schema defines and describes the types of Azure resources included in environment definitions.
17+
18+
19+
## What is environment.yaml?
20+
21+
The environment.yaml file acts as a manifest, describing the resources used and the template location for the environment definition.
22+
23+
### Sample environment.yaml
24+
The following script is a generic example of an environment.yaml required for your environment definition.
25+
26+
```yml
27+
name: WebApp
28+
version: 1.0.0
29+
summary: Azure Web App Environment
30+
description: Deploys a web app in Azure without a datastore
31+
runner: ARM
32+
templatePath: azuredeploy.json
33+
```
34+
### Definitions
35+
The following table describes the properties that you can use in environment.yaml.
36+
37+
| **Property** | **Type** | **Description** | **Required** | **Examples** |
38+
| ------------ | -------- | -------------------------------------------------- | ------------ | ----------------------------------------------- |
39+
| name | string | The display name of the catalog item. | Yes | |
40+
| version | string | The version of the catalog item. | | 1.0.0 |
41+
| summary | string | A short summary string about the catalog item. | | |
42+
| description | string | A description of the catalog item. | | |
43+
| runner | string | The container image to use when executing actions. | | ARM template </br> Terraform |
44+
| templatePath | string | The relative path of the entry template file. | Yes | main.tf </br> main.bicep </br> azuredeploy.json |
45+
| parameters | array | Input parameters to use when creating the environment and executing actions. | | #/definitions/Parameter |
46+
47+
## Parameters in environment.yaml
48+
49+
Parameters enable you to reuse an environment definition in different scenarios. For example, you might want developers in different regions to deploy the same environment. You can define a location parameter to prompt the developer to enter the desired location as they create their environment.
50+
51+
### Sample environment.yaml with parameters
52+
53+
The following script is an example of a environment.yaml file that includes two parameters; `location` and `name`:
54+
55+
```yml
56+
name: WebApp
57+
summary: Azure Web App Environment
58+
description: Deploys a web app in Azure without a datastore
59+
runner: ARM
60+
templatePath: azuredeploy.json
61+
parameters:
62+
- id: "location"
63+
name: "location"
64+
description: "Location to deploy the environment resources"
65+
default: "[resourceGroup().location]"
66+
type: "string"
67+
required: false
68+
- id: "name"
69+
name: "name"
70+
description: "Name of the Web App "
71+
default: ""
72+
type: "string"
73+
required: false
74+
```
75+
76+
### Parameter definitions
77+
78+
The following table describes the data types that you can use in environment.yaml. The data type names used in the environment.yaml manifest file differ from the ones used in ARM templates.
79+
80+
Each parameter can use any of the following properties:
81+
82+
| **Properties** | **Type** | **Description** | **Further Settings** |
83+
| -------------- | -------------- |------------------------------------------------ |--------------------------------------- |
84+
| ID | string | Unique ID of the parameter. | |
85+
| name | string | Display name of the parameter. | |
86+
| description | string | Description of the parameter. | |
87+
| default | array </br> boolean </br> integer </br> number </br> object </br> string | The default value of the parameter. | |
88+
| type | array </br> boolean </br> integer </br> number </br> object </br> string | The data type of the parameter. This data type must match the parameter data type in the ARM template, BICEP file, or Terraform file with the corresponding parameter name. | **Default type:** string |
89+
| readOnly | boolean | Whether or not this parameter is read-only. | |
90+
| required | boolean | Whether or not this parameter is required. | |
91+
| allowed | array | An array of allowed values. | "items": { </br> "type": "string" </br> }, </br> "minItems": 1, </br> "uniqueItems": true, |
92+
93+
## YAML schema
94+
95+
There's a defined schema for Azure Deployment Environments environment.yaml files, which can make editing these files a little easier. You can add the schema definition to the beginning of your environment.yaml file:
96+
97+
```yml
98+
# yaml-language-server: $schema=https://github.com/Azure/deployment-environments/releases/download/2022-11-11-preview/manifest.schema.json
99+
```
100+
101+
Here's an example environment definition that uses the schema:
102+
103+
```yml
104+
# yaml-language-server: $schema=https://github.com/Azure/deployment-environments/releases/download/2022-11-11-preview/manifest.schema.json
105+
name: FunctionApp
106+
version: 1.0.0
107+
summary: Azure Function App Environment
108+
description: Deploys an Azure Function App, Storage Account, and Application Insights
109+
runner: ARM
110+
templatePath: azuredeploy.json
111+
112+
parameters:
113+
- id: name
114+
name: Name
115+
description: 'Name of the Function App.'
116+
type: string
117+
required: true
118+
119+
- id: supportsHttpsTrafficOnly
120+
name: 'Supports Https Traffic Only'
121+
description: 'Allows https traffic only to Storage Account and Functions App if set to true.'
122+
type: boolean
123+
124+
- id: runtime
125+
name: Runtime
126+
description: 'The language worker runtime to load in the function app.'
127+
type: string
128+
allowed:
129+
- 'dotnet'
130+
- 'dotnet-isolated'
131+
- 'java'
132+
- 'node'
133+
- 'powershell'
134+
- 'python'
135+
default: 'dotnet-isolated'
136+
```
137+
138+
## Related content
139+
140+
- [Add and configure an environment definition in Azure Deployment Environments](configure-environment-definition.md)
141+
- [Parameters in ARM templates](../azure-resource-manager/templates/parameters.md)
142+
- [Data types in ARM templates](../azure-resource-manager/templates/data-types.md)

‎articles/deployment-environments/configure-environment-definition.md

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ An environment definition is combined of least two files:
2525
>[!NOTE]
2626
> Azure Deployment Environments currently supports only ARM templates.
2727
28-
The IaC template contains the environment definition (template), and the environment file, that provides metadata about the template. Your development teams use the environment definitions that you provide in the catalog to deploy environments in Azure.
28+
The IaC template contains the environment definition (template), and the environment file, which provides metadata about the template. Your development teams use the environment definitions that you provide in the catalog to deploy environments in Azure.
2929

3030
We offer a [sample catalog](https://aka.ms/deployment-environments/SampleCatalog) that you can use as your repository. You also can use your own private repository, or you can fork and customize the environment definitions in the sample catalog.
3131

@@ -60,7 +60,7 @@ To add an environment definition:
6060
- [Understand the structure and syntax of ARM templates](../azure-resource-manager/templates/syntax.md): Describes the structure of an ARM template and the properties that are available in the different sections of a template.
6161
- [Use linked templates](../azure-resource-manager/templates/linked-templates.md?tabs=azure-powershell#use-relative-path-for-linked-templates): Describes how to use linked templates with the new ARM template `relativePath` property to easily modularize your templates and share core components between environment definitions.
6262

63-
- A environment as a YAML file.
63+
- An environment as a YAML file.
6464

6565
The *environment.yaml* file contains metadata related to the ARM template.
6666

@@ -80,6 +80,8 @@ To add an environment definition:
8080

8181
:::image type="content" source="../deployment-environments/media/configure-environment-definition/create-subfolder-path.png" alt-text="Screenshot that shows a folder path with a subfolder that contains an ARM template and an environment file.":::
8282

83+
To learn more about the options and data types you can use in environment.yaml, see [Parameters and data types in environment.yaml](concept-environment-yaml.md#what-is-environmentyaml).
84+
8385
1. In your dev center, go to **Catalogs**, select the repository, and then select **Sync**.
8486

8587
:::image type="content" source="../deployment-environments/media/configure-environment-definition/sync-catalog-list.png" alt-text="Screenshot that shows how to sync the catalog." :::
@@ -90,16 +92,7 @@ The service scans the repository to find new environment definitions. After you
9092

9193
You can specify parameters for your environment definitions to allow developers to customize their environments.
9294

93-
Parameters are defined in the environment.yaml file. You can use the following options for parameters:
94-
95-
|Option |Description |
96-
|---------|---------|
97-
|ID |Enter an ID for the parameter.|
98-
|name |Enter a name for the parameter.|
99-
|description |Enter a description for the parameter.|
100-
|default |Optional. Enter a default value for the parameter. The default value can be overwritten at creation.|
101-
|type |Enter the data type for the parameter.|
102-
|required|Enter `true` for a required value, and `false` for an optional value.|
95+
Parameters are defined in the environment.yaml file.
10396

10497
The following script is an example of a *environment.yaml* file that includes two parameters; `location` and `name`:
10598

@@ -123,6 +116,7 @@ parameters:
123116
type: "string"
124117
required: false
125118
```
119+
To learn more about the parameters and their data types you can use in environment.yaml, see [Parameters and data types in environment.yaml](concept-environment-yaml.md#parameters-in-environmentyaml).
126120

127121
Developers can supply values for specific parameters for their environments through the developer portal.
128122

‎articles/deployment-environments/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ items:
2424
href: concept-environments-key-concepts.md
2525
- name: Usage scenarios
2626
href: concept-environments-scenarios.md
27+
- name: Parameters and data types in environment.yaml
28+
href: concept-environment-yaml.md
2729
- name: Reliability in Azure Deployment Environments
2830
href: ../reliability/reliability-deployment-environments.md?toc=/azure/deployment-environments/toc.json&bc=/azure/deployment-environments/breadcrumb/toc.json
2931
- name: How-to guides

0 commit comments

Comments
 (0)