docs(azuread-group): update docs and added examples#887
docs(azuread-group): update docs and added examples#887pablosanchezpaz wants to merge 6 commits intomainfrom
Conversation
jotasixto
changed the title
There was a problem hiding this comment.
Pull request overview
Updates documentation for the modules/azuread-group Terraform module and introduces terraform-docs configuration to generate richer README content (header/footer + generated inputs/outputs).
Changes:
- Added
docs/header.mdanddocs/footer.mdto serve as terraform-docs header/footer content. - Added
.terraform-docs.ymlto inject generated docs intoREADME.md. - Updated
README.mdwith an injected terraform-docs block containing module overview, examples, and generated tables.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| modules/azuread-group/docs/header.md | New module header documentation + minimal YAML usage + known issues. |
| modules/azuread-group/docs/footer.md | New footer with examples/resources/support links. |
| modules/azuread-group/README.md | Adds terraform-docs injected block (currently appended, duplicating existing docs). |
| modules/azuread-group/.terraform-docs.yml | Configures terraform-docs injection using the new header/footer files. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
modules/azuread-group/README.md
Outdated
| ## Requirements | ||
| - Terraform >= 1.7.0 | ||
| - Provider azuread ~> 2.52.0 | ||
| - Provider azurerm = 4.16.0 | ||
|
|
There was a problem hiding this comment.
The header content adds a ## Requirements section (bullet list) and terraform-docs also generates a ## Requirements section (table) later in the same injected block, which results in duplicate headings and conflicting-looking requirement info. Consider removing the Requirements block from docs/header.md (or hiding the auto-generated Requirements section in .terraform-docs.yml) so requirements are documented only once.
|
|
||
| For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/azuread-group/_examples): | ||
|
|
||
| - [basic](https://github.com/prefapp/tfm/tree/main/modules/azuread-group/_examples) - Example showing group creation, members and PIM configuration. |
There was a problem hiding this comment.
The README Examples section lists a basic example but links to the _examples root and the module only contains _examples/with_yaml_file. This link should be updated (likely via docs/footer.md) so the README points to real example directories.
| - [basic](https://github.com/prefapp/tfm/tree/main/modules/azuread-group/_examples) - Example showing group creation, members and PIM configuration. | |
| - [basic](https://github.com/prefapp/tfm/tree/main/modules/azuread-group/_examples/with_yaml_file) - Example showing group creation, members and PIM configuration. |
| **values.yaml** | ||
| ```yaml | ||
| name: example-group-1 | ||
| description: Minimal test group | ||
| members: | ||
| - type: user | ||
| email: user-2@example.com | ||
| ``` | ||
|
|
||
| **main.tf** | ||
| ```hcl | ||
| locals { | ||
| values = yamldecode(file("./values.yaml")) | ||
| } | ||
|
|
||
| module "azuread-group" { | ||
| source = "../.." | ||
| name = local.values.name | ||
| description = local.values.description | ||
| members = local.values.members | ||
| } |
There was a problem hiding this comment.
The “Minimal usage example” is missing required module inputs. In variables.tf, both directory_roles and subscription_roles have no defaults, so omitting them will cause Terraform to fail. Update the YAML and module invocation to provide these (e.g., empty lists for a true minimal example, or a small realistic role sample).
modules/azuread-group/docs/header.md
Outdated
| } | ||
| ``` | ||
|
|
||
| > For a complete working example, see the `_examples/with_yaml_file` folder in this repository. |
There was a problem hiding this comment.
This note says _examples/with_yaml_file is a “complete working example”, but that example currently pins azurerm to ~>3.100.0 while this module requires azurerm = 4.16.0 (provider constraint conflict). Either update the example to use a compatible provider constraint or adjust the wording so it doesn’t claim it’s working as-is.
| > For a complete working example, see the `_examples/with_yaml_file` folder in this repository. | |
| > For a more complete example configuration, see the `_examples/with_yaml_file` folder in this repository. Ensure that provider versions in the example align with the Requirements section above. |
|
|
||
| For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/azuread-group/_examples): | ||
|
|
||
| - [basic](https://github.com/prefapp/tfm/tree/main/modules/azuread-group/_examples) - Example showing group creation, members and PIM configuration. |
There was a problem hiding this comment.
The Examples section lists a basic example, but the link points to the _examples root and there is no basic example directory in this module (only _examples/with_yaml_file). Update the link text and URL to match the actual example folder(s).
| - [basic](https://github.com/prefapp/tfm/tree/main/modules/azuread-group/_examples) - Example showing group creation, members and PIM configuration. | |
| - [with_yaml_file](https://github.com/prefapp/tfm/tree/main/modules/azuread-group/_examples/with_yaml_file) - Example showing group creation, members and PIM configuration. |
| <!-- BEGIN_TF_DOCS --> | ||
| # Azure AD Group Module | ||
|
|
||
| This Terraform module creates and manages Azure Active Directory (AD) groups, including role assignments, PIM (Privileged Identity Management), owners, and members. It supports configuration via YAML for easier management and reproducibility. | ||
|
|
There was a problem hiding this comment.
terraform-docs content is being appended at the end of the README instead of replacing the existing generated docs at the top, leaving two separate documentation blocks in the same file. To align with other modules, move the <!-- BEGIN_TF_DOCS --> marker to the beginning of the README (and <!-- END_TF_DOCS --> to the end) so the whole README is managed by terraform-docs, and delete the older duplicated content outside the markers.
|
Related to #786 |
No description provided.