Skip to content

Commit

Permalink
[Modules] Removed auto-generated parameter usage sections (#4083)
Browse files Browse the repository at this point in the history 
* Removed readme sources

* Removed role assignments

* Removed tags

* Removed PE

* Removed manage identity

* excess newlines

* Removed remaining occurences

* Cleanup notes

* Finalizing touches
  • Loading branch information
@AlexanderSehr
AlexanderSehr authored Oct 14, 2023
1 parent 56c94e0 commit 08b86f0
Show file tree
Hide file tree
Showing 205 changed files with 7 additions and 21,158 deletions.
59 changes: 0 additions & 59 deletions constructs/Authorization/roleAssignmentsMultiRolesMultiPrincipals/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,65 +31,6 @@ This module deploys Role Assignments.
| `subscriptionId` | string | `''` | Subscription ID of the subscription to assign the RBAC role to. If no Resource Group name is provided, the module deploys at subscription level, therefore assigns the provided RBAC role to the subscription. |


### Parameter Usage: `roleAssignments`

Create a role assignment for the given resource. If you want to assign a service principal / managed identity that is created in the same deployment, make sure to also specify the `'principalType'` parameter and set it to `'ServicePrincipal'`. This will ensure the role assignment waits for the principal's propagation in Azure.

<details>

<summary>Parameter JSON format</summary>

```json
"roleAssignments": {
"value": [
{
"roleDefinitionIdOrName": "Reader",
"description": "Reader Role Assignment",
"principalIds": [
"12345678-1234-1234-1234-123456789012", // object 1
"78945612-1234-1234-1234-123456789012" // object 2
]
},
{
"roleDefinitionIdOrName": "/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11",
"principalIds": [
"12345678-1234-1234-1234-123456789012" // object 1
],
"principalType": "ServicePrincipal"
}
]
}
```

</details>

<details>

<summary>Bicep format</summary>

```bicep
roleAssignments: [
{
roleDefinitionIdOrName: 'Reader'
description: 'Reader Role Assignment'
principalIds: [
'12345678-1234-1234-1234-123456789012' // object 1
'78945612-1234-1234-1234-123456789012' // object 2
]
}
{
roleDefinitionIdOrName: '/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11'
principalIds: [
'12345678-1234-1234-1234-123456789012' // object 1
]
principalType: 'ServicePrincipal'
}
]
```

</details>
<p>

### Parameter Usage: `managementGroupId`

To deploy resource to a Management Group, provide the `managementGroupId` as an input parameter to the module.
Expand Down
131 changes: 0 additions & 131 deletions constructs/Compute/virtualMachinesMultiple/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -133,138 +133,7 @@ Name(s) of the virtual machine(s). If no explicit names are provided, VM name(s)
}
```

### Parameter Usage: `roleAssignments`

Create a role assignment for the given resource. If you want to assign a service principal / managed identity that is created in the same deployment, make sure to also specify the `'principalType'` parameter and set it to `'ServicePrincipal'`. This will ensure the role assignment waits for the principal's propagation in Azure.

<details>

<summary>Parameter JSON format</summary>

```json
"roleAssignments": {
"value": [
{
"roleDefinitionIdOrName": "Reader",
"description": "Reader Role Assignment",
"principalIds": [
"12345678-1234-1234-1234-123456789012", // object 1
"78945612-1234-1234-1234-123456789012" // object 2
]
},
{
"roleDefinitionIdOrName": "/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11",
"principalIds": [
"12345678-1234-1234-1234-123456789012" // object 1
],
"principalType": "ServicePrincipal"
}
]
}
```

</details>

<details>

<summary>Bicep format</summary>

```bicep
roleAssignments: [
{
roleDefinitionIdOrName: 'Reader'
description: 'Reader Role Assignment'
principalIds: [
'12345678-1234-1234-1234-123456789012' // object 1
'78945612-1234-1234-1234-123456789012' // object 2
]
}
{
roleDefinitionIdOrName: '/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11'
principalIds: [
'12345678-1234-1234-1234-123456789012' // object 1
]
principalType: 'ServicePrincipal'
}
]
```

</details>
<p>

### Parameter Usage: `tags`

Tag names and tag values can be provided as needed. A tag can be left without a value.

<details>

<summary>Parameter JSON format</summary>

```json
"tags": {
"value": {
"Environment": "Non-Prod",
"Contact": "test.user@testcompany.com",
"PurchaseOrder": "1234",
"CostCenter": "7890",
"ServiceName": "DeploymentValidation",
"Role": "DeploymentValidation"
}
}
```

</details>

<details>

<summary>Bicep format</summary>

```bicep
tags: {
Environment: 'Non-Prod'
Contact: 'test.user@testcompany.com'
PurchaseOrder: '1234'
CostCenter: '7890'
ServiceName: 'DeploymentValidation'
Role: 'DeploymentValidation'
}
```

</details>
<p>

### Parameter Usage: `userAssignedIdentities`

You can specify multiple user assigned identities to a resource by providing additional resource IDs using the following format:

<details>

<summary>Parameter JSON format</summary>

```json
"userAssignedIdentities": {
"value": {
"/subscriptions/[[subscriptionId]]/resourcegroups/validation-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/adp-sxx-az-msi-x-001": {},
"/subscriptions/[[subscriptionId]]/resourcegroups/validation-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/adp-sxx-az-msi-x-002": {}
}
}
```

</details>

<details>

<summary>Bicep format</summary>

```bicep
userAssignedIdentities: {
'/subscriptions/[[subscriptionId]]/resourcegroups/validation-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/adp-sxx-az-msi-x-001': {}
'/subscriptions/[[subscriptionId]]/resourcegroups/validation-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/adp-sxx-az-msi-x-002': {}
}
```

</details>
<p>

## Outputs

Expand Down
36 changes: 0 additions & 36 deletions constructs/Management/managementGroupStructure/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,42 +68,6 @@ Describes the Management groups to be created. Each management group is represen
| `parentNotManagedInThisTemplate` | bool | `false` | | Optional. `true` if the parent management group is existing and defined elsewhere, `false` if the parent MG is also managed in this template. This parameter is used to define the deployment sequence |
| `roleAssignments` | array | | | Optional. Array of role assignment objects |

### Parameter Usage: `roleAssignments`

<details>

<summary>Parameter JSON format</summary>

```json
"roleAssignments": [
{
"roleDefinitionIdOrName": "Desktop Virtualization User",
"principalIds": [
"12345678-1234-1234-1234-123456789012", // object 1
"78945612-1234-1234-1234-123456789012" // object 2
]
},
{
"roleDefinitionIdOrName": "Reader",
"principalIds": [
"12345678-1234-1234-1234-123456789012", // object 1
"78945612-1234-1234-1234-123456789012" // object 2
]
},
{
"roleDefinitionIdOrName": "/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11",
"principalIds": [
"12345678-1234-1234-1234-123456789012" // object 1
]
}
]
```

| Parameter Name | Type | Default Value | Possible values | Description |
| :- | :- | :- | :- | :- |
| `roleDefinitionIdOrName` | string | | | Mandatory. The name or the ID of the role to assign to the management group |
| `principalIds` | array | | | Mandatory. An array of principal IDs |

## Outputs

| Output Name | Type | Description |
Expand Down
21 changes: 0 additions & 21 deletions docs/wiki/Contribution guide - Generate module readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ The ReadMe generator utility aims to simplify contributing to the CARML library,

- [Location](#location)
- [How it works](#how-it-works)
- [Special case: 'Parameter Usage' section](#special-case-parameter-usage-section)
- [How to use it](#how-to-use-it)

---
Expand All @@ -23,26 +22,6 @@ You can find the script under [`/utilities/tools/Set-ModuleReadMe.ps1`](https://
1. The script then goes through all sections defined as `SectionsToRefresh` (by default all) and refreshes the sections' content (for example, for the `Parameters`) based on the values in the ARM/JSON Template. It detects sections by their header and always regenerates the full section.
1. Once all are refreshed, the current ReadMe file is overwritten. **Note:** The script can be invoked combining the `WhatIf` and `Verbose` switches to just receive an console-output of the updated content.

## Special case: 'Parameter Usage' section

The `Parameter Usage` examples are located just beneath the `Parameters` table. They are intended to show how to use complex objects/arrays that can be leveraged as parameters, excluding the child resources' parameters, since they have their own readMe files.

**For the most part, this section is to be populated manually**. However, for a specific set of common parameters, we automatically add their example to the readMe if the parameter exists in the template. At the time of this writing these are:
- Private Endpoints
- Role Assignments
- Tags
- User Assigned Identities

To change this list with minimum effort, the script reads the content from markdown files in the folder of `utilities/tools/moduleReadMeSource`, and matches their title to the parameters of the template file. If a match is found, it's content is added to the readme alongside the generated header. This means, if you want to add another case, you just need to add a new file to the `moduleReadMeSource` folder and follow the naming pattern `resourceUsage-<parameterName>.md`.

For example, the content of the `resourceUsage-roleAssignments.md` file in the `moduleReadMeSource` folder is added to a template's readMe if it contains a `roleAssignments` parameter. The combined result is:

```markdown
### Parameter Usage: `roleAssignments`

<[resourceUsage-roleAssignments.md] file content>
```

# How to use it

For details on how to use the function, please refer to the script's local documentation.
Expand Down
1 change: 0 additions & 1 deletion docs/wiki/The library - Module design.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -583,7 +583,6 @@ Its primary components are in order:
- A short description
- A **Resource types** section with a table that outlines all resources that can be deployed as part of the module.
- A **Parameters** section with a table containing all parameters, their type, default and allowed values if any, and their description.
- Optionally, a **Parameter Usage** section that shows how to use complex structures such as parameter objects or array of objects, e.g., roleAssignments, tags, privateEndpoints.
- An **Outputs** section with a table that describes all outputs the module template returns.
- A **Template references** section listing relevant resources [Azure resource reference](https://learn.microsoft.com/en-us/azure/templates).

Expand Down
100 changes: 0 additions & 100 deletions modules/aad/domain-service/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,106 +67,6 @@ This module deploys an Azure Active Directory Domain Services (AADDS).
| `tlsV1` | string | `'Enabled'` | `[Disabled, Enabled]` | The value is to enable clients making request using TLSv1. |


### Parameter Usage: `roleAssignments`

Create a role assignment for the given resource. If you want to assign a service principal / managed identity that is created in the same deployment, make sure to also specify the `'principalType'` parameter and set it to `'ServicePrincipal'`. This will ensure the role assignment waits for the principal's propagation in Azure.

<details>

<summary>Parameter JSON format</summary>

```json
"roleAssignments": {
"value": [
{
"roleDefinitionIdOrName": "Reader",
"description": "Reader Role Assignment",
"principalIds": [
"12345678-1234-1234-1234-123456789012", // object 1
"78945612-1234-1234-1234-123456789012" // object 2
]
},
{
"roleDefinitionIdOrName": "/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11",
"principalIds": [
"12345678-1234-1234-1234-123456789012" // object 1
],
"principalType": "ServicePrincipal"
}
]
}
```

</details>

<details>

<summary>Bicep format</summary>

```bicep
roleAssignments: [
{
roleDefinitionIdOrName: 'Reader'
description: 'Reader Role Assignment'
principalIds: [
'12345678-1234-1234-1234-123456789012' // object 1
'78945612-1234-1234-1234-123456789012' // object 2
]
}
{
roleDefinitionIdOrName: '/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11'
principalIds: [
'12345678-1234-1234-1234-123456789012' // object 1
]
principalType: 'ServicePrincipal'
}
]
```

</details>
<p>

### Parameter Usage: `tags`

Tag names and tag values can be provided as needed. A tag can be left without a value.

<details>

<summary>Parameter JSON format</summary>

```json
"tags": {
"value": {
"Environment": "Non-Prod",
"Contact": "test.user@testcompany.com",
"PurchaseOrder": "1234",
"CostCenter": "7890",
"ServiceName": "DeploymentValidation",
"Role": "DeploymentValidation"
}
}
```

</details>

<details>

<summary>Bicep format</summary>

```bicep
tags: {
Environment: 'Non-Prod'
Contact: 'test.user@testcompany.com'
PurchaseOrder: '1234'
CostCenter: '7890'
ServiceName: 'DeploymentValidation'
Role: 'DeploymentValidation'
}
```

</details>
<p>

## Outputs

| Output Name | Type | Description |
Expand Down
Loading

0 comments on commit 08b86f0

Please sign in to comment.