README.md 15.1 KB
Newer Older
Kay Singh's avatar
Kay Singh committed
1
2
# Azure Resource Manager QuickStart Templates

Marc van Eijk's avatar
Marc van Eijk committed
3
This repo contains all currently available Azure Resource Manager templates contributed by the community. A searchable template index is maintained at https://azure.microsoft.com/en-us/documentation/templates/.
Marc van Eijk's avatar
Marc van Eijk committed
4
The following information is relevant to get started with contributing to this repository.
Kay Singh's avatar
Kay Singh committed
5

6
7
8
+ [**Contribution guide**](/1-CONTRIBUTION-GUIDE/README.md#contribution-guide). Describes the minimal guidelines for contributing.
+ [**Best practices**](/1-CONTRIBUTION-GUIDE/best-practices.md#best-practices). Best practices for improving the quality of your template design.
+ [**Git tutorial**](/1-CONTRIBUTION-GUIDE/git-tutorial.md#git-tutorial). Step by step to get you started with Git.
crystaju's avatar
crystaju committed
9
+ [**Useful Tools**](/1-CONTRIBUTION-GUIDE/useful-tools.md#useful-tools). Useful resources and tools for Azure development.
Kay Singh's avatar
Kay Singh committed
10

11
12
13
14
## Deploying Samples

You can deploy these samples directly through the Azure Portal or by using the scripts supplied in the root of the repo.

Aftab Ansari's avatar
Aftab Ansari committed
15
To deploy a sample using the Azure Portal, click the **Deploy to Azure** button found in the README.md of each sample.
16
17
18

To deploy the sample via the command line (using [Azure PowerShell or the Azure CLI](https://azure.microsoft.com/en-us/downloads/)) you can use the scripts.

indolent's avatar
indolent committed
19
Simply execute the script and pass in the folder name of the sample you want to deploy.  For example:
20
21

```PowerShell
indolent's avatar
indolent committed
22
.\Deploy-AzureResourceGroup.ps1 -ResourceGroupLocation 'eastus' -ArtifactStagingDirectory '[foldername]'
23
24
```
```bash
25
azure-group-deploy.sh -a [foldername] -l eastus
26
27
28
29
30
31
```
If the sample has artifacts that need to be "staged" for deployment (Configuration Scripts, Nested Templates, DSC Packages) then set the upload switch on the command.
You can optionally specify a storage account to use, if so the storage account must already exist within the subscription.  If you don't want to specify a storage account
one will be created by the script or reused if it already exists (think of this as "temp" storage for AzureRM).

```PowerShell
indolent's avatar
indolent committed
32
.\Deploy-AzureResourceGroup.ps1 -ResourceGroupLocation 'eastus' -ArtifactStagingDirectory '201-vm-custom-script-windows' -UploadArtifacts 
33
34
35
36
```
```bash
azure-group-deploy.sh -a '201-vm-custom-script-windows' -l eastus -u
```
Kay Singh's avatar
Kay Singh committed
37

Marc van Eijk's avatar
Marc van Eijk committed
38
## Contribution guide
39

Marc van Eijk's avatar
Marc van Eijk committed
40
To make sure your template is added to Azure.com index, please follow these guidelines. Any templates that are out of compliance will be added to the **blacklist** and not be indexed on Azure.com
41

Marc van Eijk's avatar
Marc van Eijk committed
42
## Files, folders and naming conventions
43

Marc van Eijk's avatar
Marc van Eijk committed
44
1. Every deployment template and its associated files must be contained in its own **folder**. Name this folder something that describes what your template does. Usually this naming pattern looks like **appName-osName** or **level-platformCapability** (e.g. 101-vm-user-image) 
45
 + **Required** - Numbering should start at 101. 100 is reserved for things that need to be at the top.
Marc van Eijk's avatar
Marc van Eijk committed
46
 + **Protip** - Try to keep the name of your template folder short so that it fits inside the Github folder name column width.
47
48
2. Github uses ASCII for ordering files and folder. For consistent ordering **create all files and folders in lowercase**. The only **exception** to this guideline is the **README.md**, that should be in the format **UPPERCASE.lowercase**.
3. Include a **README.md** file that explains how the template works. 
Marc van Eijk's avatar
Marc van Eijk committed
49
 + Guidelines on the README.md file below.
50
51
4. The deployment template file must be named **azuredeploy.json**.
5. There should be a parameters file named **azuredeploy.parameters.json**. 
Marc van Eijk's avatar
Marc van Eijk committed
52
 + Please fill out the values for the parameters according to rules defined in the template (allowed values etc.), For parameters without rules, a simple "changeme" will do as the acomghbot only checks for syntactic correctness using the ARM Validate Template [API](https://msdn.microsoft.com/en-us/library/azure/dn790547.aspx).
53
6. The template folder must contain a **metadata.json** file to allow the template to be indexed on [Azure.com](http://azure.microsoft.com/). 
Marc van Eijk's avatar
Marc van Eijk committed
54
 + Guidelines on the metadata.json file below.
55
56
57
58
7. The custom scripts that are needed for successful template execution must be placed in a folder called **scripts**.
8. Linked templates must be placed in a folder called **nested**.
9. Images used in the README.md must be placed in a folder called **images**. 
10. Any resources that need to be setup outside the template should be named prefixed with existing (e.g. existingVNET, existingDiagnosticsStorageAccount).
59

Marc van Eijk's avatar
Marc van Eijk committed
60
![alt text](/1-CONTRIBUTION-GUIDE/images/namingConvention.png "Files, folders and naming conventions")
Marc van Eijk's avatar
Marc van Eijk committed
61
62
 
## README.md
63

Marc van Eijk's avatar
Marc van Eijk committed
64
The README.md describes your deployment. A good description helps other community members to understand your deployment. The README.md uses [Github Flavored Markdown](https://guides.github.com/features/mastering-markdown/) for formatting text. If you want to add images to your README.md file, store the images in the **images** folder. Reference the images in the README.md with a relative path (e.g. `![alt text](images/namingConvention.png "Files, folders and naming conventions")`). This ensures the link will reference the target repository if the source repository is forked. A good README.md contains the following sections
65

Marc van Eijk's avatar
Marc van Eijk committed
66
+ Deploy to Azure button
Marc van Eijk's avatar
Marc van Eijk committed
67
+ Visualize button
Marc van Eijk's avatar
Marc van Eijk committed
68
+ Description of what the template will deploy
Michael's avatar
Michael committed
69
+ Tags, that can be used for search. Specify the tags comma seperated and enclosed between two back-ticks (e.g Tags: `cluster, ha, sql`)
Marc van Eijk's avatar
Marc van Eijk committed
70
71
72
+ *Optional: Prerequisites
+ *Optional: Description on how to use the application
+ *Optional: Notes
Marc van Eijk's avatar
Marc van Eijk committed
73
74
75

Do **not include** the **parameters or the variables** of the deployment script. We render this on Azure.com from the template. Specifying these in the README.md will result in **duplicate entries** on Azure.com.

Marc van Eijk's avatar
Marc van Eijk committed
76
77
You can download a [**sample README.md**](/1-CONTRIBUTION-GUIDE/sample-README.md) for use in your deployment scenario. The **sample README.md** also contains the code for the **Deploy to Azure** and **Visualize** buttons, that you can use as a reference.

Marc van Eijk's avatar
Marc van Eijk committed
78
## metadata.json
Kay Singh's avatar
Kay Singh committed
79

80
A valid metadata.json must adhere to the following structure
Marc van Eijk's avatar
Marc van Eijk committed
81
82
83
84
85
86
87
88
89
90

```
{
  "itemDisplayName": "",
  "description": "",
  "summary": "",
  "githubUsername": "",
  "dateUpdated": "<e.g. 2015-12-20>"
}
```
Kay Singh's avatar
Kay Singh committed
91
92
93
94

The metadata.json file will be validated using these rules

**itemDisplayName**
Marc van Eijk's avatar
Marc van Eijk committed
95

Marc van Eijk's avatar
Marc van Eijk committed
96
+ Cannot be more than 60 characters
Kay Singh's avatar
Kay Singh committed
97
98

**description**
Marc van Eijk's avatar
Marc van Eijk committed
99

Marc van Eijk's avatar
Marc van Eijk committed
100
101
+ Cannot be more than 1000 characters
+ Cannot contain HTML This is used for the template description on the Azure.com index template details page
Kay Singh's avatar
Kay Singh committed
102
103

**summary**
Marc van Eijk's avatar
Marc van Eijk committed
104

Marc van Eijk's avatar
Marc van Eijk committed
105
106
+ Cannot be more than 200 characters
+ This is shown for template description on the main Azure.com template index page
Kay Singh's avatar
Kay Singh committed
107
108
109

**githubUsername**

Marc van Eijk's avatar
Marc van Eijk committed
110
111
+ This is the username of the original template author. Do not change this
+ This is used to display template author and Github profile pic in the Azure.com index
Kay Singh's avatar
Kay Singh committed
112

Marc van Eijk's avatar
Marc van Eijk committed
113
**dateUpdated**
Kay Singh's avatar
Kay Singh committed
114

Marc van Eijk's avatar
Marc van Eijk committed
115
116
+ Must be in yyyy-mm-dd format.
+ The date must not be in the future to the date of the pull request
Kay Singh's avatar
Kay Singh committed
117

Kay Singh's avatar
Kay Singh committed
118
119
120
121
## Common errors from acomghbot

acomghbot is a bot designed to enforce the above rules and check the syntactic correctness of the template using the ARM Validate Template [API](https://msdn.microsoft.com/en-us/library/azure/dn790547.aspx). Below are some of the more cryptic error messages you might receive from the bot and how to solve these issues.

Marc van Eijk's avatar
Marc van Eijk committed
122
+ This error is received when the parameters file contains a parameter that is not defined in the template.
Kay Singh's avatar
Kay Singh committed
123

Marc van Eijk's avatar
Marc van Eijk committed
124
 The file azuredeploy.json is not valid. Response from ARM API: BadRequest - {"error":{"code":"InvalidTemplate","message":"Deployment template validation failed: 'The template parameters 'vmDnsName' are not valid; they are not present in the original template and can therefore not be provided at deployment time. The only supported parameters for this template are 'newStorageAccountName, adminUsername, adminPassword, dnsNameForPublicIP, windowsOSVersion, sizeOfDiskInGB'.'."}}
Kay Singh's avatar
Kay Singh committed
125

Marc van Eijk's avatar
Marc van Eijk committed
126
+ This error is received when a parameter in the parameter file has an empty value.
Kay Singh's avatar
Kay Singh committed
127

Marc van Eijk's avatar
Marc van Eijk committed
128
 The file azuredeploy.json is not valid. Response from ARM API: BadRequest - {"error":{"code":"InvalidTemplate","message":"Deployment template validation failed: 'The template resource '' at line '66' and column '6' is not valid. The name property cannot be null or empty'."}}
Kay Singh's avatar
Kay Singh committed
129

Marc van Eijk's avatar
Marc van Eijk committed
130
+ This error message is received when a value entered in the parameters file is different from the allowed values defined for the parameter in the template file.
Kay Singh's avatar
Kay Singh committed
131

Marc van Eijk's avatar
Marc van Eijk committed
132
 The file azuredeploy.json is not valid. Response from ARM API: BadRequest - {"error":{"code":"InvalidTemplate","message":"Deployment template validation failed: 'The provided value for the template parameter 'publicIPAddressType' at line '40' and column '29' is not valid.'."}}
133
134
135

## Travis CI

136
We have automated template validation through Travis CI. These builds can be accessed by clicking the 'Details' link at the bottom of the pull-request dialog. This process will ensure that your template conforms to all the rules mentioned above and will also deploy your template to our test azure subscription.
137
138
139
140
141

### Parameters File Placeholders

To ensure your template passes, special placeholder values are required when deploying a template, depending what the parameter is used for:

Marc van Eijk's avatar
Marc van Eijk committed
142
143
144
145
+ **GEN-UNIQUE** - use this placeholder for new storage account names, domain names for public ips and other fields that need a unique name. The value will always be alpha numeric value with a length of 18 characters.
+ **GEN-UNIQUE-[N]** - use this placeholder for new storage account names, domain names for public ips and other fields that need a unique name. The value will always be alpha numeric value with a length of `[N]`, where `[N]` can be any number from 3 to 32 inclusive.
+ **GEN-SSH-PUB-KEY** - use this placeholder if you need an SSH public key
+ **GEN-PASSWORD** - use this placeholder if you need an azure-compatible password for a VM
146
147
148
149
150

Here's an example in an `azuredeploy.parameters.json` file:

```
{
Marc van Eijk's avatar
Marc van Eijk committed
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
"$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
"contentVersion": "1.0.0.0",
"parameters": {
 "newStorageAccountName":{
  "value": "GEN-UNIQUE"
 },
 "adminUsername": {
  "value": "sedouard"
 },
 "sshKeyData": {
  "value": "GEN-SSH-PUB-KEY"
 },
 "dnsNameForPublicIP": {
  "value": "GEN-UNIQUE-13"
 }
166
167
168
}
```

Marc van Eijk's avatar
Marc van Eijk committed
169
### raw.githubusercontent.com Links
170

Marc van Eijk's avatar
Marc van Eijk committed
171
If you're making use of **raw.githubusercontent.com** links within your template contribution (within the template file itself or any scripts in your contribution) please ensure the following:
172

Marc van Eijk's avatar
Marc van Eijk committed
173
174
175
+ Ensure any raw.githubusercontent.com links which refer to content within your pull request points to `https://raw.githubusercontent.com/Azure/azure-quickstart-templates/...` and **NOT** your fork.
+ All raw.githubusercontent.com links are placed in your azuredeploy.json and you pass the link down into your scripts & linked templates via this top-level template. This ensures we re-link correctly from your pull-request repository and branch.
+ Although pull requests with links pointing to `https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/...` may not exist in the Azure repo at the time of your pull-request, at CI run-time, those links will be converted to `https://raw.githubusercontent.com/{your_user_name}/azure-quickstart-templates/{your_branch}/...`. Be sure to check the casing of `https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/...` as this is case-sensitive.
176

Marc van Eijk's avatar
Marc van Eijk committed
177
Note: You can find an **example** of relative linking in the [nested template section](/1-CONTRIBUTION-GUIDE/best-practices.md#nested-templates) of best practices document.
178

Marc van Eijk's avatar
Marc van Eijk committed
179
### Template Pre-requisites
180

Marc van Eijk's avatar
Marc van Eijk committed
181
If your template has some pre-requisite such as an Azure Active Directory application or service principal, we don't support this yet. To bypass the CI workflow include a file called .ci_skip in the root of your template folder.
182

Marc van Eijk's avatar
Marc van Eijk committed
183
### Diagnosing Failures
184
185

If your deployment fails, check the details link of the Travis CI build, which will take you to the CI log. If the template deployment was attempted, you will get two top-level fields. The first is `parameters` which is the rendered version of your `azuredeploy.parameters.json`. This will include any replacements for `GEN-` parameters. The second is `template` which is the contents of your `azuredeploy.json`, after any `raw.githubusercontent.com` relinking. These values are the exact values you need to reproduce the error. Keep in mind, that depending on the resources allocated, it can take a few minutes for the CI system to cleanup provisioned resources.
186

187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
Here is an example failure log:

```
Server Error:{
    "error": "Deployment provisioning state was not successful\n",
    "_rgName": "qstci-26dd2ec4-bae9-12fb-fd46-fd4ce455a035",
    "command": "azure group deployment create --resource-group (your_group_name) --template-file azuredeploy.json --parameters-file azuredeploy.parameters.json",
    "parameters": {
        "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
        "contentVersion": "1.0.0.0",
        "parameters": {
            "clusterName": {
                "value": "ci4391bcd700f86e84"
            },
            "clusterType": {
                "value": "hadoop"
            },
            "clusterStorageAccountName": {
                "value": "cifb07cf059735afba"
            },
            "clusterLoginUserName": {
                "value": "admin"
            },
            "clusterLoginPassword": {
                "value": "ciP$ss2e6a28784055eda8"
            }
        }
    },
    "template": {
        "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
        "contentVersion": "1.0.0.0",
        "parameters": {
            "clusterType": {
                "type": "string",
                "allowedValues": [
                    "hadoop",
                    "hbase",
                    "storm",
                    "spark"
                ],
                "metadata": {
                    "description": "The type of the HDInsight cluster to create."
                }
            }
            // more parameters here...
        },
        "variables": {
            "defaultApiVersion": "2015-06-15",
            "clusterApiVersion": "2015-03-01-preview",
            "adlsApiVersion": "2015-10-01-preview"
        },
        "resources": [
            {
                "name": "[parameters('adlStoreName')]",
                "type": "Microsoft.DataLakeStore/accounts",
                "location": "East US 2",
                "apiVersion": "[variables('adlsApiVersion')]",
                "dependsOn": [],
                "tags": {},
                "properties": {
                    "initialUser": "[parameters('servicePrincipalObjectId')]"
                }
            },
            // more resources here...
        ],
        "outputs": {
            "adlStoreAccount": {
                "type": "object",
                "value": "[reference(resourceId('Microsoft.DataLakeStore/accounts',parameters('adlStoreName')))]"
            }
            // more outputs here...
        }
    }
}
261
```
Kay Singh's avatar
Kay Singh committed
262
263
264

```
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
Aftab Ansari's avatar
Aftab Ansari committed
265
```