Task 06: Customer Transfer
DOCUMENT CATEGORY: Implementation Runbook
SCOPE: The Azure resources of one Azure Local instance
PURPOSE: Give the customer administrator access in Azure and write the record of the transfer
MASTER REFERENCE: Assign Azure roles using Azure CLI
Status: Active
The script looks the customer administrator up in Microsoft Entra ID (by user principal name, then by mail for a guest), assigns the built-in role Contributor on the resource group and Reader on the subscription when the administrator does not have them, counts the role assignments, and writes the record (Markdown and JSON). It is idempotent: a role the administrator already has is reported, and the script never removes a role assignment. It does not touch the nodes: local access is the customer's decision (a domain group, identity.active_directory.security_groups), and the record says so. It does not sign in.
Values from infrastructure.yml
The values for this task come from infrastructure.yml (schema 5). Every key, with its type, default and example, is in the variables reference.
| Key | What the script does with it |
|---|---|
cluster.name | The instance that is handed over (in the record) |
azure.tenant_id | The tenant the sign-in must belong to |
azure.subscription_id, azure.resource_group | The scopes of the two role assignments |
site.customer | The customer named in the record |
The customer's own tenant (-CustomerTenantId) and administrator (-CustomerAdminUPN) are parameters: they are not part of the deployment.
Execution Options
- PowerShell
- Azure CLI
PowerShell
When to use: The Az PowerShell modules are installed. Sign in first:
Connect-AzAccount -Tenant <azure.tenant_id>, with an account that may create role assignments (Owner or User Access Administrator)
| Script | What it does |
|---|---|
scripts/deploy/07-validation-handover/task-06-customer-transfer/powershell/Set-CustomerTransfer.ps1 | Entra lookup, two role assignments, the record. -WhatIf reads Azure, assigns nothing and writes no file |
| Parameter | Meaning |
|---|---|
-InfrastructureFile | The infrastructure.yml (schema 5). Required |
-CustomerTenantId | The customer's Entra tenant id (a GUID). It goes in the portal link of the record. Required |
-CustomerAdminUPN | The user principal name (or the mail of a guest) of the customer administrator. Required |
-OutputPath | The folder for the record. Without it nothing is written |
./Set-CustomerTransfer.ps1 -InfrastructureFile ./infrastructure.yml -CustomerTenantId <customer-tenant-id> -CustomerAdminUPN admin@contoso.example -WhatIf
./Set-CustomerTransfer.ps1 -InfrastructureFile ./infrastructure.yml -CustomerTenantId <customer-tenant-id> -CustomerAdminUPN admin@contoso.example -OutputPath ./handover
Azure CLI
When to use: The Azure CLI is installed. Sign in first:
az login --tenant <azure.tenant_id>
| Script | What it does |
|---|---|
scripts/deploy/07-validation-handover/task-06-customer-transfer/azurecli/Set-CustomerTransfer.azcli.ps1 | The same with az ad user show, az role assignment list and az role assignment create --assignee-object-id --assignee-principal-type User. Same parameters, same record |
az login --tenant <tenant-id>
./Set-CustomerTransfer.azcli.ps1 -InfrastructureFile ./infrastructure.yml -CustomerTenantId <customer-tenant-id> -CustomerAdminUPN admin@contoso.example -OutputPath ./handover
- Arguments. Every
azargument goes through the toolkit's guard (scripts/common/azure-cli/AzlAzureCliArgument.psm1). A value of the file, or the-CustomerAdminUPN, that holds&,|,<,>,^,%,"or a line break ends the run with exit code 2 before anyazcall, also under-WhatIf. On Windowsazis a batch file (az.cmd), which would read these characters as commands. - An apostrophe in the address. The guest lookup by mail uses an OData filter, and the script doubles an apostrophe in the address as OData requires (
o'brien@contoso.exampleis sent aso''brien@contoso.example). The address reachesazwhole. - Subscription. The script selects
azure.subscription_idand puts the earlier subscription back at the end. If it cannot, it prints a warning, adds aFailedstep and ends with exit code 1;azthen stays set to the subscription of the file. Runaz account set --subscription <your earlier subscription>.
Exit codes (both): 0 the transfer is in place (assigned, already there, or planned under -WhatIf) and the record is written; 1 an Azure call failed or a precondition failed (not signed in, wrong tenant, the administrator not found, an assignment failed), or (Azure CLI) the earlier subscription could not be put back; 2 a value in the file or a parameter is missing or not usable.
Validation
- Exit code 0 and both roles are
AssignedorAlreadyAssigned - The customer administrator sees the resource group in the Azure portal (the link is in the record)
- The record is saved with the rest of the handover package
Troubleshooting
| Issue | Cause | Resolution |
|---|---|---|
was not found in Microsoft Entra ID | A guest has not been invited, or the name is wrong | Invite the guest first, then run again |
An assignment fails with AuthorizationFailed | The signed-in account cannot create role assignments | Sign in as Owner or User Access Administrator |
| Signed in to the wrong tenant | az or Connect-AzAccount is in another tenant | Sign in to azure.tenant_id |
Navigation
| Previous | Up | Next |
|---|---|---|
| Task 05: Deployment Documentation | Part 7 Index | Part 8: Day 2 Operations |
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2026-11-15 | Azure Local Cloud | Initial release (the script moved here from the old handover folder of the toolkit; adds the Azure CLI script) |
| 1.0.1 | 2026-11-16 | Azure Local Cloud | Azure CLI tab: the argument guard, an apostrophe in the address, exit code 1 when the earlier subscription cannot be put back |