Feature Request: Support a global Bicep config file (under ~/.bicep/bicepconfig.json)

[asilverman]

Is your feature request related to a problem? Please describe.
Whenever I use the Bicep VSCode / VS extension on a scratch file (or a temporary file) I would like to configure a default behavior for the VSCode extension language server. As of now I am forced to create a bicepconfig.json in the directory where my scratch file is found so that the language server recognizes the features of the language I am using.

For example, notice the file below, (found in ~/tmp/foo.bicep)

The linter complains that it doesn't know about imports. I want to be able to specify ~/.bicep/bicepconfig.json as follows

{
    "experimentalFeaturesEnabled": {
        "imports": true,
        "extensibility": true
    }
}

And have the language server pick this up in the absence of a bicepconfig.json inside ~/tmp.

== NOTE: If a bicepconfig.json is specified in the folder structure it should take precedece ==

For example: if the file below was specified under ~/tmp/ then I would expect the behavior of the language server to be the same as shown above (with the red squigglys)

~/tmp/bicepconfig.json

{
    "experimentalFeaturesEnabled": {
        "imports": false,
        "extensibility": false
    }
}

[asilverman]

Additional Info

In the case of an unsaved file, the error message doesn't guide the user about what to do. It only says that EXPERIMENTAL is needed but doesn't describe how to enable it.

[asilverman]

Hey folks, I feel like my memory is already deceiving me and I may forgot what the conclusion was with relation to the topic of the bicepconfig.json. I will try to summarize my notes and please feel free to reply with anything I missed or misunderstood.

So the initial proposal was motivated by the need for a defined behavior in the case of a user authoring an unsaved file.

Alan ('A' user :)) has heard about Bicep and he is interested in exploring a new Bicep experimental feature called 'kubernetes extensibility'. Alan reads about this feature in some ⁠blog.

Alan installs the Bicep extension for VSCode and creates a new unsaved (scratch) file to go along with the content written in the blog. The blog says that he needs to setup his bicepconfig.json however Alan skips reading this because he is an eager user and moves on.

He proceeds to paste the following content into his scratch file:

@secure()
param kubeConfig string

import 'kubernetes@1.0.0' with {
  namespace: 'default'
  kubeConfig: kubeConfig
}

resource aks 'Microsoft.ContainerService/managedClusters@2022-05-02-preview' existing = {
  name: 'demoAKSCluster'
}

module kubernetes './kubernetes.bicep' = {
  name: 'buildbicep-deploy'
  params: {
    kubeConfig: aks.listClusterAdminCredential().kubeconfigs[0].value
  }
}

Alan notices the IDE is complaining about the code he just pasted (see image below).

-- Silly Alan --, he forgot to setup the bicepconfig.json so he goes to the link in the blog that tells him how to set these up, (the hyperlink in the picture below -> bicepconfig.json)

Now Alan follows the instructions to create his bicepconfig.json, he uses Ctrl+P to use the extension contextual action to create one

The IDE prompts him with a question: "Where would you like to save the Bicep configuration file?" ... Alan is faced with a question he can't really answer because the current behavior is not documented.

The current behavior per our investigation is that the extension will look (in the windows case) in the C:\ directory for a bicepconfig.json however Alan does not know this. Instead, he decides to use the default location provided by the extension: the $HOME folder (C:\users\alan) and proceeds with the documented guidance.

However, he notices that he is still in a weird state, his IDE hasn't picked up on his newly created bicepconfig.json (see image below)

It turns out that Alan had a trailing comma in the bicepconfig.json and that was causing all the problems... so he removes the trailing comma

However, because the file is unsaved, the changes aren't picked up by the IDE...

Alan now tired from this experience, tries to cut and paste the contents of his scratch file to refresh the state of the extension:
Yay! finally Alan is able to follow the tutorial ->

Except... seems like the tutorial is missing an alias for the kubernetes provider and is causing a naming collision between the provider and the resource (both named kubernetes) so he renames the resource kubernetes -> k8s and now hes done.

[asilverman]

Meeting minutes from bicep discussion held 03/08/23

Notable comments

• @majastrz - As a design principle we want to maintain consistency in the behavior of the bicep cli and the bicep extensions.
• @StephenWeatherford - The current behavior will traverse the directory structure starting with the location of the saved file and inspecting each parent directory for a bicepconfig.json file. If it finds one it will use its settings, if it cannot find one or it doesn't have permissions to list the contents of the parent directory it will stop traversing and will use a default set of configurations.
• @asilverman - The default set is not documented in https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-config and we should create an issue to address this.
• Using a ~/.bicep/bicepconfig.json file as a default configuration may cause 'doesn't work on my machine' phenomena, this can be mitigated if users adhere to having a bicepconfig.json specified in their bicep project folder structure when sharing.
• The language server searches upwards in the filepath based on the URI of the file being processed. When the file is unsaved, its URI will look something like untitled:Untitled-1 with scheme untitled rather than file resulting in the use of the default configuration and making it not possible to enable an experimental feature (see logic here)
• We want the bicep lint rule to be more informative and specify not only that the feature is experimental but also link to some place where it explains how to enable the experimental feature. This is currently missing.
• We also want the extension output to allow for a verbose output that describes in more detail what actions the extension is taking, what are the directories its inspecting and using as execution current directory and any other relevant verbose output to assist in troubleshooting its behavior. This would also be useful for the CLI executable. Consider adding a VSCODE/VS setting to enable verbose output and a flag in the CLI to enable verbose.

Issues to resolve

• Document what are the default values being used when no bicepconfig.json is found.
• Consider unifying all Bicep configuration under ~/.bicep
• Improve language server error for experimental features to include a link to guidance about how to enable the experimental features
• Enable verbose output in VSCode/VS extensions and --verbose flag in Bicep CLI
• The extension settings (settings.json) are lacking documentation, this makes it hard for people to discover they exist and also what are they used for. Consider adding documentation in the extension homepage/overview in the marketplace to describe the functionality

[StephenWeatherford]

@asilverman

Some thoughts:

Document what are the default values being used when no bicepconfig.json is found.

I hesitate on this because it's misleading if the docs get out of date. I'm thinking it would be sufficient if we simply had a way to display the current effective values, which is useful on its own. I know we discussed this in an issue recently but can't find it. Feel free to open a new one.

Consider unifying all Bicep configuration under ~/.bicep

I personally feel this is more complexity than it's worth right now.

Improve language server error for experimental features to include a link to guidance about how to enable the experimental features

Makes sense. Would probably need to be added to each help message manually. Needs new issue.

Enable verbose output in VSCode/VS extensions and --verbose flag in Bicep CLI

I guess my suggestion above is subsumed by this.

The extension settings (settings.json) are lacking documentation, this makes it hard for people to discover they exist and also what are they used for. Consider adding documentation in the extension homepage/overview in the marketplace to describe the functionality

Don't have a strong opinion, but it's more docs to keep up to date. Do people really have trouble finding them?

Probably makes sense to open separate bugs for the open issues and consider closing this one.

[asilverman]

Created some issues as a result of this conversation and will handle those on a case by case basis