From 1182d087cb0e6c24a60fdf05a9ba540f7fffb3f7 Mon Sep 17 00:00:00 2001 From: stephaniezyen <77693576+stephaniezyen@users.noreply.github.com> Date: Tue, 20 Aug 2024 12:20:05 -0700 Subject: [PATCH 1/7] Create Extendable Params Files Doc --- docs/experimental/extendable-param-files.md | 56 +++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/experimental/extendable-param-files.md diff --git a/docs/experimental/extendable-param-files.md b/docs/experimental/extendable-param-files.md new file mode 100644 index 00000000000..5decf83249f --- /dev/null +++ b/docs/experimental/extendable-param-files.md @@ -0,0 +1,56 @@ +# Using the Extendable Bicep Parameters Feature (Experimental!) + +## 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. + +When using extendable bicep parameter files, you will have a `base.bicepparam` file that can be used by multiple `.bicep` and `.bicepparam` files. + +The `base.bicepparam` file will link to a `shared.bicepparam` file, which will refer to a `main.bicep` file and your `base.bicepparam file`. In this case, you will be able to reuse and refer to this `base.bicepparam` file multiple times. + +## Using + +`main.bicep` +This is your main bicep file, which will define your parameters for deployment. +```bicep +param foo string +param foo string +``` + +`base.bicepparam` This is your base bicepparam file, which can be reused by multiple shared.bicepparam files and in multiple deployments. +```bicep +using none + +param foo = 'foo' +param bar = 'bar' +``` + +`shared.bicepparam` This is your shared bicepparam file, which will refer to one main.bicep file and one base.bicepparam file. Any parameter definition in this file will override all previous definitions. +```bicep +using 'main.bicep' + +extends 'base.bicepparam' + +param foo = 'bar' +param baz = foo +``` + +Compiled json output +```bicep +{ + foo: 'bar' + bar: 'bar' + baz: 'bar' +} +``` + +**Note**: As `foo` is defined in both `base.bicepparam` and `shared.bicepparam` files, any parameter definitions in the **`shared.bicepparam`** file will override the definitions of the parameter in **both** the `main.bicep` and `base.bicepparam` files. + +## Limitations +We do not have support for: +* variables +* import/export function +* Multiple extends statements +* Ability to merge (union) parameters of type object and array + +## Raising bugs or feature requests +Please raise bug reports or feature requests under [Bicep Issues](https://github.com/Azure/bicep/issues) as usual. From 914e072e4da380bef22ec6ce3a587a2c66a9069f Mon Sep 17 00:00:00 2001 From: stephaniezyen <77693576+stephaniezyen@users.noreply.github.com> Date: Tue, 20 Aug 2024 12:21:23 -0700 Subject: [PATCH 2/7] Update experimental-features.md --- docs/experimental-features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/experimental-features.md b/docs/experimental-features.md index 712fc13cde2..800de71527e 100644 --- a/docs/experimental-features.md +++ b/docs/experimental-features.md @@ -16,7 +16,7 @@ Requires `extensibility` to be enabled. If enabled, users are able to fetch the The provider definitions also support aliasing via `bicepconfig.json` similar to [`moduleAliases`](https://learn.microsoft.com/azure/azure-resource-manager/bicep/bicep-config-modules#aliases-for-modules). For example `provider 'br/public:az@1.0.0' as az`. ### `extendableParamFiles` -Enables the ability to extend bicepparam files from other bicepparam files. +Enables the ability to extend bicepparam files from other bicepparam files. For more information, see [Extendable Bicep Params Files](./experimental/extendable-param-files.md). ### `extensibility` Allows Bicep to use a provider model to deploy non-ARM resources. Currently, we support Kubernetes provider ([Bicep extensibility Kubernetes provider](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-extensibility-kubernetes-provider)) and Microsoft Graph provider ([Bicep templates for Microsoft Graph](https://aka.ms/graphbicep)). From 6a5bae10b7d784e7b157ca97f60b5a5d6b0af4fd Mon Sep 17 00:00:00 2001 From: polatengin Date: Tue, 20 Aug 2024 12:47:54 -0700 Subject: [PATCH 3/7] fixing markdown linter warnings --- docs/experimental/extendable-param-files.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/experimental/extendable-param-files.md b/docs/experimental/extendable-param-files.md index 5decf83249f..cbbba935f96 100644 --- a/docs/experimental/extendable-param-files.md +++ b/docs/experimental/extendable-param-files.md @@ -1,22 +1,24 @@ # Using the Extendable Bicep Parameters Feature (Experimental!) ## 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. -When using extendable bicep parameter files, you will have a `base.bicepparam` file that can be used by multiple `.bicep` and `.bicepparam` files. +When using extendable bicep parameter files, you will have a `base.bicepparam` file that can be used by multiple `.bicep` and `.bicepparam` files. The `base.bicepparam` file will link to a `shared.bicepparam` file, which will refer to a `main.bicep` file and your `base.bicepparam file`. In this case, you will be able to reuse and refer to this `base.bicepparam` file multiple times. ## Using -`main.bicep` -This is your main bicep file, which will define your parameters for deployment. +`main.bicep` This is your main bicep file, which will define your parameters for deployment. + ```bicep param foo string param foo string ``` `base.bicepparam` This is your base bicepparam file, which can be reused by multiple shared.bicepparam files and in multiple deployments. + ```bicep using none @@ -25,6 +27,7 @@ param bar = 'bar' ``` `shared.bicepparam` This is your shared bicepparam file, which will refer to one main.bicep file and one base.bicepparam file. Any parameter definition in this file will override all previous definitions. + ```bicep using 'main.bicep' @@ -35,6 +38,7 @@ param baz = foo ``` Compiled json output + ```bicep { foo: 'bar' @@ -46,11 +50,14 @@ Compiled json output **Note**: As `foo` is defined in both `base.bicepparam` and `shared.bicepparam` files, any parameter definitions in the **`shared.bicepparam`** file will override the definitions of the parameter in **both** the `main.bicep` and `base.bicepparam` files. ## Limitations + We do not have support for: + * variables * import/export function * Multiple extends statements * Ability to merge (union) parameters of type object and array ## Raising bugs or feature requests + Please raise bug reports or feature requests under [Bicep Issues](https://github.com/Azure/bicep/issues) as usual. From 09d57e80bc46d461ddc3a8a9b1fb7d998076b7fe Mon Sep 17 00:00:00 2001 From: stephaniezyen <77693576+stephaniezyen@users.noreply.github.com> Date: Tue, 20 Aug 2024 16:58:20 -0700 Subject: [PATCH 4/7] Update extendable-param-files.md --- docs/experimental/extendable-param-files.md | 71 ++++++++++++++------- 1 file changed, 49 insertions(+), 22 deletions(-) diff --git a/docs/experimental/extendable-param-files.md b/docs/experimental/extendable-param-files.md index cbbba935f96..46c5446539d 100644 --- a/docs/experimental/extendable-param-files.md +++ b/docs/experimental/extendable-param-files.md @@ -4,17 +4,16 @@ 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. -When using extendable bicep parameter files, you will have a `base.bicepparam` file that can be used by multiple `.bicep` and `.bicepparam` files. - -The `base.bicepparam` file will link to a `shared.bicepparam` file, which will refer to a `main.bicep` file and your `base.bicepparam file`. In this case, you will be able to reuse and refer to this `base.bicepparam` file multiple times. +When using extendable bicep parameter files, you will have a base `.bicepparam` file that can be consumed by multiple shared `.bicepparam` files. ## Using `main.bicep` This is your main bicep file, which will define your parameters for deployment. ```bicep -param foo string -param foo string +param namePrefix string +param location string +param symbolicName ``` `base.bicepparam` This is your base bicepparam file, which can be reused by multiple shared.bicepparam files and in multiple deployments. @@ -22,41 +21,69 @@ param foo string ```bicep using none -param foo = 'foo' -param bar = 'bar' +param namePrefix = 'share' +param location = 'westus' ``` -`shared.bicepparam` This is your shared bicepparam file, which will refer to one main.bicep file and one base.bicepparam file. Any parameter definition in this file will override all previous definitions. +`shared.bicepparam` This is your shared bicepparam file, which will refer to one main.bicep file and one base.bicepparam file. Any parameter value in this file will override all previous values. ```bicep using 'main.bicep' extends 'base.bicepparam' -param foo = 'bar' -param baz = foo +param namePrefix = 'extend' +param symbolicName = 'test' ``` -Compiled json output +Resolved Values +| Param | Value | +| -- | -- | +| namePrefix | `'extend'` | +| location | `'westus'` | +| symbolicName | `'test'` | -```bicep -{ - foo: 'bar' - bar: 'bar' - baz: 'bar' -} -``` - -**Note**: As `foo` is defined in both `base.bicepparam` and `shared.bicepparam` files, any parameter definitions in the **`shared.bicepparam`** file will override the definitions of the parameter in **both** the `main.bicep` and `base.bicepparam` files. +**Note**: As `foo` is defined in both `base.bicepparam` and `shared.bicepparam` files, any parameter values in the **`shared.bicepparam`** file will override the values of the parameter in **both** the `main.bicep` and `base.bicepparam` files. ## Limitations We do not have support for: -* variables -* import/export function +* variables: we will not have variable support in the `base.bicepparam` file to be able to read and override values in other files + ```bicep + var namePrefix = 'share' + ``` +* import function: you will not be able to import a parameter from another file +* ```bicep + import {bar} from 'main.bicep' + ``` * Multiple extends statements + ```bicep + using 'main.bicep' + + extends 'base.bicepparam' + extends 'base2.biepparam' + extends 'base3.bicepparam' + ``` * Ability to merge (union) parameters of type object and array + ```bicep + param loc1 string = [ + 'westus' + 'westus2' + ] + + param loc2 string = [ + 'eastus' + 'eastus2' + ] + + union(loc1, loc2) + ``` +* user-defined functions and user-defined types + ```bicep + type namePrefix = 'extend' + func outputName(name string) => 'Hi ${name}!' + ``` ## Raising bugs or feature requests From 4e2102d84edc79275a24aed1e1bc902ee3272291 Mon Sep 17 00:00:00 2001 From: stephaniezyen <77693576+stephaniezyen@users.noreply.github.com> Date: Tue, 20 Aug 2024 17:01:45 -0700 Subject: [PATCH 5/7] Update extendable-param-files.md --- docs/experimental/extendable-param-files.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/experimental/extendable-param-files.md b/docs/experimental/extendable-param-files.md index 46c5446539d..9cc1d6f0c56 100644 --- a/docs/experimental/extendable-param-files.md +++ b/docs/experimental/extendable-param-files.md @@ -13,7 +13,7 @@ When using extendable bicep parameter files, you will have a base `.bicepparam` ```bicep param namePrefix string param location string -param symbolicName +param symbolicName string ``` `base.bicepparam` This is your base bicepparam file, which can be reused by multiple shared.bicepparam files and in multiple deployments. From 1e24262bf0347c72b4a6569c3de9b8d5b163439b Mon Sep 17 00:00:00 2001 From: stephaniezyen <77693576+stephaniezyen@users.noreply.github.com> Date: Tue, 20 Aug 2024 17:04:13 -0700 Subject: [PATCH 6/7] Update extendable-param-files.md --- docs/experimental/extendable-param-files.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/experimental/extendable-param-files.md b/docs/experimental/extendable-param-files.md index 9cc1d6f0c56..434bbd2328e 100644 --- a/docs/experimental/extendable-param-files.md +++ b/docs/experimental/extendable-param-files.md @@ -4,7 +4,7 @@ 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. -When using extendable bicep parameter files, you will have a base `.bicepparam` file that can be consumed by multiple shared `.bicepparam` files. +When using extendable bicep parameter files, you will have a main `.bicepparam` file that can be consumed by multiple extended `.bicepparam` files. ## Using @@ -16,7 +16,7 @@ param location string param symbolicName string ``` -`base.bicepparam` This is your base bicepparam file, which can be reused by multiple shared.bicepparam files and in multiple deployments. +`root.bicepparam` This is your main bicepparam file, which can be reused by multiple extended .bicepparam files and in multiple deployments. ```bicep using none @@ -25,12 +25,12 @@ param namePrefix = 'share' param location = 'westus' ``` -`shared.bicepparam` This is your shared bicepparam file, which will refer to one main.bicep file and one base.bicepparam file. Any parameter value in this file will override all previous values. +`leaf.bicepparam` This is your extended bicepparam file, which will refer to one main.bicep file and one main .bicepparam file. Any parameter value in this file will override all previous values. ```bicep using 'main.bicep' -extends 'base.bicepparam' +extends 'root.bicepparam' param namePrefix = 'extend' param symbolicName = 'test' @@ -43,13 +43,13 @@ Resolved Values | location | `'westus'` | | symbolicName | `'test'` | -**Note**: As `foo` is defined in both `base.bicepparam` and `shared.bicepparam` files, any parameter values in the **`shared.bicepparam`** file will override the values of the parameter in **both** the `main.bicep` and `base.bicepparam` files. +**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. ## Limitations We do not have support for: -* variables: we will not have variable support in the `base.bicepparam` file to be able to read and override values in other files +* variables: we will not have variable support in the `root.bicepparam` file to be able to read and override values in other files ```bicep var namePrefix = 'share' ``` @@ -61,9 +61,9 @@ We do not have support for: ```bicep using 'main.bicep' - extends 'base.bicepparam' - extends 'base2.biepparam' - extends 'base3.bicepparam' + extends 'root1.bicepparam' + extends 'root2.biepparam' + extends 'root3.bicepparam' ``` * Ability to merge (union) parameters of type object and array ```bicep From 3d1449547e4ad36b2c4dee84d61f2cdbdb13f7af Mon Sep 17 00:00:00 2001 From: stephaniezyen <77693576+stephaniezyen@users.noreply.github.com> Date: Wed, 21 Aug 2024 15:41:31 -0700 Subject: [PATCH 7/7] Update extendable-param-files.md --- docs/experimental/extendable-param-files.md | 26 ++++++++++++--------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/experimental/extendable-param-files.md b/docs/experimental/extendable-param-files.md index 434bbd2328e..5ff73b5bc01 100644 --- a/docs/experimental/extendable-param-files.md +++ b/docs/experimental/extendable-param-files.md @@ -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. ```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. -param namePrefix = 'share' +param namePrefix = 'Prod' param location = 'westus' ``` @@ -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`. ## Limitations @@ -54,7 +58,7 @@ We do not have support for: var namePrefix = 'share' ``` * import function: you will not be able to import a parameter from another file -* ```bicep + ```bicep import {bar} from 'main.bicep' ``` * Multiple extends statements