Merge pull request #186344 from tfitzmac/0126concepts

move bicep reference

Author: ShannonLeavitt

articles/azure-resource-manager/bicep/best-practices.md

@@ -92,7 +92,7 @@ For more information about Bicep variables, see [Variables in Bicep](variables.m
 
 * Make sure you don't create outputs for sensitive data. Output values can be accessed by anyone who has access to the deployment history. They're not appropriate for handling secrets.
 
-* Instead of passing property values around through outputs, use the [existing keyword](resource-declaration.md#existing-resources) to look up properties of resources that already exist. It's a best practice to look up keys from other resources in this way instead of passing them around through outputs. You'll always get the most up-to-date data.
+* Instead of passing property values around through outputs, use the [existing keyword](existing-resource.md) to look up properties of resources that already exist. It's a best practice to look up keys from other resources in this way instead of passing them around through outputs. You'll always get the most up-to-date data.
 
 For more information about Bicep outputs, see [Outputs in Bicep](outputs.md).
 

articles/azure-resource-manager/bicep/conditional-resource-deployment.md

@@ -42,7 +42,7 @@ module dnsZone 'dnszones.bicep' = if (deployZone) {
 }
 ```
 
-Conditions may be used with dependency declarations. For [explicit dependencies](resource-declaration.md#dependencies), Azure Resource Manager automatically removes it from the required dependencies when the resource isn't deployed. For implicit dependencies, referencing a property of a conditional resource is allowed but may produce a deployment error.
+Conditions may be used with dependency declarations. For [explicit dependencies](resource-dependencies.md), Azure Resource Manager automatically removes it from the required dependencies when the resource isn't deployed. For implicit dependencies, referencing a property of a conditional resource is allowed but may produce a deployment error.
 
 ## New or existing resource
 

articles/azure-resource-manager/bicep/existing-resource.md

@@ -0,0 +1,47 @@
+---
+title: Reference existing resource in Bicep
+description: Describes how to reference a resource that already exists.
+ms.topic: conceptual
+ms.date: 02/04/2022
+---
+
+# Existing resources in Bicep
+
+To reference an existing resource that isn't deployed in your current Bicep file, declare the resource with the `existing` keyword. Use the `existing` keyword when you're deploying a resource that needs to get a value from an existing resource. You access the existing resource's properties through its symbolic name.
+
+The resource isn't redeployed when referenced with the `existing` keyword.
+
+## Same scope
+
+The following example gets an existing storage account in the same resource group as the current deployment. Notice that you provide only the name of the existing resource. The properties are available through the symbolic name.
+
+```bicep
+resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' existing = {
+  name: 'examplestorage'
+}
+
+output blobEndpoint string = stg.properties.primaryEndpoints.blob
+```
+
+## Different scope
+
+Set the `scope` property to access a resource in a different scope. The following example references an existing storage account in a different resource group.
+
+```bicep
+resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' existing = {
+  name: 'examplestorage'
+  scope: resourceGroup(exampleRG)
+}
+
+output blobEndpoint string = stg.properties.primaryEndpoints.blob
+```
+
+For more information about setting the scope, see [Scope functions for Bicep](bicep-functions-scope.md).
+
+## Troubleshooting
+
+If you attempt to reference a resource that doesn't exist, you get the `NotFound` error and your deployment fails. Check the name and scope of the resource you're trying to reference.
+
+## Next steps
+
+For the syntax to deploy a resource, see [Resource declaration in Bicep](resource-declaration.md).

articles/azure-resource-manager/bicep/loops.md

@@ -340,4 +340,4 @@ resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2021-06-01
 
 ## Next steps
 
-- To set dependencies on resources that are created in a loop, see [Resource dependencies](./resource-declaration.md#dependencies).
+- To set dependencies on resources that are created in a loop, see [Resource dependencies](resource-dependencies.md).

articles/azure-resource-manager/bicep/media/resource-declaration/bicep-resource-visualizer.png renamed to articles/azure-resource-manager/bicep/media/resource-dependencies/bicep-resource-visualizer.png

@@ -59,7 +59,7 @@ To deploy **more than one instance** of a module, add the `for` expression. You
 
 ::: code language="bicep" source="~/azure-docs-bicep-samples/syntax-samples/modules/iterative-definition.bicep" highlight="3" :::
 
-Like resources, modules are deployed in parallel unless they depend on other modules or resources. Typically, you don't need to set dependencies as they're determined implicitly. If you need to set an explicit dependency, you can add `dependsOn` to the module definition. To learn more about dependencies, see [Resource dependencies](resource-declaration.md#dependencies).
+Like resources, modules are deployed in parallel unless they depend on other modules or resources. Typically, you don't need to set dependencies as they're determined implicitly. If you need to set an explicit dependency, you can add `dependsOn` to the module definition. To learn more about dependencies, see [Resource dependencies](resource-dependencies.md).
 
 ::: code language="bicep" source="~/azure-docs-bicep-samples/syntax-samples/modules/dependsOn-definition.bicep" highlight="6-8" :::
 

articles/azure-resource-manager/bicep/modules.md

@@ -1,10 +1,8 @@
 ---
 title: Declare resources in Bicep
 description: Describes how to declare resources to deploy in Bicep.
-author: mumian
-ms.author: jgao
 ms.topic: conceptual
-ms.date: 11/12/2021
+ms.date: 02/04/2022
 ---
 
 # Resource declaration in Bicep
@@ -187,111 +185,8 @@ resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
 }
 ```
 
-## Dependencies
-
-When deploying resources, you may need to make sure some resources exist before other resources. For example, you need a logical SQL server before deploying a database. You establish this relationship by marking one resource as dependent on the other resource. Order of resource deployment can be influenced in two ways: [implicit dependency](#implicit-dependency) and [explicit dependency](#explicit-dependency)
-
-Azure Resource Manager evaluates the dependencies between resources, and deploys them in their dependent order. When resources aren't dependent on each other, Resource Manager deploys them in parallel. You only need to define dependencies for resources that are deployed in the same Bicep file.
-
-### Implicit dependency
-
-An implicit dependency is created when one resource declaration references another resource in the same deployment. For example, *dnsZone* is referenced by the second resource definition in the following example:
-
-```bicep
-resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = {
-  name: 'myZone'
-  location: 'global'
-}
-
-resource otherResource 'Microsoft.Example/examples@2020-06-01' = {
-  name: 'exampleResource'
-  properties: {
-    // get read-only DNS zone property
-    nameServers: dnsZone.properties.nameServers
-  }
-}
-```
-
-A nested resource also has an implicit dependency on its containing resource.
-
-```bicep
-resource myParent 'My.Rp/parentType@2020-01-01' = {
-  name: 'myParent'
-  location: 'West US'
-
-  // depends on 'myParent' implicitly
-  resource myChild 'childType' = {
-    name: 'myChild'
-  }
-}
-```
-
-When an implicit dependency exists, **don't add an explicit dependency**.
-
-For more information about nested resources, see [Set name and type for child resources in Bicep](./child-resource-name-type.md).
-
-### Explicit dependency
-
-An explicit dependency is declared with the `dependsOn` property. The property accepts an array of resource identifiers, so you can specify more than one dependency.
-
-The following example shows a DNS zone named `otherZone` that depends on a DNS zone named `dnsZone`:
-
-```bicep
-resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = {
-  name: 'demoeZone1'
-  location: 'global'
-}
-
-resource otherZone 'Microsoft.Network/dnszones@2018-05-01' = {
-  name: 'demoZone2'
-  location: 'global'
-  dependsOn: [
-    dnsZone
-  ]
-}
-```
-
-While you may be inclined to use `dependsOn` to map relationships between your resources, it's important to understand why you're doing it. For example, to document how resources are interconnected, `dependsOn` isn't the right approach. You can't query which resources were defined in the `dependsOn` element after deployment. Setting unnecessary dependencies slows deployment time because Resource Manager can't deploy those resources in parallel.
-
-Even though explicit dependencies are sometimes required, the need for them is rare. In most cases, you can use a symbolic name to imply the dependency between resources. If you find yourself setting explicit dependencies, you should consider if there's a way to remove it.
-
-### Visualize dependencies
-
-Visual Studio Code provides a tool for visualizing the dependencies. Open a Bicep file in Visual Studio Code, and then select the visualizer button on the upper left corner.  The following screenshot shows the dependencies of a virtual machine.
-
-:::image type="content" source="./media/resource-declaration/bicep-resource-visualizer.png" alt-text="Screenshot of Visual Studio Code Bicep resource visualizer":::
-
-## Existing resources
-
-To reference a resource that's outside of the current Bicep file, use the `existing` keyword in a resource declaration.
-
-When using the `existing` keyword, provide the `name` of the resource. The following example gets an existing storage account in the same resource group as the current deployment.
-
-```bicep
-resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' existing = {
-  name: 'examplestorage'
-}
-
-output blobEndpoint string = stg.properties.primaryEndpoints.blob
-```
-
-Optionally, you can set the `scope` property to access a resource in a different scope. The following example references an existing storage account in a different resource group.
-
-```bicep
-resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' existing = {
-  name: 'examplestorage'
-  scope: resourceGroup(exampleRG)
-}
-
-output blobEndpoint string = stg.properties.primaryEndpoints.blob
-```
-
-If you attempt to reference a resource that doesn't exist, you get the `NotFound` error and your deployment fails.
-
-For more information about setting the scope, see [Scope functions for Bicep](bicep-functions-scope.md).
-
-The preceding examples don't deploy the storage account. Instead, you can access properties on the existing resource by using the symbolic name.
-
 ## Next steps
 
 - To conditionally deploy a resource, see [Conditional deployment in Bicep](./conditional-resource-deployment.md).
+- To reference an existing resource, see [Existing resources in Bicep](existing-resource.md).
+- To learn about how deployment order is determined, see [Resource dependencies in Bicep](resource-dependencies.md).

articles/azure-resource-manager/bicep/resource-declaration.md

@@ -0,0 +1,84 @@
+---
+title: Set resource dependencies in Bicep
+description: Describes how to specify the order resources are deployed.
+ms.topic: conceptual
+ms.date: 02/04/2022
+---
+
+# Resource dependencies in Bicep
+
+When deploying resources, you may need to make sure some resources are deployed before other resources. For example, you need a logical SQL server before deploying a database. You establish this relationship by marking one resource as dependent on the other resource. The order of resource deployment is determined in two ways: [implicit dependency](#implicit-dependency) and [explicit dependency](#explicit-dependency)
+
+Azure Resource Manager evaluates the dependencies between resources, and deploys them in their dependent order. When resources aren't dependent on each other, Resource Manager deploys them in parallel. You only need to define dependencies for resources that are deployed in the same Bicep file.
+
+## Implicit dependency
+
+An implicit dependency is created when one resource declaration references another resource in the same deployment. In the following example, `otherResource` gets a property from  `exampleDnsZone`. The resource named `otherResource` is implicitly dependent on `exampleDnsZone`.
+
+```bicep
+resource exampleDnsZone 'Microsoft.Network/dnszones@2018-05-01' = {
+  name: 'myZone'
+  location: 'global'
+}
+
+resource otherResource 'Microsoft.Example/examples@2020-06-01' = {
+  name: 'exampleResource'
+  properties: {
+    // get read-only DNS zone property
+    nameServers: exampleDnsZone.properties.nameServers
+  }
+}
+```
+
+A nested resource also has an implicit dependency on its containing resource.
+
+```bicep
+resource myParent 'My.Rp/parentType@2020-01-01' = {
+  name: 'myParent'
+  location: 'West US'
+
+  // implicit dependency on 'myParent'
+  resource myChild 'childType' = {
+    name: 'myChild'
+  }
+}
+```
+
+When an implicit dependency exists, **don't add an explicit dependency**.
+
+For more information about nested resources, see [Set name and type for child resources in Bicep](./child-resource-name-type.md).
+
+## Explicit dependency
+
+An explicit dependency is declared with the `dependsOn` property. The property accepts an array of resource identifiers, so you can specify more than one dependency.
+
+The following example shows a DNS zone named `otherZone` that depends on a DNS zone named `dnsZone`:
+
+```bicep
+resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = {
+  name: 'demoeZone1'
+  location: 'global'
+}
+
+resource otherZone 'Microsoft.Network/dnszones@2018-05-01' = {
+  name: 'demoZone2'
+  location: 'global'
+  dependsOn: [
+    dnsZone
+  ]
+}
+```
+
+While you may be inclined to use `dependsOn` to map relationships between your resources, it's important to understand why you're doing it. For example, to document how resources are interconnected, `dependsOn` isn't the right approach. You can't query which resources were defined in the `dependsOn` element after deployment. Setting unnecessary dependencies slows deployment time because Resource Manager can't deploy those resources in parallel.
+
+Even though explicit dependencies are sometimes required, the need for them is rare. In most cases, you can use a symbolic name to imply the dependency between resources. If you find yourself setting explicit dependencies, you should consider if there's a way to remove it.
+
+## Visualize dependencies
+
+Visual Studio Code provides a tool for visualizing the dependencies. Open a Bicep file in Visual Studio Code, and select the visualizer button on the upper left corner.  The following screenshot shows the dependencies of a virtual machine.
+
+:::image type="content" source="./media/resource-dependencies/bicep-resource-visualizer.png" alt-text="Screenshot of Visual Studio Code Bicep resource visualizer":::
+
+## Next steps
+
+For the syntax to deploy a resource, see [Resource declaration in Bicep](resource-declaration.md).

articles/azure-resource-manager/bicep/resource-dependencies.md

@@ -93,7 +93,7 @@ When you deploy your Azure resources by using a pipeline, you need to take care
   - [Azure Key Vault](../../key-vault/general/overview.md)
 - Bicep features
   - [Secure parameters](parameters.md#secure-parameters)
-  - [Referencing existing resources](resource-declaration.md#existing-resources)
+  - [Referencing existing resources](existing-resource.md)
   - [`getSecret` function](bicep-functions-resource.md#getsecret)
 - Quickstart templates
   - [Create a user-assigned managed identity and role assignments](https://github.com/Azure/azure-quickstart-templates/tree/master/modules/Microsoft.ManagedIdentity/user-assigned-identity-role-assignment/1.0)

articles/azure-resource-manager/bicep/scenarios-secrets.md

@@ -31,7 +31,7 @@ When you redeploy the same Bicep file, the same deployment sequence occurs. Howe
 
 ### Access subnet resource IDs
 
-You often need to refer to a subnet's resource ID. When you use the `subnets` property to define your subnet, [you can use the `existing` keyword](resource-declaration.md#existing-resources) to also obtain a strongly typed reference to the subnet, and then access the subnet's `id` property:
+You often need to refer to a subnet's resource ID. When you use the `subnets` property to define your subnet, [you can use the `existing` keyword](existing-resource.md) to also obtain a strongly typed reference to the subnet, and then access the subnet's `id` property:
 
 ::: code language="bicep" source="~/azure-docs-bicep-samples/samples/scenarios-virtual-networks/vnet.bicep" range="7-42" highlight="26-28, 30-32, 35-36" :::