Cloudaware PowerShell Modules

Use Cloudaware PowerShell modules to automate Azure integration setup and cleanup tasks.

info

• Audience: Cloudaware administrators, Azure administrators
• Outcome: Cloudaware PowerShell modules are available for Azure registration or unregister workflows

Available Modules

Cloudaware provides PowerShell modules for:

• Registering Cloudaware access in Azure
• Removing previously registered Cloudaware access from Azure

Before You Begin

Before using the modules, make sure that:

• You have access to Azure Cloud Shell or a PowerShell environment with Azure tooling installed.
• Your Azure user has the required permissions to create and manage app registrations, API permissions, and role assignments.
• You have reviewed the Azure Setup Guide.

Register Cloudaware

Use the Register-Cloudaware module to create a Microsoft Entra ID application in Azure and grant Cloudaware the permissions required for Azure discovery.

Prepare the Register Module Environment

1. Log in to the Azure portal.

2. Open Azure Cloud Shell and select PowerShell.

3. Sign in with Azure CLI:

   az login

4. Create a working directory and download the module:

   mkdir cloudaware
   cd cloudaware
   curl -LJO https://raw.githubusercontent.com/cloudaware/public-utilities/master/PowerShell%20modules/Register-Cloudaware.ps1

5. Import the module for the current Cloud Shell session:

   Import-Module -Name .\Register-Cloudaware.ps1 -Force

After the module is imported, Register-Cloudaware is available in the current Azure Cloud Shell session.

Register Module Parameters

Parameter	Description
-name <NAME>	Name of the Microsoft Entra ID application to create. Example: -name cloudaware-api-access.
-credentialExpiration <YEAR>	Credential expiration period, in years. Example: -credentialExpiration 1.
-certificateFile <path_to_PEM_FILE_NAME>	Path to the certificate file. Example: -certificateFile cert.pem.
-createKeyAndSertificate	Automatically generates .key and .cert files and uses them for the created application. Generated files are stored in ~\cloudaware and use the format <USER_PRINCIPAL_NAME>_<APP_ID>.
-redirectUri <URI>	Redirect URI for the application. Example: -redirectUri https://cloudaware-api-access.com.
-withSubscriptionRole <ID1 [,ID2, IDn]>	Assigns the Reader role to the application for all subscriptions (all) or for specific subscription IDs. If omitted, subscription role assignment is skipped.
-withKeyVaultPolicies <NAME1 [,NAME2, NAMEn]>	Assigns the Key Vault list policy for keys and secrets so Cloudaware can access Key Vault metadata. Use all for all available Key Vaults or specify Key Vault names. If omitted, Key Vault policy assignment is skipped.
-withKubernetesRole <ID1 [,ID2, IDn]>	Assigns the Azure Kubernetes Service Cluster Admin Role to the application for all subscriptions (all) or for specific subscription IDs. If omitted, Kubernetes role assignment is skipped.
-withReservationRole <ID1 [,ID2, IDn]>	Assigns the Reader role to reservation orders. The reservation scope must be Shared. Use all or specify reservation order IDs. If omitted, reservation role assignment is skipped.
-dryRun	Saves the parameter values that would be used to create the application to ~\cloudaware\dryRunToCreateApp_<USER_PRINCIPAL_NAME>_<APPLICATION_NAME>.json.
-generateTemplate	Generates a sample JSON template at ~\cloudaware\template.json.
-fromTemplate <path_to_JSON_FILE_NAME>	Runs the module using parameters from a JSON file. Example: -fromTemplate register-cloudaware-parameters.json.

Register Module Examples

Show help for the module:

Get-Help Register-Cloudaware -Full
Get-Help Register-Cloudaware -Examples
Get-Help Register-Cloudaware -Parameter *

Run the module with parameters directly:

Register-Cloudaware -name cloudaware-api-access `
                    -credentialExpiration 10 `
                    -certificateFile cert.pem `
                    -redirectUri 'https://cloudaware-api-access.com' `
                    -withSubscriptionRole all `
                    -withKeyVaultPolicies keyVaultName_1, keyVaultName_2 `
                    -withKubernetesRole all `
                    -withReservationRole all `
                    -dryRun `
                    -verbose

Generate a template, then run the module from a JSON file:

Register-Cloudaware -generateTemplate
Register-Cloudaware -fromTemplate '~\cloudaware\register-cloudaware-parameters.json' `
                    -dryRun `
                    -verbose

Run the module from a JSON file through the pipeline:

Get-Content -Raw '~\cloudaware\register-cloudaware-parameters.json' `
                | ConvertFrom-Json `
                | Register-Cloudaware -dryRun -verbose

Load Generated Data into Cloudaware

After Register-Cloudaware runs, open the ~\cloudaware\ directory in Azure Cloud Shell:

cd ~\cloudaware\
ls

The directory may include:

• Register-Cloudaware.ps1, the module file.
• template.json, the generated sample parameter template.
• Parameter JSON files used with -fromTemplate or pipeline execution.
• log.log, the module execution log.
• Dry-run JSON files such as dryRunToCreateApp_<USER_PRINCIPAL_NAME>_<APPLICATION_NAME>.json.
• Result JSON files such as result_<USER_PRINCIPAL_NAME>_<APP_ID>.json.
• Generated .key and .cert files if -createKeyAndSertificate was used.

Download the result_<USER_PRINCIPAL_NAME>_<APP_ID>.json file from Azure Cloud Shell and use it when configuring Azure in Cloudaware. For the Cloudaware-side setup flow, see the Azure Setup Guide.

Unregister Cloudaware

Use the Unregister-Cloudaware module to delete a Microsoft Entra ID application previously created for Cloudaware.

Prepare the Unregister Module Environment

1. Log in to the Azure portal.

2. Open Azure Cloud Shell and select PowerShell.

3. Sign in with Azure CLI:

   az login

4. Create a working directory and download the module:

   mkdir cloudaware
   cd cloudaware
   curl -LJO https://raw.githubusercontent.com/cloudaware/public-utilities/master/PowerShell%20modules/Unregister-Cloudaware.ps1

5. Import the module for the current Cloud Shell session:

   Import-Module -Name .\Unregister-Cloudaware.ps1 -Force

After the module is imported, Unregister-Cloudaware is available in the current Azure Cloud Shell session.

Unregister Module Parameters

Parameter	Description
-name <NAME>	Name of the Microsoft Entra ID application to delete. Example: -name cloudaware-api-access.
-withoutSubs	Deletes the application without unassigning roles or policies assigned to the application.
-dryRun	Saves the parameter values that would be used to delete the application to ~\cloudaware\dryRunToDeleteApp_<USER_PRINCIPAL_NAME>_<APPLICATION_NAME>.json.

Unregister Module Examples

Show help for the module:

Get-Help Unregister-Cloudaware -Full
Get-Help Unregister-Cloudaware -Examples
Get-Help Unregister-Cloudaware -Parameter *

Run a dry run before deleting the application:

Unregister-Cloudaware -name cloudaware-api-access -dryRun -verbose

Delete the application without unassigning roles or policies:

Unregister-Cloudaware -name cloudaware-api-access -withoutSubs -verbose

Troubleshooting

User Is Not a Global Administrator

Error:

[2026-02-01 00:00:00] The user does not have the role 'Global administrator' assigned.

Check the current user's Microsoft Entra ID roles in the Azure portal. Go to All services > Users, select the user, and review Assigned roles.

Application Already Exists

Error:

[2026-02-01 00:00:00] The AD application 'cloudaware-api-access' already exists.

Open App registrations in the Azure portal, select All applications, and search for the application name.

Application Does Not Exist

Error:

[2026-02-01 00:00:00] The AD application 'cloudaware-api-access' does not exist.

Open App registrations in the Azure portal, select All applications, and confirm that the application name is correct.

No Subscriptions Are Available

Error:

[2026-02-01 00:00:00] Impossible to assign role(s) or a policy to the AD application 'cloudaware-api-access': Subscription(s) are not available.

Check the current user's Azure role assignments in the Azure portal. Go to All services > Users, select the user, and review Azure role assignments.

Incorrect Parameter Type

Errors:

[2026-02-01 00:00:00] The value of the parameter 'name' does not correspond to the data type [String]: '123'
[2026-02-01 00:00:00] The value of the parameter 'redirectUri' does not correspond to the data type [String]: '123'
[2026-02-01 00:00:00] The value of the parameter 'credentialExpiration' does not correspond to the data type [Int]: '3.5'

Use string values for -name and -redirectUri. Use an integer value for -credentialExpiration.

Certificate File Path Is Invalid

Error:

[2026-02-01-01 00:00:00] The path in the parameter 'certificateFile' is not correct: './cert.pem'

Use the correct path to the certificate file.

Certificate Content Is Invalid

Error:

[2026-02-01 00:00:00] ValidationError: Incorrect padding. Detailed information: 'https://docs.microsoft.com/en-us/cli/azure/ad/app/credential?view=azure-cli-latest#az_ad_app_credential_reset'

Confirm that the certificate was generated correctly, then rerun Register-Cloudaware.

User Does Not Have Owner Role

Errors:

[2026-02-01 00:00:00] Subscription ID(s) from 'withSubscriptionRole', where the user does not have the role 'Owner' (RBAC) assigned: ['00000000-0000-0000-0000-000000000000']
[2026-02-01 00:00:00] Subscription ID(s) from 'withKubernetesRole', where the user does not have the role 'Owner' (RBAC) assigned: ['00000000-0000-0000-0000-000000000000']
[2026-02-01 00:00:00] Subscription ID(s) from 'withKeyVaultPolicies', where the user does not have the role 'Owner' (RBAC) assigned: ['00000000-0000-0000-0000-000000000000']

Ask an Azure administrator to assign the required Owner role, then rerun the module.

Reservation Access Is Missing

Errors:

[2026-02-01 00:00:00] Reservation Order ID(s), where the user does not have the role 'Owner' (RBAC) assigned: ['00000000-0000-0000-0000-000000000000']
[2026-02-01 00:00:00] Reservation Order ID(s) were not discovered.
[2026-02-01 00:00:00] Reservation Order ID(s) where the scope is not set up as 'Shared': ['00000000-0000-0000-0000-000000000000']

In the Azure portal, go to Reservations and confirm that reservations exist, the reservation scope is Shared, and the current user has the required access.

Key Vault Name Is Unavailable or Incorrect

Error:

[2026-02-01 00:00:00] Key Vault name(s) that are not associated with any of the available Subscription ID(s): ['keyVaultName_1']

Confirm that the Key Vault names are correct and that the current user has access to the subscriptions that contain them.

Service Principal Extraction Failed

Error:

[2026-02-01 00:00:00] An error occurred while extracting Service Principal Name(s).

Open Enterprise applications in the Azure portal, select All applications, and search for the application name. If the issue appears temporary, rerun the module.

API Permissions Were Not Assigned

Error:

[2026-02-01 00:00:00] Deleting the AD application 'cloudaware-api-access': API permissions were not assigned correctly.

Rerun the module if the issue appears temporary. If it persists, contact Cloudaware Support.