remove apiVersion requirement from list* functions when resource is defined in the template

[bmoore-msft]

Like reference, when we can assert and apiVersion for the function, don't require the user to supply it. More reasonable now that we have type info and can help with authoring.

A bonus would be to not require it when it's in a module (as I think this will probably be more common in bicep).

[miqm]

we have a mechanism to have instance methods on resources (developed for getSecret function), perhaps we could use that one so we'll have a resourceSymbol.list() syntax? Open question is how to get which functions particular resource type supports...

[anthony-c-martin]

@bmoore-msft, @miqm - this has actually just been checked in under #3430. The API version is optional; by default we'll use the API version of the resource that is being referenced.

Also note, we don't yet have type availability for list* functions; but it's something I'm hoping to get to soon.

Here's an example of the syntax; we'll publicly document it for the next Bicep release:

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: accountName
  ...
}

// use the resource's API version
output pkMethod string = stg.listKeys().keys[0].value

// use a custom API version
output pkMethod string = stg.listKeys('2020-01-01').keys[0].value

[miqm]

Sweet:)

[bmoore-msft]

@anthony-c-martin - a couple questions:

1. does this only work when called on a symbolic reference? or also when standalone?
2. does it only work when defined in the same template (i.e. not a module)?

[anthony-c-martin]

@anthony-c-martin - a couple questions:

1. does this only work when called on a symbolic reference? or also when standalone?

Only on a symbolic reference. There's no way to accurately obtain an API version for the standalone (string-based) equivalent AFAIK.

2. does it only work when defined in the same template (i.e. not a module)?

Currently only in the same template, but my plan is to leverage #2245 & #2246 to provide better options between modules. Of course with modules, you can always obtain a new symbolic reference using existing, but it's a little tedious.

[bmoore-msft]

For for first one, we would know by the resourceId reference.... e.g. https://github.com/Azure/azure-quickstart-templates/blob/master/quickstarts/microsoft.web/function-premium-vnet-integration/main.bicep#L116

Since the first arg is a symbolic ref, we can grab the apiVersion from there... Though a better option might be to lint the use of listkeys with the type of arg since we might prefer myStorage.listKeys() anyway?

[alex-frankel]

So the request is to support a function signature like so?

resource stg '...' = { ... }

output keys string = listKeys(stg).keys[0].value

Is that right? If so, I'd prefer to not build support for a new function signature like that. Instead, just like you mention, we should push them to the new functionality that Anthony implemented via the linter. Thoughts?

[bmoore-msft]

I think the spirit we're after is to minimize the places where I have to worry about apiVersions, when bicep already has one to use... In the case where things are all in the same deployment, linting this:

listkeys(storageAccount.id, storageAccount.apiVersion).keys[0].value

to be this:

storageAccount.listKeys().keys[0].value

seems like the right bicep sln.

The next scenario would be when the stg account is in a different deployment (i.e. module)... can we simplify that case case to have the new sig you suggested (as the output). It's worth poking how we could but seems like a prereq to that is being able to say stg when stg isn't defined in the deployment. Which seems like a larger issue that needs to be ironed out before worrying about simplifying the list*() functions...

[alex-frankel]

a prereq to that is being able to say stg when stg isn't defined in the deployment.

Isn't this what the existing keyword and #2245 is for? IOW, if we solve the "getting a symbolic reference anywhere" problem, combined with the new syntax for *.list*() functions, should we consider this issue closed?

[bmoore-msft]

yes, but as @anthony-c-martin mentioned it's a little tedious, and... we already know the information since it's in a module...

if we require the existing syntax, it's easier just to use the independent function of listKeys().

[anthony-c-martin]

if we require the existing syntax, it's easier just to use the independent function of listKeys().

Agreed - today. However I'm planning this with #2245 & #2246 in mind (to simplify the existing/other-module scenario), and #667 (to provide actual completions and type safety).

Some examples (and keep in mind that type safety, hovers, completions will work in all parts of the following):

// resource reference
var accountKey = resource('Microsoft.Storage/storageAccounts@2019-06-01', accountName).listKeys().keys[0].value

// param
param stg resource<'Microsoft.Storage/storageAccounts@2019-06-01'>

var accountkey = stg.listKeys().keys[0].value

[majastrz]

@bmoore-msft does this address your concerns?

[bmoore-msft]

yep - the param route is golden - what would I pass in to a deployment for that though?

[alex-frankel]

what would I pass in to a deployment for that though?

Do you mean a module? If so, you would pass in the resource symbol directly. So if you had a resource like:

resource stg '...' = { ... }

Then you have a module that expects a storage resource:

module thingThatNeedsStorage 'thingThatNeedsStorage.bicep' = {
  name: 'foo'
  params: {
    storageAccount: stg
  }
}

If that looks good, should we close this issue?

[bmoore-msft]

Not for the module but for the top level deployment... e.g. if I have this declaration in main.bicep

param stg resource<'Microsoft.Storage/storageAccounts@2019-06-01'>

What [string?] value is in my parameter file? a resourceId?

[alex-frankel]

What [string?] value is in my parameter file? a resourceId?

Yep - a resource ID. I don't think it is 100% closed, but that's the plan unless we have a good reason to change it.

[bmoore-msft]

Got it... it's probably worth thinking through a scenario where the constituent parts of the resource ID are used instead of a full uri (which are unwieldy to deal with as a human)... not sure common it will be but I suspect as the pattern catches on, moreso...

[alex-frankel]

Makes sense. I'm definitely open to other ways to provide the necessary info. We can start with a resourceId as a "floor" and expand from there.

Going to close this issue for now and we will track this part of the discussion in #2245/#2246