Azure / Azure/bicep

Proposal - simplifying resource referencing (part 1)

Open
#2,245 27 comments 34 reactions 0 assignees View on GitHub
proposal
Dominant language
Bicep
Stars
3.6k
Forks
830
Avg merge
1d 2h
Merged PRs (30d)
79

Description

# Proposal - simplifying `resource` referencing (part 1)
[Part 1](https://github.com/Azure/bicep/issues/2245) / [Part 2](https://github.com/Azure/bicep/issues/2246)

## Problem statement
Passing around / obtaining references to resources in a type-safe manner is overly complex. Rather than inventing non-type-safe mechanisms to refer to resources or resource properties, we should provide a first-class syntax for doing so, with full type-safety and editor support.

## New 'resource' function
The `az` namespace will expose an additional function named `resource`, which can be used to obtain a reference to a resource within the current scope.

The `resource()` function takes the first parameter a string (following the [resource type](https://github.com/Azure/bicep/blob/main/docs/spec/resources.md#resource-type) format), and a variable number of arguments based on the number of qualified types in the type string. The semantics and validation for the type string parameter behave exactly as those for the type string in resource declarations.

Objects of type `scope` will also expose a `resource()` function, which can be used similarly to obtain a reference to a resource at a different scope.

### Examples
#### Global function
```bicep
var server = resource('Microsoft.Sql/servers@2020-02-02-preview', serverName)
// 'server' can now be used to access resource properties.
var serverProp = server.properties.someProp
```

#### Scope function
```bicep
var otherRg = resourceGroup('otherRgName')
var otherRgServer = otherRg.resource('Microsoft.Sql/servers@2020-02-02-preview', serverName)
// 'otherRgServer' is a reference to a resource in another scope.
var otherRgServerProp = otherRgServer.properties.someProp
```

#### Use to set parent property
```bicep
// here we can inline the function to provide a reference to the parent resource
resource mySubnet 'Microsoft.Network/virtualNetworks/subnets@2020-08-01' = {
parent: resource('Microsoft.Network/virtualNetworks@2020-08-01', vnetName)
name: 'mySubnet'
...
}
```

#### Use to set scope property
```bicep
// here we can inline the function to set a scope for the extension resource
resource diagnosticSettings 'Microsoft.Insights/diagnosticSettings@2020-01-01' = {
scope: resource('Microsoft.Compute/virtualMachines@2020-01-01', vmName)
name: 'diags'
...
}
```

### Notes
1. This provides the same functionality as the `existing` keyword, but as a more convenient one-liner.

## The 'child' function on a resource
All resources will expose an additional function named `child`, which can be used to obtain a reference to a child resource of a given type.

The `child()` function takes a string for the first parameter (following the [nested resource type](https://github.com/Azure/bicep/blob/main/docs/spec/resources.md#resource-nesting) format), and a second argument for the child resource name.

### Examples
#### Obtaining child resource references
```bicep
resource myVnet 'Microsoft.Network/virtualNetworks@2020-06-01' = {
name: 'myVnet'
...
}

// inheriting the same API version
var subnetRef1 = myVnet.child('subnets', subnetName)

// obtaining a reference with a different API version
var subnetRef2 = myVnet.child('subnets@2020-08-01', subnetName)
```

**EDIT 5/28/21**: Added info on `child()` function, removed proposal for extension resources

Contributor guide

Open the contributing guide

Research direction

Start by reading the resource type and resource nesting sections linked from docs/spec/resources.md, then compare the proposal with the existing existing keyword and scope/resource references. Done means the global and scope resource() forms and the resource child() form support the type and property-reference examples described in the issue, including alternate API versions.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure
Domain
cloud, compilers
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.