Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create Extendable Bicep Params File Article #14865

Merged
merged 7 commits into from
Aug 26, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 15 additions & 11 deletions docs/experimental/extendable-param-files.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,28 @@
# Using the Extendable Bicep Parameters Feature (Experimental!)
# Using the Extendable Bicep Parameters Feature

## What is it?

Extendable Bicep Parameter Files is a feature that allows you to extend `.bicepparam` files from another `.bicepparam` file in order to reuse parameters across multiple deployments.
Extendable Bicep Parameter Files (enabled with the `extend` keyword) is a feature that allows you to reuse parameters from one `.bicepparam` file in another `.bicepparam` file. This enables better re-use across multiple deployments and helps to keep your code [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself).

When using extendable bicep parameter files, you will have a main `.bicepparam` file that can be consumed by multiple extended `.bicepparam` files.

## Using
## Example Usage

`main.bicep` This is your main bicep file, which will define your parameters for deployment.

```bicep
param namePrefix string
param location string
param symbolicName string
param tag string
```

`root.bicepparam` This is your main bicepparam file, which can be reused by multiple extended .bicepparam files and in multiple deployments.

stephaniezyen marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe I am the only one, but to me root.bicepparam file is the one being extended, not leaf.bicepparam. So when we say "can be reused by multiple extended .bicepparam files", I get confused.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So the way I see it is that the root connects to multiple leaves - so the root can be reused multiple times into several different leaf files, which I think is also how Engin views it - should we ask the team?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if I'm the only one with this perspective, it's fine to leave it as is

```bicep
using none
// Notice that the first line of this .bicepparam file declares `using none` which tells the compiler not to validate this against any particular .bicep file.

stephaniezyen marked this conversation as resolved.
Show resolved Hide resolved
param namePrefix = 'share'
param namePrefix = 'Prod'
param location = 'westus'
```

Expand All @@ -32,18 +33,21 @@ using 'main.bicep'

extends 'root.bicepparam'

param namePrefix = 'extend'
param symbolicName = 'test'
param namePrefix = 'Dev'
param tag = 'test'
```

Resolved Values
| Param | Value |
| -- | -- |
| namePrefix | `'extend'` |
| namePrefix | `'Dev'` |
| location | `'westus'` |
| symbolicName | `'test'` |
| tag | `'test'` |

**Note**: As `foo` is defined in both `root.bicepparam` and `leaf.bicepparam` files, any parameter values in the **`leaf.bicepparam`** file will override the values of the parameter in **both** the `main.bicep` and `root.bicepparam` files.
**Note**: Any parameter values in the **`leaf.bicepparam`** file will override the values of the parameter in **both** the `main.bicep` and `root.bicepparam` files. So in this case, `namePrefix`is defined in both the `root.bicepparam` and `leaf.bicepparam` files, and is given the value `Dev` as defined in the `leaf.bicepparam` file, overriding the original value of `Prod`.

### Nested Parameter Files
We also support nested parameter files, so that `a.bicepparam` extends `b.bicepparam` extends `c.bicepparam`. In this case, you will use `using none` for file `a.bicepparam` and `b.bicepparam`.
stephaniezyen marked this conversation as resolved.
Show resolved Hide resolved

## Limitations
alex-frankel marked this conversation as resolved.
Show resolved Hide resolved

Expand All @@ -54,7 +58,7 @@ We do not have support for:
var namePrefix = 'share'
```
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a little odd to have such specific code samples for features that don't work. I think it's ok just to describe the limitation in words.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So Anthony had requested I add an explanation and example for each of these bullet points - I'll follow up with him to see if this is what he is looking for or if just a quick description is good enough.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Anthony said the examples should be helpful for users - would you be okay if I kept them in?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yep - fine with me

* import function: you will not be able to import a parameter from another file
* ```bicep
```bicep
import {bar} from 'main.bicep'
```
* Multiple extends statements
Expand Down
Loading