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. The output of this module is a set of credentials that need to be configured in meshStack as described in meshcloud public docs.
We currently support Microsoft Enterprise Agreements and Microsoft Customer Agreements as well as pre-provisioned subscriptions when integrating Azure as a meshPlatform.
To run this module, you need the following:
- Terraform installed (already installed in Azure Portal)
- Azure CLI installed (already installed in Azure Portal)
- Permissions on AAD level. If using Microsoft Customer Agreement, AAD level permissions must be set in the Tenant Directory that will create the subscriptions (Source Tenant) as well as the Tenant Directory that will receive the subscriptions (Destination Tenant). An Azure account with one of the following roles:
- Global Administrator
- Privileged Role Administrator AND (Cloud) Application Administrator
- Permissions on Azure Resource Level: User Access Administrator on the Management Group that should be managed by meshStack
If using a Microsoft Customer Agreement, go through these steps in the Destination Tenant
-
Login into Azure Portal with your Admin user.
-
Open a cloud shell.
-
Create a terraform file that calls this module and produces outputs. Similar to:
module "meshplatform" { source = "git::https://github.com/meshcloud/terraform-azure-meshplatform.git" # FILL INPUTS } output "meshplatform" { sensitive = true value = module.meshplatform }
It is highly recommended to configure a terraform backend, otherwise you risk losing track of your applied resources.
-
Execute the module.
# Changes into ~/terraform-azure-meshplatform and applies terraform cd ~/terraform-azure-meshplatform terraform init terraform apply
-
Use the information from terraform output to configure the platform in meshStack.
# The JSON output contains sensitive values that must not be transmitted anywhere other then the platform config screen in meshStack. terraform output -json
-
Login with az CLI
az login --tenant TENANT_ID
-
Follow the instructions for Azure Portal
Using an Enterprise Agreement enrollment account requires manual steps outside of terraform.
- Ensure you have permissions on Enterprise Agreement level:
Account Owner
for the enrollment account that should be used for creating subscriptions - Grant access on the enrollment account as described in the section Use an Enteprise Enrollment.
Until hashicorp/terraform-provider-azurerm#15211 is resolved, MCA service principal setup can only be done manually outside of terraform.
- Ensure you have permissions in the source AAD Tenant for granting access to the billing account used for subscription creation using the
Account Administrator
role - Switch to the Tenant Directory that contains your Billing Account and follow the steps to Register an Application and Add Credentials. Make sure to copy down the Directory (tenant) ID, Application (client) ID, Object ID and the App Secret value that was generated. The App Secret is only visible during the creation process.
- You must grant the Enterprise Application permissions on the Billing Account, Billing Profile, or Invoice Section so that it can generate new subscriptions. Follow the steps in this guide to grant the necessary permissions. You must grant one of the following permissions
- Billing Account or Billing Profile: Owner, Contributor
- Invoice Section: Owner, Contributor, Azure Subscription Creator
- Write down the Billing Scope ID that looks something like this /providers/Microsoft.Billing/billingAccounts/5e98e158-xxxx-xxxx-xxxx-xxxxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxx-xx-xx/billingProfiles/AW4F-xxxx-xxx-xxx/invoiceSections/SH3V-xxxx-xxx-xxx
- Use the following information to configure the platform in meshStack
- Billing Scope
- Destination Tenant ID
- Source Tenant ID
- Billing Account Principal Client ID (Application Client ID that will be used to create new subscriptions)
- Principal Client Secret (Application Secret created in the Source Tenant)
meshStack will need to be able to read subscriptions at the source location
(typically the root of your management group hierarchy) and then have permission to rename them.
Please include the following additional_permission
when configuring this terraform module.
additional_permissions = ["Microsoft.Subscription/rename/action"]
In order to enable meshStack to call Azure Functions as part of tenant replication for your landing zones, you must provide the SPN with access to the function.
additional_required_resource_accesses = [
# The block below configures replicator access
# to the app with id `fe81736c-99c6-4fca-8cc2-2818a2365451` with the appRole with id `e29066a1-ecb1-4a8e-af2d-1627fae35711`
#
# This example configures access to an azure function
{
resource_app_id = "fe81736c-99c6-4fca-8cc2-2818a2365451" # https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application#resource_app_id
resource_accesses = [
# https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application#resource_access
{
id = "e29066a1-ecb1-4a8e-af2d-1627fae35711"
type = "Role"
},
]
},
]
Before opening a Pull Request, please do the following:
-
Install pre-commit
We use pre-commit to perform several terraform related tasks such as
terraform validate
,terraform fmt
, and generating terraform docs withterraform_docs
-
Execute
pre-commit install
: Hooks configured in.pre-commit-config.yaml
will be executed automatically on commit. For manual execution, you can usepre-commit run -a
.
Name | Version |
---|---|
terraform | > 1.1 |
azuread | 2.46.0 |
azurerm | 3.81.0 |
Name | Version |
---|---|
azuread | 2.46.0 |
azurerm | 3.81.0 |
Name | Source | Version |
---|---|---|
metering_service_principal | ./modules/meshcloud-metering-service-principal/ | n/a |
replicator_service_principal | ./modules/meshcloud-replicator-service-principal/ | n/a |
sso_service_principal | ./modules/meshcloud-sso/ | n/a |
Name | Type |
---|---|
azuread_client_config.current | data source |
azurerm_management_group.metering_assignment_scopes | data source |
azurerm_management_group.replicator_assignment_scopes | data source |
azurerm_management_group.replicator_custom_role_scope | data source |
Name | Description | Type | Default | Required |
---|---|---|---|---|
additional_permissions | Additional Subscription-Level Permissions the Service Principal needs. | list(string) |
[] |
no |
additional_required_resource_accesses | Additional AAD-Level Resource Accesses the replicator Service Principal needs. | list(object({ resource_app_id = string, resource_accesses = list(object({ id = string, type = string })) })) |
[] |
no |
can_cancel_subscriptions_in_scopes | The scopes to which Service Principal cancel subscription permission is assigned to. List of management group id of form /providers/Microsoft.Management/managementGroups/<mgmtGroupId>/ . |
list(string) |
[] |
no |
can_delete_rgs_in_scopes | The scopes to which Service Principal delete resource group permission is assigned to. Only relevant when replicator_rg_enabled . List of subscription scopes of form /subscriptions/<subscriptionId> . |
list(string) |
[] |
no |
create_passwords | Create passwords for service principals. | bool |
true |
no |
metering_assignment_scopes | Names or UUIDs of the Management Groups that kraken should collect costs for. | list(string) |
n/a | yes |
metering_enabled | Whether to create Metering Service Principal or not. | bool |
true |
no |
metering_service_principal_name | Service principal for collecting cost data. Kraken ist the name of the meshStack component. Name must be unique per Entra ID. | string |
"kraken" |
no |
replicator_assignment_scopes | Names or UUIDs of the Management Groups which replicator should manage. | list(string) |
n/a | yes |
replicator_custom_role_scope | Name or UUID of the Management Group of the replicator custom role definition. The custom role definition must be available for all assignment scopes. | string |
n/a | yes |
replicator_enabled | Whether to create replicator Service Principal or not. | bool |
true |
no |
replicator_rg_enabled | Whether the created replicator Service Principal should be usable for Azure Resource Group based replication. Implicitly enables replicator_enabled if set to true. | bool |
false |
no |
replicator_service_principal_name | Service principal for managing subscriptions. Replicator is the name of the meshStack component. Name must be unique per Entra ID. | string |
"replicator" |
no |
sso_enabled | Whether to create SSO Service Principal or not. | bool |
true |
no |
sso_meshstack_redirect_uri | Redirect URI that was provided by meshcloud. It is individual per meshStack. | string |
"<replace with uri>" |
no |
sso_service_principal_name | Service principal for Entra ID SSO. Name must be unique per Entra ID. | string |
"sso" |
no |
workload_identity_federation | Enable workload identity federation by creating federated credentials for enterprise applications. Usually you'd receive the required settings when attempting to configure a platform with workload identity federation in meshStack. | object({ issuer = string, replicator_subject = string, kraken_subject = string }) |
null |
no |
Name | Description |
---|---|
azure_ad_tenant_id | The Azure AD tenant id. |
metering_service_principal | Metering Service Principal. |
metering_service_principal_password | Password for Metering Service Principal. |
replicator_service_principal | Replicator Service Principal. |
replicator_service_principal_password | Password for Replicator Service Principal. |
sso_service_principal | SSO Service Principal. |
sso_service_principal_password | Password for SSO Service Principal. |