diff --git a/AGENTS.md b/AGENTS.md index 33458105..a63b11a5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -192,6 +192,12 @@ description: One-sentence description of what the module provisions. - Usage motivation and examples (1–2 developer scenarios). - Shared responsibility matrix (platform team vs. application team) as a markdown table with ✅ / ❌ emojis. +**`backplane/README.md`** — documentation relevant to platform engineers deploying the backplane. Include an overview of what the backplane provisions, required permissions/roles, and operational notes. + +**Anti-pattern: `documentation_md` output** — do **not** add a `documentation_md` output to backplane modules. This is a legacy pattern. Documentation must instead be split into: +- User-facing content → BBD `readme` field in `meshstack_integration.tf` +- Platform-engineer-facing content → `backplane/README.md` + --- ## Hub as a Shim for IaC Runtimes @@ -369,5 +375,6 @@ Pass `module..building_block_definition.version_ref` **directly** — do n - [ ] `terraform { required_providers { ... } }` block is at the **bottom** of `meshstack_integration.tf` - [ ] `meshstack` and `hub` variables are at the end of the variable section - [ ] `logo.png` included in `buildingblock/` +- [ ] No `documentation_md` output in `backplane/` — use BBD `readme` field and `backplane/README.md` instead - [ ] No trailing whitespace - [ ] **Azure modules**: also follow the [Azure Backplane Checklist](.github/instructions/azure-backplane.instructions.md#checklist-for-azure-backplanes) diff --git a/modules/azure/aks/backplane/README.md b/modules/azure/aks/backplane/README.md index af660364..b381d623 100644 --- a/modules/azure/aks/backplane/README.md +++ b/modules/azure/aks/backplane/README.md @@ -68,7 +68,6 @@ No modules. | [created\_hub\_application](#output\_created\_hub\_application) | Information about the created hub Azure AD application. | | [created\_hub\_service\_principal](#output\_created\_hub\_service\_principal) | Information about the created hub service principal. | | [created\_service\_principal](#output\_created\_service\_principal) | Information about the created service principal. | -| [documentation\_md](#output\_documentation\_md) | Markdown documentation with information about the AKS Building Block building block backplane | | [hub\_application\_password](#output\_hub\_application\_password) | Information about the created hub application password (excludes the actual password value for security). | | [hub\_role\_assignment\_ids](#output\_hub\_role\_assignment\_ids) | The IDs of the hub role assignments for all service principals. | | [hub\_role\_assignment\_principal\_ids](#output\_hub\_role\_assignment\_principal\_ids) | The principal IDs of all service principals that have been assigned the hub role. | diff --git a/modules/azure/aks/backplane/documentation.tf b/modules/azure/aks/backplane/documentation.tf deleted file mode 100644 index eb9bbbcb..00000000 --- a/modules/azure/aks/backplane/documentation.tf +++ /dev/null @@ -1,18 +0,0 @@ -output "documentation_md" { - value = <", formatlist("- `%s`", azurerm_role_definition.buildingblock_deploy.permissions[0].actions))} | - -EOF - description = "Markdown documentation with information about the AKS Building Block building block backplane" -} diff --git a/modules/azure/azure-virtual-machine/backplane/README.md b/modules/azure/azure-virtual-machine/backplane/README.md index 905d4471..59d21a56 100644 --- a/modules/azure/azure-virtual-machine/backplane/README.md +++ b/modules/azure/azure-virtual-machine/backplane/README.md @@ -102,7 +102,6 @@ No modules. | [application\_password](#output\_application\_password) | Information about the created application password (excludes the actual password value for security). | | [created\_application](#output\_created\_application) | Information about the created Azure AD application. | | [created\_service\_principal](#output\_created\_service\_principal) | Information about the created service principal. | -| [documentation\_md](#output\_documentation\_md) | Markdown documentation with information about the Azure Virtual Machine Building Block backplane | | [role\_assignment\_ids](#output\_role\_assignment\_ids) | The IDs of the role assignments for all service principals. | | [role\_assignment\_principal\_ids](#output\_role\_assignment\_principal\_ids) | The principal IDs of all service principals that have been assigned the role. | | [role\_definition\_id](#output\_role\_definition\_id) | The ID of the role definition that enables deployment of the building block to subscriptions. | diff --git a/modules/azure/azure-virtual-machine/backplane/documentation.tf b/modules/azure/azure-virtual-machine/backplane/documentation.tf deleted file mode 100644 index f8eea8b6..00000000 --- a/modules/azure/azure-virtual-machine/backplane/documentation.tf +++ /dev/null @@ -1,18 +0,0 @@ -output "documentation_md" { - value = <", formatlist("- `%s`", azurerm_role_definition.buildingblock_deploy.permissions[0].actions))} | - -EOF - description = "Markdown documentation with information about the Azure Virtual Machine Building Block backplane" -} diff --git a/modules/azure/container-registry/backplane/README.md b/modules/azure/container-registry/backplane/README.md index f6299113..02eb6186 100644 --- a/modules/azure/container-registry/backplane/README.md +++ b/modules/azure/container-registry/backplane/README.md @@ -183,7 +183,6 @@ No modules. | [created\_hub\_application](#output\_created\_hub\_application) | Information about the created hub Azure AD application. | | [created\_hub\_service\_principal](#output\_created\_hub\_service\_principal) | Information about the created hub service principal. | | [created\_service\_principal](#output\_created\_service\_principal) | Information about the created service principal. | -| [documentation\_md](#output\_documentation\_md) | Markdown documentation with information about the Container Registry Building Block backplane | | [hub\_application\_password](#output\_hub\_application\_password) | Information about the created hub application password (excludes the actual password value for security). | | [hub\_role\_assignment\_ids](#output\_hub\_role\_assignment\_ids) | The IDs of the hub role assignments for all service principals. | | [hub\_role\_assignment\_principal\_ids](#output\_hub\_role\_assignment\_principal\_ids) | The principal IDs of all service principals that have been assigned the hub role. | diff --git a/modules/azure/container-registry/backplane/documentation.tf b/modules/azure/container-registry/backplane/documentation.tf deleted file mode 100644 index 256cf3c4..00000000 --- a/modules/azure/container-registry/backplane/documentation.tf +++ /dev/null @@ -1,19 +0,0 @@ -output "documentation_md" { - value = <", formatlist("- `%s`", azurerm_role_definition.buildingblock_deploy.permissions[0].actions))} | -| `${azurerm_role_definition.buildingblock_deploy_hub.name}` | ${azurerm_role_definition.buildingblock_deploy_hub.description} | ${join("
", formatlist("- `%s`", azurerm_role_definition.buildingblock_deploy_hub.permissions[0].actions))} | - -EOF - description = "Markdown documentation with information about the Container Registry Building Block backplane" -} diff --git a/modules/azure/github-actions-terraform-setup/backplane/README.md b/modules/azure/github-actions-terraform-setup/backplane/README.md index af72d416..dc45bb1a 100644 --- a/modules/azure/github-actions-terraform-setup/backplane/README.md +++ b/modules/azure/github-actions-terraform-setup/backplane/README.md @@ -199,6 +199,5 @@ No modules. | Name | Description | |------|-------------| -| [documentation\_md](#output\_documentation\_md) | n/a | | [provider\_config](#output\_provider\_config) | ENVIRONMENT VARIABLES for the AzureRM and AzureAD Providers, which you can use to configure your Building Block Definition. | diff --git a/modules/azure/github-actions-terraform-setup/backplane/documentation.tf b/modules/azure/github-actions-terraform-setup/backplane/documentation.tf deleted file mode 100644 index df2c98e8..00000000 --- a/modules/azure/github-actions-terraform-setup/backplane/documentation.tf +++ /dev/null @@ -1,39 +0,0 @@ -output "documentation_md" { - value = < Starter Kits are meant to be used in [Sandbox Landing Zones](./azure-landingzones-sandbox.md) for learning and experimentation only. - -The easiest way to get started with a Starter Kit is to search for "Starter Kit" in the Likvid Bank Cloud Portal -Marketplace and let the portal help you add it to a Sandbox Subscription (or create a new one if you don't have one yet). - -Starter Kits will create a (private) GitHub repository for you in our [GitHub Organization](https://github.com/your_github_org). -You will find the URL for your repository in the Starter Kit building block output tab. Please review the `README.md` -of that repository for further instructions and inspiration for working with the starter kit. - -## Next Steps when using a Starter Kit - -Once you are happy with your results, please provision a [Cloud-Native Landing Zone](./azure-landingzones-cloud-native.md) and fork-and-own the -starter kit template, including the infrastructure set up by the starter kit building block. We recommend this policy, -because for productive use cases you will eventually need to customize the way your CI/CD pipeline interacts with the -cloud. See [Secure DevOps Best Practices](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/secure/best-practices/secure-devops) -for a good overview of securing production pipelines. - -## Automation - -This building block uses its own dedicated service principal `${azuread_application.starterkit.display_name}` to automate deployment -of required resources to your Azure subscription. - -EOF -} diff --git a/modules/azure/key-vault/backplane/README.md b/modules/azure/key-vault/backplane/README.md index 3d0416fc..3fe17a1c 100644 --- a/modules/azure/key-vault/backplane/README.md +++ b/modules/azure/key-vault/backplane/README.md @@ -72,7 +72,6 @@ No modules. | [created\_hub\_application](#output\_created\_hub\_application) | Information about the created hub Azure AD application. | | [created\_hub\_service\_principal](#output\_created\_hub\_service\_principal) | Information about the created hub service principal. | | [created\_service\_principal](#output\_created\_service\_principal) | Information about the created service principal. | -| [documentation\_md](#output\_documentation\_md) | Markdown documentation with information about the Key Vault Building Block building block backplane | | [hub\_application\_password](#output\_hub\_application\_password) | Information about the created hub application password (excludes the actual password value for security). | | [hub\_role\_assignment\_ids](#output\_hub\_role\_assignment\_ids) | The IDs of the hub role assignments for all service principals. | | [hub\_role\_assignment\_principal\_ids](#output\_hub\_role\_assignment\_principal\_ids) | The principal IDs of all service principals that have been assigned the hub role. | diff --git a/modules/azure/key-vault/backplane/documentation.tf b/modules/azure/key-vault/backplane/documentation.tf deleted file mode 100644 index b1d71b2d..00000000 --- a/modules/azure/key-vault/backplane/documentation.tf +++ /dev/null @@ -1,19 +0,0 @@ -output "documentation_md" { - value = <", formatlist("- `%s`", azurerm_role_definition.buildingblock_deploy.permissions[0].actions))} | - -EOF - description = "Markdown documentation with information about the Key Vault Building Block building block backplane" -} - diff --git a/modules/azure/postgresql/backplane/README.md b/modules/azure/postgresql/backplane/README.md index cabfa2a1..ef7521ab 100644 --- a/modules/azure/postgresql/backplane/README.md +++ b/modules/azure/postgresql/backplane/README.md @@ -1,10 +1,14 @@ -# Azure Subscription Postgresql +# Azure PostgreSQL Building Block — Backplane -This documentation is intended as a reference documentation for cloud foundation or platform engineers using this module. +This documentation is intended as a reference for platform engineers deploying the PostgreSQL Building Block backplane. + +## Overview + +The backplane provisions the automation identity and permissions required to deploy Azure Database for PostgreSQL on behalf of application teams. ## Permissions -This is a very simple building block, which means we let the SPN have access to Key Vault +This is a simple building block backplane that grants the automation principal access to PostgreSQL across all subscriptions underneath a management group (typically the top-level management group for landing zones). @@ -39,7 +43,6 @@ No modules. | Name | Description | |------|-------------| -| [documentation\_md](#output\_documentation\_md) | Markdown documentation with information about the Key Vault Building Block building block backplane | | [role\_assignment\_ids](#output\_role\_assignment\_ids) | The IDs of the role assignments for the service principals. | | [role\_assignment\_principal\_ids](#output\_role\_assignment\_principal\_ids) | The principal IDs of the service principals that have been assigned the role. | | [role\_definition\_id](#output\_role\_definition\_id) | The ID of the role definition that enables deployment of the building block to subscriptions. | diff --git a/modules/azure/postgresql/backplane/documentation.tf b/modules/azure/postgresql/backplane/documentation.tf deleted file mode 100644 index f7c42544..00000000 --- a/modules/azure/postgresql/backplane/documentation.tf +++ /dev/null @@ -1,19 +0,0 @@ -output "documentation_md" { - value = <", formatlist("- `%s`", azurerm_role_definition.buildingblock_deploy.permissions[0].actions))} | - -EOF - description = "Markdown documentation with information about the Key Vault Building Block building block backplane" -} - diff --git a/modules/azure/service-principal/backplane/README.md b/modules/azure/service-principal/backplane/README.md new file mode 100644 index 00000000..ba5a2002 --- /dev/null +++ b/modules/azure/service-principal/backplane/README.md @@ -0,0 +1,91 @@ +# Azure Service Principal Building Block — Backplane + +This documentation is intended as a reference for platform engineers deploying the Service Principal Building Block backplane. + +## Overview + +The backplane provisions the automation identity and permissions required to deploy Azure AD service principals on behalf of application teams. + +It creates: +- A custom Azure RBAC role definition with the minimum permissions required to deploy service principal building blocks +- Role assignments for the automation identity (service principal or existing principals) +- Microsoft Graph API application permission grant (`Application.ReadWrite.OwnedBy`) — requires admin consent in Azure AD + +## Required Permissions + +### Azure RBAC Role + +The backplane creates a custom role definition and assigns it to the automation principal. The role grants permissions to manage Azure resources (e.g. resource group and role assignment operations) needed during building block deployment. + +### Microsoft Graph API Permissions + +The automation principal requires the following Microsoft Graph API application permission: + +| Permission | Description | +|------------|-------------| +| `Application.ReadWrite.OwnedBy` | Allows the app to create other applications and service principals, and fully manage those applications (read, update, delete). It cannot update applications it does not own. | + +> **Note:** `Application.ReadWrite.OwnedBy` requires admin consent in Azure AD before the backplane can function. + +## Operational Notes + +- The backplane must be deployed once per platform team before any building block instances can be created. +- Admin consent for the Graph API permission must be granted manually in the Azure portal or via the Azure CLI. +- The automation principal identity output (`identity`) is consumed by `meshstack_integration.tf` to wire the building block definition. + + +## Requirements + +| Name | Version | +|------|---------| +| [terraform](#requirement\_terraform) | >= 1.3.0 | +| [azuread](#requirement\_azuread) | ~> 3.6.0 | +| [azurerm](#requirement\_azurerm) | ~> 4.36.0 | + +## Modules + +No modules. + +## Resources + +| Name | Type | +|------|------| +| [azuread_app_role_assignment.msgraph_application_readwrite_ownedby](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/app_role_assignment) | resource | +| [azuread_app_role_assignment.msgraph_application_readwrite_ownedby_existing](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/app_role_assignment) | resource | +| [azuread_application.buildingblock_deploy](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application) | resource | +| [azuread_application_federated_identity_credential.buildingblock_deploy](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application_federated_identity_credential) | resource | +| [azuread_application_password.buildingblock_deploy](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application_password) | resource | +| [azuread_service_principal.buildingblock_deploy](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/service_principal) | resource | +| [azurerm_role_assignment.created_principal](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/role_assignment) | resource | +| [azurerm_role_assignment.existing_principals](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/role_assignment) | resource | +| [azurerm_role_definition.buildingblock_deploy](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/role_definition) | resource | +| [azuread_service_principal.msgraph](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/data-sources/service_principal) | data source | +| [azurerm_subscription.current](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/data-sources/subscription) | data source | + +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|------|---------|:--------:| +| [create\_service\_principal\_name](#input\_create\_service\_principal\_name) | Name of a service principal to create and grant permissions to deploy the building block | `string` | `null` | no | +| [existing\_principal\_ids](#input\_existing\_principal\_ids) | Set of existing principal IDs that will be granted permissions to deploy the building block | `set(string)` | `[]` | no | +| [name](#input\_name) | Name of the building block, used for naming resources | `string` | `"service-principal"` | no | +| [scope](#input\_scope) | Scope where the building block should be deployable (management group or subscription), typically the parent of all Landing Zones. | `string` | n/a | yes | +| [workload\_identity\_federation](#input\_workload\_identity\_federation) | Configuration for workload identity federation. If not provided, an application password will be created instead. | 
object({
    issuer  = string
    subject = string
  })
| `null` | no | + +## Outputs + +| Name | Description | +|------|-------------| +| [application\_password](#output\_application\_password) | Information about the created application password (excludes the actual password value for security). | +| [application\_password\_value](#output\_application\_password\_value) | The actual password value for the created application password. | +| [created\_application](#output\_created\_application) | Information about the created Azure AD application. | +| [created\_service\_principal](#output\_created\_service\_principal) | Information about the created service principal. | +| [provider\_tf](#output\_provider\_tf) | Ready-to-use provider.tf configuration for buildingblock deployment | +| [role\_assignment\_ids](#output\_role\_assignment\_ids) | The IDs of the role assignments for all service principals. | +| [role\_assignment\_principal\_ids](#output\_role\_assignment\_principal\_ids) | The principal IDs of all service principals that have been assigned the role. | +| [role\_definition\_id](#output\_role\_definition\_id) | The ID of the role definition that enables deployment of the building block. | +| [role\_definition\_name](#output\_role\_definition\_name) | The name of the role definition that enables deployment of the building block. | +| [scope](#output\_scope) | The scope where the role definition and role assignments are applied. | +| [tenant\_id](#output\_tenant\_id) | The tenant ID of the Azure subscription. | +| [workload\_identity\_federation](#output\_workload\_identity\_federation) | Information about the created workload identity federation credential. | + diff --git a/modules/azure/service-principal/backplane/documentation.tf b/modules/azure/service-principal/backplane/documentation.tf deleted file mode 100644 index 3d6582e0..00000000 --- a/modules/azure/service-principal/backplane/documentation.tf +++ /dev/null @@ -1,29 +0,0 @@ -output "documentation_md" { - value = <", formatlist("- `%s`", azurerm_role_definition.buildingblock_deploy.permissions[0].actions))} | - -### Microsoft Graph API Permissions - -The service principal also requires the following Microsoft Graph API application permissions: - -| Permission | Description | -|------------|-------------| -| `Application.ReadWrite.OwnedBy` | Allows the app to create other applications and service principals, and fully manage those applications (read, update, delete). It cannot update any applications that it is not an owner of. | - -> **Note:** The `Application.ReadWrite.OwnedBy` permission requires admin consent in Azure AD. - -EOF - description = "Markdown documentation with information about the Service Principal Building Block backplane" -} diff --git a/modules/azure/spoke-network/backplane/README.md b/modules/azure/spoke-network/backplane/README.md index 86356763..3c35e16f 100644 --- a/modules/azure/spoke-network/backplane/README.md +++ b/modules/azure/spoke-network/backplane/README.md @@ -44,7 +44,6 @@ No modules. | Name | Description | |------|-------------| -| [documentation\_md](#output\_documentation\_md) | n/a | | [role\_assignment\_ids](#output\_role\_assignment\_ids) | The IDs of the role assignments for the service principals. | | [role\_assignment\_principal\_ids](#output\_role\_assignment\_principal\_ids) | The principal IDs of the service principals that have been assigned the role. | | [role\_definition\_id](#output\_role\_definition\_id) | The ID of the role definition that enables deployment of the Connectivity building block to the hub. | diff --git a/modules/azure/spoke-network/backplane/documentation.tf b/modules/azure/spoke-network/backplane/documentation.tf deleted file mode 100644 index e7ffa0e4..00000000 --- a/modules/azure/spoke-network/backplane/documentation.tf +++ /dev/null @@ -1,20 +0,0 @@ -output "documentation_md" { - value = <", formatlist("- `%s`", azurerm_role_definition.buildingblock_deploy_hub.permissions[0].actions))} | -| `Owner` | On the resource group hosting the spoke network in the target subscription. | `*` | - -EOF -} - diff --git a/tools/scorecard/scorecard.mjs b/tools/scorecard/scorecard.mjs index 077f5709..cd1fb28a 100755 --- a/tools/scorecard/scorecard.mjs +++ b/tools/scorecard/scorecard.mjs @@ -249,6 +249,20 @@ const detectors = [ return { pass: /readme\s*=/.test(content) }; }, }, + { + id: "no_documentation_md_output", + category: "integration", + name: "No documentation_md output in backplane", + emoji: "🚫", + fn: (mod) => { + const allTf = readAllBackplaneTf(mod); + if (!allTf) return { pass: true, detail: "no backplane" }; + return { + pass: !/output\s+"documentation_md"/.test(allTf), + detail: "legacy documentation_md output found — move content to BBD readme and backplane/README.md", + }; + }, + }, // ─── Azure Backplane ──────────────────────────────────────────────────── {