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
createOption
must be set to"Upload"
- The managed disk’s
uploadSizeBytes
must be set to theuploadSize
specified 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
userData
property 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
message
output 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.