Authoring ARM templates
This section is intended for users familiar with ARM templates. It provides detailed information about authoring templates for the App Layering Azure Deployments connector. For general ARM template authoring information, see the Microsoft documentation.
Input
Every deployment type is passed one parameter, an object named al. This object has two properties, input and context. The input property is an object specific to each deployment type and its properties change depending on the deployment type. The context property is the same for all deployment types. It contains data about the App Layering task, item (layer or image template), and connector configuration associated with the current deployment. For detailed information about the parameter object, see Azure Deployments Template Parameter.
Each template must declare the al parameter in its parameters section, as follows:
{
...
"parameters": {
"al": {
"type": "object"
}
},
...
}
<!--NeedCopy-->
A template can declare more parameters, but the parameters must all have default values. Otherwise, App Layering doesn’t provide value to them. This can be useful for using functions that can only be used in the default value section of a parameter, for example utcNow.
Output
All ARM templates can have outputs. With the Azure Deployments connector, template outputs can be used to pass information to the next deployment. They can also be used to override some default behaviors.
The outputs of a deployment are passed to the next deployment using the input property of the al template parameter.
For example, when a Cache Disk deployment has these outputs:
{
...
"outputs": {
"generation": {
"type": "string",
"value": "[variables('generation')]"
},
"name": {
"type": "string",
"value": "[variables('name')]"
},
}
...
}
<!--NeedCopy-->
The Boot Image deployment receives this input:
{
"input":
{
"type": "BootImage",
"source": {
"generation": "V2",
"name": "MyCoolDiskName"
}
},
"context": {
...
}
}
<!--NeedCopy-->
Notice the source property of the input object has a property for each output specified by the Cache Disk deployment template. The origins of each output depend on the type of deployment.
Deployment type details
Each deployment type has a different set of inputs and outputs that can change the behavior of the App Layering operation. These deployment-specific details are described in this section.
For real-world examples that use all of these concepts, see Starter Templates.
Cache Disk
The Cache Disk deployment must create a managed disk resource. You can optionally create other resources in addition to the disk. The App Layering appliance must have permission to write to the disk using a SAS token (generated by the appliance). A boot image containing the App Layering compositing engine is uploaded to the disk after it’s created.
Cache Disk Requirements
- Must create a managed disk resource
- The managed disk’s
createOptionmust be set to"Upload" - The managed disk’s
uploadSizeBytesmust be set to theuploadSizespecified by the input, such as"[parameters('al').input.uploadSize]" - The App Layering appliance must be able to write to the managed disk using a SAS token
{
...
"resources": [
{
"type": "Microsoft.Compute/disks",
...
"properties": {
...
"creationData": {
"createOption": "Upload",
"uploadSizeBytes": "[parameters('al').input.uploadSize]"
}
...
}
}
]
...
}
<!--NeedCopy-->
Cache Disk Input
The input object includes the size and uploadSize properties. This object does not include output from another deployment.
Cache Disk Output
The output of the deployment is passed to the Boot Image deployment if one is specified. Otherwise, it’s passed to the Machine deployment.
An output named diskId can be specified to explicitly tell App Layering which disk to use. If no diskId output is specified, App Layering automatically adds one and sets it to the resource ID of the first managed disk resource created by the deployment. The disk specified by diskId has the App Layering compositing engine boot image uploaded to it.
Boot Image
This deployment creates a resource from the managed disk created by the Cache Disk deployment. There are no hard requirements as to what type of resources are created. However, it must create a resource that can be used as the source of an OS disk when creating a VM, such as a compute gallery image version.
Boot Image Disk Requirements
- Must create a resource that can be used to create the OS disk of a VM with the same contents as the disk with the ID passed in as input.
As an example, a compute gallery image version using the input diskId as a source:
{
...
"resources": [
{
"type": "Microsoft.Compute/galleries/images/versions",
...
"properties": {
...
"storageProfile": {
"osDiskImage": {
"source": {
"id": "[parameters('al').input.source.diskId]"
}
}
}
...
}
}
]
...
}
<!--NeedCopy-->
Boot Image Input
The input object includes the source property. The source represents the outputs of the Cache Disk deployment, with a property for each output specified. Use the diskId property for the source of the resource being created.
Boot Image Output
The output of the Boot Image deployment is passed to the Machine deployment. There are no special or required outputs. However, you must include the data required to create a VM from the created resource, like a resource ID.
Machine
The Machine deployment must create a virtual machine resource. The virtual machine must be attached a network on which it can reach the App Layering appliance and the other way around, as per Firewall ports internal connections for Compositing machine.
Important:
Don’t attach the disk created by the Cache Disk deployment to the virtual machine. The Cache Disk is a shared resource and considered read only. Create a copy of the disk and attach that instead when not using the Boot Image deployment.
Machine Requirements
- Must create a virtual machine resource
- The virtual machine must be attached to a network that allows communication to and from the App Layering appliance
- The virtual machine’s OS disk must be created using Boot Image or Cache Disk resource as its source
- The virtual machine’s OS disk size must be set to
"[parameters('al').input.disk.size]" - The virtual machine’s
userDataproperty must be set to"[parameters('al').input.vm.userData]"
{
...
"resources": [
{
"type": "Microsoft.Compute/disks",
"name": "[variables('diskName')]",
...
"properties": {
...
"creationData": {
"createOption": "Copy",
"sourceResourceId": "[parameters('al').input.disk.image.diskId]"
},
"diskSizeGB": "[parameters('al').input.disk.size]",
...
}
},
{
"type": "Microsoft.Compute/virtualMachines",
...
"dependsOn": [
"[resourceId('Microsoft.Compute/disks', variables('diskName'))]"
],
...
"properties": {
...
"storageProfile": {
"osDisk": {
...
"createOption": "Attach",
"managedDisk": {
"id": "[resourceId('Microsoft.Compute/disks', variables('diskName'))]"
}
},
"dataDisks": []
},
...
"userData": "[parameters('al').input.vm.userData]"
...
}
}
]
...
}
<!--NeedCopy-->
Machine Input
The input object includes the disk and vm properties.
The disk.image property contains the output from the Boot Image deployment if one was specified. Otherwise, it contains the output of the Cache Disk deployment. The disk.size property contains the size of the disk in GB.
The vm.userData property contains the user data that must be assigned to the created virtual machine.
Machine Output
The output of the Machine deployment is passed to the Layered Image deployment if one is specified. If you’re using a Layered Image deployment, then you must include the ID of the VM or OS disk in the output so it can be referenced by the Layered Image deployment.
An output named machineId can be specified to explicitly tell App Layering which virtual machine to use. If no machineId output is specified, App Layering automatically adds one and sets it to the resource ID of the first virtual machine resource created by the deployment.
An output named ipAddress can be specified to explicitly tell App Layering which IP address to use to communicate with the machine. If no ipAddress output is specified, App Layering uses the primary private address of the primary network card attached to the virtual machine resource.
An output named message can be specified to provide a message that is appended to the final status of a publish image task and the action required status of a layer creation task in the App Layering UI. This message is only used in the final status of the image publish task if a Layered Image deployment isn’t specified.
- The Machine Starter Template sets the
messageoutput parameter to a link to the machine in the Azure portal.
Layered Image
The Layered Image deployment creates a resource from the virtual machine or other resources created by the Machine deployment. There are no hard requirements as to what type of resources are created. However, it creates a resource that can be used as an input to a Provisioning Service such as Machine Creation Services (MCS). A compute gallery image resource is a good example.
Layered Image Disk Requirements
- Creates a resource that can be used by a Provisioning Service to create virtual machines.
As an example, the following code block creates a compute gallery image version using the input diskId as a source. This assumes that the Machine deployment included an output named diskId that is set to the ID of the machine’s OS disk:
{
...
"resources": [
{
"type": "Microsoft.Compute/galleries/images",
"name": "[format('{0}/{1}', variables('galleryName'), variables('name'))]",
...
"resources": [
{
"type": "versions",
...
"dependsOn": [
"[resourceId('Microsoft.Compute/galleries/images', variables('galleryName'), variables('name'))]"
],
...
"properties": {
...
"storageProfile": {
"osDiskImage": {
"source": {
"id": "[parameters('al').input.source.diskId]"
}
}
}
...
}
}
]
}
],
...
}
<!--NeedCopy-->
Layered Image Input
The input object includes the source and diskName properties. The source represents the outputs of the Machine deployment, with a property for each output specified. The diskName property is the name of the disk specified in the App Layering image template.
Layered Image Output
The output of the deployment isn’t passed to any other deployments. However, an output named message can be specified to provide a message that is appended to the final status of a publish image task in the App Layering UI.