Azure Arm Templates Use Reference?
Reference() Role Explained With Examples - ARM Template
In this mail, we will review reference() function which often comes handy when working with ARM templates. This function allows to retrieving runtime state of a resource which contains useful data such every bit URIs, names or other settings.
When I merely started poking ARM templates, reference() function was a lilliputian scrap unclear for me. That'south why in this post I decided to discuss it and walk though some mutual use cases.
Contents:
- Syntax
- 'Full' parameter
- Determining The Render Value
- [Best] Using ARM Template Outputs Department
- Creating ARM Template
- Applying Template
- Azure CLI Command
- Resources Explorer
- ARM Template Reference
- [Best] Using ARM Template Outputs Department
- Examples Of reference() Function
- Reference Existing Resource In The Aforementioned Resource Group
- Reference Existing Resources In Another Resource Group
- Reference Managed Identity
- Reference Nested Deployment Output
- Useful Links
Syntax
As defined in documentation, reference office can have from i to three parameters where simply the first one is required.
reference(resourceName or resourceIdentifier, [apiVersion], ['Full'])
Actually, parameters are well described in the official documentation only here is a high level overview:
-
resourceName- use it when referencing a resource in the same template -
resourceIdentifier- use it when referencing a resource not in the current template or when resources name is ambiguous. Utilise resourceId() function function to get the unique identifier of a resources. -
apiVersion- required only when the resource is not in the electric current template -
'Full'- use to remember total resource object, when omitted only properties object is returned
'Total' parameter
As already mentioned, 'Full' parameter should exist used when we need data that is non in properties department.
Probably, the near common utilise case for using 'Full' pick is to think information about Managed Identity associated with a resource, it is returned every bit identity property.
NOTE: Without 'Full' parameter reference() function returns properties object, with 'Full' - the unabridged runtime country object.
Determining The Return Value
The chief inconvenience with reference() function is that properties of a return value are dissimilar for every resources type and they are not documented well. Additionally, even for the aforementioned resources schema could differ depending on the apiVersion.
Let's review some of the ways we tin find out the schema of the render value for any resource (storage account, key vault, virtual machine, VMSS, AKS, Part App, etc.).
[All-time] Using ARM Template Outputs Section
This is a bulletproof method that will definitely work. The idea is simple - just output the render value from ARM template. This will allow you to view the bodily properties that are being returned from the reference() function.
Creating ARM Template
Here is an ARM template that you tin apply, just alter parameter values according to your resources.
{ "$schema" : "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#" , "contentVersion" : "1.0.0.0" , "parameters" : { "resourceType" : { "defaultValue" : "Microsoft.Storage/storageAccounts" , "blazon" : "String" }, "resourceName" : { "defaultValue" : "stcontoso" , "type" : "String" }, "apiVersion" : { "defaultValue" : "2019-06-01" , "type" : "Cord" } }, "resource" : [], "outputs" : { "resource" : { "type" : "Object" , "value" : "[reference(resourceId(parameters('resourceType'), parameters('resourceName')), parameters('apiVersion'))]" }, "resourceFull" : { "type" : "Object" , "value" : "[reference(resourceId(parameters('resourceType'), parameters('resourceName')), parameters('apiVersion'), 'Total')]" } } } Applying Template
There are many ways to utilize an ARM template file. In this case I would prefer to utilise "Custom Template Deployment In Azure Portal".
You lot should become results quite fast, for me information technology took less than 10 seconds. Output values are under the corresponding tab, just copy and prettify the JSON.
Template deployment outputs
For a storage account you will get output like to this:
{ "apiVersion" : "2019-06-01" , "location" : "westus2" , "sku" : { "name" : "Standard_RAGRS" , "tier" : "Standard" }, "tags" : {}, "kind" : "StorageV2" , "properties" : { "privateEndpointConnections" : [], "minimumTlsVersion" : "TLS1_2" , "allowBlobPublicAccess" : true , "allowSharedKeyAccess" : true , "networkAcls" : { "bypass" : "AzureServices" , "virtualNetworkRules" : [], "ipRules" : [], "defaultAction" : "Allow" }, "supportsHttpsTrafficOnly" : true , "encryption" : { "services" : { "file" : { "keyType" : "Account" , "enabled" : true , "lastEnabledTime" : "2021-01-28T16:18:46.5479110Z" }, "blob" : { "keyType" : "Account" , "enabled" : true , "lastEnabledTime" : "2021-01-28T16:18:46.5479110Z" } }, "keySource" : "Microsoft.Storage" }, "accessTier" : "Hot" , "provisioningState" : "Succeeded" , "creationTime" : "2021-01-28T16:18:46.4697950Z" , "primaryEndpoints" : { "dfs" : "https://stcontoso.dfs.core.windows.net/" , "web" : "https://stcontoso.z5.web.cadre.windows.net/" , "hulk" : "https://stcontoso.blob.core.windows.cyberspace/" , "queue" : "https://stcontoso.queue.core.windows.cyberspace/" , "tabular array" : "https://stcontoso.table.core.windows.internet/" , "file" : "https://stcontoso.file.core.windows.net/" }, "primaryLocation" : "westus2" , "statusOfPrimary" : "bachelor" , "secondaryLocation" : "westcentralus" , "statusOfSecondary" : "available" , "secondaryEndpoints" : { "dfs" : "https://stcontoso-secondary.dfs.core.windows.net/" , "web" : "https://stcontoso-secondary.z5.web.cadre.windows.internet/" , "blob" : "https://stcontoso-secondary.blob.core.windows.cyberspace/" , "queue" : "https://stcontoso-secondary.queue.core.windows.net/" , "table" : "https://stcontoso-secondary.table.core.windows.net/" } }, "subscriptionId" : "8e9b92ce-07d7-45d9-9544-cbfd1d3f1270" , "resourceGroupName" : "rg-contoso" , "scope" : "" , "resourceId" : "Microsoft.Storage/storageAccounts/stcontoso" , "referenceApiVersion" : "2019-06-01" , "condition" : truthful , "isConditionTrue" : true , "isTemplateResource" : imitation , "isAction" : simulated , "provisioningOperation" : "Read" } Azure CLI Command
Another good method to view resource state is to use az resource show command. Y'all can run this control in Azure Portal Cloud Shell.
NOTES:
- Compared to the previous method this one doesn't return additional backdrop related to ARM template when using 'Total' option and could differ in terms of other fields. Only most probable it won't be critical for you employ case.
- Demand to pass
--idand optionally--api-versionarguments,idcan be found underPropertiestab of resource page in Azure Portal
az resource prove --id /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName} --api-version 2018-04-01 For case, for a storage business relationship you'll get something similar to the following:
{ "id" : "/subscriptions/8e9b92ce-07d7-45d9-9544-cbfd1d3f1270/resourceGroups/rg-contoso/providers/Microsoft.Storage/storageAccounts/stcontoso" , "identity" : null , "kind" : "StorageV2" , "location" : "westus2" , "managedBy" : cipher , "name" : "stcontoso" , "plan" : nil , "properties" : { "accessTier" : "Hot" , "allowBlobPublicAccess" : true , "allowSharedKeyAccess" : true , "creationTime" : "2021-01-28T16:18:46.4697950Z" , "encryption" : { "keySource" : "Microsoft.Storage" , "services" : { "blob" : { "enabled" : true , "keyType" : "Business relationship" , "lastEnabledTime" : "2021-01-28T16:18:46.5479110Z" }, "file" : { "enabled" : true , "keyType" : "Business relationship" , "lastEnabledTime" : "2021-01-28T16:18:46.5479110Z" } } }, "minimumTlsVersion" : "TLS1_2" , "networkAcls" : { "bypass" : "AzureServices" , "defaultAction" : "Allow" , "ipRules" : [], "virtualNetworkRules" : [] }, "primaryEndpoints" : { "blob" : "https://stcontoso.hulk.core.windows.net/" , "dfs" : "https://stcontoso.dfs.core.windows.net/" , "file" : "https://stcontoso.file.core.windows.net/" , "queue" : "https://stcontoso.queue.core.windows.cyberspace/" , "tabular array" : "https://stcontoso.table.core.windows.cyberspace/" , "web" : "https://stcontoso.z5.web.cadre.windows.net/" }, "primaryLocation" : "westus2" , "privateEndpointConnections" : [], "provisioningState" : "Succeeded" , "secondaryEndpoints" : { "hulk" : "https://stcontoso-secondary.blob.cadre.windows.cyberspace/" , "dfs" : "https://stcontoso-secondary.dfs.core.windows.net/" , "queue" : "https://stcontoso-secondary.queue.core.windows.net/" , "table" : "https://stcontoso-secondary.table.core.windows.net/" , "web" : "https://stcontoso-secondary.z5.web.core.windows.net/" }, "secondaryLocation" : "westcentralus" , "statusOfPrimary" : "available" , "statusOfSecondary" : "available" , "supportsHttpsTrafficOnly" : true }, "resourceGroup" : "rg-contoso" , "sku" : { "capacity" : cypher , "family" : null , "model" : zip , "name" : "Standard_RAGRS" , "size" : null , "tier" : "Standard" }, "tags" : {}, "type" : "Microsoft.Storage/storageAccounts" } Resource Explorer
Resource Explorer is an culling way to view the land of a resource through Azure Portal. Search for "Resource Explorer" in the top bar, then select the resources you want to view.
Note: The chief downside is that it uses fixed apiVersion and in that location is no option to select another i. However, feel complimentary to use it if this version returns properties you are interested in.
Resource Explorer
ARM Template Reference
Just to mention that some information well-nigh the properties you might become from ARM template reference, for example, Microsoft.Storage storageAccounts template reference. Notwithstanding, be enlightened that it doesn't accept exactly the same schema since information technology'due south used for authoring resource just not retrieving their state, therefore, it might be not suitable for your needs.
Examples Of reference() Function
In the post-obit subsections allow's become over some mutual utilize cases you lot might see.
Reference Existing Resource In The Same Resource Grouping
To get a resource that is non role of the electric current template we have to invoke reference() function with at least 2 parameters:
reference(resourceIdentifier, apiVersion, ['Full'])
IMPORTANT: Parameter apiVersion is required.
Resources identifier could be hands retrieved using resourceId function. Below there is an example for a storage account, you lot could specify 'Full' parameter if needed.
"[reference(resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName')), '2019-06-01')]" Reference Existing Resource In Another Resource Group
If the resource we want to reference is in a different resource grouping, the only modification we need to brand compared to the previous example is to pass optional resourceGroupName parameter to the resourceId role.
For a storage account information technology will look like this:
"[reference(resourceId(parameters('resourceGroupName'), 'Microsoft.Storage/storageAccounts', parameters('storageAccountName')), '2019-06-01')]" Reference Managed Identity
To retrieve managed identity associated with a resource, simply invoke reference() function for this resource with 'Total' parameter. Identity data will exist returned inside of identity field.
For example, referencing VMSS managed identity principalId can be washed like this:
"[reference(resourceId('Microsoft.Compute/virtualMachineScaleSets', parameters('vmssName')), '2020-06-01', 'Full').identity.principalId]" The return object volition have the following schema:
{ "apiVersion" : "2020-06-01" , "..." : "..." "identity" : { "principalId" : "23d6c0c2-adf2-4958-a2da-6fc2d437e0c6" , "tenantId" : "283a576f-45dd-454b-99c0-b2c2680460e7" , "type" : "SystemAssigned" }, "properties" : { "..." : "..." } } Reference Nested Deployment Output
Allow's assume that we have a Microsoft.Resource/deployments resource where we do some nested deployment and return information about created resources. Next, we want to become this info in the parent resource.
It is easily achievable using reference() function in a fashion shown below:
"[reference('myNestedDeployment').outputs.someNestedResource.value.name]" Notation: Property expressionEvaluationOptions scope must be ready to inner if nosotros want to use reference part in the nested template. I've included this setting in the example beneath even though it's not strictly necessary here. https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/linked-templates?tabs=azure-powershell#expression-evaluation-scope-in-nested-templates
Here is an example of a template that references output of a nested deployment:
{ "$schema" : "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#" , "contentVersion" : "1.0.0.0" , "parameters" : {}, "resources" : [ { "type" : "Microsoft.Resources/deployments" , "apiVersion" : "2019-x-01" , "name" : "myNestedDeployment" , "properties" : { "mode" : "Incremental" , "expressionEvaluationOptions" : { "scope" : "inner" }, "template" : { "$schema" : "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#" , "contentVersion" : "1.0.0.0" , "resources" : [], "outputs" : { "someNestedResource" : { "type" : "object" , "value" : { "blazon" : "foo" , "name" : "bar" } } } } } } ], "outputs" : { "resource" : { "blazon" : "Object" , "value" : "[reference('myNestedDeployment')]" }, "resourceFull" : { "type" : "Object" , "value" : "[reference('myNestedDeployment', '2019-10-01', 'Full')]" } } } The output from a template above for resourceFull object is shown below. Actually, non-Full version is sufficient but I'one thousand including total object just for illustration purposes.
{ "apiVersion" : "2019-10-01" , "properties" : { "templateHash" : "16948081250938308320" , "mode" : "Incremental" , "provisioningState" : "Succeeded" , "timestamp" : "2021-02-01T16:45:07.8440489Z" , "duration" : "PT0.5157196S" , "correlationId" : "6c6e2fbb-6d45-4f0d-889e-e8cf8d57796d" , "providers" : [], "dependencies" : [], "outputs" : { "someNestedResource" : { "type" : "Object" , "value" : { "type" : "foo" , "name" : "bar" } } }, "outputResources" : [] }, "subscriptionId" : "ad51e962-25df-4b3f-bf46-e148c71d33e0" , "resourceGroupName" : "rg-contoso" , "scope" : "" , "resourceId" : "Microsoft.Resources/deployments/myNestedDeployment" , "referenceApiVersion" : "2019-10-01" , "condition" : true , "isConditionTrue" : true , "isTemplateResource" : false , "isAction" : imitation , "provisioningOperation" : "Read" } Useful Links
- Reference function documentation
- ARM templates
- Azure CLI
- https://resources.azure.com/
Azure Arm Templates Use Reference?,
Source: https://ochzhen.com/blog/reference-function-arm-template
Posted by: gordonlievaight.blogspot.com
0 Response to "Azure Arm Templates Use Reference?"
Post a Comment