search

Azure / bicep

Bicep is a declarative language for describing and deploying Azure resources
MIT License
3.2k stars 742 forks source link

Best practices for Bicep #446

Closed slavizh closed 3 years ago

slavizh commented 4 years ago

Is your feature request related to a problem? Please describe. As I see discussions like #410 may be it is good to setup some best practices for writing bicep code in advance and not be the wild west like in ARM Templates. For example camelCase usage for parameters and variables, etc. Of course anyone will be free to adopt or not these. And of course they should not be too restrictive so if you want to adopt them you do not have to make big effort.

alex-frankel commented 4 years ago

wondering if we can combine this with #443

majastrz commented 4 years ago

Some of the formatting best practices can be captured in a formatter as well (#220).

alex-frankel commented 3 years ago

Related to #441

shenglol commented 3 years ago

I think this is also related to https://github.com/Azure/bicep/issues/428. Things like always using camelCase for identifier names and removing unused parameters and variables can be linter rules and can be auto fixed.

JustinGrote commented 3 years ago

To throw in my thought, it should be PascalCase for parameters and camelCase for variables, both to easily distinguish between the two, and because using tools like new-azvmdeployment make dynamic parameters based on the parameters, so they will look more "powershell-like" if they are PascalCase.

alex-frankel commented 3 years ago

We have this doc, which may or may not go far enough: https://github.com/Azure/bicep/blob/main/docs/arm2bicep.md

@slavizh / @JustinGrote - can you take a look and let me know what is missing?

JustinGrote commented 3 years ago

@alex-frankel this request is less around "how to convert from arm to bicep" and more about best practices for templates that are typically open to interpretation. Examples:

  1. Standard naming conventions for parameters, module parameters, variables, and functions so there is a "visual contract" so people who work or consume multiple bicep templates don't come across the same parameter named MYPARAMETER, my_parameter, MyParameter, my-parameter, etc. in different modules.
  2. When newline syntax gets relaxed, general guidelines about how to structure or indent functions and expressions across multiple lines
  3. Naming of modules and how to structure modules in directories or files within a repository.

For example, the current document just recommends "use consistent casing", it should probably be expounded into a default recommendation, but of course people can do whatever they want, it would just be a recommendation that would probably become a de-facto standard.

There is probably a minimal amount of this stuff to cover since Bicep mostly takes the 'one and only one right way to do it' approach similar to Python and unlike Powershell :)

stan-sz commented 3 years ago

Can the scope of this work also include best practices for particular resource types, like storageAccounts with https and tls1.2 enabled-by-default (the former is on-by-default with 2019-04-01, the latter is still at 1.0)?

slavizh commented 3 years ago

The intent of the work item is best practices for writing Bicep code so the code when written by different people have some common similarity. The above is proposal for best practices for deploying Azure services so it is not related to Bicep. The above is probably for documents like CAF.

alex-frankel commented 3 years ago

We now have this best practices doc - can folks take a look? Any enhancements/changes can be provided through the feedback channels provide in ms docs. Going to close this thread in the meantime, but feel free to continue the discussion here: