Skip to content

Commit 6d5ce71

Browse files
malhussanmalhussan
committed
chore: script to generate tf docs
1 parent ccfece3 commit 6d5ce71

File tree

4 files changed

+98
-83
lines changed

4 files changed

+98
-83
lines changed

‎README.md

Lines changed: 28 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,28 @@
11
# Azure meshPlatform Module
22

3-
Terraform module to integrate Azure as a meshPlatform into meshStack instance.
4-
5-
With this module, service principals used by meshStack are created with the required permissions.
3+
Terraform module to integrate Azure as a meshPlatform into meshStack instance. With this module, service principals used by meshStack are created with the required permissions.
64

75
## Prerequisites
86

9-
Permissions on AAD level are needed to run this module.
10-
Tenant wide admin consent must be granted for a succesful meshPlatform setup. Therefore to integrate a meshPlatform you need:
7+
To run this module, you need the following:
118

12-
> An Azure account with one of the following roles: Global Administrator, Privileged Role Administrator, Cloud Application Administrator, or Application Administrator. A user can also be authorized to grant tenant-wide consent if they are assigned a custom directory role that includes the permission to grant permissions to applications.[^1]
9+
- Permissions on AAD level. An Azure account with one of the following roles[^1]:
10+
- Global Administrator
11+
- Privileged Role Administrator
12+
- Cloud Application Administrator
13+
- Application Administrator
14+
- [Terraform installed](https://learn.hashicorp.com/tutorials/terraform/install-cli)
15+
- [Azure CLI installed](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)
1316

14-
[^1]: See [Azure public documentation](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent#prerequisites)
17+
[^1]: Tenant wide admin consent must be granted for a successful meshPlatform setup. See [Azure public documentation](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent#prerequisites) for more details.
1518

16-
## How to use this module
19+
## Module Structure
1720

18-
### Using Azure Portal
21+
For an overview of the module structure, refer to [generated terraform docs](./TERRAFORM_DOCS.md)
1922

20-
Prerequisites: [Terraform installed](https://learn.hashicorp.com/tutorials/terraform/install-cli)
23+
## How to Use This Module
24+
25+
### Using Azure Portal
2126

2227
1. Login into [Azure Portal](https://portal.azure.com/) with your Admin user.
2328

@@ -30,19 +35,17 @@ Prerequisites: [Terraform installed](https://learn.hashicorp.com/tutorials/terra
3035
cd terraform-azure-meshplatform
3136
```
3237

33-
4. Create a `main.tf` file that references this module:
38+
4. Create a `main.tf` and an `output.tf` files in the created directory that references this module
39+
> See [Example Usages](#example-usages)
3440

3541
```sh
36-
cat > ~/terraform-azure-meshplatform/main.tf << EOF
37-
module "meshplatform" {
38-
source = "git@github.com:meshcloud/terraform-azure-meshplatform.git"
39-
40-
spp_name_suffix = "unique-name"
41-
mgmt_group_name = "management-group-name"
42-
}
43-
EOF
42+
wget https://raw.githubusercontent.com/meshcloud/terraform-azure-meshplatform/main/examples/basic-azure-integration/main.tf -O ~/terraform-azure-meshplatform/main.tf
43+
44+
wget https://raw.githubusercontent.com/meshcloud/terraform-azure-meshplatform/main/examples/basic-azure-integration/outputs.tf -O ~/terraform-azure-meshplatform/outputs.tf
4445
```
4546

47+
Fill them with your inputs and Terraform state backend settings
48+
4649
5. Run
4750

4851
```sh
@@ -59,23 +62,21 @@ Prerequisites: [Terraform installed](https://learn.hashicorp.com/tutorials/terra
5962

6063
### Using CLI
6164

62-
Prerequisites:
63-
64-
- [Azure CLI installed](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)
65-
- [Terraform installed](https://learn.hashicorp.com/tutorials/terraform/install-cli)
66-
6765
1. Login with az CLI
68-
```sh
66+
67+
```sh
6968
az login --tenant TENANT_ID
7069
```
70+
7171
2. Create a directory and change into it
72+
7273
```sh
7374
mkdir terraform-azure-meshplatform
7475
cd terraform-azure-meshplatform
7576
```
7677

7778
3. Create a `main.tf` and an `output.tf` files in the created directory that references this module
78-
> Sample files can be found in [examples](./examples/basic-azure-integration)
79+
> See [Example Usages](#example-usages)
7980

8081
4. Run
8182

@@ -90,61 +91,7 @@ Prerequisites:
9091
# The JSON output contains sensitive values that must not be transmitted to meshcloud in plain text.
9192
terraform output -json
9293
```
94+
9395
## Example Usages
9496

9597
Check [examples](./examples/) for different use cases. As a quick start we recommend using [basic-azure-integration](./examples/basic-azure-integration) example.
96-
97-
## Requirements
98-
99-
| Name | Version |
100-
|------|---------|
101-
| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
102-
| <a name="requirement_azuread"></a> [azuread](#requirement\_azuread) | 2.18.0 |
103-
| <a name="requirement_azurerm"></a> [azurerm](#requirement\_azurerm) | 2.97.0 |
104-
105-
## Providers
106-
107-
| Name | Version |
108-
|------|---------|
109-
| <a name="provider_azurerm"></a> [azurerm](#provider\_azurerm) | 2.12.0 |
110-
111-
## Modules
112-
113-
| Name | Source | Version |
114-
|------|--------|---------|
115-
| <a name="module_idp_lookup_spp"></a> [idp\_lookup\_spp](#module\_idp\_lookup\_spp) | ./modules/meshcloud-idp-lookup-spp/ | n/a |
116-
| <a name="module_kraken_spp"></a> [kraken\_spp](#module\_kraken\_spp) | ./modules/meshcloud-kraken-spp/ | n/a |
117-
| <a name="module_replicator_spp"></a> [replicator\_spp](#module\_replicator\_spp) | ./modules/meshcloud-replicator-spp/ | n/a |
118-
| <a name="module_uami_blueprint_user_principal"></a> [uami\_blueprint\_user\_principal](#module\_uami\_blueprint\_user\_principal) | ./modules/uami-blueprint-user-principal/ | n/a |
119-
120-
## Resources
121-
122-
| Name | Type |
123-
|------|------|
124-
| [azurerm_management_group.root](https://registry.terraform.io/providers/hashicorp/azurerm/2.97.0/docs/data-sources/management_group) | data source |
125-
126-
## Inputs
127-
128-
| Name | Description | Type | Default | Required |
129-
|------|-------------|------|---------|:--------:|
130-
| <a name="input_additional_permissions"></a> [additional\_permissions](#input\_additional\_permissions) | Additional Subscription-Level Permissions the SPP needs. | `list(string)` | `[]` | no |
131-
| <a name="input_additional_required_resource_accesses"></a> [additional\_required\_resource\_accesses](#input\_additional\_required\_resource\_accesses) | Additional AAD-Level Resource Accesses the replicator SPP needs. | `list(object({ resource_app_id = string, resource_accesses = list(object({ id = string, type = string })) }))` | `[]` | no |
132-
| <a name="input_idplookup_enabled"></a> [idplookup\_enabled](#input\_idplookup\_enabled) | Whether to create idplookup SPP or not. | `bool` | `true` | no |
133-
| <a name="input_kraken_enabled"></a> [kraken\_enabled](#input\_kraken\_enabled) | Whether to create kraken SPP or not. | `bool` | `true` | no |
134-
| <a name="input_mgmt_group_name"></a> [mgmt\_group\_name](#input\_mgmt\_group\_name) | The name or UUID of the Management Group. | `string` | n/a | yes |
135-
| <a name="input_replicator_enabled"></a> [replicator\_enabled](#input\_replicator\_enabled) | Whether to create replicator SPP or not. | `bool` | `true` | no |
136-
| <a name="input_spp_name_suffix"></a> [spp\_name\_suffix](#input\_spp\_name\_suffix) | Service principal name suffix. Make sure this is unique. | `string` | n/a | yes |
137-
| <a name="input_subscriptions"></a> [subscriptions](#input\_subscriptions) | The scope to which UAMI blueprint service principal role assignment is applied. | `list(any)` | `[]` | no |
138-
139-
## Outputs
140-
141-
| Name | Description |
142-
|------|-------------|
143-
| <a name="output_idp_lookup_spp"></a> [idp\_lookup\_spp](#output\_idp\_lookup\_spp) | IDP Lookup Service Principal. |
144-
| <a name="output_idp_lookup_spp_password"></a> [idp\_lookup\_spp\_password](#output\_idp\_lookup\_spp\_password) | Password for IDP Lookup Service Principal. |
145-
| <a name="output_kraken_spp"></a> [kraken\_spp](#output\_kraken\_spp) | Kraken Service Principal. |
146-
| <a name="output_kraken_spp_password"></a> [kraken\_spp\_password](#output\_kraken\_spp\_password) | Password for Kraken Service Principal. |
147-
| <a name="output_replicator_spp"></a> [replicator\_spp](#output\_replicator\_spp) | Replicator Service Principal. |
148-
| <a name="output_replicator_spp_password"></a> [replicator\_spp\_password](#output\_replicator\_spp\_password) | Password for Replicator Service Principal. |
149-
| <a name="output_uami_blueprint_user_principal"></a> [uami\_blueprint\_user\_principal](#output\_uami\_blueprint\_user\_principal) | UAMI Blueprint Assignment Service Principal. |
150-
| <a name="output_uami_blueprint_user_principal_password"></a> [uami\_blueprint\_user\_principal\_password](#output\_uami\_blueprint\_user\_principal\_password) | Password for UAMI Blueprint Assignment Service Principal. |

‎TERRAFORM_DOCS.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
## Requirements
2+
3+
| Name | Version |
4+
|------|---------|
5+
| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
6+
| <a name="requirement_azuread"></a> [azuread](#requirement\_azuread) | 2.18.0 |
7+
| <a name="requirement_azurerm"></a> [azurerm](#requirement\_azurerm) | 2.97.0 |
8+
9+
## Providers
10+
11+
| Name | Version |
12+
|------|---------|
13+
| <a name="provider_azurerm"></a> [azurerm](#provider\_azurerm) | 2.12.0 |
14+
15+
## Modules
16+
17+
| Name | Source | Version |
18+
|------|--------|---------|
19+
| <a name="module_idp_lookup_spp"></a> [idp\_lookup\_spp](#module\_idp\_lookup\_spp) | ./modules/meshcloud-idp-lookup-spp/ | n/a |
20+
| <a name="module_kraken_spp"></a> [kraken\_spp](#module\_kraken\_spp) | ./modules/meshcloud-kraken-spp/ | n/a |
21+
| <a name="module_replicator_spp"></a> [replicator\_spp](#module\_replicator\_spp) | ./modules/meshcloud-replicator-spp/ | n/a |
22+
| <a name="module_uami_blueprint_user_principal"></a> [uami\_blueprint\_user\_principal](#module\_uami\_blueprint\_user\_principal) | ./modules/uami-blueprint-user-principal/ | n/a |
23+
24+
## Resources
25+
26+
| Name | Type |
27+
|------|------|
28+
| [azurerm_management_group.root](https://registry.terraform.io/providers/hashicorp/azurerm/2.97.0/docs/data-sources/management_group) | data source |
29+
30+
## Inputs
31+
32+
| Name | Description | Type | Default | Required |
33+
|------|-------------|------|---------|:--------:|
34+
| <a name="input_additional_permissions"></a> [additional\_permissions](#input\_additional\_permissions) | Additional Subscription-Level Permissions the SPP needs. | `list(string)` | `[]` | no |
35+
| <a name="input_additional_required_resource_accesses"></a> [additional\_required\_resource\_accesses](#input\_additional\_required\_resource\_accesses) | Additional AAD-Level Resource Accesses the replicator SPP needs. | `list(object({ resource_app_id = string, resource_accesses = list(object({ id = string, type = string })) }))` | `[]` | no |
36+
| <a name="input_idplookup_enabled"></a> [idplookup\_enabled](#input\_idplookup\_enabled) | Whether to create idplookup SPP or not. | `bool` | `true` | no |
37+
| <a name="input_kraken_enabled"></a> [kraken\_enabled](#input\_kraken\_enabled) | Whether to create kraken SPP or not. | `bool` | `true` | no |
38+
| <a name="input_mgmt_group_name"></a> [mgmt\_group\_name](#input\_mgmt\_group\_name) | The name or UUID of the Management Group. | `string` | n/a | yes |
39+
| <a name="input_replicator_enabled"></a> [replicator\_enabled](#input\_replicator\_enabled) | Whether to create replicator SPP or not. | `bool` | `true` | no |
40+
| <a name="input_spp_name_suffix"></a> [spp\_name\_suffix](#input\_spp\_name\_suffix) | Service principal name suffix. Make sure this is unique. | `string` | n/a | yes |
41+
| <a name="input_subscriptions"></a> [subscriptions](#input\_subscriptions) | The scope to which UAMI blueprint service principal role assignment is applied. | `list(any)` | `[]` | no |
42+
43+
## Outputs
44+
45+
| Name | Description |
46+
|------|-------------|
47+
| <a name="output_idp_lookup_spp"></a> [idp\_lookup\_spp](#output\_idp\_lookup\_spp) | IDP Lookup Service Principal. |
48+
| <a name="output_idp_lookup_spp_password"></a> [idp\_lookup\_spp\_password](#output\_idp\_lookup\_spp\_password) | Password for IDP Lookup Service Principal. |
49+
| <a name="output_kraken_spp"></a> [kraken\_spp](#output\_kraken\_spp) | Kraken Service Principal. |
50+
| <a name="output_kraken_spp_password"></a> [kraken\_spp\_password](#output\_kraken\_spp\_password) | Password for Kraken Service Principal. |
51+
| <a name="output_replicator_spp"></a> [replicator\_spp](#output\_replicator\_spp) | Replicator Service Principal. |
52+
| <a name="output_replicator_spp_password"></a> [replicator\_spp\_password](#output\_replicator\_spp\_password) | Password for Replicator Service Principal. |
53+
| <a name="output_uami_blueprint_user_principal"></a> [uami\_blueprint\_user\_principal](#output\_uami\_blueprint\_user\_principal) | UAMI Blueprint Assignment Service Principal. |
54+
| <a name="output_uami_blueprint_user_principal_password"></a> [uami\_blueprint\_user\_principal\_password](#output\_uami\_blueprint\_user\_principal\_password) | Password for UAMI Blueprint Assignment Service Principal. |

‎examples/basic-azure-integration/main.tf

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
1-
# It is recommended to setup a backend to store the terraform state file
2-
# Removing the backend leads to terraform state output stored in the local filesystem.
1+
# It is highly recommended to setup a backend to store the terraform state file
2+
# Removing the backend will output the terraform state in the local filesystem
33
# See https://www.terraform.io/language/settings/backends for more details
4+
#
5+
# Remove/comment the backend block below if you are only testing the module.
6+
# Please be aware that you cannot destroy the created resources via terraform if you lose the state file.
47
terraform {
58
backend "gcs" {
69
prefix = "meshplatforms/azure"

‎generate_tf_docs.sh

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
#!/bin/bash
2+
3+
# Generate README.md for child modules
4+
for d in ./modules/*/; do
5+
(cd "$d" && docker run --rm --volume "$(pwd):/terraform-docs" -u "$(id -u)" quay.io/terraform-docs/terraform-docs:0.16.0 markdown /terraform-docs > README.md);
6+
done
7+
8+
# Generate TERRAFORM_DOCS.md
9+
docker run --rm \
10+
--volume "$(pwd):/terraform-docs" \
11+
-u "$(id -u)" quay.io/terraform-docs/terraform-docs:0.16.0 markdown /terraform-docs > TERRAFORM_DOCS.md

0 commit comments

Comments
 (0)