Skip to content

Commit 125dcfe

Browse files
florianowflorianow
committed
chore: adding a better docs file
chore: adding a better docs file chore: adding a better docs file chore: adding a better docs file chore: adding a better docs file chore: adding a better docs file
1 parent 914d1fa commit 125dcfe

File tree

2 files changed

+194
-0
lines changed

2 files changed

+194
-0
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -273,6 +273,7 @@ Before opening a Pull Request, please do the following:
273273
| Name | Description |
274274
|------|-------------|
275275
| <a name="output_azure_ad_tenant_id"></a> [azure\_ad\_tenant\_id](#output\_azure\_ad\_tenant\_id) | The Azure AD tenant id. |
276+
| <a name="output_documentation"></a> [documentation](#output\_documentation) | Complete module documentation in markdown format |
276277
| <a name="output_mca_service_billing_scope"></a> [mca\_service\_billing\_scope](#output\_mca\_service\_billing\_scope) | n/a |
277278
| <a name="output_mca_service_principal"></a> [mca\_service\_principal](#output\_mca\_service\_principal) | MCA Service Principal. |
278279
| <a name="output_mca_service_principal_password"></a> [mca\_service\_principal\_password](#output\_mca\_service\_principal\_password) | Password for MCA Service Principal. |

‎outputs.tf‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,3 +56,196 @@ output "azure_ad_tenant_id" {
5656
description = "The Azure AD tenant id."
5757
value = data.azuread_client_config.current.tenant_id
5858
}
59+
60+
locals {
61+
# Create a hash of all relevant variables to detect when configuration actually changes
62+
config_hash = md5(jsonencode({
63+
replicator_enabled = var.replicator_enabled || var.replicator_rg_enabled
64+
metering_enabled = var.metering_enabled
65+
sso_enabled = var.sso_enabled
66+
mca_enabled = var.mca != null
67+
replicator_service_principal_name = var.replicator_service_principal_name
68+
metering_service_principal_name = var.metering_service_principal_name
69+
sso_service_principal_name = var.sso_service_principal_name
70+
mca_service_principal_names = var.mca != null ? var.mca.service_principal_names : []
71+
replicator_custom_role_scope = var.replicator_custom_role_scope
72+
replicator_assignment_scopes = var.replicator_assignment_scopes
73+
metering_assignment_scopes = var.metering_assignment_scopes
74+
can_cancel_subscriptions_in_scopes = var.can_cancel_subscriptions_in_scopes
75+
can_delete_rgs_in_scopes = var.can_delete_rgs_in_scopes
76+
create_passwords = var.create_passwords
77+
workload_identity_federation = var.workload_identity_federation
78+
sso_meshstack_idp_domain = var.sso_meshstack_idp_domain
79+
sso_identity_provider_alias = var.sso_identity_provider_alias
80+
sso_app_role_assignment_required = var.sso_app_role_assignment_required
81+
administrative_unit_name = var.administrative_unit_name
82+
application_owners = var.application_owners
83+
mca_config = var.mca
84+
}))
85+
}
86+
87+
output "documentation" {
88+
description = "Complete module documentation in markdown format"
89+
value = <<-EOT
90+
# terraform-azure-meshplatform Documentation
91+
92+
Configuration Hash: ${local.config_hash}
93+
94+
## Overview
95+
96+
This Terraform module provisions Azure service principals and configurations for meshStack integration. It creates the necessary Azure AD applications, service principals, and role assignments required for meshStack to manage Azure resources.
97+
98+
## Deployed Components
99+
100+
### Service Principal Status
101+
102+
| Component | Enabled | Service Principal Name | Application ID |
103+
|-----------|---------|----------------------|----------------|
104+
| Replicator | ${length(module.replicator_service_principal) > 0 ? "✅ Yes" : "❌ No"} | ${length(module.replicator_service_principal) > 0 ? module.replicator_service_principal[0].credentials.display_name : "N/A"} | ${length(module.replicator_service_principal) > 0 ? module.replicator_service_principal[0].credentials.application_id : "N/A"} |
105+
| Metering (Kraken) | ${length(module.metering_service_principal) > 0 ? "✅ Yes" : "❌ No"} | ${length(module.metering_service_principal) > 0 ? module.metering_service_principal[0].credentials.display_name : "N/A"} | ${length(module.metering_service_principal) > 0 ? module.metering_service_principal[0].credentials.application_id : "N/A"} |
106+
| SSO | ${length(module.sso_service_principal) > 0 ? "✅ Yes" : "❌ No"} | ${length(module.sso_service_principal) > 0 ? module.sso_service_principal[0].application_display_name : "N/A"} | ${length(module.sso_service_principal) > 0 ? module.sso_service_principal[0].application_client_id : "N/A"} |
107+
| MCA | ${length(module.mca_service_principal) > 0 ? "✅ Yes" : "❌ No"} | ${length(module.mca_service_principal) > 0 ? join(", ", [for cred in module.mca_service_principal[0].credentials : cred.display_name]) : "N/A"} | ${length(module.mca_service_principal) > 0 ? join(", ", [for cred in module.mca_service_principal[0].credentials : cred.application_id]) : "N/A"} |
108+
109+
## Configuration Details
110+
111+
### Azure AD Tenant
112+
- **Tenant ID**: ${data.azuread_client_config.current.tenant_id}
113+
114+
### Authentication Methods
115+
- **Password Authentication**: ${var.create_passwords ? "✅ Enabled" : "❌ Disabled"}
116+
- **Workload Identity Federation**: ${var.workload_identity_federation != null ? "✅ Enabled" : "❌ Disabled"}
117+
${var.workload_identity_federation != null ? " - **Issuer**: ${var.workload_identity_federation.issuer}" : ""}
118+
119+
${var.replicator_enabled || var.replicator_rg_enabled ? <<-REPLICATOR
120+
### Replicator Service Principal
121+
The replicator service principal manages Azure subscriptions and resources.
122+
123+
- **Name**: ${var.replicator_service_principal_name}
124+
- **Custom Role Scope**: ${var.replicator_custom_role_scope}
125+
- **Assignment Scopes**:
126+
${join("\n", formatlist(" - %s", var.replicator_assignment_scopes))}
127+
- **Can Cancel Subscriptions**: ${length(var.can_cancel_subscriptions_in_scopes) > 0 ? join(", ", var.can_cancel_subscriptions_in_scopes) : "None"}
128+
- **Can Delete Resource Groups**: ${length(var.can_delete_rgs_in_scopes) > 0 ? join(", ", var.can_delete_rgs_in_scopes) : "None"}
129+
REPLICATOR
130+
: ""}
131+
132+
${var.metering_enabled ? <<-METERING
133+
### Metering Service Principal (Kraken)
134+
The metering service principal collects cost and usage data.
135+
136+
- **Name**: ${var.metering_service_principal_name}
137+
- **Assignment Scopes**:
138+
${join("\n", formatlist(" - %s", var.metering_assignment_scopes))}
139+
METERING
140+
: ""}
141+
142+
${var.sso_enabled ? <<-SSO
143+
### SSO Service Principal
144+
The SSO service principal enables single sign-on integration.
145+
146+
- **Name**: ${var.sso_service_principal_name}
147+
- **meshStack IDP Domain**: ${var.sso_meshstack_idp_domain}
148+
- **Identity Provider Alias**: ${var.sso_identity_provider_alias}
149+
- **App Role Assignment Required**: ${var.sso_app_role_assignment_required ? "Yes" : "No"}
150+
SSO
151+
: ""}
152+
153+
${var.mca != null ? <<-MCA
154+
### MCA Service Principal
155+
The MCA service principal manages Microsoft Customer Agreement billing.
156+
157+
- **Service Principal Names**: ${join(", ", var.mca.service_principal_names)}
158+
- **Billing Account**: ${var.mca.billing_account_name}
159+
- **Billing Profile**: ${var.mca.billing_profile_name}
160+
- **Invoice Section**: ${var.mca.invoice_section_name}
161+
MCA
162+
: ""}
163+
164+
## Additional Configuration
165+
166+
${var.administrative_unit_name != null ? "### Administrative Unit\n- **Name**: ${var.administrative_unit_name}\n" : ""}
167+
168+
### Application Owners
169+
${length(var.application_owners) > 0 ? join("\n", formatlist("- %s", var.application_owners)) : "- None specified"}
170+
171+
## Outputs Available
172+
173+
The following outputs are available after deployment:
174+
175+
| Output | Description | Sensitive | Available |
176+
|--------|-------------|-----------|-----------|
177+
| replicator_service_principal | Replicator service principal credentials | No | ${length(module.replicator_service_principal) > 0 ? "✅" : "❌"} |
178+
| replicator_service_principal_password | Replicator service principal password | Yes | ${length(module.replicator_service_principal) > 0 ? "✅" : "❌"} |
179+
| mca_service_principal | MCA service principal credentials | No | ${length(module.mca_service_principal) > 0 ? "✅" : "❌"} |
180+
| mca_service_principal_password | MCA service principal password | Yes | ${length(module.mca_service_principal) > 0 ? "✅" : "❌"} |
181+
| mca_service_billing_scope | MCA billing scope | No | ${length(module.mca_service_principal) > 0 ? "✅" : "❌"} |
182+
| metering_service_principal | Metering service principal credentials | No | ${length(module.metering_service_principal) > 0 ? "✅" : "❌"} |
183+
| metering_service_principal_password | Metering service principal password | Yes | ${length(module.metering_service_principal) > 0 ? "✅" : "❌"} |
184+
| sso_service_principal_client_id | SSO service principal client ID | No | ${length(module.sso_service_principal) > 0 ? "✅" : "❌"} |
185+
| sso_service_principal_password | SSO service principal password | Yes | ${length(module.sso_service_principal) > 0 ? "✅" : "❌"} |
186+
| sso_discovery_url | SSO OpenID Connect discovery URL | Yes | ${length(module.sso_service_principal) > 0 ? "✅" : "❌"} |
187+
| azure_ad_tenant_id | Azure AD tenant ID | No | ✅ |
188+
| documentation | This documentation in markdown format | No | ✅ |
189+
190+
## Usage Examples
191+
192+
### Available Commands for Current Configuration
193+
```bash
194+
# Always available
195+
terraform output azure_ad_tenant_id
196+
terraform output documentation
197+
198+
${length(module.replicator_service_principal) > 0 ? <<-REPLICATOR_CMDS
199+
# Replicator Service Principal (✅ deployed)
200+
terraform output replicator_service_principal
201+
terraform output -raw replicator_service_principal_password # sensitive
202+
REPLICATOR_CMDS
203+
: "# Replicator Service Principal (❌ not deployed)"}
204+
205+
${length(module.metering_service_principal) > 0 ? <<-METERING_CMDS
206+
# Metering Service Principal (✅ deployed)
207+
terraform output metering_service_principal
208+
terraform output -raw metering_service_principal_password # sensitive
209+
METERING_CMDS
210+
: "# Metering Service Principal (❌ not deployed)"}
211+
212+
${length(module.sso_service_principal) > 0 ? <<-SSO_CMDS
213+
# SSO Service Principal (✅ deployed)
214+
terraform output sso_service_principal_client_id
215+
terraform output -raw sso_service_principal_password # sensitive
216+
terraform output -raw sso_discovery_url # sensitive
217+
SSO_CMDS
218+
: "# SSO Service Principal (❌ not deployed)"}
219+
220+
${length(module.mca_service_principal) > 0 ? <<-MCA_CMDS
221+
# MCA Service Principal (✅ deployed)
222+
terraform output mca_service_principal
223+
terraform output -raw mca_service_principal_password # sensitive
224+
terraform output mca_service_billing_scope
225+
MCA_CMDS
226+
: "# MCA Service Principal (❌ not deployed)"}
227+
228+
# Save documentation to file
229+
terraform output -raw documentation > meshplatform-docs.md
230+
```
231+
232+
### Integration with meshStack
233+
1. Use the service principal credentials in your meshStack platform configuration
234+
2. Configure the appropriate scopes and permissions based on your requirements
235+
3. Set up workload identity federation if enabled for enhanced security
236+
237+
## Security Considerations
238+
239+
- Sensitive outputs (passwords, discovery URLs) are marked as sensitive in Terraform
240+
- Consider using workload identity federation instead of passwords for enhanced security
241+
- Regularly rotate service principal passwords if using password authentication
242+
- Follow principle of least privilege when assigning scopes and permissions
243+
244+
## Support
245+
246+
For issues and questions regarding this module, please refer to the project repository or contact your meshStack administrator.
247+
248+
---
249+
*This documentation was automatically generated by Terraform (config hash: ${local.config_hash})*
250+
EOT
251+
}

0 commit comments

Comments
 (0)