---
title: "Working with templates"
author: Hong Ooi
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Working with templates}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{utf8}
---

An Azure [template](https://learn.microsoft.com/en-us/azure/azure-resource-manager/template-deployment-overview) is a JSON file that can be used to automate the deployment of a set of related resources. The template uses declarative syntax, which lets you state what you intend to deploy without having to write the sequence of programming commands to create it. In the template, you specify the resources to deploy and the properties for those resources.

Deploying a template with AzureRMR is just a matter of calling a resource group object's `deploy_template` method. This takes two arguments, `template` and `parameters`. `deploy_template` is very flexible in how you can specify its arguments:

- As character strings containing unparsed JSON text.
- As a (nested) list of R objects, which will be converted to JSON via `jsonlite::toJSON`.
- A filename or connection pointing to a JSON file.
- A URL from which the template can be accessed.
- For the `parameters` argument, this can also be a character vector containing the types of each parameter.

```r
vm_tpl <- rg$deploy_template("myNewVirtualMachine",
    template="vm_template.json",
    parameters=list(
        os="Linux",
        size="Standard_DS2_v2",
        username="ruser",
        publickey=readLines("~/id_rsa.pub")
    ))
```

Normally, deleting a template doesn't touch the resources it creates: it only deletes the template itself. However, AzureRMR optionally allows you to free any resources created when you delete a template. This is useful when managing complex objects like VMs, which actually consist of multiple individual resources in Azure (storage account, disk, network interface, etc). When you are done with the VM, deleting the template lets you free all these resources with a single command.

```r
vm_tpl$delete(free_resources=TRUE)
```

## Template helper functions

AzureRMR also provides the `build_template_definition` and `build_template_parameters` functions to help you construct or modify a template. Both of these are generics and can be extended by other packages to handle specific deployment scenarios, eg virtual machines.

`build_template_definition` is used to generate the template JSON. The default method has 4 arguments `parameters`, `variables`, `resources` and `outputs`, which are the components of a template; these should be either strings containing the unparsed JSON text, or lists to be converted into JSON. `build_template_parameters` is for creating the list of parameters to be passed along with the template. Its arguments should all be named, and contain either the JSON text or an R list giving the parsed JSON.

```r
# a storage account template
storage_tpl <- build_template_definition(
    parameters=c(
        name="string",
        location="string",
        sku="string"
    ),
    variables=list(
        id="[resourceId('Microsoft.Storage/storageAccounts', parameters('name'))]"
    ),
    resources=list(
        list(
            name="[parameters('name')]",
            location="[parameters('location')]",
            type="Microsoft.Storage/storageAccounts",
            apiVersion="2018-07-01",
            sku=list(
                name="[parameters('sku')]"
            ),
            kind="Storage"
        )
    ),
    outputs=list(
        storageId="[variables('id')]"
    )
)

# the corresponding parameters
storage_pars <- build_template_parameters(
    name="mystorageacct",
    location="westus",
    sku="Standard_LRS"
)
```

Once created, the template defintion and parameters can be passed directly to `deploy_template`:

```r
# deploying
rg$deploy_template("mystorageacct", template=storage_tpl, parameters=storage_pars)
```
